design-review

Type	Skill
Plugin	awl-design · v0.0.4
Invoke	/awl-design:design-review
Tools	Read, Glob, Grep
Source	plugins/awl-design/skills/design-review/SKILL.md

When Claude uses it

Audits UI code (React, Vue, Svelte, CSS, HTML) against AWL design system tokens — flags hardcoded hex colors, wrong font families, non-token spacing, missing focus-visible, and missing dark mode. Use when asked to “review design”, “check styles”, “design audit”, “token compliance”, “UI compliance”, or “AWL compliance check”. Generates a prioritized violation report (P1-P3) with correct token suggestions.

Trigger phrases: review design · check styles · design audit · token compliance · UI compliance · AWL compliance check

Definition

You audit UI code against the AWL design system. Scan files, compare values to the token set, and report violations.

Workflow

1. Read references/design-tokens.json for the full token set
2. Read references/compliance-checklist.md for allowed values per category
3. Identify UI files to scan (user-specified or auto-detect via Glob)
4. Scan each file for violations
5. Generate a structured report

What to Scan

Auto-detect UI files unless the user specifies:

• **/*.tsx, **/*.jsx — React components
• **/*.vue — Vue components
• **/*.svelte — Svelte components
• **/*.css, **/*.scss — Stylesheets
• **/*.html — HTML files
• **/tailwind.config.* — Tailwind configuration

Exclude: node_modules/, dist/, build/, .next/

Violation Categories

P1 — Critical (must fix)

• Hardcoded hex colors not in token set
• Font families other than Museo Sans
• Missing focus-visible on interactive elements
• Missing dark mode support on custom components

P2 — Warning (should fix)

• Spacing values not on 4px grid
• Font sizes not in type scale
• Border-radius values not in token set
• Shadow values not matching tokens
• Arbitrary z-index values

P3 — Info (nice to fix)

• Animation durations not matching tokens
• Custom easing functions
• Missing hover/active states
• Inconsistent use of CSS variables vs hardcoded token values

Report Format

# AWL Design Compliance Report

**Files scanned**: X
**Violations found**: Y (P1: A, P2: B, P3: C)

## P1 — Critical

### [filename:line] Description
- Found: `color: #ff0000`
- Expected: Use a token value, e.g., `var(--color-red-source)` / `#f55f7a`

## P2 — Warning

### [filename:line] Description
- Found: `margin: 15px`
- Expected: Use spacing scale (closest: `var(--spacing-4)` / `16px`)

## P3 — Info

### [filename:line] Description
- Found: `transition: 200ms`
- Expected: Use duration token (closest: `var(--duration-fast)` / `300ms`)

Scanning Strategy

Use Grep to efficiently find potential violations:

1. Colors: Search for #[0-9a-fA-F]{3,8} patterns, compare against token hex values
2. Font sizes: Search for font-size: or fontSize with non-token values
3. Spacing: Search for margin|padding with pixel values not on 4px grid
4. Font families: Search for font-family declarations not using Museo Sans
5. Z-index: Search for z-index with non-token values
6. Border radius: Search for border-radius with non-token values

Important

• Only flag actual violations — don’t flag CSS variable usage (var(--token))
• Don’t flag Tailwind utility classes that map to tokens
• Context matters: button padding uses rem values per the pattern — don’t flag those
• Offer the correct token value for each violation