Design Quality

Design Quality Engine

Three composable layers that produce better UI code — automatically (invisible quality floor), interactively (design conversation partner), and educationally (teaching tool).

Layer Architecture

┌─────────────────────────────────────────────┐
│              Project CLAUDE.md              │
│  layers: [craft, a11y]                     │
│  aesthetic: shadcn | preset:clean-functional│
│  overrides: { ... }                        │
└──────────────────┬──────────────────────────┘
                   │
         ┌─────────┴─────────┐
         │  Design Engine    │  ← this file (orchestrator)
         │  (always loaded)  │
         └─────────┬─────────┘
                   │
    ┌──────────────┼──────────────┐
    ▼              ▼              ▼
┌────────┐  ┌───────────┐  ┌─────────┐
│ Craft  │  │ Aesthetic  │  │  A11y   │
│craft.md│  │preset/DS  │  │ a11y.md │
└────────┘  └───────────┘  └─────────┘

Related Skills

/design:review produces a composite score with layer sub-scores. /design:a11y works as a standalone a11y-only shortcut.

Step 1: Load Project Config

Read the project's CLAUDE.md for a ## Design Quality section. Parse these fields:

Config Example

## Design Quality

**Layers:** craft, a11y
**Aesthetic:** clean-functional
**Strictness:** standard
**Teaching:** normal
**Auto-fix:** none
**Overrides:**
- measure: 60-80ch (wider for code documentation)

Smart Defaults (when no config exists)

If no ## Design Quality section is found:

• Layers: craft + a11y (both on)
• Aesthetic: clean-functional (fallback preset)
• Strictness: standard
• Teaching: normal
• Auto-fix: none
• Overrides: none

Design System Detection

When Aesthetic: design-system is set, look for:

1. Shadcn/ui components (components/ui/ directory)
2. Design tokens file (tokens.json, theme.ts, tailwind.config custom theme)
3. Figma-exported tokens

When a design system is detected, it replaces the aesthetic preset — the craft and a11y layers still apply on top.

Loading Sequence

1. Parse ## Design Quality from project CLAUDE.md (or apply smart defaults)
2. Load active layers:
   • If craft in layers → load craft.md
   • If a11y in layers → load a11y.md
3. Load aesthetic:
   • If preset name → load the matching file from presets/
   • If design-system → detect and load project's design system
   • If none → skip aesthetic layer
4. Load guard checks from guard-checks.md
5. Apply any overrides from config

Step 2: Skill Precedence

When this skill is active with a project preset, its rules take precedence over the generic frontend-design skill. The frontend-design skill's generic aesthetic guidance ("avoid Inter," "make unexpected choices") does NOT apply when a preset is configured. The preset defines the project's aesthetic — follow it.

Other design skills (interface-design, accessibility-a11y, ui-design-system) remain complementary.

Step 3: Inline Guard During Coding

When writing UI code, silently apply checks from all active layers:

1. Before writing a component, check the code against:
   • Craft checks — measure, rhythm, scale, weight, typeface constraints
   • Aesthetic checks (preset) — colors, fonts, spacing grid, elevation, motion
   • A11y checks — touch targets, ARIA labels, contrast, keyboard nav, WCAG 2.2
2. If violations found, flag them in your response BEFORE writing the code
3. Write the corrected code (not the violating version)
4. Apply teaching moments per the Teaching setting:
   • verbose: Explain every violation with context from the layer reference
   • normal: Explain the first occurrence of each concept per session
   • quiet: Just flag the violation, no explanation

Refer to guard-checks.md for the full checklist. Checks are tagged by layer — only run checks for active layers.

This is automatic — no user action needed. Use /design:review for the explicit version.

Platform Detection

Proactive Recommendations

Proactively suggest the right command at the right time. Don't wait for the user to remember — guide them through the workflow.

Recommendation Rules

1. Suggest once, don't nag. If the user skips a suggestion, don't repeat it.
2. Be brief. One sentence max.
3. Context-sensitive. Only suggest during UI work, not backend work.
4. Natural flow. Feel like a teammate's suggestion, not a popup.
5. Never block. Recommendations are always optional.

Preset System

Built-in Presets

Presets are in the presets/ directory.

Custom Presets

Create a new .md file in presets/ following the same structure. Reference it in CLAUDE.md:

## Design Quality
**Aesthetic:** my-custom-preset

Use /design:direction to generate a custom preset interactively.

Per-Session Override

"Use the premium-depth preset for this session"

Overrides the project default until the session ends.

Workflow Integration