mantra-kmp/docs/material-design-conformance.md

# Bringing the UI in line with Material Design 3

What the M3 foundations actually require, where this app's 43 screens stand
against them today, and a phased order of work that makes each phase mechanical
by the time it starts.

The app already builds on Material 3 — `compose-material3:1.10.0-alpha05`, a
generated `ColorScheme`, `Scaffold`/`TopAppBar`/`ListItem` throughout. What is
missing is not the library. It is that **the design decisions live at the call
site rather than in the theme**, so there is no single place to change and no
way to check whether a screen conforms. Every phase below moves one class of
decision out of 18,000 lines of screen code and into something a test can read.

Sources are the current foundations pages on <https://m3.material.io/foundations>,
read September 2026 — after the May 2026 revision that renamed window size
classes to breakpoints and published the spacing system as tokens. Numbers
quoted here are from those pages, not from memory of older M3.

## What the spec asks for

### The seven foundations

`/foundations` lists seven areas. Each maps onto something concrete in this
codebase:

| foundation | what it governs | where it lands here |
|---|---|---|
| Accessibility | contrast, target size, labels, focus order, structure | `Icon` labels, `.clickable` targets, colour pairings, keyboard flow on desktop |
| Content design | UX writing, sentence case, alt text, global writing | 334 string literals in composables |
| Customizing Material | brand colour through the role system, dynamic colour | `Color.kt`, `Theme.kt`, `BluePill`/`RedPill` |
| Design tokens | style values named by role, never hardcoded | `10.dp` × 132, `20.dp` × 115 |
| Interaction states | enabled/disabled/hover/focus/press/drag, state layers | `Clickable.kt`, custom `Card` colours |
| Layout | breakpoints, panes, grids, spacing, bidirectionality | one phone layout on three platforms |
| Material A-Z | shared vocabulary | naming in this document |

### The numbers

**Breakpoints** (renamed from window size classes; apply to Android and web,
and are the right vocabulary for the desktop target too):

| breakpoint | width | panes | navigation |
|---|---|---|---|
| Compact | under 600dp | 1 | navigation bar, modal expanded rail |
| Medium | 600–839dp | 1 recommended, 2 possible | collapsed navigation rail |
| Expanded | 840–1199dp | 2 recommended | collapsed or standard expanded rail |
| Large | 1200–1599dp | 2 recommended | standard expanded rail |
| Extra-large | 1600dp+ | up to 3 | standard expanded rail |

Two rules from the same page are easy to miss and both bite here: *"across all
breakpoints, adjust margins and type styles to keep text between 40–60
characters per line"*, and *"don't use two panes in medium layouts with high
information density"*.

**Spacing.** The system is an 8dp scale where `space100 = 8dp`. Material defines
only the recommended stops, including sub-8 nested units:

| token | dp | | token | dp |
|---|---|---|---|---|
| space0 | 0 | | space250 | 20 |
| space25 | 2 | | space300 | 24 |
| space50 | 4 | | space400 | 32 |
| space75 | 6 | | space450 | 36 |
| space100 | 8 | | space500 | 40 |
| space125 | 10 | | space600 | 48 |
| space150 | 12 | | space700 | 56 |
| space175 | 14 | | space800 | 64 |
| space200 | 16 | | space900 | 72 |

Spacing has three categories with different rules: **padding** (inside an
element), **gap** (between elements in a container), **margin** (outside an
element). The spec is explicit that margins are a last resort — *"define padding
and gaps on the parent container"*, *"avoid defining margins on child
elements"*. The note that these tokens are Compose-only is in our favour: this
is a Compose app.

**Targets.** Touch targets at least 48×48dp; pointer targets at least 44×44dp;
targets separated by 8dp or more. An icon may be 24dp while its target is 48dp —
the padding is part of the target, not decoration.

**Contrast.** Small text at least 4.5:1 against its background; large text
(14pt bold / 18pt regular and up) and graphics at least 3:1. Disabled states are
exempt. Clustered non-text elements — a group of buttons — need 3:1 between
container and background; a standalone element such as a FAB does not.

**State layers.** A fixed overlay in the content colour: hover 8%, focus 10%,
press 10%, drag 16%, disabled 38%. State layer 40dp, interactive target 48dp.

### What the May 2026 revision changed

Worth knowing before reading older guidance or older code:

- window size class → **breakpoint**, and there are now five, not three;
- responsive design → **adaptive design**;
- the spacing system is published as tokens, on an 8dp scale, Compose-first;
- the **layout scaffold** (bars, rails, panes, rulers) is the recommended
  structure, replacing hand-rolled adaptive branches;
- there are now expressive spacing guidelines, and a stated position that
  spacing carries product personality rather than being neutral.

## Where this app stands

Counts below are over `composeApp/src/commonMain/kotlin/press/mantra/compose/ui`
unless stated. Phase 0 turns them into a script so they can be re-run.

### The theme is incomplete, and two entry points bypass it

`Color.kt` defines six schemes — light, dark, and medium/high contrast variants
of each — and `Theme.kt` wires four of them into `lightColorScheme`/
`darkColorScheme`. That is more than most apps do, and the generated pairs hold
up: every `onX`-on-`X` pair in every scheme clears 4.5:1, the tightest being
`onPrimaryContainer` on `primaryContainer` at 4.61:1 (light) and 4.56:1 (dark).

