Planning Frontend Design Orchestrator

Use this skill to run multi-style frontend concept ideation with strict pass isolation and maximum variety.

Config Source

• .claude/skills/planning-frontend-design-orchestrator/references/style-config.json

Reference Catalogs

• references/layout-uniqueness-catalog.json - 20 structural layout profiles
• references/style-config.json - Style families with per-pass overrides
• .claude/skills/frontend-design-subagent/references/available-libraries.json - CDN library catalog
• .claude/skills/frontend-design-subagent/references/asset-sources.json - Approved media download sources
• .claude/skills/frontend-design-subagent/references/external-inspiration-catalog.json - Per-pass specific inspiration URLs
• .claude/skills/frontend-design-subagent/references/product-context.md - Product data models, terminology, and content vocabulary

Workflow

1. Read the style config to get all style families and their pass definitions.
2. Read the uniqueness catalog, inspiration catalog, library catalog, and asset sources.
3. For each (style, pass) job, build a comprehensive creative brief that includes: a. Select a uniqueness profile (ensuring no two passes share the same profile). b. Apply per-pass paletteOverrides and typographyOverrides from the config. c. Include the pass's interactionProfile with all category selections and prompts. d. Include the pass's contentPersona for visual/tonal flavor. e. Include the product context from references/product-context.md — this defines all mock content (data models, terminology, view content, sample data). Content persona controls HOW it looks; product context controls WHAT it says. f. Include the pass's viewHints for per-view component directives. g. Include the pass's antiRepeat list as hard constraints. h. Include the specific inspiration references (not generic Awwwards categories). i. Include the available libraries catalog so the agent can choose 0-5 libraries. j. Include the asset sources catalog so the agent can optionally download media. k. Include the Professional Quality Standards checklist (see subagent SKILL.md). l. Dispatch as a Claude Code Task agent with subagent_type=general-purpose.
4. The Task agent generates ALL files from scratch (no template scripts).
5. After each pass completes, run scripts/validate-concepts-playwright.mjs --style <style> --pass <n> to capture desktop + mobile screenshots.
6. Visual Quality Review (REQUIRED — see details below).
7. After all passes complete, run scripts/validate-design-uniqueness.mjs for pairwise checks.
8. Write summary index for review.

Visual Quality Review (Step 6)

After Playwright screenshots are captured for each pass, the orchestrator MUST visually inspect the screenshots and validate design quality. This is not optional — a pass that generates files and screenshots but has quality defects is NOT complete.

How to Review

For each pass, use the Read tool to view at least 4 screenshots covering different views and both viewports:

1. validation/desktop/dashboard.png — Primary view, desktop
2. validation/mobile/dashboard.png — Primary view, mobile
3. validation/desktop/kanban.png — Complex layout view, desktop
4. validation/mobile/settings.png — Form-heavy view, mobile

Quality Checklist (all must pass)

On Failure

If ANY check fails:

