Skip to content

Migration Guide — Status Bar Ownership & Tonal Theme

This release replaces FioriHorizonTheme with FioriCustomTonalTheme as the internal theme engine and overhauls how status bar and navigation bar colors are controlled. The fragmented approach (flags on CustomStyles, Accompanist SystemUiController hooks, a composable FlowActionHandler override) is replaced by two typed SystemBarStyle properties on FlowOptions.

Affects: flows-compose and onboarding-compose libraries. Behavior differences noted for API 35+ (Android 15).


Breaking Changes

1. CustomStyles.applyStatusBarColor Removed

The applyStatusBarColor: Boolean field on CustomStyles has been removed.

Before:

FlowOptions(
    customStyles = CustomStyles(applyStatusBarColor = false)
)

After: Remove the argument entirely. The default behavior (apply SapFioriColorS1 to the status bar on API < 35) is unchanged when neither statusBarStyle nor fullScreen is set.

To suppress status bar coloring entirely, pass a transparent style:

import androidx.activity.SystemBarStyle
import android.graphics.Color

FlowOptions(
    statusBarStyle = SystemBarStyle.light(
        scrim = Color.TRANSPARENT,
        darkScrim = Color.TRANSPARENT
    )
)

2. CustomStyles Default BaseAttributes No Longer Sets statusBarColor

Previously, the light and dark BaseAttributes created by the CustomStyles default were initialized with statusBarColor = SapFioriColorS1. That field was used by FioriHorizonTheme to tint the status bar.

After: The default BaseAttributes no longer set statusBarColor. The tonal theme manages status bar coloring directly via a SideEffect inside FlowComposeTheme. If your override of FlowActionHandler.adjustThemeAttributes() mutates src.statusBarColor, that mutation has no visual effect under FioriCustomTonalTheme - see Breaking Change 4 below.


3. FlowActionHandler.updateSystemBarColors() Deprecated (Empty No-Op)

updateSystemBarColors() is now @Deprecated with an empty body. Overriding it has no effect.

Before:

class MyFlowActionHandler : FlowActionHandler() {
    @Composable
    override fun updateSystemBarColors() {
        val controller = rememberSystemUiController()
        SideEffect { controller.setStatusBarColor(Color.Blue) }
    }
}

After: Delete the override. Use FlowOptions.statusBarStyle instead:

FlowOptions(
    statusBarStyle = SystemBarStyle.light(
        scrim = android.graphics.Color.BLUE,
        darkScrim = android.graphics.Color.DKGRAY
    )
)

4. FlowActionHandler.adjustThemeAttributes() — Color-only; Other Overrides Ignored

Under FioriCustomTonalTheme, only color fields in BaseAttributes are forwarded to the theme. Font family, typography (TextStyle), shape, and behavior flags are managed internally by the tonal theme and are no longer applied via this hook.

Additionally:

  • The default implementation is now a no-op (empty body). Previously it normalized statusBarColor to SapFioriColorS0 when it matched the horizon default. That logic has been removed.
  • The method is called twice per composition — once for light attributes (darkTheme = false) and once for dark attributes (darkTheme = true). Overrides must be idempotent and must not rely on being called exactly once.
  • statusBarColor mutations in src no longer have any effect on the actual status bar.

Before:

override fun adjustThemeAttributes(src: BaseAttributes, darkTheme: Boolean, downloadedTheme: Boolean) {
    src.statusBarColor = Color.Blue  // changed the status bar
    src.defaultTypography = myTypography  // changed typography
}

After:

override fun adjustThemeAttributes(src: BaseAttributes, darkTheme: Boolean, downloadedTheme: Boolean) {
    // Only color mutations take effect
    src.SapFioriColorT1 = if (darkTheme) Color.DarkGray else Color.LightGray
    // Typography/shape overrides: remove — they are no-ops under FioriCustomTonalTheme
    // statusBarColor mutations: remove — use FlowOptions.statusBarStyle instead
}

5. Accompanist SystemUiController Removed

The com.google.accompanist:accompanist-systemuicontroller dependency is no longer used internally. If your custom FlowActionHandler still imports rememberSystemUiController, remove that import and the override — it served no purpose once updateSystemBarColors() was deprecated.


New Features

FlowOptions.statusBarStyle — Typed Status Bar Control

val style: SystemBarStyle? // null = SDK default
  • null (default): SDK applies SapFioriColorS1 as the status bar background on API < 35 and sets the icon tint automatically based on the background color's brightness. On API 35+ the platform enforces edge-to-edge and this setting has no effect.
  • Non-null: The provided SystemBarStyle is passed to enableEdgeToEdge() in FlowActivity. This enables edge-to-edge layout for the activity window. All SDK flow screens use Scaffold with inset handling, but verify that any custom screens you inject via FlowActionHandler.getFlowCustomizationSteps().

Example — branded status bar:

FlowOptions(
    statusBarStyle = SystemBarStyle.light(
        scrim = android.graphics.Color.parseColor("#0070F2"), // SAP brand blue
        darkScrim = android.graphics.Color.parseColor("#003D8F")
    )
)