Three gaps:

1. **Twelve roles are never set.** `primaryFixed`, `primaryFixedDim`,
   `onPrimaryFixed`, `onPrimaryFixedVariant` and the secondary/tertiary
   equivalents are absent from both schemes, so they fall through to
   `ColorLightTokens.PrimaryFixed` — `PaletteTokens.Primary90`, which is
   `#EADDFF`. Any component reaching for a fixed role paints **Material baseline
   lavender** into a monochrome app, in light and dark alike. Nothing uses them
   today; the trap springs the first time an expressive component does.

2. **The medium and high contrast schemes are dead code.** All four are declared
   `private val`; `TorchTheme` only ever selects `darkScheme` or `lightScheme`.
   There is no plumbing to the platform's contrast setting, so the two schemes
   that would honour it are unreachable. The accessibility foundation's first
   principle is *honour individuals* — *"supporting varying preferences and
   choices"* — and the values to do it are already sitting in the file.

3. **`AuxTypography` is `Typography()`** — the baseline, in package
   `com.example.ui.theme`, in a file otherwise unused. No shapes and no motion
   scheme are passed to `MaterialTheme` at all.

Two entry points render outside the theme:

- `composeApp/src/jvmMain/kotlin/press/mantra/desktop/Main.kt:126` —
  `PassphraseGate` sits in the `else` branch beside `MantraApp`, so it composes
  under the **default** `MaterialTheme`. Its `MaterialTheme.colorScheme.error`
  and `typography.headlineSmall` are baseline M3, not this app's. It is the
  first screen a desktop user sees.
- `Profile.kt:183` and 50 other `@Preview` bodies wrap in `TorchTheme` by hand,
  which is correct, but there is no preview that exercises dark, high-contrast
  or a wide window — so nothing catches the two problems below.

### Colour is decided at the call site, and one pairing is invisible

Eleven sites hardcode a `Color`, and 14 more derive one with `.copy(alpha = …)`.
Measured against the light scheme:

| site | pairing | ratio | needs |
|---|---|---|---|
| `ProposalListScreen.kt:228` | `ListItem` headline (`onSurface`) on a `Card` of `primaryContainer` | **1.00:1** | 4.5:1 |
| `HomeScreen.kt:113` | `titleContentColor = primary` on `containerColor = primaryContainer` | **1.22:1** | 4.5:1 |
| `ArticleCard.kt:67`, `QuotedNote.kt:101`, `QuotedAddressableNote.kt:62`, `LiveStreamCardContent.kt:42` | `onSurfaceVariant.copy(alpha = 0.5f)` on surface | 2.49:1 | 4.5:1 |
| `CreateProfileScreen.kt:329` | `Color.DarkGray` on `BluePill` | 2.90:1 | 4.5:1 |
| `ArticleCard.kt:154` | `onSurfaceVariant.copy(alpha = 0.7f)` on surface | 3.96:1 | 4.5:1 |
| `CreateProfileScreen.kt:311` | `Color.White` on `RedPill` (75% alpha over surface) | 3.50:1 | 4.5:1 |
| `LiveStreamCardContent.kt:86` | `Color.White` on `#E53935` | 4.23:1 | 4.5:1 |

The first is the worst and is worth spelling out, because it is not obvious from
reading the call:

```kotlin
Card(
    onClick = onClick,
    colors = if (proposal.awaitsYou) {
        CardDefaults.cardColors(
            containerColor = MaterialTheme.colorScheme.primaryContainer
        )
    } else {
        CardDefaults.cardColors()
    }
) {
    ListItem(
        colors = ListItemDefaults.colors(containerColor = Color.Transparent),
```

`cardColors(containerColor = …)` does derive `contentColor = contentColorFor(…)`,
so `LocalContentColor` inside the card is right. But `ListItem` does not read
`LocalContentColor` — its headline colour comes from `ListTokens.ItemLabelTextColor`,
which is `onSurface`, and the call site overrides only `containerColor`. In the
light scheme `onSurface` and `primaryContainer` are both `#1B1B1B`. **The
proposals that await your signature are the ones rendered invisible.**

`BluePill` and `RedPill` are brand colours held as raw `Color` values outside the
role system. The customization foundation's whole argument is that a brand colour
becomes a *source colour* generating a role family — `container`/`on`/
`onContainer` — so contrast is handled and dynamic colour still works.

Note what is *not* a finding: `outlineVariant` at 1.61:1 against surface, and
`secondaryContainer` at 1.65:1. M3's own baseline is in the same range, and the
3:1 rule is for clustered interactive containers, not dividers or tonal
surfaces. `onSurface.copy(alpha = 0.38f)` in `TranslationChapterScreen.kt:203`
is the specified disabled opacity and is exempt.

### Spacing is a habit, not a system

527 `.dp` literals. 419 land on a defined spacing stop, 19 are dimensions rather
than spacing (a hairline border, an avatar, an image height), and 89 are off-scale:

```
  5dp × 10   15dp × 14   18dp × 1   22dp × 1   30dp × 2
 35dp ×  3   50dp × 53   55dp ×  2   70dp × 2   75dp × 1
```

