System Architecture
How UI Foundations is structured — from atomic layers to governance and quality controls.
UI Foundations is the implementation repository for the runtime design system. It documents how tokens, patterns, components, build output, validation, and CI work together.
Canonical design foundation knowledge is maintained in the UI Foundations Vault. This repository only documents implementation-specific usage.
Vault reference: configured vault foundations
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 |
| Appearance | Mode-dependent decisions such as light and dark rendering context | :root, :root[data-mode="dark"] |
| Semantics (Brands) | Brand-scoped semantic roles for color, corner, font, and size decisions | :root[data-brand="a"], --brand-corner-button |
| Patterns / Components | Pattern-specific usage tokens scoped to a UI element or interactive component | --uif-button-solid-background-hover |
Governance & Quality
Every pattern and component decision is informed by durable foundation knowledge in the vault and implemented through local rule IDs, pattern rules, component rules, validation, and CI.
| Layer | Purpose | Examples |
|---|---|---|
| Design Principles | Vault-owned foundation knowledge applied through local implementation rules | Pattern-rule citations and component documentation |
| Usability Heuristics | Vault-owned usability knowledge surfaced as local traceability IDs | Rule pipeline and validation manifest |
| Design Intelligence | Vault-owned reasoning model used as an implementation review lens | Pattern, component, and docs review |
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.
Brand And Mode Context
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 roles 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