System Architecture
How UI Foundations is structured — from atomic layers to governance and quality controls.
UI Foundations follows an Atomic Design model using chemistry as its mental model. Each layer builds on the previous through composition, governed by principles and heuristics.
Atomic Layers
| Layer | Chemistry | Definition | Location |
|---|---|---|---|
| Tokens | Subatomic particles | Raw design values — colors, spacing, radii, typography. The physical constants of the system. | dist/tokens/ |
| Patterns | Atoms | Smallest self-contained UI unit. CSS-only, stateless. Works without JavaScript. | src/ui/patterns/ |
| Components | Molecules | Multiple atoms bound together with vanilla JavaScript for state and interactivity. | src/ui/components/ (planned) |
| Compositions | Organisms | Multiple molecules and atoms arranged for a specific task or use-case. | site/examples/ (docs only, not shipped) |
The binding energy that turns atoms into molecules is JavaScript and state management. If it works with pure CSS, it's a pattern. If it needs JS to function, it's a component.
Note: Compositions live in site/examples/ on the documentation site — they are reference implementations, not shipped library code. The "Examples" section in the navigation corresponds to the Organisms layer.
Token Architecture
Tokens follow a four-layer cascade. Each layer can only reference the one below it — never sideways or upward.
| Layer | Purpose | Example |
|---|---|---|
| Core | Raw values — the palette, spacing scale, font stacks | --color-neutral-800, --size-spacing-300 |
| Semantic | Intent-based — what a value means, not what it looks like | --color-fill-brand, --color-text-danger |
| Component | Pattern-specific — scoped to a single UI element | --button-solid-background-hover |
| Brand/Mode | Contextual overrides — adapts per brand or light/dark mode | :root[data-brand="a"], :root[data-mode="dark"] |
Governance & Quality
Every pattern and component decision is guided by three governance layers that form a quality net above the implementation:
| Layer | Purpose | Examples |
|---|---|---|
| Design Principles | Cross-cutting composition intent — the "why" behind layout and structure | Proximity, Hierarchy, Contrast, Affordance, Cognitive Load, Consistency |
| Usability Heuristics | Interaction quality rules — the "how" of user experience | Feedback, Error Prevention, Recognition, User Control, Accessibility |
| Design Intelligence | Judgment layer — evaluates quality beyond compliance | Appropriateness, Complexity, Trade-offs, Emotional Fit, Confidence |
Pattern rules must cite principle and heuristic IDs. Component rules must preserve the cited pattern intent. This traceability ensures every visual decision can be traced back to a documented rationale.
Theming Model
Brand and appearance mode are orthogonal concerns applied via data attributes:
data-brand="a|b|c"— switches color palette, typography, and corner radiidata-mode="light|dark"— switches semantic color mappings
Patterns never hardcode brand or mode values. They reference semantic tokens that resolve differently per context.
Build Pipeline
The system flows from Figma to production in a one-directional pipeline:
Generated files in dist/ are never edited directly. Changes flow from Figma exports through the pipeline.
Validation
npm run ci:check validates the full system:
- Lint — JS syntax correctness
- Unit tests — token pipeline logic
- Build — generates all dist artifacts
- Smoke check — verifies critical outputs exist
- Token validation — zero missing aliases, zero duplicates
- DTCG validation — schema compliance
- Asset check — all referenced icons/assets exist
- Rule pipeline — principles and heuristics are properly cited