The off-scale values are the smaller half of the problem. `10.dp` (132 uses) and
`20.dp` (115) — the two dominant values — *are* on the scale, as `space125` and
`space250`, so a sweep for off-grid numbers would change almost nothing. What is
wrong is that **nothing records which of padding, gap or margin any of these
is**, so there is no way to adapt them per breakpoint or density later, and no
way to tell a deliberate 15dp from a typo.

`Modifier.height(50.dp)` appears 49 times, almost always as a `Spacer` pushing
an empty or error message down the screen. It is the same three lines copied
into 16 files.

### Typography uses half the scale, weighted small

240 `MaterialTheme.typography.*` reads, which is good — only two `fontSize`
literals in the whole tree. The distribution is the problem:

```
labelMedium 49   bodySmall 46   bodyLarge 41   bodyMedium 30   labelSmall 28
labelLarge  13   titleSmall 12  titleMedium 6  titleLarge 4    headlineSmall 4
headlineMedium 2 headlineLarge 2 displayMedium 1
```

`label*` roles are 92 of 240 uses. Labels are for component text — buttons,
tabs, chips — not for body copy or list content, and they are the smallest and
tightest roles in the scale. Reading a screen where `labelMedium` carries the
prose is the visual equivalent of everything being at the same pitch. Meanwhile
the three `display*` and three `headline*` roles carry 9 uses between them
across 43 screens, so almost nothing establishes hierarchy.

The pinned material3 ships **30** type roles, not 15 — every role has an
`…Emphasized` variant. Two are used (`labelSmallEmphasized`,
`labelLargeEmphasized`).

### Targets and labels are mostly right, with a countable set of exceptions

- 153 `Icon(` calls; 18 pass `contentDescription = null`. Some of those are
  correct (a decorative icon beside its own label should be null), but they have
  not been triaged.
- 45 `IconButton` and 5 `FilledIconButton` — these enforce 48dp themselves.
- 33 bare `Modifier.clickable`, which does not. Two are text-sized:
  `ArticleCard.kt:143` makes an author name clickable, and `LinkPreview.kt:122`
  a `Text` with 2dp vertical padding. Both are around 20dp tall.
- `Clickable.kt` — a vendored ACINQ helper, still in package
  `com.machankura.compose.ui.composable.widgets.buttons` — defaults to
  `internalPadding = PaddingValues(0.dp)` and `RectangleShape`, so every use
  starts below the minimum.
- Zero uses of `minimumInteractiveComponentSize()`.

91 `TextAlign.Center` and 128 `Alignment.CenterHorizontally`. Centring is the
default posture of this UI. The grids-and-spacing page asks the opposite for
lists and content: *"leading elements like thumbnails, avatars, or icons should
always be aligned"*, and the rulers section builds hierarchy from a shared
leading edge. Centred body text also loses the 40–60 character line the
breakpoints page asks for, because there is no ruler to hold it to.

Bidirectionality is, unexpectedly, in decent shape: 23 uses of
`padding(horizontal =`/`vertical =`, 6 of `start`/`end`, and no `left`/`right`
anywhere.

### Text cannot be translated

Two `stringResource` calls. 334 literal strings inside composables — 247
`text = "…"` and 87 `Text("…")`. `strings.xml` exists but holds Phoenix wallet
strings inherited from the fork, under `app_name` = "Machankura".

Capitalisation is title case throughout — roughly 45 distinct strings including
`"Edit Profile"`, `"Create Profile"`, `"New Chat"`, `"Sign In"`, `"Leave Group"`,
`"Key Package Management"`, `"Publish New Key Package"`. The style guide is
unambiguous: *"All text, including titles, headings, labels, menu items,
navigation components, app bars, and buttons should use sentence-style
capitalization."*

The app's top bar reads `"Torch"` while the window title reads `"Mantra"` and
`app_name` reads `"Machankura"`. Three names for one product.

### There is no feedback surface, and empty states are bare

Zero `Snackbar`, zero `SnackbarHost`, zero `rememberSnackbarHostState` — across
26 `Scaffold`s. There is one `AlertDialog` in the whole app. Every transient
outcome — a message sent, an invite failing, a key package published — has
nowhere to be reported.

The error state is `Text("Something went wrong")`, duplicated at 16 sites, and
`Text("No events were found")` at 5. **None of the 16 offers a retry.** No icon,
no explanation, no action. The content design foundation asks for the opposite:
*"emphasize the results of the user's potential action"*, *"tell users what will
happen … and how they can undo it"*.

Interaction states are the library's defaults, which is mostly correct — ripple,
hover and focus come free with `Button`, `Card`, `ListItem`. But the 33 bare
`.clickable` sites and `Clickable.kt` opt out of the shape and padding that make
a state layer legible, and nothing anywhere handles keyboard focus explicitly,
which the desktop target needs.

### One layout, three platforms

Two `BoxWithConstraints` in the entire tree, both inside
`ChatMessageListViewModel.kt`. No `WindowSizeClass`, no
`currentWindowAdaptiveInfo`, no `NavigationSuiteScaffold`, no
`ListDetailPaneScaffold`, no `NavigationBar`, no `NavigationRail`. The desktop
entry point says so itself:

```kotlin
// The layouts have only ever been exercised at phone widths. This is a starting size
// that does not immediately misrepresent them, not a considered desktop layout.
state = rememberWindowState(width = 480.dp, height = 900.dp),
```

