WesleySmits/agent-skills / .agent/skills/design-token-validator
validating-design-tokens
VerifiedEnsures 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.
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:
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:
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:
grep -rn --include="*.css" --include="*.scss" -E '#[0-9a-fA-F]{3,8}|rgb\(|rgba\(|hsl\(' src/
Hardcoded colors in JSX/TSX:
grep -rn --include="*.tsx" --include="*.jsx" -E "color:\s*['\"]#|background:\s*['\"]#|borderColor:\s*['\"]#" src/
Hardcoded spacing (px values):
grep -rn --include="*.css" --include="*.scss" -E ':\s*[0-9]+px' src/ | grep -v "0px\|1px"
Inline styles in React:
grep -rn --include="*.tsx" --include="*.jsx" "style={{" src/
Tailwind arbitrary values (if using tokens with Tailwind):
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:
## 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:
/* 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:
// 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:
// 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:
// 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):
// .eslintrc.js
module.exports = {
rules: {
"no-hardcoded-colors": "error",
"no-hardcoded-spacing": "warn",
},
};
Stylelint for CSS:
npm install -D stylelint stylelint-declaration-strict-value
// .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
## 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
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 197k | Updated | Claude CodeCodex | Verified | Install |