Skip to content

feat: add automated design-spec compliance checks to CI #697

@zacharias-ona

Description

@zacharias-ona

Description

The project has had 14 "UI does not match design spec" bug issues since inception. Each feature PR risks introducing design drift (wrong border-radius, non-oklch colors, incorrect spacing tokens, wrong font). Currently, design compliance is only caught post-merge by the UI Verifier automation, which creates follow-up bug issues. Catching violations pre-merge in CI would eliminate this entire bug category.

Acceptance Criteria

  • A Vitest test suite that statically checks component source files for common design-spec violations:
    • rounded- classes other than rounded-none or rounded-sm (design spec requires sharp corners, --radius: 0)
    • Hex/RGB/HSL color values instead of oklch design tokens
    • Hardcoded font-family instead of the JetBrains Mono CSS variable
    • px- / py- / p- values that don't match the 4px grid (design spec spacing)
  • The check runs as part of pnpm test (no separate CI step needed)
  • False positives are manageable — shadcn/ui components in src/components/ui/ are excluded
  • At least the rounded- check catches the most common violation pattern
  • pnpm lint && pnpm typecheck && pnpm test pass

Approval Required

This is HIGH risk because:

  • Static analysis of Tailwind classes can produce false positives (e.g., rounded-sm is valid per design spec but rounded-md is not)
  • May need an allowlist for edge cases (third-party component wrappers)
  • Could slow down the test suite if file scanning is expensive
  • Scope could expand beyond what's useful — should start minimal (just rounded- check) and iterate

Comment "approved" to release this to the automation queue.

Dependencies

None

Technical Notes

  • Design spec is at .agents/design.md — the source of truth for visual rules
  • Existing pattern: src/components/editor/design-spec-compliance.test.ts already does similar static checks for editor components (11 tests)
  • The overlay-opacity.test.ts and dialog-design-spec.test.ts also follow this pattern
  • Start with the rounded- class check — it accounts for the majority of design-spec bugs
  • Exclude src/components/ui/ (shadcn/ui managed files) and node_modules/
  • Reference .agents/conventions.md for test patterns

Metadata

Metadata

Assignees

No one assigned

    Labels

    enhancementNew feature or requestneeds-humanNeeds human input — automation will re-queue when user respondspriority:3

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions