design-token-validator_skill

Overview

This skill validates that CSS and component code use approved design tokens instead of hardcoded values. It scans token source files and project files, reports violations by severity, and suggests token replacements or automated fixes. Use it to enforce a consistent design system and reduce visual drift and design debt.

How this skill works

The validator first locates token definitions (CSS variables, tokens.json, or JS/TS token objects) and extracts available token names. It then scans target files (CSS/SCSS, JSX/TSX, Vue) for hardcoded colors, spacing, inline styles, Tailwind arbitrary values, and other magic numbers. Each finding is categorized by severity and matched to the closest token using a mapping; the tool can generate suggested fixes or patch examples.

When to use it

• Enforcing design token usage across a codebase
• Auditing for hardcoded colors, spacing, or typography values
• Preparing a codebase for a design-system migration
• Blocking new design-debt in CI or pre-commit checks
• Finding inline styles or Tailwind arbitrary values that bypass tokens

Best practices

• Identify and point the tool at the canonical token file before scanning
• Maintain a token-to-value mapping to enable deterministic suggestions
• Run scans in CI and fail builds on 'Error' severity violations
• Use Stylelint/ESLint rules to prevent regressions after fixes
• Treat gradients, calc() and complex values as manual-review items

Example use cases

• Scan src/ for hardcoded hex or rgb colors and replace with var(--color-*) tokens
• Detect px spacing in components and suggest corresponding --spacing-* tokens
• Find inline React styles and recommend moving values to CSS modules with tokens
• Report Tailwind arbitrary values and map them to theme classes or CSS variables
• Create a summary report for a pull request listing violations and auto-fixable items