0103. Platform looks, and per-part overrides in theme.yaml
- Status: Accepted (Mik, 16 Nov 2026)
- Date: 2026-11-15
- Decided by: domain E implementer (internal only), approved by Mik on 16 Nov 2026 as a design change
- Planning item: wave 5, kit platform look
Context
The kit looks the same on every platform. People asked for an app that feels like iOS on an iPhone and like Material on Android, without writing two apps or a style block per platform. Themes could change colours, spacing and radii, but not the shape of a switch, the height of a field, how fast a sheet opens, or a single part's look.
Decision
- Motion, shape and control tokens.
theme.yamlgainsduration,easing,shape(control, field, container, chip, sheet, dialog, thumb) andcontrol(switch, checkbox, slider, progress and field measures) groups. A value may name another token,{radius.md}, resolved when the app is built. The kit and the motion presets read them. - Part tokens. Every kit part declares its own tokens under
look:in its spec (spec/kit/*.yaml): each with a value, and aniosand amaterialvalue where those platforms differ. Its style block reads them asvar(--part-<part>-<token>); a test checks every read is declared and every declared token is read. - **
look: default | platform.** Withplatform, iOS gets theiosvalues and Android thematerialones; the web followsweb-look(user-agentby default, orios,material,default). Looks change shape, control, motion and part tokens only, never colours or utilities, so a native build (which resolves utilities when it is built) and the web agree. On the web the root carriesdata-look; on native the root view carriesst-look-iosorst-look-material. - **
parts:overrides.**parts: { Button: { tokens: { radius: 2px }, variants: { primary: { background: "{color.ink}" } }, slots: { label: { weight: "700" } } } }. An unknown part (E0507), token (E0508), slot (E0509) or variant (E0510), or a reference to no token (E0511), fails the build. An override applies under every look.
Alternatives considered
| Option | Why not |
|---|---|
| Two kits, one per platform | Twice the parts to keep accessible and tested, and apps that drift apart |
ios: and android: style variants in style blocks | Every project restyles every part; the kit's defaults stay one-platform |
| Swap colours with the look too | Native resolves utilities at build time, so it could not follow a look chosen at run time |
Consequences
Each kit spec has a look: section (spec/schemas/kit.schema.json requires it). Projects that set nothing look as before: look: default is the default.
On native, an icon inside a part is drawn in the colour its class gives text in the default look, since the engine strokes icons from a light and dark table per class, built ahead of time. A part token whose colour differs by look (the secondary button's ink is the primary colour under iOS and Material) colours the text in that look but not the icon; following the look there needs the engine to stroke icons from the running look's values.