Skip to main contentSkip to design system navigation

ENFORCEMENT

The checks below run in CI or local tooling. CI scheduling and local-only coverage are stated separately.

Tokens

app/css/theme.css (@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.

GateCommandChecks
GateContrastCommandpnpm lint:contrastChecksParses --color-* from theme.css; fails if any documented pair misses WCAG AA
GateToken boundaryCommandpnpm lint:css-tokensChecksFails a raw hex or color function outside theme.css, 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/css/theme.css: 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:contrast checks the color pairs; the unit tests in app/(en)/design-system/_lib/theme-tokens.test.ts pin the scale, and tests/e2e/type-floor.spec.ts 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/css/components-*.css. The PostCSS configuration uses @tailwindcss/postcss. Design-system component directories have no CSS Modules.

Components

GateCommandChecks
GateComponent docsCommandpnpm check:component-docsChecksEvery directory under design-system/components has a ## Name section in components/page.mdx
GateUnit testsCommandpnpm testChecksA *.test.tsx beside each component, run in the Vitest suite (jsdom)
GateBehavior in a browserCommand*.e2e.ts beside a componentChecksRun by the four -components Playwright projects (Chromium and WebKit, desktop and mobile)
GateVisual regressionCommandtests/e2e/design-system-components.spec.tsChecksLocal Darwin component snapshots; ignored in CI by playwright.config.ts
GateA11yCommandpnpm playwright test tests/a11yChecksaxe-core scan including wcag22aa, zero violations

Cross-cutting

GateCommand
GateLint + formatCommandpnpm biome ci --error-on-warnings .
GateTypesCommandpnpm typecheck
GateContent schemaCommandpnpm validate-content
GateClient/RSC naming (app, components, lib; excludes design-system)Commandpnpm check:client-naming
GateDependency pinningCommandpnpm check:dep-pinning
GateDependency vetting (purpose, license, install scripts)Commandpnpm check:dependency-vetting
GateTest integrity (no focused test, assertion-less body or unexplained skip)Commandpnpm check:test-integrity
GateDoc drift (paths marked in ARCHITECTURE.md exist)Commandpnpm check:doc-drift
GateSection order (rendered section ids match the registry)Commandpnpm check:section-order
GateChange-filter paths (no orphaned CI path filter)Commandpnpm check:detect-changes-paths
GateStatic analysis (CI scan is non-blocking)Commandpnpm lint:semgrep
GateSecret scanCommandpnpm gitleaks:staged 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:mobile

Adding a New Component

  1. Create design-system/components/NewComponent/ with .tsx, .test.tsx, and index.ts · styled with Tailwind utilities, no .module.css.
  2. Export it from design-system/index.ts, unless it is a boundary exception: Field is deliberately client-only and BrandIcon is imported by path, and neither ships through the barrel.
  3. Add a ## NewComponent heading in app/(en)/design-system/components/page.mdx · check:component-docs fails if it is missing.
  4. Update the counts the docs state (README.md, the overview and the components page); __tests__/design-system-doc-counts.test.ts compares them with the directory.
  5. If the component gets its own page under app/(en)/design-system/primitives/, add it to DS_NAV_GROUPS in _components/ds-nav.ts and to both Lighthouse configs; __tests__/design-system-route-coverage.test.ts fails when a page is missing from the menu, the sitemap or either config.
  6. Add a local Darwin visual baseline in tests/e2e/design-system-components.spec.ts. CI ignores this spec; page-section snapshots and co-located component behavior tests have separate coverage.

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/detect-changes-paths.mjs.