The 23 wallet notes move to docs/retired/ with a banner; every link between notes is rewritten for the move and checked. The index lists them as one Retired paragraph, and seven kept notes carry a line on what changed. The README and CLAUDE.md describe a Giza with no wallet. brand-audit.sh loses its "bennu/ exception: every such tag was a wallet's, so one now is a wallet coming back. wallet-audit.sh --check, in check and in CI, fails on a retired kind in the app's code, a lightning-kmp import, a file named for a wallet's pieces, or sats in a string. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
11 KiB
Conventions for UI code
Eight phases of work brought what were then 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. 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
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…)
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:
// 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
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:
// 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
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:
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:
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
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
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
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.
The app is Giza; Bennu is only protocol
Giza is a fork of Bennu (docs/giza-rebrand.md). Name the app Giza everywhere a person reads it, and never name Bennu outside a comment.
The derivation tags -- mantra/… -- look like brand strings and are hash inputs. Renaming one
derives different keys from the same seed and cuts Giza off from every Bennu peer. Leave them
spelled as they are.
private const val TWEAK_TAG = "mantra/shared-key/tweak/v1" // yes, protocol
Text("Open Bennu") // no
./gradlew check runs docs/scripts/brand-audit.sh --check, which fails on Bennu anywhere
in composeApp or iosApp but a comment. There used to be bennu/… tags too; every one was
a wallet's, so one appearing now is a wallet coming back, and fails.
Giza keeps no wallet
The wallets Giza inherited from Bennu are gone (docs/giza-wallet-removal.md). Bennu still has them, and a Bennu member can put one to a group Giza is in, so:
- A proposal Giza cannot check -- a wallet's kind, a transaction, a certificate with wallet
tags -- is declined, out loud, through
WalletRefusal. Never dropped silently, which the group cannot tell from a phone in a pocket, and never signed. - The wallet's kind numbers (
RetiredKinds) stay Bennu's. Nothing new goes on them. - A recovery phrase is a key backup.
PhraseKeysderives the npub and the profile id, and both are pinned inForkCompatibilityTest.
./gradlew check runs docs/scripts/wallet-audit.sh --check, which fails on a retired kind in
the app's code, a lightning-kmp import, a file named for a wallet's pieces, or sats in a string.
Checking your work
./gradlew :composeApp:m3Audit
./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.