home / skills / phrazzld / claude-config / design-audit

design-audit skill

safe

This skill audits your design system for consistency, gaps, and accessibility, identifying tokens, violations, and design debt to improve cohesion.

npx playbooks add skill phrazzld/claude-config --skill design-audit

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.2 KB

---
name: design-audit
description: |
  DESIGN-AUDIT
effort: high
---

---
description: Audit current design system for consistency and debt
---

# DESIGN-AUDIT

Analyze the current design system for violations, gaps, and inconsistencies.

## What This Does

1. **Inventory tokens** — Colors, typography, spacing, shadows
2. **Check consistency** — Are tokens used consistently?
3. **Find violations** — Hardcoded values, magic numbers
4. **Assess accessibility** — WCAG compliance
5. **Report debt** — Design debt that's accumulated

## Process

### 1. Load Design Skills

```
Skill("design-tokens")        # Token patterns
Skill("ui-skills")            # Implementation constraints
Skill("web-interface-guidelines")  # Vercel standards
```

### 2. Extract Current Tokens

Scan for design token definitions:
- Tailwind config (`tailwind.config.ts`, `globals.css`)
- CSS variables
- Theme files
- Component defaults

### 3. Audit Token Usage

For each token category:

**Colors**:
- Are colors from the palette? Or hardcoded hex?
- Is there semantic naming (primary, error, success)?
- Dark mode support?

**Typography**:
- Font scales defined?
- Consistent heading hierarchy?
- Line heights appropriate?

**Spacing**:
- Spacing scale in use?
- Magic numbers in margins/padding?

**Components**:
- Consistent component patterns?
- Reusable primitives?
- Duplicated styles?

### 4. Accessibility Check

```
/rams — Score current state
```

Check:
- Color contrast (WCAG AA minimum)
- Focus states
- Touch targets
- Screen reader support

### 5. Report Findings

```markdown
## Design Audit: [Project Name]

### Token Inventory
- Colors: [count] defined, [violations] hardcoded
- Typography: [count] scales, [violations] magic sizes
- Spacing: [count] values, [violations] arbitrary

### Consistency Score: [X]/100

### Critical Issues
- [ ] [Issue] - [location] - [fix]

### Debt Items
- [ ] [Tech debt] - [impact] - [effort]

### RAMS Score: [X]/100

### Recommendations
1. [Priority fix]
2. [Improvement]
```

## Diagram Documentation

For design system diagrams (component hierarchy, token relationships), use `/beautiful-mermaid` for production-quality renders.

## Output

Audit report ready. Next: `/design-catalog` to explore new directions, or `/design-theme` to fix issues.

Overview

This skill audits an existing design system to find inconsistencies, violations, and accumulated design debt. It inventories tokens, evaluates component patterns, and generates an actionable report with severity, remediation, and accessibility scoring. The goal is a clear path to consistent, accessible, and maintainable UI systems.

How this skill works

The audit scans code and theme files for token definitions (colors, typography, spacing, shadows) and inspects component styles for hardcoded values and duplicated patterns. It runs accessibility checks—contrast, focus states, touch targets, and screen reader attributes—and computes scores for consistency and accessibility. The output is a prioritized report with token inventory, critical issues, debt items, and practical recommendations.

When to use it

Before a major UI redesign to baseline current system health
When onboarding a new design or engineering team to understand existing patterns
Prior to component library consolidation or migration (e.g., Tailwind to design tokens)
To identify accessibility gaps and ensure WCAG AA minimums
When technical or design debt is suspected to slow feature delivery

Best practices

Start with a full token inventory: CSS variables, theme files, and Tailwind config
Prioritize fixes that remove hardcoded colors and magic spacing values first
Assign severity and effort to each debt item to plan incremental remediation
Enforce semantic token naming (primary, error, surface) and dark-mode variants
Integrate automated linting and contrast checks into CI pipelines

Example use cases

Scan a repo to list all color tokens, detect hardcoded hex values, and report fixes
Assess heading and body typography for scale consistency and suggest line-height corrections
Detect duplicated component styles and recommend extraction into reusable primitives
Produce an accessibility RAMS score and highlight elements below WCAG AA contrast
Generate a prioritized remediation plan with estimated effort and impact

FAQ

What inputs does the audit need?

A codebase or build output with theme files, CSS/SCSS, Tailwind config, and component sources to scan for tokens and styles.

How are accessibility issues scored?

Accessibility is assessed against WCAG criteria like color contrast, focus visibility, touch target size, and semantic markup, and aggregated into a RAMS-style score.