Design Approach

The north star for this design system. Every token, every foundation, and every component answers to these principles. When a decision is unclear, come back here.

They are deliberately few — a long list is a list nobody follows.

1. Accessible by default

Contrast, readability, and clear focus are requirements, not enhancements. If a choice fails an accessibility check, it fails — we find another way rather than making an exception.

Why: Accessibility can't be bolted on later without rework. Building it into the foundation means everything downstream inherits it for free.

2. Semantic over literal

Name things by intent, not appearance. A token is primary, not blue; destructive, not red. Consumers reference the semantic name, never the raw value underneath.

Why: Intent survives change. Re-theme, go dark, or swap the brand hue, and semantic names still hold — only the value behind them moves. Literal names break the moment the value does.

3. Restraint

Fewer, well-chosen tokens beat a sprawling set. Add a token when a real, repeated need exists — not "just in case."

Why: Every token is a decision others must learn and honor. A tight set is easier to use correctly and harder to misuse. Sprawl is how systems rot.

4. Consistency through templates

Every foundation follows the same shape — Overview, Principles, Tokens, Rationale, Do / Don't — and every component follows its own fixed template. Within each kind of page, the structure never varies.

Why: A predictable structure makes docs scannable and complete. You always know where to look, and the template quietly enforces that nothing important gets skipped.

5. Every choice carries its rationale

Document the why, right next to the what. Why 4px, why this radius, why a theme re-points only one token.