Skip to main content

Source: ocean/docs/adr/0026-design-validation-in-ci.md | ✏️ Edit on GitHub

ADR-0026: Enforce Design Token Validation in CI

Date: 2025-08-14

Status​

Accepted

Context​

We adopted a token-driven design system (see ADR-0025) with Tailwind 4 @theme, shadcn semantics, and Style Dictionary generation. To prevent regressions and drift between token sources and generated CSS variables, we need a CI gate that fails builds when generated palettes diverge from our canonical configuration.

Decision​

  • Add a CI validation step that runs immediately after token generation.
  • The step executes:
    • pnpm run tokens:build (generates tokens.generated.css and color-themes.generated.css)
    • pnpm run design:validate (compares src/config/themes.ts against src/styles/color-themes.generated.css)
  • The CI job fails if any theme variable mismatch or missing mapping is detected.

Consequences​

  • Pros
    • Prevents accidental visual changes from merging.
    • Ensures generated CSS remains aligned with token sources and shadcn semantic classes.
    • Produces actionable diffs (theme/mode/var with expected vs actual values).
  • Cons
    • Adds a fast, deterministic step to CI; requires updating tokens or config when intentional changes are made.

Implementation​

  • Scripts (available now):

    • tokens:build → builds tokens via Style Dictionary
    • design:validate → validates generated palettes against config
    • Recommended CI command:
      • pnpm run tokens:build && pnpm run design:validate

  • Example GitHub Actions step (for reference):

- name: Build design tokens
  run: pnpm run tokens:build

- name: Validate design output
  run: pnpm run design:validate

Rollback Plan​

  • Disable the validation step in CI if blocking issues arise; no runtime impact to the application.

References​

  • ADR-0025: Token-driven Design System with Tailwind 4 and shadcn