ai-design-gate

Design quality gate for Claude Code — 4-agent creative design team + 7-agent review panel (21 visual dimensions).

An AI-powered design self-iteration system that automatically designs, reviews, and iterates on your frontend pages until they meet your quality bar.

How it works

/creative-design "redesign hero section"
         │
         ▼
   4 Design Agents ──── Analyze ──── Design Plan ──── 2-Wave Build
   (Visual, Layout,      (parallel)   (user approves)   (parallel)
    Motion, Content)
         │
         ▼
   7 Review Agents ──── Score 21 Dimensions ──── Pass/Fail
   (parallel, 3 dims each)
         │
         ├── avg >= 9 & no must_fix ──► ✓ Approved
         └── otherwise ──► Iterate (discuss → rebuild → re-review, max 3x)

Install

npx ai-design-gate init

This will:

1. Ask you a few questions about your project (CSS prefixes, tech stack, thresholds)
2. Install skills, agents, and hooks into your .claude/ directory
3. Patch .claude/settings.json to enable the auto-review Stop hook

Requirements

• Node.js 18+
• Python 3.10+
• Claude Code CLI installed
• Playwright (optional, for screenshot-based review)

Usage

Start a creative design session

claude --agent creative-designer

Then describe what to improve:

/creative-design src/pages/home "redesign hero section with parallax scrolling"

Manual review

/design-review <session_id>

Auto-review (Stop hook)

When you have an active creative-design session, the Stop hook automatically triggers a design review whenever you try to complete a task. If the score is below threshold, it blocks completion and provides feedback.

Update

After changing .claude/design-review.config.json:

npx ai-design-gate update

This regenerates the markdown files (skills/agents) with your new config values. Python hooks read config at runtime, so they pick up changes automatically.

Configuration

All settings live in .claude/design-review.config.json:

| Setting | Default | Description | |---------|---------|-------------| | cssVarPrefixes | ["--brand-", "--accent-"] | CSS variable prefixes to enforce | | fontNames | [] | Font names (empty = no restriction) | | devServerPort | 3000 | Dev server port for screenshots | | viewports.mobile | 375×812 | Mobile viewport for screenshots | | viewports.desktop | 1440×900 | Desktop viewport for screenshots | | passThreshold | 9 | Minimum average score to pass (1-10) | | strongPushbackLimit | 4 | Score at or below triggers strong pushback | | maxIterations | 3 | Max design-review cycles before giving up | | bannedAnimations | [] | Animation effect names to flag as must_fix | | designSystemPath | "" | Path to design system file (for token validation) | | exemptedFiles | [] | Filenames exempt from hardcoded color checks | | sourceDir | "src/" | Source code directory | | stateDir | "state" | State directory for session data |

21 Review Dimensions

7 reviewer groups × 3 dimensions each:

| Group | Dimensions | |-------|-----------| | 色彩与对比 | color_palette, contrast, visual_weight_balance | | 排版与层次 | typography, visual_hierarchy, content_emphasis | | 布局与空间 | layout_structure, whitespace_density, spatial_layering | | 图像与叙事 | images_icons, image_text_integration, environmental_storytelling | | 动效与交互 | animations_transitions, interactivity, emotional_design | | 一致性与适配 | consistency, responsive_design, visual_flow | | 节奏与留白 | anchor_point_density, rhythm_repetition, purposeful_empty_space |

Severity Levels

• must_fix — Blocks release (accessibility, design system violations, layout breaks)
• should_fix — Impacts quality but not release-blocking
• nice_to_have — Polish and enhancement suggestions

Pass Criteria

• Average score >= threshold (default 9)
• Zero must_fix issues
• No strong pushback (score <= 4 on any dimension)

Architecture

.claude/
├── skills/
│   ├── creative-design/SKILL.md    # 4-agent design + build workflow
│   └── design-review/SKILL.md     # 7-agent review orchestration
├── agents/
│   ├── creative-designer.md        # Team lead agent config
│   └── design-reviewer.md          # Reviewer agent config
├── hooks/
│   ├── task-completed-design-review.py  # Stop hook (auto-triggers review)
│   └── lib/
│       ├── common.py               # Config loading, exit helpers
│       ├── state.py                # Design loop state management
│       ├── design_grader.py        # Programmatic 21-dimension grading
│       └── tokens.py               # Design token validation
└── design-review.config.json       # Your configuration

License

MIT