create-cmp-cli 0.9.0 → 0.10.0

package/template/composeApp/src/commonMain/kotlin/com/example/app/presentation/theme/Typography.kt

@@ -5,6 +5,7 @@ import androidx.compose.runtime.Composable
 import androidx.compose.ui.text.TextStyle
 import androidx.compose.ui.text.font.FontFamily
 import androidx.compose.ui.text.font.FontWeight
+import androidx.compose.ui.unit.TextUnit
 import androidx.compose.ui.unit.sp
 import org.jetbrains.compose.resources.Font
 import __PACKAGE__.generated.resources.DMSans_Bold
@@ -22,15 +23,78 @@ val DmSansFontFamily: FontFamily
         Font(Res.font.DMSans_Bold,     weight = FontWeight.Bold),
     )
 
+/**
+ * One rung of the ramp, as plain data. The ramp has to be readable WITHOUT a
+ * composition — the preview harness publishes it into `design-system.json`, and
+ * the studio console's Design language page renders the type ramp from that
+ * catalog. Holding the numbers here (rather than only inside the [Typography]
+ * factory below, which needs `@Composable` for the font family) is what keeps
+ * the published ramp and the rendered ramp the same numbers by construction.
+ *
+ * [tracking] is nullable on purpose: `null` means "leave letter spacing
+ * unspecified", which is NOT the same as `0.sp` — Compose resolves those
+ * differently, and flattening one into the other would silently retrack the
+ * mid-ramp styles.
+ */
+data class __THEME_PREFIX__TypeStyle(
+    val name: String,
+    val weight: Int,
+    val sizeSp: Int,
+    val lineHeightSp: Int,
+    val tracking: Float? = null,
+)
+
+/**
+ * A full ramp, not a minimal one. `display*` are the hero numerics (counts,
+ * totals, dashboard figures) — heavy and optically tightened; `headline`/`title`
+ * structure the screens; `label*` carries small ALL-CAPS eyebrows and metric
+ * units. Tight negative tracking on the big sizes is what makes a data-forward
+ * screen read as a considered product rather than a form — a thin ramp is the
+ * single cheapest tell of a scaffold.
+ */
+val __THEME_PREFIX__TypeRamp: List<__THEME_PREFIX__TypeStyle> = listOf(
+    __THEME_PREFIX__TypeStyle("displayLarge",   weight = 700, sizeSp = 56, lineHeightSp = 58, tracking = -1.5f),
+    __THEME_PREFIX__TypeStyle("displayMedium",  weight = 700, sizeSp = 44, lineHeightSp = 46, tracking = -1.0f),
+    __THEME_PREFIX__TypeStyle("displaySmall",   weight = 700, sizeSp = 32, lineHeightSp = 36, tracking = -0.5f),
+    __THEME_PREFIX__TypeStyle("headlineLarge",  weight = 700, sizeSp = 28, lineHeightSp = 32, tracking = -0.5f),
+    __THEME_PREFIX__TypeStyle("headlineMedium", weight = 600, sizeSp = 22, lineHeightSp = 28, tracking = -0.3f),
+    __THEME_PREFIX__TypeStyle("titleLarge",     weight = 600, sizeSp = 18, lineHeightSp = 24),
+    __THEME_PREFIX__TypeStyle("titleMedium",    weight = 600, sizeSp = 16, lineHeightSp = 22),
+    __THEME_PREFIX__TypeStyle("bodyLarge",      weight = 400, sizeSp = 16, lineHeightSp = 24),
+    __THEME_PREFIX__TypeStyle("bodyMedium",     weight = 400, sizeSp = 14, lineHeightSp = 20),
+    __THEME_PREFIX__TypeStyle("labelLarge",     weight = 600, sizeSp = 14, lineHeightSp = 18),
+    __THEME_PREFIX__TypeStyle("labelMedium",    weight = 500, sizeSp = 12, lineHeightSp = 16, tracking = 0.5f),
+    __THEME_PREFIX__TypeStyle("labelSmall",     weight = 600, sizeSp = 11, lineHeightSp = 14, tracking = 0.8f),
+)
+
+private fun ramp(name: String): __THEME_PREFIX__TypeStyle =
+    __THEME_PREFIX__TypeRamp.first { it.name == name }
+
 @Composable
 fun remember__THEME_PREFIX__Typography(): Typography {
     val dmSans = DmSansFontFamily
+    fun style(name: String): TextStyle {
+        val spec = ramp(name)
+        return TextStyle(
+            fontFamily = dmSans,
+            fontWeight = FontWeight(spec.weight),
+            fontSize = spec.sizeSp.sp,
+            lineHeight = spec.lineHeightSp.sp,
+            letterSpacing = spec.tracking?.sp ?: TextUnit.Unspecified,
+        )
+    }
     return Typography(
-        displayLarge   = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Bold,     fontSize = 32.sp),
-        headlineMedium = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.SemiBold, fontSize = 24.sp),
-        titleMedium    = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.SemiBold, fontSize = 18.sp),
-        bodyLarge      = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Normal,   fontSize = 16.sp),
-        bodyMedium     = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Normal,   fontSize = 14.sp),
-        labelSmall     = TextStyle(fontFamily = dmSans, fontWeight = FontWeight.Medium,   fontSize = 12.sp),
+        displayLarge   = style("displayLarge"),
+        displayMedium  = style("displayMedium"),
+        displaySmall   = style("displaySmall"),
+        headlineLarge  = style("headlineLarge"),
+        headlineMedium = style("headlineMedium"),
+        titleLarge     = style("titleLarge"),
+        titleMedium    = style("titleMedium"),
+        bodyLarge      = style("bodyLarge"),
+        bodyMedium     = style("bodyMedium"),
+        labelLarge     = style("labelLarge"),
+        labelMedium    = style("labelMedium"),
+        labelSmall     = style("labelSmall"),
     )
 }

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/ComponentStories.kt

