Moby Design System Validation

Updated: 2025-11-07

Two Bun scripts enforce design-token hygiene across the repo. They live in scripts/ and are exposed via package.json aliases so you only need Bun installed.

1. Token validation (scripts/validate-moby-ds.ts)

Ensures the CSS token architecture matches the documented Moby palette, semantic variables point to valid tokens, WCAG AA ratios hold, and no hardcoded colors slip into component code.

bun scripts/validate-moby-ds.ts          # quick run
bun scripts/validate-moby-ds.ts --verbose

Outputs:

• Summary table (files scanned, tokens found, warnings)
• Error/warning list with file + line references
• Contrast results for the default semantic pairings

Exit codes: 0 = pass, 1 = blocking issues.

2. Token usage audit (scripts/audit-token-usage.ts)

Scans the entire repo, classifies token usage per component, and highlights migration targets.

bun scripts/audit-token-usage.ts --components --migration-plan
bun scripts/audit-token-usage.ts --json > audit-report.json

Use it to:

• Find dead tokens or leftover hardcoded colors
• Generate prioritized migration lists
• Track coverage across component folders

Package.json helpers

{
  "scripts": {
    "ds:validate": "bun scripts/validate-moby-ds.ts --verbose",
    "ds:audit": "bun scripts/audit-token-usage.ts",
    "ds:migrate": "bun scripts/audit-token-usage.ts --migration-plan",
    "ds:check": "bun run ds:validate && bun run ds:audit"
  }
}

Call bun run ds:check locally or wire it into CI for a single command gate.

Adding new rules

1. Update scripts/validate-moby-ds.ts with the new requirement and extend its tests if needed.
2. Adjust any expected token arrays/hardcoded patterns.
3. Document the change here so other engineers know why the validator might fail.