Agent skill

validating-design-tokens

Ensures CSS and components only use approved design tokens. Use when the user asks about design system enforcement, hardcoded colors, spacing values, or wants to validate token usage across files.

View SKILL.md on GitHub Repository
Stars 163
Forks 31

Install this agent skill to your Project

npx add-skill https://github.com/majiayu000/claude-skill-registry/tree/main/skills/data/design-token-validator

SKILL.md

Design System Token Validator

When to use this skill

  • User asks to check for hardcoded colors or spacing
  • User wants to enforce design token usage
  • User mentions design system consistency
  • User asks to find var(--token-*) violations
  • User wants to prevent design debt

Workflow

  • Identify design token source file
  • Scan target files (CSS, TSX, Vue)
  • Detect hardcoded values
  • Match violations to available tokens
  • Generate fix suggestions
  • Report violations by severity

Instructions

Step 1: Identify Token Source

Locate design token definitions:

bash
ls src/styles/tokens.css src/tokens/*.css styles/variables.css 2>/dev/null
ls src/styles/tokens.ts src/tokens/*.ts 2>/dev/null
ls tokens.json style-dictionary.config.* 2>/dev/null

Common token file patterns:

  • CSS custom properties: --color-*, --spacing-*, --font-*
  • JavaScript/TypeScript objects: tokens.colors.*, theme.spacing.*
  • Style Dictionary output: tokens.json

Step 2: Extract Available Tokens

From CSS variables:

bash
grep -hoE 'var\(--[a-zA-Z0-9-]+' src/styles/tokens.css | sort -u

Parse into categories:

Category Pattern Examples
Colors --color-* --color-primary, --color-text-muted
Spacing --spacing-*, --space-* --spacing-md, --space-4
Typography --font-*, --text-* --font-size-lg, --font-weight-bold
Radii --radius-*, --rounded-* --radius-md, --rounded-lg
Shadows --shadow-* --shadow-sm, --shadow-elevated
Transitions --transition-*, --duration-* --transition-fast
Z-index --z-* --z-modal, --z-tooltip

Step 3: Scan for Violations

Hardcoded colors in CSS:

bash
grep -rn --include="*.css" --include="*.scss" -E '#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(' src/

Hardcoded colors in JSX/TSX:

bash
grep -rn --include="*.tsx" --include="*.jsx" -E "color:\s*['\"]#|background:\s*['\"]#|borderColor:\s*['\"]#" src/

Hardcoded spacing (px values):

bash
grep -rn --include="*.css" --include="*.scss" -E ':\s*[0-9]+px' src/ | grep -v "0px\|1px"

Inline styles in React:

bash
grep -rn --include="*.tsx" --include="*.jsx" "style={{" src/

Tailwind arbitrary values (if using tokens with Tailwind):

bash
grep -rn --include="*.tsx" --include="*.jsx" -E '\[#[0-9a-fA-F]+\]|\[[0-9]+px\]' src/

Step 4: Categorize Violations

Severity levels:

Severity Description Examples
Error Hardcoded colors in component styles color: #333333
Error Hardcoded spacing in layout padding: 24px
Warning Inline styles with raw values style={{ margin: 10 }}
Warning Magic numbers width: 347px
Info One-off values that may be intentional Border widths, specific dimensions

Step 5: Match to Available Tokens

For each violation, suggest the closest token:

markdown
## Violation Report

### src/components/Card.module.css:15

**Found**: `background-color: #f5f5f5;`
**Suggestion**: `background-color: var(--color-surface);`

### src/components/Button.tsx:42

**Found**: `padding: '16px 24px'`
**Suggestion**: `padding: 'var(--spacing-md) var(--spacing-lg)'`

### src/pages/Home.module.css:8

**Found**: `color: #1a1a1a;`
**Suggestion**: `color: var(--color-text-primary);`

Step 6: Generate Fixes

CSS fix pattern:

css
/* Before */
.card {
  background-color: #ffffff;
  padding: 16px;
  border-radius: 8px;
  box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
}

/* After */
.card {
  background-color: var(--color-surface);
  padding: var(--spacing-md);
  border-radius: var(--radius-md);
  box-shadow: var(--shadow-sm);
}