FlowOptions.navigationBarStyle — Typed Navigation Bar Control

val navigationBarStyle: SystemBarStyle? // null = SDK default
  • null (default): SDK applies SapFioriColorS0 (theme background color) as the navigation bar background on API < 35.
  • Non-null: The provided SystemBarStyle is passed to enableEdgeToEdge(). Same edge-to-edge implications as statusBarStyle.

Example — transparent navigation bar:

FlowOptions(
    navigationBarStyle = SystemBarStyle.light(
        scrim = android.graphics.Color.TRANSPARENT,
        darkScrim = android.graphics.Color.TRANSPARENT
    )
)

Behavior Changes (No API Action Required)

Status Bar Defaults Changed

Scenario Before After
Default (no custom style) statusBarColor from BaseAttributes, tinted via Accompanist SystemUiController SapFioriColorS1 applied via direct Window API + WindowInsetsControllerCompat. Icon tint derived from luminance.
fullScreen = true No status bar coloring (suppressed) Icon tint tracks system dark/light theme. Color left to enableEdgeToEdge().
API 35+ (Android 15) No-op (Accompanist call silently ignored) No-op (direct Window API wrapped in Build.VERSION_CODES.VANILLA_ICE_CREAM guard)

Runtime Light/dark Theme Switch

System bar icon tints now re-sync automatically when the user switches between light and dark mode at runtime. Previously, a runtime theme switch could leave stale icon tints until the next full recomposition cycle.


Removal Summary

Removed API Replacement
CustomStyles.applyStatusBarColor: Boolean FlowOptions.statusBarStyle (pass transparent style to suppress)
BaseAttributes.statusBarColor default in CustomStyles Not required — theme manages status bar internally
FlowActionHandler.updateSystemBarColors() (functional body) FlowOptions.statusBarStyle / FlowOptions.navigationBarStyle
Accompanist rememberSystemUiController usage internally Direct Window API + WindowCompat.getInsetsController()

Quick Migration Checklist

  • Remove all uses of CustomStyles(applyStatusBarColor = ...).
  • Remove overrides of FlowActionHandler.updateSystemBarColors().
  • Remove src.statusBarColor mutations from adjustThemeAttributes() overrides.
  • Remove font, typography, and shape mutations from adjustThemeAttributes() overrides — they are no-ops.
  • Ensure adjustThemeAttributes() overrides are idempotent (they are now called twice per composition).
  • If you previously relied on applyStatusBarColor = false to keep the status bar transparent, pass SystemBarStyle.light(scrim = Color.TRANSPARENT, ...) via FlowOptions.statusBarStyle.
  • If you use fullScreen = true and also want a custom status bar style, set FlowOptions.statusBarStyle — it now participates in the same enableEdgeToEdge() call.
  • Verify any custom screens injected via getFlowCustomizationSteps() handle window insets correctly if you set statusBarStyle or navigationBarStyle (this triggers edge-to-edge on devices running below API 35).

Known Issues

Typography Size Changes on Flow Screens

After migrating to FioriCustomTonalTheme, the following visual differences have been observed compared to 26.8.x:

  • Launch screen header title appears smaller than before.
  • Launch screen bottom text (e.g. "View our Terms of Service") appears larger than before.
  • Validation error messages below text fields on Basic Authentication, Passcode, and Discovery Service screens appear larger than before.

These are a consequence of FioriCustomTonalTheme managing typography internally. Font family, text style, and typography overrides set via BaseAttributes in adjustThemeAttributes() are no longer applied. There is currently no API to override typography in flows. A future SDK release will address this.

Status Bar Default Color Changed From S0 to S1

In 26.8.x, the default status bar background matched the content area background (SapFioriColorS0). As of this release the default is SapFioriColorS1. This change was made in response to an SMS customer request.

Workaround: To restore the S0 background on the status bar, pass the desired color explicitly via FlowOptions.statusBarStyle:

// Read the resolved S0 color from your theme attributes, or hardcode your brand color
FlowOptions(
    statusBarStyle = SystemBarStyle.light(
        scrim = android.graphics.Color.WHITE, // replace with your S0 value
        darkScrim = android.graphics.Color.BLACK
    )
)

statusBarStyle and navigationBarStyle Do Not Track Runtime Theme Changes

statusBarStyle and navigationBarStyle are passed to enableEdgeToEdge() once in FlowActivity.onCreate(). The styles are evaluated from FlowContext at that point and remain fixed for the lifetime of the flow. Toggling the system theme (light ↔ dark) after the flow has started updates status and navigation bar icon tints automatically, but does not update the scrim color set by statusBarStyle or navigationBarStyle.

If you compute statusBarStyle from the current isDark state when constructing FlowContext, the color will not change when the user switches themes mid-flow.

Workaround: Use a single theme-agnostic scrim color, or do not set statusBarStyle/navigationBarStyle and let the SDK apply its defaults. If your app must support dynamic scrim colors, recreate FlowContext when the system theme changes - however, this restarts the flow.


Last update: November 12, 2026