Files
giza-kmp/CLAUDE.md
T
Kgothatso NgakoandClaude Opus 5.5 68a86b4d77 refactor: remove the unreachable nip30303 document screens (Phase 7, part 1)
Nothing navigated to the artifact, chapter, dialect or translation screens:
ArtifactDetailRoute, AddArtifactRoute and AddDialectRoute were never built,
and the other six were only reached from inside those screens. Removed with
their view models, UI states, routes, nav host entries, the repository behind
them, TranslationScaffold, DetailRow, and the 65 strings only they used. The
group details screen loses the document repository it stored and never read.

The string catalogue test now checks its escapes on a string that stays.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-23 16:42:15 +02:00

204 lines
8.8 KiB
Markdown

# Conventions for UI code
Eight phases of work brought this app's 43 screens onto Material Design 3; the full
account, with the numbers and the reasoning, is in
[docs/material-design-conformance.md](docs/material-design-conformance.md). What follows
is the short version — the rules a new screen has to follow, in the place they are needed,
which is while it is being written rather than while it is being reviewed.
Most of these are enforced. `./gradlew check` runs `docs/scripts/m3-audit.sh --check`,
which fails on a budget that has been exceeded or a floor that has been undercut. Where a
rule below has a number beside it, that number is the budget.
## Spacing comes from the scale — never a `.dp` literal
```kotlin
Modifier.padding(MaterialTheme.spacing.containerPadding) // yes
Modifier.padding(16.dp) // no
```
M3's eighteen stops live on `Spacing`, with eight semantic names over them —
`screenMargin`, `containerPadding`, `compactPadding`, `relatedGap`, `itemGap`,
`sectionGap`, `emphasisGap`, `targetGap`, `paneGap`. Reach for a semantic name first and
a raw stop (`space125`) only when none of them says the job.
The semantic names are what adapt: `screenMargin` widens from 16dp to 24dp at the medium
breakpoint without a call site changing. That is the whole reason the scale exists rather
than a file of constants.
**Budget: 0 dp literals in spacing positions.** A `.dp` in a *dimension* position — an
avatar's size, a hairline border — is fine and is counted separately.
## Colour comes from a role — never a `Color(0x…)`
```kotlin
MaterialTheme.colorScheme.onSurfaceVariant // yes
MaterialTheme.extendedColors.bluePill.onContainer // yes, for the brand pair
Color(0xFF888888) // no
onSurfaceVariant.copy(alpha = 0.5f) // almost never
```
Six schemes are declared — light and dark, each with medium and high contrast variants —
and the platform's contrast setting selects between them. A colour written at a call site
belongs to none of them and will be wrong in five.
`.copy(alpha = …)` on a content role is how nine contrast failures got in: an alpha over
an unknown background has no ratio until it is composited, and the composite is usually
under 4.5:1. The exception M3 states is the 38% disabled state.
Where a colour genuinely cannot come from a role — a QR code's modules, a control over an
arbitrary photograph — mark it at the site:
```kotlin
// m3-color-exempt: the modules of a QR code have to be pure black on pure white
```
**Budget: 0 hardcoded colours outside `ui/theme/`.** `ColorSchemeContrastTest` measures
every pair in all six schemes; it runs in `:composeApp:jvmTest`.
## Text comes from the catalogue, in sentence case
```kotlin
Text(stringResource(Res.string.publish_new_key_package)) // yes
Text("Publish New Key Package") // no, twice over
```
Strings live in `composeApp/src/commonMain/composeResources/values/strings.xml`.
Interpolation is a format argument (`%1$s`), not a `"${…}"`.
Capitalisation is **sentence case everywhere** — titles, headings, labels, menu items,
buttons — which is M3's rule and not a preference. Proper nouns keep their capitals.
Compose Resources is not aapt: it does *not* unescape `\'` and does *not* collapse `%%`,
though it does process `\n`. `StringCatalogueJvmTest` asserts each escape the app depends
on; add to it rather than assuming a family rule.
A file whose strings are sample text rather than UI text — a gallery of colour pairings,
say — marks itself once at the top:
```kotlin
// m3-string-exempt: these words are sample text for looking at colour pairings
```
**Budget: 0 title-case strings.** Literals in composables are reported without a budget —
19 remain, all of them terms of a `+` concatenation.
## Every target is 48dp, and every icon has a decided description
```kotlin
Modifier.clickable { … }.minimumInteractiveComponentSize() // yes
Icon(Icons.Default.Search, contentDescription = "Search") // yes
Icon(Icons.Default.Add, contentDescription = Decorative) // yes, when the label is beside it
Icon(Icons.Default.Add, contentDescription = null) // no — say which
```
`IconButton` and `FilledIconButton` enforce 48dp themselves; a bare `Modifier.clickable`
does not, and three of the app's nineteen were text-sized before this rule.
`Decorative` is the same `null` the compiler sees, and it records that somebody looked. An
icon carrying state the surrounding text does not repeat needs a real description.
**Budgets: 0 unguarded `.clickable`, 0 untriaged `contentDescription = null`.**
## A screen has four states, and says so
Loading, empty, error, loaded. `ErrorState`, `EmptyState` and `LoadingDataIndicator` are
the shared ones; `ErrorState` takes an `onRetry`, and passing `null` is a decision rather
than a default. `EmptyState`'s message is required, because one shared default is how five
different absences all came to say "No events were found".
Report outcomes through the snackbar host:
```kotlin
val notify = rememberNotifier(rememberCoroutineScope())
val published = stringResource(Res.string.key_package_published) // read outside the handler
…
onClick = { viewModel.publish { notify(published) } }
```
Both `rememberNotifier` and `stringResource` are composable and an `onClick` lambda is
not, so read them above the handler. The notifier takes the caller's scope on purpose:
"saved" is usually shown as the screen navigates away, and a message launched in the
departing composable's scope would be cancelled with it.
Wrap the state `when` so the change is a transition rather than a cut:
```kotlin
ScreenStateTransition(viewModel.uiState) { uiState ->
when (val state = uiState) { … }
}
```
It only works where the `when` is the composable's whole body — `AnimatedContent` is a
layout node, so wrapping one inside a `Column` takes its branches out of `ColumnScope`.
## A pushed screen has a way back
```kotlin
TopAppBar(
title = { Text(stringResource(Res.string.add_post)) },
navigationIcon = { NavigateBackButton(onNavigateBack) }, // yes
)
TopAppBar(title = { … }) // no, on a pushed screen
```
A screen reached by `navController.navigate(...)` takes an `onNavigateBack: () -> Unit`
and puts `NavigateBackButton` in its app bar's leading slot; the host passes
`popBackStack()`. Android has a system back and iOS an edge swipe, but the desktop target
has neither, and a pushed screen with no button there is a dead end. Twenty-two were.
The button is *only* for pushed screens. The three top-level destinations have the
navigation bar instead, and a screen that cleared the stack to get there -- onboarding,
the loading gate -- has nothing under it to pop to. Where one composable is reached both
ways, the callback is nullable and the caller decides: `ChatRoomMessagingScreen` is a
destination on a phone and the home screen's detail pane in a wide window, and in the
pane the list beside it is the way back.
## Layout adapts to the window, not to the composable
```kotlin
Modifier.padding(innerPadding).readableContent() // on every screen's content root
MaterialTheme.breakpoint.isAtLeast(Breakpoint.Expanded)
```
`readableContent()` holds content to sixty characters of `bodyLarge` — derived from the
type scale, so it follows the reader's text size — and centres the column, not the text.
Centring text loses the leading edge that rows, avatars and icons align to; centre a block
only when it is the only thing on the screen.
Two panes from `Breakpoint.Expanded` up and never below, which is M3's rule for dense
content and also what `calculatePaneScaffoldDirective` does. `listPaneWidthFor` gives the
width.
Read the *window* through `MaterialTheme.breakpoint`, not the local constraints. A pane
300dp wide inside a 1400dp window is still in a large layout.
**Floors: at least 12 adaptive API uses, at least 2 navigation components.** These regress
by being removed, so the audit checks them from below.
## Motion comes from the scheme
```kotlin
MaterialTheme.motionScheme.defaultSpatialSpec<IntOffset>() // things that move
MaterialTheme.motionScheme.defaultEffectsSpec<Float>() // things that fade
tween(300) // no
```
`MotionSchemeKeyTokens` is `internal` to material3 and cannot be reached from here;
`MaterialTheme.motionScheme` is the public surface. Honour `MaterialTheme.reducedMotion`
— it means drop the movement, not the transition.
## Checking your work
```bash
./gradlew :composeApp:m3Audit
```
```bash
./gradlew :composeApp:compileDebugKotlinAndroid :composeApp:jvmTest
```
`docs/scripts/` also holds the tools each phase was done with —
`m3-spacing-positions.py`, `m3-touch-targets.py`, `m3-title-case.py` and the two string
extractors — each of which takes `--list` to show the sites rather than the count.