design-system-structure

design-system-structure

A design system is code that is incapable of holding a stray opinion: every aesthetic value lives in one directory, and every widget reads it back through a named slot. This skill owns how tokens, themes, components, and shapes are structured and consumed — not which colors or radii to pick (that belongs to your design source of truth). Getting the structure right makes a reskin a diff lib/theme/ and turns a stray Color(0xFF…) in feature code into a build failure instead of a style nit.

Read the reference for the task at hand:

• references/token-tiers-and-themeextension.md — two-tier token naming, ThemeExtension mechanics, the asserting of(), hand-authored ColorScheme vs fromSeed, honest lerp.
• references/motion-and-reduced-motion.md — the three animations Material mounts by default, why NoSplash is not enough, reduced-motion-means-zero, pumpAndSettle bans in tests.
• references/typography-and-fonts.md — bundling fonts, LicenseRegistry, FontWeight drives wght, silent FontVariation no-ops, subsetting without instancing, per-script fallback cascades.
• references/contrast-and-redundant-encoding.md — AA as a unit test, ≥3 grayscale-legible signals per meaning, reading a11y flags from MediaQuery.

Run scripts/check_raw_values.sh and scripts/check_font_bundling.sh before a PR.

Non-negotiable rules

1. No raw aesthetic value outside lib/theme/** — the gate is the law. A Color(0x…) / Colors.* (except transparent) / Curves.* / Duration(milliseconds:|seconds: (except Duration.zero) / literal BorderRadius.circular(n) / fontSize: n in feature or shared UI code fails scripts/check_raw_values.sh. A legitimate new need is a new token slot, never a // ignore — one place to diff is the whole point.
2. Two token tiers; widgets read only the semantic tier. Tier 1 = primitives named by the measured value (neutral12 = OKLCH lightness ×100), never by rank (grey700), appearance (darkGrey), or brand (brandPrimary). Tier 2 = semantic slots named by role (surface, onSurface, hairline, accent). A widget that reaches a Tier-1 primitive has hardcoded one theme. WHY: rank scales have no room to insert and lie in dark mode; appearance names invert catastrophically; brand names die with the brand.
3. Read tokens through a ThemeExtension and an asserting of(context). Never a static const class, never an InheritedWidget side channel. of() asserts on a missing extension — it does not ?? fallback. WHY: MaterialApp drives light/dark switching and correct-by-construction invalidation; a fallback silently ships a theme no test verified, and loud-in-debug beats wrong-in-field.
4. Hand-author ColorScheme; never ColorScheme.fromSeed (or dynamic_color) for identity. fromSeed's per-role overrides do not propagate — override surface and surfaceContainerHigh stays seed-derived. State every role you consume, keep the M3 role names so Material widgets theme themselves, and let unstated roles take ColorScheme's own defaults, not a seed's opinion. WHY: "seed plus a few overrides" means owning the ~9 roles you chose and every seam of the ~40 you didn't.
5. Layer the system: tokens → theme → modifiers/components → shapes. Author light and dark by hand (dark is never an auto-flip), each passing AA independently, and attach every extension to both ThemeDatas. Inject the theme exactly once, at the composition root. WHY: theming the app must touch one directory; a palette-only dark theme ships light's ratios into the dark.
6. lerp honestly or snap deliberately; copyWith is mandatory. Interpolate colors and doubles; snap non-interpolables (font families, ShapeBorder) at t < 0.5. If your app bans theme animation and you snap everything, leave a comment — a bare step-lerp reads as unfinished and the next reader will "fix" it. WHY: a new field silently forgotten in lerp is the classic design-system rot.
7. Color is a derived token, computed LAST — never a status's only channel. Color is a pure function of a canonical value object (an enum/small class), resolved through a semantic slot at the end; status is never read from color, and the supporting color is a slot read, not a literal. The never-color-alone floor itself — ≥3 non-color signals (glyph, label, weight/position) per stateful meaning — is owned by accessibility-as-code; this skill only enforces that the color reinforcing them is a derived slot. WHY: a color not derived from the value object drifts out of sync, and a widget that leans on color alone dies in grayscale.
8. Reduced motion collapses to zero, not "gentler." Read MediaQuery.disableAnimationsOf(context) and resolve to Duration.zero / a cross-fade to the end state — never a shorter duration or a softer curve. Motion is never the only signal for a state change. WHY: a user who asked the OS to stop animations asked for stop.
9. Restore the persisted theme before first paint. Load the saved theme mode / variant before runApp, from the same versioned settings the rest of the app uses (not an async shared_preferences read that lands a frame late). An unknown or corrupt stored value falls back explicitly and visibly, never to a null that leaves of() asserting on a device with no debugger. WHY: a flash of the wrong theme is a sudden luminance change the user did not cause.
10. Bundle fonts; never google_fonts at runtime. Declare fonts in pubspec.yaml, ship the license text and register it via LicenseRegistry, and drive weight with FontWeight (which drives the wght axis) — not a redundant FontVariation('wght', …). Declare a per-script fontFamilyFallback cascade that ends in a known-good face. WHY: google_fonts ships an HTTP code path by default; FontVariation('opsz'|'ital', …) silently no-ops on a font that lacks the axis, so a "working" italic is invisible in review.
11. Painters snapshot tokens; paint() never reads BuildContext. Resolve Theme.of(context).extension<T>() once at the widget layer and pass the values into the CustomPainter/Scene fields. WHY: keeps paint() allocation-free and testable without a MaterialApp; see custom-canvas-and-gestures.
12. The reduced-motion flag is read from MediaQuery (disableAnimationsOf), never app state — it feeds resolveMotion (this skill's helper, below). Reading the other platform a11y flags (boldTextOf, highContrastOf, textScaler) from MediaQuery rather than a stale app-state copy is owned by accessibility-as-code.