React inline style fix:

tsx
// Before
<div style={{ color: '#333', marginBottom: 16 }}>

// After
<div style={{ color: 'var(--color-text)', marginBottom: 'var(--spacing-md)' }}>

// Best: Use CSS modules instead
<div className={styles.container}>

Tailwind with CSS variables:

tsx
// Before (arbitrary value)
<div className="bg-[#3b82f6] p-[24px]">

// After (use theme or CSS var)
<div className="bg-primary p-6">
// Or with CSS variable in tailwind.config.js

Token Mapping Reference

Create a mapping file for consistent suggestions:

typescript
// scripts/token-map.ts
export const colorMap: Record<string, string> = {
  "#ffffff": "var(--color-surface)",
  "#000000": "var(--color-text)",
  "#3b82f6": "var(--color-primary)",
  "#ef4444": "var(--color-error)",
  "#22c55e": "var(--color-success)",
};

export const spacingMap: Record<string, string> = {
  "4px": "var(--spacing-xs)",
  "8px": "var(--spacing-sm)",
  "16px": "var(--spacing-md)",
  "24px": "var(--spacing-lg)",
  "32px": "var(--spacing-xl)",
};

export const findClosestToken = (
  value: string,
  map: Record<string, string>,
): string | null => {
  return map[value.toLowerCase()] ?? null;
};

ESLint Integration

Custom ESLint rule (conceptual):

javascript
// .eslintrc.js
module.exports = {
  rules: {
    "no-hardcoded-colors": "error",
    "no-hardcoded-spacing": "warn",
  },
};

Stylelint for CSS:

bash
npm install -D stylelint stylelint-declaration-strict-value
javascript
// .stylelintrc.js
module.exports = {
  plugins: ["stylelint-declaration-strict-value"],
  rules: {
    "scale-unlimited/declaration-strict-value": [
      ["/color/", "fill", "stroke", "background", "border-color"],
      {
        ignoreValues: ["transparent", "inherit", "currentColor"],
      },
    ],
  },
};

Report Template

markdown
## Design Token Validation Report

**Scanned**: 47 files
**Violations**: 12
**Auto-fixable**: 9

### Summary by Category

| Category   | Violations | Fixable |
| ---------- | ---------- | ------- |
| Colors     | 7          | 6       |
| Spacing    | 4          | 3       |
| Typography | 1          | 0       |

### Violations

#### Colors (7)

| File            | Line | Found             | Suggested Token   |
| --------------- | ---- | ----------------- | ----------------- |
| Card.module.css | 15   | `#f5f5f5`         | `--color-surface` |
| Button.tsx      | 42   | `#3b82f6`         | `--color-primary` |
| Header.css      | 8    | `rgba(0,0,0,0.5)` | `--color-overlay` |

#### Spacing (4)

| File       | Line | Found  | Suggested Token |
| ---------- | ---- | ------ | --------------- |
| Layout.css | 23   | `24px` | `--spacing-lg`  |
| Modal.tsx  | 67   | `16px` | `--spacing-md`  |

Validation

Before completing:

  • All hardcoded colors replaced with tokens
  • Spacing uses token scale
  • No inline styles with raw values
  • Stylelint configured for enforcement
  • New violations blocked in CI

Error Handling

  • No token file found: Ask user to specify token source location.
  • Unknown color value: Flag for manual review; may need new token.
  • False positives: Exclude reset styles, third-party CSS, and intentional overrides.
  • Complex values: Gradients, calc() expressions may need manual review.

Resources

Recommended Agent Skills

Expand your agent's capabilities with these related and highly-rated skills.

majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-spec

Manage specification documents in .agent/specs/. Use when user provides requirements, acceptance criteria, or feature descriptions that need to be tracked and validated against implementation.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-testing

Test strategy, execution, and coverage analysis. Use when designing tests, running test suites, or analyzing test results beyond baseline checks.

163 31
Explore
majiayu000/claude-skill-registry

agent-ops-state

Maintain .agent state files. Use at session start, after meaningful steps, and before concluding: read/update constitution/memory/focus/issues/baseline consistently.

163 31
Explore

Didn't find tool you were looking for?

Be as detailed as possible for better results