Every one of the components needed is present in the pinned material3 —
`NavigationRailKt`, `ShortNavigationBarKt`, `WideNavigationRail`,
`AppBarRowKt`/`AppBarColumnKt`, `FloatingToolbarKt`, `ButtonGroupKt`,
`SplitButtonKt`, `LoadingIndicatorKt`, `MaterialShapesKt`, `MotionSchemeKt`,
`MaterialExpressiveTheme`. What is missing is the adaptive layer
(`material3-adaptive`), which is not declared in `libs.versions.toml`.

Insets are thin but not absent: `enableEdgeToEdge()` is called in
`MainActivity.kt:22`, and `Scaffold` consumes `ScaffoldDefaults.contentWindowInsets`
by default, so most screens are covered. Nine explicit inset uses exist —
`imePadding` appears once, in `SovereignWalletStartupScreen.kt`, though nine
screens and a dialog carry text fields.

### Nothing moves

One animation API in use, `animateScrollToPage`, twice. No `AnimatedVisibility`,
no `AnimatedContent`, no `Crossfade`, no `MotionScheme`, and no
`enterTransition`/`exitTransition` on any of the 43 navigation routes. Every
state change in the app is a hard cut.

### Summary

| area | state | phase |
|---|---|---|
| Theme completeness | 12 roles unset, 4 schemes unreachable, no shapes/motion | 1 |
| Colour at call sites | 7 pairings under threshold, one at 1.00:1 | 1, 3 |
| Spacing | 527 literals, no role recorded | 2 |
| Typography | 90/240 uses on `label*`, 2/30 roles emphasized | 1 |
| Targets & labels | 33 unguarded `.clickable`, 18 untriaged nulls | 3 |
| Content | 334 literals, title case throughout | 4 |
| Feedback | 0 snackbars, 16 duplicated error states, 0 retries | 5 |
| Adaptive | 1 layout, 5 breakpoints | 6 |
| Motion | 1 API, 0 transitions | 7 |

## The phases

Each phase lands on its own and leaves the app shippable. The order is chosen so
that each phase makes the next one mechanical rather than judgemental: tokens
before the call sites that consume them, the accessibility floor before the
adaptive work that would otherwise double the surface to fix, guard rails last
so they lock in real state rather than aspiration.

---

### Phase 0 — a baseline that can be re-measured

**Why first.** Every count in this document was produced by hand. If they cannot
be regenerated, the phases below have no acceptance criteria — only opinions.

**Built.**

1. **`docs/scripts/m3-audit.sh`** regenerates every count in "Where this app
   stands": the dp histogram split three ways, the typography role
   distribution, hardcoded colour sites, `.clickable` sites,
   `contentDescription = null`, string literals, snackbars, adaptive APIs. Each
   number that a phase is meant to move carries a **budget** at the top of the
   file, and `--check` exits 1 when one is exceeded. Budgets ratchet down in the
   same commit that earns the reduction; Phase 8 wires `--check` into CI, at
   which point raising one is the thing a reviewer looks for.

   Two counts it reports separately, because conflating them would overstate the
   problem: the twelve `*Fixed*` roles that fall through to Material baseline
   lavender, and `surfaceTint`, which is also unassigned but defaults to
   `primary` and is therefore correct. The `.dp` histogram likewise splits
   dimensions (a hairline border, an avatar) out of the off-scale count.

2. **`ColorSchemeContrastTest`** in `commonTest` — WCAG relative luminance from
   first principles, no Compose runtime, four assertions over all six schemes:
   every content role on its container at 4.5:1, `onSurface` on each of the
   seven tonal surfaces at 4.5:1, `outline` against every surface it is drawn on
   at 3:1, and `primary`/`error` containers against `surface` at 3:1. 4 tests,
   green.

   It walks the real `ColorScheme` objects, which is why `Theme.kt`'s six
   schemes moved from `private` to `internal`: rebuilding them in the test from
   `Color.kt` would assert the palette and miss the wiring, and a role pointed at
   its neighbour's value is exactly the slip that reads fine in review.

   Verified to bite. Nudging `onSurfaceVariantLight` from `#4C4546` to `#9C9496`
   — a plausible "soften the secondary text" edit — fails it with
   `light: onSurfaceVariant on surfaceVariant is 2.29:1`.

**Deliberately not asserted:** monotonicity across the contrast ladder. The
obvious invariant — high-contrast beats medium beats default, for every pair —
is false, and correctly so: ten pairs move the other way because a high-contrast
scheme darkens `surfaceContainerHighest` to separate it from `surface`, trading
ratio against `onSurface` for the separation that matters. The floor is the
invariant; the ladder is not.

**Risk:** none to the app. The only production change is a visibility keyword.

---

### Phase 1 — one theme, complete

**Why here.** Six of the nine problem areas are call sites reaching past a theme
that has nothing to offer them. Fill the theme and most later phases become
find-and-replace.

**Work.**

1. **Regenerate the scheme with all 49 roles.** Feed the existing source colours
   through Material Theme Builder and take the full export — the twelve
   `*Fixed*` roles and `surfaceTint` included. This removes the latent lavender.
   Keep the existing hex values for the roles already defined so nothing shifts
   visually; this phase adds, it does not restyle.