@@ -1,6 +1,5 @@
 package __PACKAGE__.inspector
 
-import androidx.compose.foundation.background
 import androidx.compose.foundation.layout.Arrangement
 import androidx.compose.foundation.layout.Box
 import androidx.compose.foundation.layout.BoxScope
@@ -10,9 +9,11 @@ import androidx.compose.foundation.layout.fillMaxSize
 import androidx.compose.foundation.layout.height
 import androidx.compose.foundation.layout.padding
 import androidx.compose.material.icons.Icons
+import androidx.compose.material.icons.automirrored.filled.ArrowBack
 import androidx.compose.material.icons.filled.Home
 import androidx.compose.material.icons.filled.Person
 import androidx.compose.material3.Icon
+import androidx.compose.material3.Surface
 import androidx.compose.material3.Text
 import androidx.compose.runtime.Composable
 import androidx.compose.ui.Alignment
@@ -22,6 +23,7 @@ import androidx.compose.ui.semantics.testTag
 import androidx.compose.ui.unit.dp
 import __PACKAGE__.presentation.components.AppBottomBar
 import __PACKAGE__.presentation.components.AppHeader
+import __PACKAGE__.presentation.components.AppIconButton
 import __PACKAGE__.presentation.components.AppPrimaryButton
 import __PACKAGE__.presentation.components.AppTextButton
 import __PACKAGE__.presentation.components.BaseScreen
@@ -140,6 +142,21 @@ fun componentStories(): List<ScreenPreview> = listOf(
             modifier = Modifier.semantics { testTag = "story_text_disabled" },
         )
     },
