Duolith docs

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

  1. Motion, shape and control tokens. theme.yaml gains duration, easing, shape (control, field, container, chip, sheet, dialog, thumb) and control (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.
  2. Part tokens. Every kit part declares its own tokens under look: in its spec (spec/kit/*.yaml): each with a value, and an ios and a material value where those platforms differ. Its style block reads them as var(--part-<part>-<token>); a test checks every read is declared and every declared token is read.
  3. **look: default | platform.** With platform, iOS gets the ios values and Android the material ones; the web follows web-look (user-agent by default, or ios, 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 carries data-look; on native the root view carries st-look-ios or st-look-material.
  4. **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

OptionWhy not
Two kits, one per platformTwice the parts to keep accessible and tested, and apps that drift apart
ios: and android: style variants in style blocksEvery project restyles every part; the kit's defaults stay one-platform
Swap colours with the look tooNative 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.