2. **Reach the contrast schemes.** *Built.* `TorchTheme` takes a `ThemeContrast`
   defaulted from a new `platformThemeContrast()` expect/actual, and the six-way
   selection table lives in common code as `appColorScheme`. The old
   `themeColorScheme` expect took four arguments and did both jobs; it splits into
   `platformThemeContrast()` and `dynamicColorScheme()`, each answering one narrow
   question, so the scheme table is in one place rather than three.

   Android reads `UiModeManager.getContrast()` (API 34+) and registers a
   `ContrastChangeListener`, because a contrast change does not restart the
   activity or arrive as a `Configuration` update — without the listener the new
   setting would wait for the next cold start, which is the case the setting
   exists for. iOS reads `UIAccessibilityDarkerSystemColorsEnabled` and observes
   `…StatusDidChangeNotification`; it is a boolean, so iOS never reports Medium.
   Desktop reads Windows' `win.highContrast.on` AWT desktop property and answers
   Standard on linux and macos, which is honest rather than complete — see
   "What this plan does not cover".

   Verified on an API 36 emulator with dynamic colour off: the `onPrimaryContainer`
   pixel of the "Skip for now" label reads `#848484` → `#A7A7A7` → `#D0D0D0` as the
   setting moves, the three declared values exactly, **without the app restarting**.

3. **Give the theme its other three slots.** *Built.* The expressive-vs-standard
   question was put to the product owner on 2026-09-08 and answered
   **expressive**, so `TorchTheme` calls `MaterialExpressiveTheme` with all four
   slots passed explicitly — colour, `MotionScheme.expressive()`, `MantraShapes`,
   `AuxTypography`. Explicitly, because `MaterialExpressiveTheme` would otherwise
   default them to `expressiveLightColorScheme()` and friends, which is Material's
   palette rather than this app's: the same class of accident as the twelve
   unassigned fixed roles.

   No visual change on the screens checked. The "Invite a Friend" button measures
   byte-identical before and after — same fill, same 357×… box — because the
   expressive default for a `Button` at default size matches the baseline in this
   version. What expressive buys is elsewhere: `LocalUsingExpressiveTheme`, the
   three increased shape steps, the fifteen `…Emphasized` type roles, and the
   components later phases need (button groups, split buttons, floating toolbars,
   wide navigation rails, `LoadingIndicator`).

   `MantraShapes` is baseline `Shapes()`, and `Shape.kt` records why: the corners
   hand-written across the tree already land on the scale — 4dp ×3 = `extraSmall`,
   12dp ×11 = `medium`, 16dp ×2 = `large`, and one 30dp that drifted two units off
   `extraLarge`. Nothing needs restyling; seventeen literals need migrating, later.

4. **Move and fill typography.** `Type.kt` moves from `com.example.ui.theme` to
   `press.mantra.compose.ui.theme`. It stays baseline-derived, but it becomes a
   real file with a stated font stack and a comment recording which roles carry
   what: `display*`/`headline*` for screen identity, `title*` for section and
   card headers, `body*` for prose, `label*` for component text only.

5. **Brand colours become roles.** `BluePill` and `RedPill` leave `Color.kt` as
   raw values and enter the scheme as extended colour families with their own
   `container`/`on`/`onContainer`. `CreateProfileScreen.kt:311` and `:329` then
   stop pairing them with `Color.White`/`Color.DarkGray` by eye.

6. **Wrap the desktop gate.** *Built.* `Main.kt` moves `TorchTheme` outside the
   `unlocked` branch, so `PassphraseGate` — the first screen a desktop user sees —
   stops composing under the default `MaterialTheme`. `MantraApp` keeps its own
   `TorchTheme`, so the unlocked branch is wrapped twice: android and ios enter
   through `MantraApp` and would lose the theme entirely if it moved out, and a
   second application of the same values costs one `CompositionLocalProvider`.

   `Type.kt` also left `com.example.ui.theme` for `press.mantra.compose.ui.theme`,
   which removes one of the three package namespaces the UI was living across.

**Done when** every role in `ColorScheme` is explicitly assigned in both
schemes; the contrast test still passes and now covers six schemes; `Type.kt`
lives under `press.mantra`; no composable in the tree renders under a default
`MaterialTheme`.

**Risk:** medium. Adding the fixed roles cannot regress anything (nothing reads
them), but switching to `MaterialExpressiveTheme` changes default component
shapes and sizes app-wide. Land it as its own commit so it can be reverted
alone.

---

### Phase 2 — spacing becomes a token

**Why here.** Phase 6 has to adapt spacing per breakpoint. It cannot adapt 527 literals.

**Built.** Three commits.

1. **The scale**, `Spacing.kt` — M3's eighteen stops on a composition local, with eight
   semantic names over them (`screenMargin`, `containerPadding`, `compactPadding`,
   `relatedGap`, `itemGap`, `sectionGap`, `emphasisGap`, `targetGap`) split along the
   spec's padding / gap / margin distinction, with exactly one margin. A `data class`
   rather than constants so that a wider instance at a larger breakpoint moves every
   value, including the semantic ones — asserted, because a semantic name holding a
   literal would stay behind and the layout would half-adapt.

   Reached through `MaterialTheme.spacing.containerPadding`, matching
   `MaterialTheme.colorScheme.primary`. `LocalSpacing.current` would have to be read into
   a local first and so could not appear inline in a `Modifier` chain; over 500 call sites
   that difference is what decides whether the scale gets used.