+    variantsStory("component.app-icon-button", "AppIconButton") {
+        AppIconButton(
+            icon = Icons.AutoMirrored.Filled.ArrowBack,
+            contentDescription = "Back",
+            onClick = {},
+            modifier = Modifier.semantics { testTag = "story_icon_button" },
+        )
+        AppIconButton(
+            icon = Icons.AutoMirrored.Filled.ArrowBack,
+            contentDescription = "Back — disabled",
+            onClick = {},
+            enabled = false,
+            modifier = Modifier.semantics { testTag = "story_icon_button_disabled" },
+        )
+    },
     // The four-state contract: all four arms of the container, stacked.
     variantsStory("component.content-state-container", "ContentStateContainer") {
         ContentStateContainer<List<String>>(
@@ -262,8 +279,22 @@ private fun variantsStory(
  * generated registry can host the PlaceholderScreen story on custom-tab
  * scaffolds (PlaceholderScreen ships only when a configured tab has no
  * feature yet, so its story rides PreviewRegistry.kt, not this file).
+ *
+ * A `Surface`, not a bare `Box`: real screens root in [BaseScreen]'s `Scaffold`, which
+ * provides `LocalContentColor` to everything below it. A Box only PAINTS a background —
+ * it supplies no content color — so any component that correctly inherits one (an
+ * [AppIconButton] tint, a bare `Text`) fell back to `LocalContentColor`'s black default
+ * and rendered black-on-near-black. The story read as an empty rectangle while the
+ * component was in fact drawing perfectly. Stories must sit in the same content-color
+ * context as the screens they document, or they document a lie.
  */
 @Composable
 internal fun StoryHost(content: @Composable BoxScope.() -> Unit) {
-    Box(Modifier.fillMaxSize().background(__THEME_PREFIX__Colors.Background)) { content() }
+    Surface(
+        modifier = Modifier.fillMaxSize(),
+        color = __THEME_PREFIX__Colors.Background,
+        contentColor = __THEME_PREFIX__Colors.OnSurface,
+    ) {
+        Box(Modifier.fillMaxSize()) { content() }
+    }
 }

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewDaemon.kt

@@ -69,6 +69,11 @@ fun main(args: Array<String>) {
             put("ok", JsonPrimitive(true))
             put("pid", JsonPrimitive(ProcessHandle.current().pid()))
             put("port", JsonPrimitive(port))
+            // WHICH project this daemon serves. The port is machine-global, so a
+            // preview service that finds a healthy daemon here has no other way to
+            // tell "my project's daemon" from "another checkout's daemon on the
+            // same port" — and adopting the wrong one renders another app's screens.
+            put("previewsDir", JsonPrimitive(outRoot.absolutePath))
             put("reloadCount", JsonPrimitive(reloadCount.get()))
             put("reloadErrors", JsonPrimitive(reloadErrors.get()))
             put("reloadHooked", JsonPrimitive(reloadHooked))

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewHarness.kt

@@ -25,12 +25,16 @@ import __PACKAGE__.di.appModules
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Colors
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Theme
 import __PACKAGE__.presentation.theme.__THEME_PREFIX__Tokens
+import __PACKAGE__.presentation.theme.__THEME_PREFIX__TypeRamp
 import kotlinx.serialization.json.Json
 import kotlinx.serialization.json.JsonElement
+import kotlinx.serialization.json.JsonNull
 import kotlinx.serialization.json.JsonPrimitive
 import kotlinx.serialization.json.buildJsonArray
 import kotlinx.serialization.json.buildJsonObject
+import org.jetbrains.skia.Bitmap
 import org.jetbrains.skia.EncodedImageFormat
+import org.jetbrains.skia.Image
 import org.koin.core.context.startKoin
 import org.koin.dsl.module
 import java.io.File
@@ -189,7 +193,8 @@ internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
             }
             iterations++
         }
-        val data = image.encodeToData(EncodedImageFormat.PNG)
+        val framed = if (isComponentStory(entry.id)) cropToContent(image, scale) else image
+        val data = framed.encodeToData(EncodedImageFormat.PNG)
             ?: error("Skia failed to encode ${entry.id} as PNG")
         outFile.writeBytes(data.bytes)
     } finally {
@@ -197,6 +202,74 @@ internal fun renderPng(entry: ScreenPreview, outFile: File, scale: Float) {
     }
 }
 
+/**
+ * Component stories are the ONLY previews cropped. A screen's frame is part of
+ * what is being reviewed (insets, bottom bar, where content sits on the page),
+ * so screens keep the full phone viewport. A component story is the opposite:
+ * a 48 dp button rendered on an 891 dp canvas is 3% component and 97% empty
+ * background, which is what made the Components gallery read as broken.
+ */
+private fun isComponentStory(id: String) = id.startsWith("component.")
+
+/**
+ * Tightest rectangle whose pixels differ from the frame's own background,
+ * plus one page-padding gutter. Measured from the PIXELS, not the semantics
+ * tree — decoration with no semantics (a ring, a shimmer, a divider) is part
+ * of the component and must not be cropped off.
+ *
+ * The background reference is the top-left pixel: [StoryHost] paints the whole
+ * canvas in the Background token before drawing, so that corner is background
+ * by construction. Two honest fallbacks, never a wrong crop:
+ *   - nothing differs (a story whose content IS the background color) -> the
+ *     full frame, uncropped;
+ *   - a degenerate box (under 8 px on a side) -> the full frame too.
+ * Cropping is lossless: the kept pixels are the rendered pixels, untouched.
+ */
+private fun cropToContent(image: Image, scale: Float): Image {
+    val bitmap = Bitmap.makeFromImage(image)
+    val info = bitmap.imageInfo
+    val w = info.width
+    val h = info.height
+    val bpp = info.bytesPerPixel
+    if (w <= 0 || h <= 0 || bpp <= 0) return image
+    // One bulk read, then scan in memory — getColor(x, y) per pixel would be
+    // ~1.5M native calls per story.
+    val rowBytes = w * bpp
+    val pixels = bitmap.readPixels(info, rowBytes, 0, 0) ?: return image
+    fun samePixelAsOrigin(offset: Int): Boolean {
+        for (b in 0 until bpp) if (pixels[offset + b] != pixels[b]) return false
+        return true
+    }
+    var minX = w
+    var minY = h
+    var maxX = -1
+    var maxY = -1
+    for (y in 0 until h) {
+        val row = y * rowBytes
+        for (x in 0 until w) {
+            if (!samePixelAsOrigin(row + x * bpp)) {
+                if (x < minX) minX = x
+                if (y < minY) minY = y
+                if (x > maxX) maxX = x
+                if (y > maxY) maxY = y
+            }
+        }
+    }
+    if (maxX < 0 || maxY < 0) return image
+    val gutter = (__THEME_PREFIX__Tokens.PaddingPage.value * scale).toInt().coerceAtLeast(1)
+    val left = (minX - gutter).coerceAtLeast(0)
+    val top = (minY - gutter).coerceAtLeast(0)
+    val right = (maxX + 1 + gutter).coerceAtMost(w)
+    val bottom = (maxY + 1 + gutter).coerceAtMost(h)
+    val cw = right - left
+    val ch = bottom - top
+    if (cw < 8 || ch < 8) return image
+    val croppedInfo = info.withWidthHeight(cw, ch)
+    val croppedRowBytes = cw * bpp
+    val cropped = bitmap.readPixels(croppedInfo, croppedRowBytes, left, top) ?: return image
+    return Image.makeRaster(croppedInfo, cropped, croppedRowBytes)
+}
+
 /** The declared design-system catalog — generated FROM the theme objects, so it can't drift. */
 internal fun designSystemCatalog(): String {
     val pretty = Json { prettyPrint = true }
@@ -237,6 +310,23 @@ internal fun designSystemCatalog(): String {
             put("RadiusModal", dp(__THEME_PREFIX__Tokens.RadiusModal))
             put("RadiusInput", dp(__THEME_PREFIX__Tokens.RadiusInput))
         })
+        // The type ramp, published from the SAME data the Typography factory
+        // builds its styles from (presentation/theme/Typography.kt) — the
+        // console's Design language page renders the ramp from this block, so a
+        // ramp that ships and a ramp that is documented cannot diverge. Font
+        // family is deliberately absent: it resolves through @Composable Font()
+        // and is not derivable here, and a guessed name would be a fabrication.
+        put("typography", buildJsonArray {
+            __THEME_PREFIX__TypeRamp.forEach { spec ->
+                add(buildJsonObject {
+                    put("name", JsonPrimitive(spec.name))
+                    put("weight", JsonPrimitive(spec.weight))
+                    put("size", JsonPrimitive("${spec.sizeSp}sp"))
+                    put("lineHeight", JsonPrimitive("${spec.lineHeightSp}sp"))
+                    put("tracking", spec.tracking?.let { JsonPrimitive("${it}sp") } ?: JsonNull)
+                })
+            }
+        })
     }
     return pretty.encodeToString(JsonElement.serializer(), doc)
 }

