30
Backend
06
Security
12
iOS
21
Infra

Express the iOS design system in SwiftUI's own vocabulary instead of portable design tokens

Amended by ADR-0090
ADR-0085 AMENDED · 2026-08-06
Express the iOS design system in SwiftUI's own vocabulary instead of portable design tokens

Decision

State the design system as rules in the platform's vocabulary, and give each composite that has an anatomy a component. Type is Dynamic Type text styles by role, and no size is ever written down. Colour is semantic roles, and no role means good or bad: status is carried by weight, role and position, never by a label or a red/green pair. Depth is a system material, with no shadows and no card surfaces; content sits on the background and an inset separator divides it. Spacing is a short fixed scale, the one thing the platform does not name. A row, a section header, or a piece of prose whose state has to read differently is a component, so its anatomy is stated once. Prefer deleting a modifier to replacing it: the semantic default is usually right, and every explicit value is one more thing to keep correct.

Why

A token layer maps names to fixed values, and the platform already names each of those values with behaviour attached. The indirection hides what is lost. A fixed point size opts out of Dynamic Type, a hex value opts out of dark mode and increased contrast, and a shadow opts out of materials, while the call site still looks disciplined. The token layer this replaces was a web token system ported to Swift, with fixed point sizes, hover states and a 9999pt corner radius. Its portability paid for nothing: there is no second client consuming the values, and nothing builds from the design handoff; a person reads it.

Rejected alternatives

  • Keep a three-tier token layer. It buys portability we do not use, and it costs the platform's behaviour on text sizing, contrast, materials and every future OS change.
  • Generate Swift from the design tool's export. Same cost, plus the exported values become authoritative, so the app inherits what the tool can express rather than what the platform can do.

Consequences

The system cannot be diffed against a design export, because it deliberately holds different values. What it can be checked against is the vocabulary it deleted, and that half is enforced: a deny-list runs as a ratchet whose count may fall and never rise. Anything the platform does not name, such as the spacing scale or a readable measure on a resizable window, still has to be decided and defended, and that is where drift should be expected.