2. **The 89 off-grid values**, to their nearest stop — 5→4, 15→16, 30→32, 50→48. Largest
   move 2dp. Plus the one hand-written corner that was off the *shape* scale, 30dp against
   `extraLarge`'s 28, which is the drift a scale exists to stop.

3. **The remaining 353**, shape-aware: `padding + 8dp → compactPadding`,
   `padding + 16dp → containerPadding`, `gap + 4dp → relatedGap`, `gap + 8dp → itemGap`,
   everything else to the raw stop. 38 of 353 take a semantic name; the rest do not,
   because assigning one needs somebody to have read what the container is, and a name
   asserting a meaning the code lacks is worse than a stop asserting none.

**The audit was measuring the wrong thing, and this is where it showed.** It split
literals by *value* against an exemption list, and the split is not a property of the
value: 16dp is a spacing stop and a plausible icon size, and 50dp was a `Spacer` height in
52 places and a divider width in one. `docs/scripts/m3-spacing-positions.py` classifies by
**call shape** instead — brace-matching `padding(…)`, `PaddingValues(…)`,
`Arrangement.spacedBy(…)`, and a `.height()`/`.width()` whose enclosing call is `Spacer(`
— and `docs/scripts/m3-migrate-spacing.py` rewrites using the same parse, so the audit and
the migration agree by construction.

One value is exempt and says so at the site, through an inline `// m3-spacing-exempt:
<reason>` comment the classifier honours: a 128dp spacer reserving room to scroll the last
wallet clear of the window. Exemptions belong at the call site rather than in a list of
numbers in the tool.

**Done:** spacing positions 527 → **0**, 431 token reads, one reasoned exemption.
Verified on-device that nothing moved — the landing screen differs in 47 of 162,000
sampled pixels, 0.03%, all of them the status bar clock.

**Left for later:** 76 `.dp` in dimension positions — avatar sizes at 35/55/70/75dp, icon
sizes at 18/22dp. Sizing is a per-component question, and the plan puts component specs
after the adaptive phase. They are reported rather than exempted so the number stays
visible.

---

### Phase 3 — the accessibility floor

**Why here.** These are defects, not polish, and one of them hides the app's
most important rows. It goes before the adaptive work so the fixes are made once
rather than per breakpoint.

**Work.**

1. **Fix the seven measured pairings.** Take them in the order of the table.
   `ProposalListScreen.kt:228` needs the `ListItem` colours derived from the
   card's container, not left at `onSurface`:

   ```kotlin
   ListItemDefaults.colors(
       containerColor = Color.Transparent,
       headlineColor = contentColorFor(cardContainer),
       supportingColor = contentColorFor(cardContainer),
       leadingIconColor = contentColorFor(cardContainer),
   )
   ```

   `HomeScreen.kt:113` should drop its `topAppBarColors` override entirely —
   the default is `surface`/`onSurface` and is correct. The four
   `onSurfaceVariant.copy(alpha = 0.5f)` sites should use `onSurfaceVariant` at
   full opacity, which is already the role for secondary text.

2. **Extend the contrast test to call sites.** Every non-default
   `containerColor`/`contentColor` pairing in the tree gets a row in a table the
   test walks. This is what stops the class of bug rather than the instance —
   the `ListItem`-inside-`Card` case is invisible to a reviewer and obvious to
   an assertion.

