create-cmp-cli 0.8.0 → 0.9.0

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppBottomBar.kt

@@ -0,0 +1,138 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.background
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.defaultMinSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.height
+import androidx.compose.foundation.layout.navigationBarsPadding
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.layout.size
+import androidx.compose.foundation.shape.RoundedCornerShape
+import androidx.compose.material3.Icon
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.draw.clip
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.dp
+import androidx.compose.ui.unit.sp
+import __PACKAGE__.presentation.navigation.AppTab
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.designToken
+
+/**
+ * The bottom tab bar: one item per tab, icon over label. Owns the 48 dp touch targets,
+ * the deterministic `nav_<slug>` testTags, token-bound colors, the navigation-bar inset
+ * padding, and the `BottomNavHeight` inspector self-report. Selection state stays with
+ * the caller; `AppShell` wires it.
+ *
+ * @param tabs Tabs in display order; each label also derives its item's `nav_*` testTag.
+ * @param selectedIndex Index of the selected tab in [tabs].
+ * @param onSelect Called with the index of the tapped tab.
+ */
+@Composable
+fun AppBottomBar(
+    tabs: List<AppTab>,
+    selectedIndex: Int,
+    onSelect: (Int) -> Unit,
+    modifier: Modifier = Modifier,
+) {
+    Column(modifier.fillMaxWidth()) {
+        Box(
+            Modifier
+                .fillMaxWidth()
+                .height(1.dp)
+                .background(__THEME_PREFIX__Colors.OutlineVariant)
+        )
+        Row(
+            modifier = Modifier
+                .fillMaxWidth()
+                .background(__THEME_PREFIX__Colors.Surface)
+                // Lift tabs above the gesture pill / 3-button nav (maps to iOS safe area).
+                .navigationBarsPadding()
+                .height(__THEME_PREFIX__Tokens.BottomNavHeight)
+                // Inspector: the bottom-nav container self-reports its height token.
+                .designToken(
+                    tokens = listOf("BottomNavHeight"),
+                    resolved = mapOf("height" to "${__THEME_PREFIX__Tokens.BottomNavHeight.value.toInt()}dp"),
+                )
+                .semantics { testTag = "app_bottom_nav" }
+                .padding(bottom = 8.dp),
+            verticalAlignment = Alignment.CenterVertically,
+            horizontalArrangement = Arrangement.SpaceEvenly,
+        ) {
+            tabs.forEachIndexed { index, tab ->
+                NavItem(
+                    label = tab.label,
+                    selected = selectedIndex == index,
+                    onClick = { onSelect(index) },
+                ) {
+                    Icon(
+                        imageVector = tab.icon,
+                        contentDescription = tab.label,
+                        tint = if (selectedIndex == index) __THEME_PREFIX__Colors.Primary
+                               else __THEME_PREFIX__Colors.OnSurfaceVariant.copy(alpha = 0.55f),
+                        modifier = Modifier.size(24.dp),
+                    )
+                }
+            }
+        }
+    }
+}
+
+/**
+ * Deterministic automation tag for a nav item: `nav_` + the label lowercased with every
+ * non-[a-z0-9] run collapsed to `_` and trimmed (e.g. "My Stuff!" → `nav_my_stuff`).
+ * Must mirror `navSlug` in create-cmp's engine (src/lib/tabs.mjs), which generates
+ * `qa/e2e/smoke.yaml`'s id selectors from the configured tabs — keep the two in sync.
+ */
+private fun navItemTag(label: String): String =
+    "nav_" + label.lowercase().replace(Regex("[^a-z0-9]+"), "_").trim('_')
+
+/**
+ * A single tab item: icon over label, a 48 dp minimum touch target, tagged from its
+ * label via [navItemTag]. Internal (not private) so the component story
+ * (`component.nav-item`) can render it in isolation; absent from the public API surface.
+ *
+ * @param selected True renders the item in the selected treatment (primary color, bold label).
+ * @param icon Icon slot, rendered above the label.
+ */
+@Composable
+internal fun NavItem(
+    label: String,
+    selected: Boolean,
+    onClick: () -> Unit,
+    icon: @Composable () -> Unit,
+) {
+    Column(
+        modifier = Modifier
+            .clip(RoundedCornerShape(8.dp))
+            .clickable(onClick = onClick)
+            // a11y: guarantee the 48dp minimum touch target regardless of label width
+            // (the inspector's audit_a11y flags anything smaller).
+            .defaultMinSize(minWidth = 48.dp, minHeight = 48.dp)
+            // Durable selection handle (tests/E2E select by testTag, never display text).
+            .semantics { testTag = navItemTag(label) }
+            .padding(horizontal = 8.dp, vertical = 4.dp),
+        horizontalAlignment = Alignment.CenterHorizontally,
+        verticalArrangement = Arrangement.Center,
+    ) {
+        icon()
+        Text(
+            text = label,
+            fontSize = 10.sp,
+            fontWeight = if (selected) FontWeight.Bold else FontWeight.SemiBold,
+            color = if (selected) __THEME_PREFIX__Colors.Primary else __THEME_PREFIX__Colors.OnSurfaceVariant,
+            modifier = Modifier.padding(top = 4.dp),
+        )
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppButton.kt

@@ -0,0 +1,56 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.sizeIn
+import androidx.compose.material3.Button
+import androidx.compose.material3.Text
+import androidx.compose.material3.TextButton
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+
+/**
+ * The filled call-to-action button: M3 `Button` with a 48 dp minimum touch target
+ * applied. Stock M3 buttons sit below that floor by default; wrapping them here clears
+ * WCAG 2.2 SC 2.5.8 and the harness's `audit_a11y` bar once, for every call site.
+ */
+@Composable
+fun AppPrimaryButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    Button(
+        onClick = onClick,
+        enabled = enabled,
+        modifier = modifier.sizeIn(minWidth = AppButtonDefaults.MinTouchTarget, minHeight = AppButtonDefaults.MinTouchTarget),
+    ) {
+        Text(text)
+    }
+}
+
+/**
+ * The low-emphasis text button, with the same 48 dp floor as [AppPrimaryButton]. These
+ * two are the registry's only buttons — a new variant (icon, loading, destructive, FAB)
+ * is a registry addition a human approves, not a local tweak.
+ */
+@Composable
+fun AppTextButton(
+    text: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    enabled: Boolean = true,
+) {
+    TextButton(
+        onClick = onClick,
+        enabled = enabled,
+        modifier = modifier.sizeIn(minWidth = AppButtonDefaults.MinTouchTarget, minHeight = AppButtonDefaults.MinTouchTarget),
+    ) {
+        Text(text)
+    }
+}
+
+/** Shared button constants, following the `ComponentDefaults` naming convention. */
+object AppButtonDefaults {
+    val MinTouchTarget = 48.dp
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/AppHeader.kt

@@ -0,0 +1,54 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.RowScope
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+
+/**
+ * The screen header: a headline row with an optional back affordance and a trailing
+ * actions slot, tagged `<screenTag>_title` and `<screenTag>_back`. Deliberately not an
+ * M3 `TopAppBar` — no scroll behaviors, no center-aligned variants, no window-inset
+ * handling (`BaseScreen` owns insets, SHELL-03). A collapsing toolbar would be a
+ * registry addition, not a default.
+ *
+ * @param title Headline text, rendered in `headlineMedium`.
+ * @param screenTag Feature slug; derives the `<screenTag>_title` and `<screenTag>_back` tags.
+ * @param onBack Non-null renders a 48 dp back affordance left of the title.
+ * @param actions Trailing slot at the row's end, for per-screen controls.
+ */
+@Composable
+fun AppHeader(
+    title: String,
+    screenTag: String,
+    modifier: Modifier = Modifier,
+    onBack: (() -> Unit)? = null,
+    actions: @Composable RowScope.() -> Unit = {},
+) {
+    Row(
+        modifier = modifier.fillMaxWidth().padding(bottom = 12.dp),
+        verticalAlignment = Alignment.CenterVertically,
+    ) {
+        if (onBack != null) {
+            AppTextButton(
+                text = "← Back",
+                onClick = onBack,
+                modifier = Modifier.semantics { testTag = "${screenTag}_back" },
+            )
+        }
+        Text(
+            text = title,
+            style = MaterialTheme.typography.headlineMedium,
+            modifier = Modifier.weight(1f).semantics { testTag = "${screenTag}_title" },
+        )
+        actions()
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/BaseScreen.kt

@@ -15,15 +15,23 @@ import androidx.compose.ui.graphics.Color
 import __PACKAGE__.presentation.theme.designToken
 
 /**
- * The insets moat, pre-solved. Every screen wraps its content in [BaseScreen] instead of
- * re-deriving edge-to-edge padding. The Activity is edge-to-edge (transparent system bars);
- * this Scaffold owns the status-bar / navigation-bar insets in shared code, which also maps
- * to iOS safe areas under Compose Multiplatform.
+ * The edge-to-edge scaffold that owns system-bar insets in shared code. The Activity
+ * draws behind transparent system bars; this component applies status-bar and
+ * navigation-bar padding once (mapping to iOS safe areas under Compose Multiplatform),
+ * consumes what it applies to prevent doubled padding, and self-reports the applied
+ * inset facts to the inspector. Screens wrap their content in it instead of re-deriving
+ * insets.
  *
- * - [topBar] / [bottomBar] draw edge-to-edge (e.g. a nav bar that bleeds behind the gesture
- *   pill) and are responsible for their own inset padding.
- * - The content lambda receives padding already accounting for any bars; by default the body
- *   gets status + navigation bar padding so plain screens are safe with zero ceremony.
+ * @param containerColor Background color; `Color.Unspecified` resolves to the theme background.
+ * @param applyStatusBarPadding False lets the body draw under the status bar, for
+ *   full-bleed content that handles the top inset itself.
+ * @param applyNavBarPadding False lets the body draw under the navigation bar — set it
+ *   when a bottom bar owns that inset instead.
+ * @param topBar Draws edge-to-edge and is responsible for its own inset padding.
+ * @param bottomBar Draws edge-to-edge and is responsible for its own inset padding
+ *   (e.g. a nav bar that bleeds behind the gesture pill).
+ * @param content Screen body. Its padding is already applied by the wrapper; the
+ *   `PaddingValues` are passed through for callers that need the raw values.
  */
 @Composable
 fun BaseScreen(

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/ContentStateContainer.kt

@@ -0,0 +1,105 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Arrangement
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.material3.CircularProgressIndicator
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.contentDescription
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+
+/**
+ * The state dispatcher for any data-backed screen: folds a [ContentUiState] into one of
+ * four rendered arms — loading, error, empty, content. The container owns the three
+ * non-content arms' UI and their derived testTags; the screen supplies only its content
+ * shape in the trailing slot. Every screen that loads data uses it; a feature whose
+ * state machine genuinely outgrows the four arms defines its own sealed type and skips
+ * the container — that divergence is visible in review.
+ *
+ * @param state Current arm. The fold is exhaustive; exactly one arm renders.
+ * @param screenTag Feature slug ("home"). Required, not defaulted: tests, golden trees,
+ *   and E2E flows all key on the derived tags `<screenTag>_loading` / `_error` /
+ *   `_retry` / `_empty`, so tagging cannot be left to each caller.
+ * @param onRetry Non-null renders a retry control (`<screenTag>_retry`) in the default
+ *   error arm.
+ * @param loading Loading slot; defaults to a list-shaped skeleton
+ *   (`ContentStateDefaults.ListSkeleton`).
+ * @param error Error slot; receives the message carried by [ContentUiState.Error].
+ * @param empty Empty slot; defaults to [EmptyState] with its generic copy.
+ * @param content Content arm; receives the loaded data.
+ */
+@Composable
+fun <T> ContentStateContainer(
+    state: ContentUiState<T>,
+    screenTag: String,
+    modifier: Modifier = Modifier,
+    onRetry: (() -> Unit)? = null,
+    loading: @Composable () -> Unit = { ContentStateDefaults.ListSkeleton(screenTag) },
+    error: @Composable (message: String) -> Unit = { ErrorState(message = it, screenTag = screenTag, onRetry = onRetry) },
+    empty: @Composable () -> Unit = { EmptyState(screenTag = screenTag) },
+    content: @Composable (data: T) -> Unit,
+) {
+    Box(modifier.fillMaxSize()) {
+        when (state) {
+            is ContentUiState.Loading -> loading()
+            is ContentUiState.Error -> error(state.message)
+            is ContentUiState.Empty -> empty()
+            is ContentUiState.Content -> content(state.data)
+        }
+    }
+}
+
+/** Default slot implementations for [ContentStateContainer]. */
+object ContentStateDefaults {
+
+    /**
+     * The default loading slot: skeleton rows shaped like [ListItemCard], so the loaded
+     * list replaces them without a layout jump. The container node carries the
+     * `<screenTag>_loading` tag and a "Loading" `contentDescription`; the bars
+     * themselves are decorative and stay semantics-silent.
+     *
+     * @param screenTag Feature slug; tags the container `<screenTag>_loading`.
+     * @param rows Skeleton rows to render while loading.
+     */
+    @Composable
+    fun ListSkeleton(screenTag: String, rows: Int = 3) {
+        Column(
+            modifier = Modifier
+                .fillMaxSize()
+                .semantics {
+                    testTag = "${screenTag}_loading"
+                    contentDescription = "Loading"
+                },
+            verticalArrangement = Arrangement.spacedBy(__THEME_PREFIX__Tokens.GapCard),
+        ) {
+            repeat(rows) { ListItemSkeleton() }
+        }
+    }
+
+    /**
+     * A centered spinner, for waits that are not content-shaped (a short, single-value
+     * operation where a skeleton would promise the wrong layout). Carries the same
+     * `<screenTag>_loading` tag as the skeleton.
+     *
+     * @param screenTag Feature slug; tags the container `<screenTag>_loading`.
+     */
+    @Composable
+    fun Spinner(screenTag: String) {
+        Box(
+            modifier = Modifier
+                .fillMaxSize()
+                .semantics {
+                    testTag = "${screenTag}_loading"
+                    contentDescription = "Loading"
+                },
+            contentAlignment = Alignment.Center,
+        ) {
+            CircularProgressIndicator()
+        }
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/ContentUiState.kt

@@ -0,0 +1,18 @@
+package __PACKAGE__.presentation.components
+
+/**
+ * The four-way lifecycle of a data-backed screen: Loading, Error, Empty, Content.
+ * Sealed so a `when` over it is exhaustive — a screen cannot forget a state, and cannot
+ * render two at once. ViewModels fold repository results into this type;
+ * [ContentStateContainer] renders it.
+ */
+sealed interface ContentUiState<out T> {
+    data object Loading : ContentUiState<Nothing>
+    data class Error(val message: String) : ContentUiState<Nothing>
+    data object Empty : ContentUiState<Nothing>
+    data class Content<out T>(val data: T) : ContentUiState<T>
+}
+
+/** ViewModel-side helper: the Empty/Content decision made once, not per screen. */
+fun <E> List<E>.toContentState(): ContentUiState<List<E>> =
+    if (isEmpty()) ContentUiState.Empty else ContentUiState.Content(this)

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/EmptyState.kt

@@ -0,0 +1,58 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+
+/**
+ * The Empty arm of the four-state contract: shown when a load succeeds with nothing to
+ * list. Tags itself `<screenTag>_empty`, so the state is selectable in tests and E2E
+ * flows. The default copy is deliberately generic — a shaped feature replaces
+ * `title`/`body` with its own domain language.
+ *
+ * @param screenTag Feature slug; the root is tagged `<screenTag>_empty`.
+ * @param title Headline. The default is placeholder copy, meant to be replaced per feature.
+ * @param body Optional supporting line under the title.
+ * @param action Optional call-to-action below the text — an [AppTextButton], for example.
+ */
+@Composable
+fun EmptyState(
+    screenTag: String,
+    modifier: Modifier = Modifier,
+    title: String = "Nothing here yet",
+    body: String? = null,
+    action: (@Composable () -> Unit)? = null,
+) {
+    Box(
+        modifier = modifier.fillMaxSize().semantics { testTag = "${screenTag}_empty" },
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            Text(
+                text = title,
+                style = MaterialTheme.typography.bodyLarge,
+                color = MaterialTheme.colorScheme.onSurfaceVariant,
+            )
+            if (body != null) {
+                Text(
+                    text = body,
+                    style = MaterialTheme.typography.bodyMedium,
+                    color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    modifier = Modifier.padding(top = 4.dp),
+                )
+            }
+            if (action != null) {
+                Box(Modifier.padding(top = 12.dp)) { action() }
+            }
+        }
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/ErrorState.kt

@@ -0,0 +1,52 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Box
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import androidx.compose.ui.unit.dp
+
+/**
+ * The Error arm of the four-state contract: renders the message and, when a retry
+ * handler is supplied, a `<screenTag>_retry` control with a 48 dp touch target. The
+ * error state is a rendered, testable affordance — not just a ViewModel arm.
+ *
+ * @param message User-facing copy. Presentation maps a `DomainError` kind to it; never
+ *   pass a raw exception string.
+ * @param screenTag Feature slug; derives the `<screenTag>_error` and `<screenTag>_retry` tags.
+ * @param onRetry Non-null renders the retry control; null renders the message alone.
+ */
+@Composable
+fun ErrorState(
+    message: String,
+    screenTag: String,
+    onRetry: (() -> Unit)? = null,
+    modifier: Modifier = Modifier,
+) {
+    Box(
+        modifier = modifier.fillMaxSize().semantics { testTag = "${screenTag}_error" },
+        contentAlignment = Alignment.Center,
+    ) {
+        Column(horizontalAlignment = Alignment.CenterHorizontally) {
+            Text(
+                text = message,
+                style = MaterialTheme.typography.bodyLarge,
+                color = MaterialTheme.colorScheme.error,
+            )
+            if (onRetry != null) {
+                AppTextButton(
+                    text = "Retry",
+                    onClick = onRetry,
+                    modifier = Modifier.padding(top = 12.dp).semantics { testTag = "${screenTag}_retry" },
+                )
+            }
+        }
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/ListItemCard.kt

@@ -0,0 +1,77 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.clickable
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.Row
+import androidx.compose.foundation.layout.defaultMinSize
+import androidx.compose.foundation.layout.fillMaxWidth
+import androidx.compose.foundation.layout.padding
+import androidx.compose.material3.MaterialTheme
+import androidx.compose.material3.Surface
+import androidx.compose.material3.Text
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Alignment
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.unit.dp
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.designToken
+
+/**
+ * The list row: title, optional subtitle, optional leading/trailing slots, on a card
+ * surface bound to `RadiusCard`, `ElevationCard`, and `PaddingCard`. The `clickable`
+ * sits on the `Surface`, so the whole row is the touch target, with a 48 dp minimum
+ * height. Reach for it in any list before hand-rolling a row.
+ *
+ * @param onClick Row-level click handler; the whole card is the target.
+ * @param modifier Per-item testTags go here (`Modifier.testTag("home_item_$id")`) — ids
+ *   are domain data, so the component does not derive them.
+ * @param subtitle Optional second line, in the muted variant color.
+ * @param leading Slot before the text column — an icon or avatar.
+ * @param trailing Slot after the text column — a chevron or badge.
+ */
+@Composable
+fun ListItemCard(
+    title: String,
+    onClick: () -> Unit,
+    modifier: Modifier = Modifier,
+    subtitle: String? = null,
+    leading: (@Composable () -> Unit)? = null,
+    trailing: (@Composable () -> Unit)? = null,
+) {
+    Surface(
+        color = MaterialTheme.colorScheme.surface,
+        shape = MaterialTheme.shapes.medium,
+        tonalElevation = __THEME_PREFIX__Tokens.ElevationCard,
+        modifier = modifier
+            .fillMaxWidth()
+            .defaultMinSize(minHeight = 48.dp)
+            .designToken(
+                tokens = listOf("RadiusCard", "ElevationCard", "PaddingCard"),
+                resolved = mapOf(
+                    "radius" to "${__THEME_PREFIX__Tokens.RadiusCard.value.toInt()}dp",
+                    "elevation" to "${__THEME_PREFIX__Tokens.ElevationCard.value.toInt()}dp",
+                    "padding" to "${__THEME_PREFIX__Tokens.PaddingCard.value.toInt()}dp",
+                    "color" to "#FFFFFFFF",
+                ),
+            )
+            .clickable(onClick = onClick),
+    ) {
+        Row(
+            modifier = Modifier.padding(__THEME_PREFIX__Tokens.PaddingCard),
+            verticalAlignment = Alignment.CenterVertically,
+        ) {
+            if (leading != null) leading()
+            Column(modifier = Modifier.weight(1f)) {
+                Text(title, style = MaterialTheme.typography.titleMedium)
+                if (subtitle != null) {
+                    Text(
+                        subtitle,
+                        style = MaterialTheme.typography.bodyMedium,
+                        color = MaterialTheme.colorScheme.onSurfaceVariant,
+                    )
+                }
+            }
+            if (trailing != null) trailing()
+        }
+    }
+}

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/components/ScreenColumn.kt

@@ -0,0 +1,47 @@
+package __PACKAGE__.presentation.components
+
+import androidx.compose.foundation.layout.Column
+import androidx.compose.foundation.layout.ColumnScope
+import androidx.compose.foundation.layout.fillMaxSize
+import androidx.compose.foundation.layout.padding
+import androidx.compose.foundation.rememberScrollState
+import androidx.compose.foundation.verticalScroll
+import androidx.compose.runtime.Composable
+import androidx.compose.ui.Modifier
+import androidx.compose.ui.semantics.semantics
+import androidx.compose.ui.semantics.testTag
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.designToken
+
+/**
+ * The page container every screen roots itself in. Owns the tagged root
+ * (`<screenTag>_screen`), the page padding from `PaddingPage`, and that token's
+ * inspector self-report — the reported value is derived from the token itself, so it
+ * cannot drift from the catalog. Screens never hand-roll their root column.
+ *
+ * @param screenTag Feature slug ("home"); the root is tagged `<screenTag>_screen`.
+ * @param scrollable True wraps the column in a vertical scroll. Leave false when the
+ *   content scrolls itself (a `LazyColumn`) — nesting the two crashes at runtime.
+ * @param content Column body, laid out inside the page padding.
+ */
+@Composable
+fun ScreenColumn(
+    screenTag: String,
+    modifier: Modifier = Modifier,
+    scrollable: Boolean = false,
+    content: @Composable ColumnScope.() -> Unit,
+) {
+    val base = modifier
+        .fillMaxSize()
+        .semantics { testTag = "${screenTag}_screen" }
+        .designToken(
+            tokens = listOf("PaddingPage"),
+            resolved = mapOf("padding" to "${__THEME_PREFIX__Tokens.PaddingPage.value.toInt()}dp"),
+        )
+        .padding(__THEME_PREFIX__Tokens.PaddingPage)
+
+    Column(
+        modifier = if (scrollable) base.verticalScroll(rememberScrollState()) else base,
+        content = content,
+    )
+}