ENFORCEMENT
The checks below run in CI or local tooling. CI scheduling and local-only coverage are stated separately.
Tokens
app/ (@theme) is the single source of truth for brand colour.
The file declares --color-* custom properties; Tailwind generates matching utilities.
The token swatches on the Tokens page read the
same file.
| Gate | Command | Checks |
|---|---|---|
| GateContrast | Commandpnpm lint: | ChecksParses --color-* from theme.; fails if any documented pair misses WCAG AA |
| GateToken boundary | Commandpnpm lint: | ChecksFails a raw hex or color function outside theme., a literal z-index outside the --z-* scale, and a focus rule that writes its own ring instead of --focus-ring |
Type and spacing are a maintained token layer in app/: a type scale
from --text-xs to --text-7xl with a --text-min floor of
13px at every width, spacing steps --spacing-1 to --spacing-16, and a 44px
--spacing-target for interactive targets. lint: checks the color pairs;
the unit tests in app/ pin the scale, and tests/ fails any visible text set below --text-min. Z-index, letter spacing and media-query widths are token scales too (--z-*, --tracking-*, --viewport-*); motion uses utilities and named CSS classes, including arbitrary values.
Styling
Components use Tailwind utilities and shared classes in app/.
The PostCSS configuration uses @tailwindcss/. Design-system component
directories have no CSS Modules.
Components
| Gate | Command | Checks |
|---|---|---|
| GateComponent docs | Commandpnpm check: | ChecksEvery directory under design-system/ has a ## Name section in components/ |
| GateUnit tests | Commandpnpm test | ChecksA *. beside each component, run in the Vitest suite (jsdom) |
| GateBehavior in a browser | Command*. beside a component | ChecksRun by the four -components Playwright projects (Chromium and WebKit, desktop and mobile) |
| GateVisual regression | Commandtests/ | ChecksLocal Darwin component snapshots; ignored in CI by playwright. |
| GateA11y | Commandpnpm playwright test tests/ | Checksaxe-core scan including wcag22aa, zero violations |
Cross-cutting
| Gate | Command |
|---|---|
| GateLint + format | Commandpnpm biome ci --error-on-warnings . |
| GateTypes | Commandpnpm typecheck |
| GateContent schema | Commandpnpm validate-content |
GateClient/RSC naming (app, components, lib; excludes design-system) | Commandpnpm check: |
| GateDependency pinning | Commandpnpm check: |
| GateDependency vetting (purpose, license, install scripts) | Commandpnpm check: |
| GateTest integrity (no focused test, assertion-less body or unexplained skip) | Commandpnpm check: |
GateDoc drift (paths marked in ARCHITECTURE. exist) | Commandpnpm check: |
| GateSection order (rendered section ids match the registry) | Commandpnpm check: |
| GateChange-filter paths (no orphaned CI path filter) | Commandpnpm check: |
| GateStatic analysis (CI scan is non-blocking) | Commandpnpm lint: |
| GateSecret scan | Commandpnpm gitleaks: before commit; the gitleaks CI job |
| GateGlobal chunk size (220KB gzip) | Commandpnpm bundle-check |
| GatePer-route first-load JS (164.2KB gzip) | Commandpnpm route-js-check |
| GateLighthouse (a11y = 100) | Commandpnpm lhci · pnpm lhci: |
Adding a New Component
- Create
design-system/withcomponents/ NewComponent/ .,tsx ., andtest. tsx index.· styled with Tailwind utilities, nots ..module. css - Export it from
design-system/, unless it is a boundary exception:index. ts Fieldis deliberately client-only andBrandIconis imported by path, and neither ships through the barrel. - Add a
## NewComponentheading inapp/·(en)/ design-system/ components/ page. mdx check:fails if it is missing.component-docs - Update the counts the docs state (
README., the overview and the components page);md _compares them with the directory._ tests_ _ / design-system-doc-counts. test. ts - If the component gets its own page under
app/, add it to(en)/ design-system/ primitives/ DS_inNAV_ GROUPS _and to both Lighthouse configs;components/ ds-nav. ts _fails when a page is missing from the menu, the sitemap or either config._ tests_ _ / design-system-route-coverage. test. ts - Add a local Darwin visual baseline in
tests/. CI ignores this spec; page-section snapshots and co-located component behavior tests have separate coverage.e2e/ design-system-components. spec. ts
quality-fast runs contrast and component-heading checks. The performance job runs
Lighthouse and axe; PRs enter it when the app change filter matches. app/ and
design-system/ changes match that filter. See scripts/.