package/template/composeApp/src/desktopMain/kotlin/com/example/app/inspector/PreviewSemanticsJson.kt

@@ -19,7 +19,8 @@ import kotlin.math.roundToInt
  * inspector contract (schemaVersion 1, source "headless-jvm"). Every node carries pixel,
  * root-relative `bounds` and a (possibly empty) `children` array; testTag / text /
  * contentDescription / designToken are nullable; `role` / `clickable` / `disabled` are the
- * additive interaction fields.
+ * additive interaction fields, and `size` is the additive full-composed-size field (see
+ * [sizeJson]).
  *
  * This dumper reads THIS project's [DesignTokenKey], so the resolved design tokens the
  * component kit self-reports (Modifier.designToken) appear in the dump — which is what
@@ -54,10 +55,22 @@ object PreviewSemanticsJson {
         put("clickable", JsonPrimitive(node.config.contains(SemanticsActions.OnClick)))
         put("disabled", JsonPrimitive(node.config.contains(SemanticsProperties.Disabled)))
         put("bounds", node.boundsJson())
+        put("size", node.sizeJson())
         put("designToken", node.designTokenJson())
         put("children", buildJsonArray { node.children.forEach { add(nodeToJson(it)) } })
     }
 
+    /**
+     * Full composed (UNCLIPPED) size. `bounds` is the visible slice after ancestor clipping —
+     * a scroll container's fold truncates it — while `size` is what the node actually
+     * measures. Additive contract field (consumers treat it as optional); the a11y audit
+     * judges touch targets on it so a fold-clipped list row is never a false violation.
+     */
+    private fun SemanticsNode.sizeJson(): JsonObject = buildJsonObject {
+        put("width", JsonPrimitive(size.width))
+        put("height", JsonPrimitive(size.height))
+    }
+
     private fun SemanticsNode.boundsJson(): JsonObject {
         val rect = boundsInRoot
         return buildJsonObject {

package/template/composeApp/src/desktopTest/kotlin/com/example/app/conformance/ArchitectureConformanceTest.kt

@@ -340,6 +340,44 @@ class ArchitectureConformanceTest {
         )
     }
 
+    // SPEC: ARCH-12
+    @Test
+    fun `ARCH-12 sample fixtures never cross into production wiring`() {
+        // The UI-first pattern's hazard gate. A stateless screen may default its own state
+        // parameter to a `sample*` fixture — that same-file default IS the preview seam —
+        // and the preview registry / stories / tests (desktopMain, commonTest) render it
+        // freely. But the moment ANOTHER commonMain file references the fixture (a nav
+        // host resolving entities from sample data, a repository seeding from it), fake
+        // data is driving production behavior. Proven drift: the Fuelled dogfood run's
+        // AppNavHost read `sampleFoods.firstOrNull { it.id == foodId }` for a real route.
+        val sampleDecl = Regex("""\bval\s+(sample[A-Z][A-Za-z0-9]*)""")
+        val declarations = mutableMapOf<String, File>() // symbol -> declaring file
+        for (file in sources(commonMain)) {
+            for (m in sampleDecl.findAll(file.readText())) declarations[m.groupValues[1]] = file
+        }
+        if (declarations.isEmpty()) return
+        val offenders = mutableListOf<String>()
+        for (file in sources(commonMain)) {
+            val lines = nonCommentLines(file)
+            for ((symbol, declaring) in declarations) {
+                if (file == declaring) continue
+                if (lines.any { Regex("""\b$symbol\b""").containsMatchIn(it) }) {
+                    offenders.add("${file.path} (references $symbol from ${declaring.name})")
+                }
+            }
+        }
+        if (offenders.isNotEmpty()) fail(
+            violation(
+                "ARCH-12", "a sample*/fixture symbol is never referenced outside its declaring file, " +
+                    "the preview registry, or test sources — sample data is a preview seam, not " +
+                    "production wiring.",
+                offenders.distinct(),
+                "wire the real path (repository → use case → ViewModel) and keep the sample only as " +
+                    "the stateless screen's default parameter.",
+            )
+        )
+    }
+
     // SPEC: SHELL-05
     @Test
     fun `SHELL-05 every non-shell nav destination wraps its content in BaseScreen`() {
@@ -353,7 +391,11 @@ class ArchitectureConformanceTest {
             ?: sources(commonMain).firstOrNull { under(it, "navigation") && it.readText().contains("composable(") }
             ?: return
         val text = navHost.readText()
-        val screenCall = Regex("""([A-Z][A-Za-z0-9]*Screen)\s*\(""")
+        // Both destination shapes: the plain `XScreen(...)` AND the UI-first seam's
+        // VM-backed `XRoute(...)` wrapper — keying on `Screen(` alone left every *Route
+        // destination uninspected, passing the gate vacuously (dogfood finding: the
+        // invariant held in Fuelled, but only by convention, not because this asserted it).
+        val screenCall = Regex("""([A-Z][A-Za-z0-9]*(?:Screen|Route))\s*\(""")
         // A call with only a trailing lambda has no paren — `BaseScreen { … }` — so match both.
         val baseScreenCall = Regex("""BaseScreen\s*[({]""")
         val allSources = sources(commonMain)

package/template/docs/ARCHITECTURE.md

@@ -281,6 +281,61 @@ of design values — no hardcoded `Color(0x…)` literals outside it. The regist
 components own the token call sites (declared once per component, correct everywhere it's
 used), so a screen almost never touches a token directly.
 
+### UI-first construction `[advisory, with one enforced hazard gate: ARCH-12]`
+
+Screens are built **UI-first**: a stateless composable over a plain state value, rendered in the
+preview gallery before any ViewModel or data layer exists. The pattern has four parts, and the
+fourth is a gate:
+
+1. **Stateless screen** — `XScreen(state, onEvent)`; it owns no data and calls no VM.
+2. **Preview seam** — the screen's state parameter defaults to a `sampleX` fixture declared in the
+   same file, so the preview registry renders it with zero DI. This is what lets a screen exist —
+   and be judged, styled, and approved — before its vertical slice is built.
+3. **Wiring obligation** — the sample default is scaffolding, not a destination. The screen ends up
+   driven by a VM-backed `XRoute` wrapper (the actual nav destination; `SHELL-05` inspects both
+   suffixes), and the slice follows the exemplar layer-for-layer.
+4. **The hazard → enforced.** Sample data must never leak into production wiring: a `sample*`
+   symbol is referenced only in its declaring file (the seam), the preview registry/stories, and
+   tests. `ARCH-12` fails the lane on any other `commonMain` reference — a nav host resolving
+   entities from sample data is the proven failure mode this exists to stop.
+
+This pattern is why the genesis walk can lock the design system and distill the component registry
+*after* real screens exist — the visual artifacts are extracted from the product, not guessed ahead
+of it.
+
+### Component vocabulary `[governed — registry membership is judgment]`
+
+`presentation/components/` is the design-system registry — the shared vocabulary screens compose
+from. It is **distilled from real screens, not authored before them**: build the screens, then
+promote the primitives that pass the bar. What earns a place is **judgment, not a reuse count** —
+govern a composable when it (1) encodes a *design-system decision* (how the product presents
+something — a progress ring, a metric tile, a chip) rather than *how one screen arranges its data*;
+(2) is a *stable, obvious* shape, not a speculative one; (3) would cause visible inconsistency if
+each screen reinvented it; or (4) centralizes a cross-cutting concern worth enforcing once (a11y,
+tokens — as `AppButton` does the 48 dp target). Keep it **feature-local** when it is a one-screen
+composition, carries feature/domain logic, or genuinely differs from its neighbors. Reuse count is
+a *signal* (≥2 real uses is strong evidence), never the rule — a single-use stable primitive is
+still a component; a five-times-duplicated set of *different* shapes is not.
+
+Two guardrails are first-class:
+
+- **Do not force reuse.** Cramming genuinely-different composables into one over-parameterized
+  component (leading slot + trailing slot + toggle + chevron + value…) is a *worse* antipattern
+  than duplication — god-components with leaky parameter lists and hidden coupling. "Both are rows"
+  is not a reason to unify; only near-identical shape **and** behavior is. **When in doubt, keep
+  them separate.**
+- **A domain-named component is a smell.** A composable named for a domain concept (`MacroTag`) is
+  a feature decision in design-system clothes — generalize it to a real primitive (`Tag` = label +
+  value + colour) or keep it local. Never admit domain vocabulary to the registry. Brand marks
+  (`presentation/brand/`) are their own category, governed separately.
+
+Any conformance gate here flags **only** true near-identical duplication or re-invention of an
+existing registry component — never "you have two rows, unify them" (that would push toward the
+antipattern above), and it never *forces* a promotion. Division of labor: the **agent makes the
+rubric calls** — classifies each screen composable, promotes or keeps local, with reasoning — and
+the **human governs at the Components approval**, which is exactly what that gate exists for.
+Nothing the agent promotes is law until the approval signs it.
+
 ### Automation reachability `[enforced: ARCH-04, ARCH-11, SHELL-04]`
 
 Every screen root and interactive element is testTag-addressable

package/template/docs/TESTING.md

@@ -54,6 +54,13 @@ Maestro flows (`qa/e2e/*.yaml`) cover boot + bottom-nav — install the free CLI
 (`curl -fsSL "https://get.maestro.mobile.dev" | bash`). Selectors go by **testTag** (`id:` —
 surfaced as resource-ids via `TestTagAutomation`), never by display text. One flow per
 journey, spec-clause cited; keep the E2E tip small — behavior belongs in unit tests.
+
+**Settle rule:** an assertion that follows an interaction triggering an async state change
+(typing a search query, a toggle that persists, a load) must be an `extendedWaitUntil`, not
+a bare `assertVisible` — the ViewModel round-trip passes through a brief Loading arm that a
+lane-loaded emulator stretches, and asserting into that transition is a false red (a real
+one: a search assert that passed standalone failed in-lane behind a 33s type gap). Bare
+asserts are for static post-navigation elements only.
 <!-- <<< cmp:feature e2e -->
 
 ## The verify lane

package/template/qa/e2e/smoke.yaml

@@ -6,6 +6,12 @@
 # AppShell.kt's navItemTag (lowercase, non-[a-z0-9] runs collapsed to "_", trimmed);
 # keep these ids in sync with it if the configured tabs change.
 #
+# SETTLE RULE for the behaviour steps you add: any assertion that follows an interaction
+# triggering an async state change (search input, a toggle that persists, a load) must use
+# extendedWaitUntil — the ViewModel round-trip passes through a brief Loading arm, and a
+# lane-loaded emulator stretches that window past a bare assert's patience (a real false
+# red from the field). Bare assertVisible is for static post-navigation elements only.
+#
 # Run:  maestro test qa/e2e/smoke.yaml      (device/emulator attached)
 # The verify lane's e2eSmoke step runs this automatically when maestro + a device are present.
 appId: __PACKAGE__

package/template/qa/lib/a11y.mjs

@@ -5,7 +5,13 @@
 //   touch-target-too-small — a clickable node whose width or height is below the
 //                            minimum touch target (default 48px; the harness dumps
 //                            at density 1 so px == dp there — pass a different
-//                            minTouchTargetPx for device-density trees).
+//                            minTouchTargetPx for device-density trees). Judged on the
+//                            FULL composed size (the tree's additive `size` field) when
+//                            present: `bounds` is the visible slice after ancestor
+//                            clipping, so a list row bisected by a scroll fold reports
+//                            e.g. 371x36 while measuring 371x88 — a scroll-position
+//                            artifact, never an a11y defect. Trees without `size`
+//                            (older dumps) are judged on bounds, as before.
 //   missing-label          — a clickable node with no text, no contentDescription,
 //                            and no descendant text: nothing for a screen reader.
 // Rules (warnings):
@@ -61,17 +67,20 @@ export function auditA11y(tree, opts = {}) {
 
     let violated = false;
 
+    // Judge the FULL composed size when the dump carries it (`size` is unclipped; `bounds`
+    // is the visible slice after ancestor clipping — see the rule doc above). max() keeps
+    // the check honest either way: a genuinely small target is small in both.
     const b = node.bounds;
-    if (
-      b &&
-      typeof b.width === "number" &&
-      typeof b.height === "number" &&
-      (b.width < minTouchTargetPx || b.height < minTouchTargetPx)
-    ) {
+    const s = node.size;
+    const dim = (bv, sv) =>
+      Math.max(typeof bv === "number" ? bv : -1, typeof sv === "number" ? sv : -1);
+    const width = dim(b && b.width, s && s.width);
+    const height = dim(b && b.height, s && s.height);
+    if (width >= 0 && height >= 0 && (width < minTouchTargetPx || height < minTouchTargetPx)) {
       violations.push({
         ...entryBase,
         rule: "touch-target-too-small",
-        detail: `clickable node is ${b.width}x${b.height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
+        detail: `clickable node is ${width}x${height}px; minimum touch target is ${minTouchTargetPx}x${minTouchTargetPx}px`,
       });
       violated = true;
     }

package/template/qa/lib/approvals.mjs

@@ -10,10 +10,13 @@
 //
 // Three concerns, kept separable:
 //   1. The REGISTRY (`listGovernedArtifacts`) — artifact id -> resolved file list, in
-//      GENESIS-FLOW-DESIGN.md §1 order: intent(0), design-system(1), architecture(2),
-//      components(3), exemplar-feature(4), exemplar-spec(5), then one
+//      GENESIS-FLOW-DESIGN.md §1 order: intent(0), architecture(1), exemplar-spec(2),
+//      exemplar-feature(3), design-system(4), components(5), then one
 //      `feature-spec:<name>` (6+) per non-base, non-exemplar spec file present in
-//      specs/ right now. The exemplar (feature 4/5) is CONFIGURABLE — see
+//      specs/ right now. (Spec-first: the exemplar's clauses are confirmed before the
+//      slice is built. UI-first: design system + components are distilled from the
+//      real screens, so they lock after the exemplar.) The exemplar (2/3) is
+//      CONFIGURABLE — see
 //      `getExemplarFeature`/`resolveExemplarNames` below — defaulting to `home` so
 //      every ledger written before this config key existed keeps meaning what it
 //      meant. The registry is recomputed on every call — it reflects the tree as it
@@ -235,9 +238,17 @@ function listComponentFiles(root) {
 
 /**
  * The governed-artifact registry, resolved against the project at `root` right
- * now (GENESIS-FLOW-DESIGN.md §1 order: intent(0), design-system(1),
- * architecture(2), components(3), exemplar-feature(4), exemplar-spec(5), then one
- * feature-spec:<name> (6+) per non-base, non-CONFIGURED-exemplar spec present).
+ * now. GENESIS-FLOW-DESIGN.md §1 definition order — two ordering principles,
+ * one per artifact kind (the dogfooding-run correction):
+ *   BEHAVIORAL artifacts are SPEC-FIRST — the exemplar's clauses are proposed
+ *   and human-confirmed BEFORE the slice is built (exemplar-spec precedes
+ *   exemplar-feature, matching add-feature's discipline).
+ *   VISUAL artifacts are UI-FIRST — the design system and component vocabulary
+ *   are distilled FROM the real screens, so they lock AFTER the exemplar
+ *   exists (a provisional palette carries the build until then).
+ * Order: intent(0), architecture(1), exemplar-spec(2), exemplar-feature(3),
+ * design-system(4), components(5), then one feature-spec:<name> (6+) per
+ * non-base, non-CONFIGURED-exemplar spec present.
  *
  * `complete: false` marks an artifact whose kotlin-rooted files could NOT be
  * resolved (unresolvable package — raw template / pre-stamp tree). Such an
@@ -258,16 +269,6 @@ export function listGovernedArtifacts(root) {
     complete: true,
   });
 
-  artifacts.push({
-    id: "design-system",
-    label: "Design system (presentation/theme/Theme.kt, Tokens.kt)",
-    files: [
-      kotlinFile(root, "commonMain", "presentation/theme/Theme.kt"),
-      kotlinFile(root, "commonMain", "presentation/theme/Tokens.kt"),
-    ].filter(Boolean),
-    complete: packageResolved,
-  });
-
   artifacts.push({
     id: "architecture",
     label: `Architecture + structure (${ARCHITECTURE_SPEC_REL} + ${ARCH_DOC_REL_PATH}, generated sections stripped)`,
@@ -279,20 +280,22 @@ export function listGovernedArtifacts(root) {
     complete: true,
   });
 
-  artifacts.push({
-    id: "components",
-    label: "Components (presentation/components/*.kt)",
-    files: listComponentFiles(root),
-    complete: packageResolved,
-  });
-
   const { f: exemplarF, F: exemplarF_Pascal, E: exemplarE } = resolveExemplarNames(root);
   const exemplarSpecRel = `specs/${exemplarF}.spec.md`;
   const exemplarKotlinFiles = exemplarKotlinFileSet(exemplarF_Pascal, exemplarF, exemplarE);
 
+  // Spec-first: the exemplar's behavior clauses are confirmed BEFORE the slice
+  // is built — the definition order is the discipline, not just a display order.
+  artifacts.push({
+    id: "exemplar-spec",
+    label: `Exemplar spec (${exemplarSpecRel})`,
+    files: [exemplarSpecRel],
+    complete: true,
+  });
+
   artifacts.push({
     id: "exemplar-feature",
-    label: `Exemplar feature (${exemplarF} — the 11-file set the stamper clones)`,
+    label: `Exemplar feature (${exemplarF} — the file set the stamper clones)`,
     files: [
       ...exemplarKotlinFiles.map((f) => kotlinFile(root, f.sourceSet, f.rel)).filter(Boolean),
       exemplarSpecRel,
@@ -300,11 +303,24 @@ export function listGovernedArtifacts(root) {
     complete: packageResolved,
   });
 
+  // UI-first: the design system LOCKS on the real exemplar (candidates render on
+  // real screens, never stubs), and the component vocabulary is DISTILLED from
+  // those screens — both follow the exemplar in the definition order.
   artifacts.push({
-    id: "exemplar-spec",
-    label: `Exemplar spec (${exemplarSpecRel})`,
-    files: [exemplarSpecRel],
-    complete: true,
+    id: "design-system",
+    label: "Design system (presentation/theme/Theme.kt, Tokens.kt)",
+    files: [
+      kotlinFile(root, "commonMain", "presentation/theme/Theme.kt"),
+      kotlinFile(root, "commonMain", "presentation/theme/Tokens.kt"),
+    ].filter(Boolean),
+    complete: packageResolved,
+  });
+
+  artifacts.push({
+    id: "components",
+    label: "Components (presentation/components/*.kt)",
+    files: listComponentFiles(root),
+    complete: packageResolved,
   });
 
   const specsDir = path.join(root, "specs");