Layouts, Material 3, Adaptive UI, Popups and Accessibility

Modifiers are an ordered chain: padding before background is not the same as background before padding. That rule is identical everywhere. What differs by platform is the input model that some modifiers expose.

See Kotlin docs — Working with modifiers.

Android 15 enforces edge-to-edge drawing, and iOS draws under the status bar and home indicator by default. In shared code, Scaffold consumes the insets and passes them as PaddingValues to its content. If you place content directly in a Box you must call Modifier.safeDrawingPadding() yourself. Edge-to-edge details for Android are in Adaptive Layouts, Edge-to-Edge and Large Screens.

Common mistake: applying innerPadding to a Box that wraps a LazyColumn and then padding the list again, which doubles the top inset on iOS. Pass innerPadding once, either as Modifier.padding or inside contentPadding.

The theme is the single place where color, type and shape are decided. TrailMateTheme picks a scheme from the system dark-mode setting (isSystemInDarkTheme() works in common code) and optionally from a platform-provided dynamic scheme. Dynamic color exists only on Android 12 and later, so it is an expect/actual hook with a null fallback; see expect/actual and Platform APIs.

See Kotlin docs — Layouts in Compose Multiplatform and the Android counterpart in Compose Material 3 and Theming.

Common mistakes: reading LocalContext in commonMain (Android only); forgetting that isSystemInDarkTheme() on iOS tracks the user interface style of the hosting UIViewController, so an app forced to light mode in Info.plist will never report dark.

Material 3 Expressive adds a motion scheme, richer shapes and new components. In CMP it is exposed through MaterialExpressiveTheme, which takes colorScheme, motionScheme, shapes and typography. It is Experimental: it requires @OptIn(ExperimentalMaterial3ExpressiveApi::class), and the experimental symbols are only in the alpha Material 3 builds, because the stable Material 3 line removed them. Use it only if you accept API changes between releases.

See Kotlin docs — What’s new in Compose Multiplatform 1.9.3.

A window size class buckets the available width and height into compact, medium and expanded (newer versions add larger breakpoints). The recommended entry point is currentWindowAdaptiveInfoV2(), which supersedes the earlier currentWindowAdaptiveInfo() and returns a WindowAdaptiveInfo whose windowSizeClass you query with the isWidthAtLeastBreakpoint and isHeightAtLeastBreakpoint functions rather than comparing enum values.

See Kotlin docs — Adaptive layouts.

Depend on org.jetbrains.compose.material3.adaptive:adaptive in commonMain (see the Gradle snippet above). Keep the decision in one function like rememberTrailLayout() so the thresholds are not scattered across screens, and so tests can substitute a fixed layout.

The simplest adaptive pattern is a when over the layout bucket. On a compact window TrailListScreen navigates to TrailDetailScreen; on an expanded window both appear side by side and selection changes only the right pane.

See Kotlin docs — Adaptive layouts.

The state is kept with rememberSaveable, so rotating or resizing does not lose the selection. The shared navigation setup that decides which screen is on top is covered in Lifecycle, ViewModel and Navigation in Compose Multiplatform.

For list-detail, supporting-pane and navigation chrome, the Material 3 adaptive libraries ship ready-made scaffolds that handle pane count, spacing and (on Android) fold posture:

Because stability of each scaffold changes between releases, read the API annotations in your Material 3 adaptive version rather than relying on this table. The concepts are explained for Android in Adaptive Layouts, Edge-to-Edge and Large Screens.

NavigationSuiteScaffold shows a bottom bar on a compact window, a navigation rail on medium and a drawer on large, without any expect/actual. A NavigationSuiteScaffold(navigationSuiteItems = \{ item(selected, onClick, icon, label) }) \{ content } call is all that is needed; the selected destination is kept with rememberSaveable.

A Popup is declared in the composition where its anchor lives and is shown only while a state flag is true. With alignment and offset it is positioned relative to its parent; for anchored placement implement PopupPositionProvider, which receives the anchor bounds, window size, layout direction and the popup’s content size and returns the top-left IntOffset.

See Kotlin docs — Popups.

Properties that are not in the common source set (for example usePlatformInsets) are reachable only from the platform source set, or through an expect/actual wrapper.

Dialog takes onDismissRequest, optional DialogProperties and its content; Material’s AlertDialog is a styled wrapper. A Dialog always stays inside the host window on mobile and web. On desktop, where the user may want an OS-level window that can move outside the main window, CMP offers DialogWindow (covered in Compose Multiplatform for Desktop).

A typical call is AlertDialog(onDismissRequest = onDismiss, properties = DialogProperties(dismissOnClickOutside = false), title = \{ …​ }, confirmButton = \{ …​ }) in sharedUI/src/commonMain/kotlin/com/example/trailmate/ui/detail/; dismissOnClickOutside = false forces an explicit choice for destructive actions.

See Kotlin docs — Popups.

Common mistakes: using Dialog for a dropdown (it blocks the UI and dims it); forgetting to reset the state flag in onDismissRequest, so the popup reappears on the next recomposition; and expecting the Android back button to dismiss a Popup without focusable = true.

See Kotlin docs — Accessibility.

Reading order is controlled with isTraversalGroup = true and traversalIndex inside Modifier.semantics; the default index is 0f, and a lower value is read earlier. Use it sparingly: the default left-to-right, top-to-bottom order is right for most screens, and a wrong manual order is worse than none.

On iOS, CMP converts the semantic tree into native accessibility objects, so VoiceOver and Switch Control can read and operate the Compose UI with the same gestures as a native app. For most Material widgets this is automatic. The mapping extends to automation: testTag maps to accessibilityIdentifier, so XCUITest can find a CMP element exactly as it finds a SwiftUI one.

See Kotlin docs — Support for iOS accessibility features.

The page also documents support for AssistiveTouch (pointer control) and Full Keyboard Access, and for a high-contrast theme: Material 3’s ColorScheme has no built-in high-contrast variant, so you supply an extra palette and switch to it when UIAccessibilityDarkerSystemColorsEnabled is true, observing UIAccessibilityDarkerSystemColorsStatusDidChangeNotification. Keep text contrast at least 4.5:1 (7:1 is recommended for small text). How SwiftUI views and CMP screens coexist in one app is covered in Compose Multiplatform on iOS; the platform’s own accessibility model is in Accessibility on Apple Platforms.

On Windows, enable the bridge while developing with %JAVA_HOME%\bin\jabswitch.exe /enable, and include the jdk.accessibility module in packaged apps so the shipped build exposes accessibility information.

See Kotlin docs — Support for desktop accessibility features.

Test on macOS with Xcode’s Accessibility Inspector, and on Windows with the speech history in JAWS or the Speech Viewer in NVDA. Packaging details are in Compose Multiplatform for Desktop.

CMP for web (Beta) exposes the semantic tree to the browser’s accessibility tree, so screen readers can reach the canvas-rendered UI. Because the page is drawn to a canvas, native browser features such as text search, link previews and translation behave differently from a DOM page. Always provide contentDescription for images, set a meaningful <title> in the host HTML and test with a real screen reader (VoiceOver in Safari, NVDA in Firefox). Hosting and deployment are covered in Web Targets: Kotlin/Wasm, Kotlin/JS and Compose for Web.