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
statusBarColortoSapFioriColorS0when 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. statusBarColormutations insrcno 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 appliesSapFioriColorS1as 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
SystemBarStyleis passed toenableEdgeToEdge()inFlowActivity. This enables edge-to-edge layout for the activity window. All SDK flow screens useScaffoldwith inset handling, but verify that any custom screens you inject viaFlowActionHandler.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 appliesSapFioriColorS0(theme background color) as the navigation bar background on API < 35.- Non-null: The provided
SystemBarStyleis passed toenableEdgeToEdge(). Same edge-to-edge implications asstatusBarStyle.
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.statusBarColormutations fromadjustThemeAttributes()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 = falseto keep the status bar transparent, passSystemBarStyle.light(scrim = Color.TRANSPARENT, ...)viaFlowOptions.statusBarStyle. - If you use
fullScreen = trueand also want a custom status bar style, setFlowOptions.statusBarStyle— it now participates in the sameenableEdgeToEdge()call. - Verify any custom screens injected via
getFlowCustomizationSteps()handle window insets correctly if you setstatusBarStyleornavigationBarStyle(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.