3. **Guarantee the 48dp minimum.** The 33 bare `.clickable` sites either become
   a real component (`ArticleCard.kt:143`'s author name is a `TextButton`) or
   gain `Modifier.minimumInteractiveComponentSize()`. `Clickable.kt` gets it
   built in, moves into `press.mantra`, and its `RectangleShape` default is
   reconsidered so state layers read.

4. **Triage the 18 null content descriptions.** Each is either genuinely
   decorative — and then says so with `Modifier.clearAndSetSemantics {}` or a
   comment — or gets a label. The spec's rule for the labels themselves: name
   the purpose, not the picture, and never include the role ("Search", not
   "magnifying glass", never "Search button").

5. **Survive a large font scale.** Test every screen at 200% text size. The
   pattern to look for is a fixed `height` on a container of text; the 49
   `height(50.dp)` spacers are safe, but `Modifier.height(…)` around a `Text`
   is not.

6. **Keyboard flow for the desktop target.** Initial focus per screen, focus
   into and back out of the four `ModalBottomSheet`s and the `AlertDialog`, and
   `Tab` order verified on the nine screens with text fields. The foundations
   page is explicit that when a dialog opens, focus moves into it, and when it
   closes, focus returns to what opened it.

7. `imePadding()` on all nine text-field screens and the npub dialog, not one.

**Done when** the extended contrast test passes over both scheme families; the
audit reports zero unguarded `.clickable`; every `Icon` either has a description
or a recorded reason; and every screen is legible at 200% text scale.

**Risk:** low. Each fix is local and independently verifiable.

---

### Phase 4 — text the system can translate

**Why here.** It is the last phase that touches every file, and doing it after
Phase 2 means one pass over each file instead of two. It must precede Phase 6:
RTL is a breakpoint concern too, and there is no point testing a mirrored layout
against 334 English literals.

**Work.**

1. **Externalise all 334 strings** into `composeResources/values/strings.xml`,
   organised by screen. Clear out the inherited Phoenix wallet strings that
   nothing references, and settle `app_name`.
2. **Sentence case, everywhere.** "Edit profile", "Create profile", "New chat",
   "Sign in", "Leave group", "Key package management", "Publish new key
   package". Roughly 45 strings. Product names stay capitalised — which requires
   settling on one: Torch, Mantra or Machankura.
3. **Rewrite the destructive confirmations** to state consequences plainly.
   "Delete group" and "Leave group" currently offer a label and nothing else;
   the style guide wants the outcome and whether it can be undone.
4. **Alt text for meaningful images** — profile avatars, QR codes, artifact
   images — following the Phase 3 triage rule.
5. **Spell out abbreviations** in user-facing text. Protocol terms that are
   genuinely the domain (npub, NIP-05, relay) stay; incidental shortenings go.
6. Verify RTL by mirroring: the codebase has no `left`/`right` modifiers, so
   this should be confirmation rather than repair.

**Done when** the audit reports fewer than ten string literals in composables
(test data and previews), and no user-facing string uses title case.

**Risk:** low, high volume. Sentence-casing is the part most likely to draw
disagreement — settle the product name first, in one decision.

---

### Phase 5 — every screen has four states

**Why here.** It needs the tokens from Phase 2 and the strings from Phase 4, and
it produces the components Phase 6 will lay out.

**Work.**

1. **A `SnackbarHost` on every `Scaffold`**, and a single place to send messages
   to it. 26 scaffolds, zero hosts, is why there is nowhere to report an invite
   failing.
2. **One empty-state composable, one error-state composable.** Icon, message,
   and — for errors — a retry action. This replaces 16 copies of
   `Text("Something went wrong")` and 5 of `Text("No events were found")`, and
   absorbs the 49 spacer idioms. **None of the 16 sites offers a retry today**;
   each one is a dead end for the user.
3. **Loading gets the M3 component.** `LoadingDataIndicator` hardcodes an 80dp
   `CircularProgressIndicator` in `colorScheme.secondary`. The pinned material3
   ships `LoadingIndicator`, which is the expressive equivalent and themed.
4. **Audit the disabled states.** Five screens compute a FAB container colour
   by hand from a `can…` flag (`AddArtifactScreen.kt:156`,
   `AddChapterScreen.kt:149`, `AddDialectScreen.kt:128`,
   `TranslateChunkScreen.kt:131`, `AddTranslationArtifactVersionScreen.kt:155`).
   Passing `enabled` and letting the component apply the 38% state layer is both
   less code and the specified behaviour.
5. **Give buttons a hierarchy.** 31 `Button` and 27 `TextButton`, and nothing in
   between — no `FilledTonalButton`, `OutlinedButton` or `ElevatedButton`
   anywhere. Every screen therefore reads as either maximum or minimum emphasis.
   Assign one filled button per screen and demote the rest.

**Done when** every `Scaffold` has a host, every list has an empty state, every
error offers a retry, and no screen computes a disabled colour by hand.

**Risk:** low. Additive.

---

### Phase 6 — layouts that survive a wide window

**Why here.** It is the largest phase and the only one that cannot be done
mechanically. Everything above reduces its surface: tokenised spacing can be
swapped per breakpoint, and the states from Phase 5 are what fills a second
pane.

**Work.**

1. **Declare the adaptive dependency.** `material3-adaptive` is not in
   `libs.versions.toml`. Confirm which artifact publishes multiplatform for the
   pinned Compose Multiplatform 1.11.1 before planning around it — the desktop
   target makes this a real question, not a formality, and the answer decides
   whether steps 3–4 use the library scaffolds or a hand-rolled equivalent over
   `BoxWithConstraints`.

2. **Introduce the breakpoints** — compact / medium / expanded / large /
   extra-large, at 600 / 840 / 1200 / 1600dp. Wire the spacing scale from Phase
   2 to widen with them.

3. **Swap navigation.** Today there is no navigation component at all; screens
   are reached by route. Compact gets a navigation bar, medium and expanded a
   collapsed rail, large and extra-large an expanded rail. The spec's caution
   applies: swap only functionally equivalent components.

4. **Two panes where the content is list-and-detail.** The obvious candidates
   are chat rooms → messages, proposals → proposal detail, and artifacts →
   chapters. Chat is the one to do first and the one to be careful with: a
   message list is high-density content, and the breakpoints page says not to
   put two dense panes in a medium window.

5. **Hold text to 40–60 characters** by giving content a max width rather than
   letting it stretch, and revisit the 91 `TextAlign.Center` uses — start
   alignment is what gives the rulers something to align to.

6. **Give the desktop entry a real window size** and delete the comment that
   apologises for the current one.

7. Split the four composables out of `ChatMessageListViewModel.kt` — a 1,000+
   line view model holding UI is where the only two `BoxWithConstraints` in the
   app ended up, and it will not survive a pane split.

**Done when** every screen renders correctly at 400dp, 700dp, 1000dp, 1400dp and
1800dp; navigation swaps at the right thresholds; and the desktop build opens at
a size that reflects a considered layout.

**Risk:** high. This is the phase that changes what the app looks like. Take it
screen family by screen family — chat first, then proposals, then translation —
and keep each behind its own commit.

---

### Phase 7 — motion

**Why last of the build phases.** Motion describes relationships between
layouts. Animating the current layouts and then changing them in Phase 6 is
work done twice.

**Work.**

1. **Use the `MotionScheme` wired in Phase 1.** Every spec comes from
   `MotionSchemeKeyTokens` rather than a literal `tween`, so the whole app's
   feel is one decision.
2. **Navigation transitions.** All 43 routes use the default; the container
   transform between a list item and its detail screen is the one that carries
   the most meaning, and pairs naturally with the pane work from Phase 6.
3. **State transitions.** `AnimatedContent` between the loading, empty, error
   and loaded states that Phase 5 standardises — currently a hard cut in every
   case.
4. **Respect the reduced-motion preference** on every platform, and hold to the
   spec's own caution that the dragged state is deliberately low-emphasis.

**Done when** no state change in the app is an unannounced cut, and every
animation spec comes from the scheme.

**Risk:** low. Visible, easily tuned, easily reverted.

---

### Phase 8 — guard rails

**Why last.** These lock in what the previous phases achieved. Written earlier,
they would only fail.

**Work.**

1. **CI runs the Phase 0 audit** and fails on regression: no new `.dp` literals
   outside the theme, no new hardcoded `Color`, no new string literal in a
   composable, no new bare `.clickable`.
2. **The contrast test covers every scheme and every call-site pairing**, and is
   part of the normal test run. It is the only one of these that catches a bug a
   human reviewer reliably misses.
3. **Preview coverage per screen**: light, dark, high-contrast, 200% font scale,
   compact and expanded. There are already 51 previews to build on.
4. **A short conventions note in `CLAUDE.md`** — spacing comes from the scale,
   colour from the role, text from resources, targets are 48dp — so the rules
   are visible at the point of writing new code rather than at review.

**Done when** the audit and the contrast test both run in CI, and a change
violating any of the four rules fails.

**Risk:** none to the app; some friction for contributors, which is the point.

## Order and dependencies

| phase | depends on | touches | reversible alone |
|---|---|---|---|
| 0 — baseline | — | new files only | n/a |
| 1 — theme | 0 | `ui/theme/`, 2 entry points | yes |
| 2 — spacing | 1 | ~every file | yes, mechanically |
| 3 — a11y floor | 1 | ~25 sites | yes |
| 4 — content | 2 | ~every file | yes, mechanically |
| 5 — states | 2, 4 | 26 scaffolds, 21 sites | yes |
| 6 — adaptive | 2, 3, 5 | navigation, ~15 screens | no — plan per family |
| 7 — motion | 1, 5, 6 | navigation, state switches | yes |
| 8 — guard rails | all | CI, `CLAUDE.md` | yes |

Phases 1–5 can be worked in parallel by different people if 1 lands first;
6 cannot start until 3 and 5 are done, or the same screens get touched twice.

## What this plan does not cover

- **Which M3 is the target.** Phase 1 asks the expressive-vs-standard question
  and this document does not answer it. The 66 existing
  `ExperimentalMaterial3ExpressiveApi` opt-ins and the pinned alpha both point
  expressive, but it is a product decision with a visible outcome, and it should
  be made deliberately rather than inherited from an import.
- **Whether dynamic colour should keep overriding the brand.** `TorchTheme` defaults
  `dynamicColor = true`, and on Android 12+ that wins unconditionally — so on
  essentially every current Android device, none of the six schemes below is used
  and the app renders in whatever the user's wallpaper produced. Verified on an API
  36 emulator: the app paints Material lavender until dynamic colour is switched
  off, at which point the black-and-gold brand appears. M3's customization
  foundation treats this as a developer choice, and applying it selectively — a
  profile screen, say — is the usual answer for an app with a brand. Deciding it is
  a product call, not a conformance one, and it is why phase 1's contrast work is
  reachable today only on Android below 12, on iOS and on desktop. On Android 14+
  with dynamic colour on, the platform honours contrast itself.
- **Whether the monochrome palette is right.** The scheme's `primary` is pure
  black in light and near-white in dark, with the entire tertiary family a copy
  of primary. That is a defensible choice for this product and it passes
  contrast. It is also why `HomeScreen`'s app bar override collapsed to 1.22:1 —
  a monochrome scheme has no slack. This plan fixes the call sites; it does not
  propose a repalette.
- **Component-level specs.** The foundations are the scope. The per-component
  pages — button sizes, card variants, list item densities — are a second pass,
  best taken after Phase 6 settles which components are used where.
- **iOS.** The ios targets only build on a mac (see `jvm-target.md`), so nothing
  here has been verified on the platform whose HIG asks for 44dp targets rather
  than 48dp. M3 notes the difference; this plan assumes 48dp everywhere.
- **The three package namespaces.** `press.mantra`, `com.example.ui.theme` and
  `com.machankura.compose` all hold live UI code. Phase 1 moves `Type.kt` and
  Phase 3 moves `Clickable.kt` because both are in the way; the rest of the
  `com.machankura` tree — NFC widgets among it — is out of scope.