1. Identify the specific issue (which view, which viewport, what's wrong).
2. Read the pass's index.html, style.css, and/or app.js to diagnose the root cause.
3. Fix the code directly (edit the files in the pass folder).
4. Re-run Playwright screenshots for that pass.
5. Re-review the fixed screenshots.
6. Repeat up to 2 fix cycles. If still failing after 2 attempts, write the issues to validation/quality-issues.json and flag for manual review, but continue with other passes.

Quality Report

After review, write validation/quality-review.json with this structure:

json
1{
2  "passId": "brutalist/pass-3",
3  "reviewedAt": "2026-02-15T...",
4  "screenshotsReviewed": ["desktop/dashboard.png", "mobile/dashboard.png", "desktop/kanban.png", "mobile/settings.png"],
5  "checks": {
6    "noBlankPages": { "pass": true, "notes": "" },
7    "textContrast": { "pass": true, "notes": "" },
8    "mobileResponsive": { "pass": true, "notes": "" },
9    "contentPopulated": { "pass": true, "notes": "" },
10    "layoutIntegrity": { "pass": true, "notes": "" },
11    "navigationVisible": { "pass": true, "notes": "" },
12    "visualPolish": { "pass": true, "notes": "" }
13  },
14  "overallPass": true,
15  "fixCycles": 0
16}

IMPORTANT: New Generations vs Edits

When the user asks for NEW generations:

• Scan existing pass folders per style to find the highest pass number
• Create NEW pass folders starting from the next number (e.g., if pass-1 and pass-2 exist, new passes are pass-3 and pass-4)
• Each generation run produces passesPerStyle new passes (default: 2) across all styles — the config defines how many per run, NOT the total cap
• Existing passes are preserved as-is
• New passes must be distinct from ALL existing passes (checked by uniqueness validation)

When the user asks for EDITS:

• Modify the specific pass folder they reference
• Re-run Playwright screenshots after editing

Per-Pass Variety System

Each pass variant in the style config includes these differentiation tools:

paletteOverrides

Different color palette per pass. Same style DNA, different color expression. A brutalist pass can be warm paper+red OR cool gray+electric blue — both are brutalist.

typographyOverrides

Different font families per pass within the style's typographic family. Mid-century pass-1 might use Playfair Display, pass-3 might use Fraunces. Both are serif-warm but visually distinct.

interactionProfile

Deliberate interaction design choices for every touchpoint — buttons, cards, page transitions, scroll reveals, hover states, toggles, tooltips, loading states, ambient motion, and micro-feedback. Each category can have multiple selections and an optional prompt guiding the feel. No two passes should share the same interaction profile.

contentPersona

Visual tone and metaphor per pass. The persona shapes the design language (how text, components, and interactions FEEL) while the product context from product-context.md shapes the actual content displayed (labels, metrics, column names, sample data). Content must always align with the app's real PRD.

viewHints

Per-view component/layout directives that force different patterns. Dashboard might use stat cards in one pass, radial charts in another. Kanban might use vertical columns in one, horizontal swimlanes in another.

antiRepeat

Explicit ban list from prior passes. If pass-1 used a left-rail nav and stat cards, pass-2's antiRepeat says "DO NOT use: left-rail nav, stat cards".

Required Artifacts Per Pass

• <style>/pass-<n>/index.html - Complete HTML with all 10 views
• <style>/pass-<n>/style.css - Full CSS with responsive breakpoints
• <style>/pass-<n>/app.js - Navigation, interactions, library init
• <style>/pass-<n>/README.md - Concept docs, library usage, design decisions
• <style>/pass-<n>/validation/handoff.json - Structural metadata
• <style>/pass-<n>/validation/inspiration-crossreference.json - Inspiration mapping

Required Visual Validation Artifacts

• <style>/pass-<n>/validation/desktop/<view>.png — Full-page screenshot per view at 1536x960
• <style>/pass-<n>/validation/desktop/<view>_segment-N.png — Viewport-height scroll segments (auto-generated for tall pages)
• <style>/pass-<n>/validation/mobile/<view>.png — Full-page screenshot per view at 390x844, 2x scale
• <style>/pass-<n>/validation/mobile/<view>_segment-N.png — Viewport-height scroll segments (auto-generated for tall pages)
• <style>/pass-<n>/validation/report.playwright.json — Structured report with viewport info and screenshot/segment counts

A pass is NOT considered complete until all view screenshots exist. The total count is dynamic (minimum 20 full-page + additional scroll segments). Run the Playwright validation script after each pass finishes generating files.

Optional Artifacts

• <style>/pass-<n>/assets/* - Downloaded media assets (SVGs, PNGs, Lottie JSON, video)

Scripts

• scripts/validate-concepts-playwright.mjs - Desktop + mobile screenshot capture for every view
• scripts/validate-design-uniqueness.mjs - Pairwise pass uniqueness checking

Notes

• Background images and media assets are OPTIONAL, not required
• CDN libraries are OPTIONAL — pure CSS is always valid
• Animation libraries are style-dependent, not mandated
• The agent picks libraries based on interaction profile fit, not by default
• Keep style config editable for easy iteration
• passesPerStyle in config determines how many NEW passes to generate per run (default: 2) — this is per-run, not a total cap