Uiux

---
name: uiux
description: Establishes a design philosophy based on kickoff outputs, and generates a design system/wireframes/HTML prototype. Recommended flow — /prd → /kickoff → /uiux
argument-hint: '[PRD.md path (optional)]'
disable-model-invocation: false
allowed-tools: Task, Read, Glob, Grep, Write, Edit, Bash, WebSearch
---
<!-- AUTO-GENERATED by scripts/gen_skills.py — DO NOT EDIT. Edit SKILL.md.tmpl instead. -->

## Kit Preamble — uiux

### Kit Script Root
Kit root: `${CLAUDE_PLUGIN_ROOT}`
- Absolute path above → plugin install (substituted at load time; no project
  `scripts/` dir): prefix every kit script command with it, e.g.
  `bash <kit-root>/scripts/checkpoint.sh …`. Absolute paths also work from worktrees.
- Literal `${…}` placeholder above → standalone layout: run commands as written.

### Project Context Detection
Run these checks silently at the start. Use results to adapt behavior:
- `[ -f issues.md ]` — if true, this project uses the sprint system. Respect issue numbering and STATUS.md.
- `[ -f docs/sprint_state.md ]` — if true and Status shows `running`, a sprint is active. Be aware of parallel work in worktrees.
- `[ -f docs/prd_digest.md ]` — if true, read it for quick project context before starting.

### Kit Rules
- Verify `gh auth status` before any GitHub operation.
## Prerequisites
- `/kickoff` must be run first so that the following files exist:
  - `docs/ux_spec.md` (core input — IA, flows, screen inventory)
  - `docs/requirements.md` (functional/non-functional requirements)
  - `docs/architecture.md` (tech stack reference)
- The PRD file is supplementary reference. If kickoff outputs are missing, guide the user to run `/kickoff`.

## Algorithm

### Phase 1 — Context Gathering
1) Read kickoff outputs (required):
   - `docs/ux_spec.md` — extract screen inventory, IA, flows
   - `docs/requirements.md` — identify UI elements from functional requirements
   - `docs/architecture.md` — confirm tech stack, API endpoints
2) Read PRD (`$ARGUMENTS` or `PRD.md`) as supplementary context. If `docs/prd_digest.md` exists, read it for quick PRD summary.
3) If `docs/ux_spec.md` does not exist:
   - Stop and tell the user: "Kickoff outputs are missing. Please run `/kickoff PRD.md` first."
   - Exception: if the user explicitly wants to skip kickoff, proceed with PRD only (warn about limited context).
**Caching rule**: All documents read in Phase 1 (`docs/ux_spec.md`, `docs/requirements.md`, `docs/architecture.md`, PRD) are reused across all subsequent Phases. Do not re-read the same file with the Read tool.

4) Scan the project for existing UI code, then choose the working mode:
   - Glob for `**/*.html`, `**/*.css`, `**/*.tsx`, `**/*.jsx`, `**/*.vue`, `**/*.svelte`
   - If found, read key files to understand current design patterns and tech stack.

   **Mode selection — `create` or `extend`** (ISSUE-054):
   - **Nothing found** → mode is `create`. Proceed exactly as this skill always
     has; nothing below applies.
   - **Found existing UI code** → ask the user which mode they want, quoting what you
     detected (file count and the token-bearing files you saw):
     - `create` — design a new aesthetic. The existing UI will not constrain it.
     - `extend` — read the design that already ships and add to it.
     **Never switch modes silently.** Detection proposes; the user decides. If the
     user does not answer, default to `create` (today's behaviour) and say so.

   **On `extend` only** — invoke the **design-scanner** agent via the Task tool
   before the design interview. Pass it:
   - the platform: `web`
   - the token-bearing files you detected. On `web` those live in
     CSS custom properties in stylesheets, `tailwind.config.*` theme keys, styled-components / emotion theme objects, and the component files that consume them.

   The agent returns a structured Design Scan report. It has no write tools; **you**
   write `docs/design_system.md` from its report.

   **Overwrite guard (MANDATORY)** — before writing, check whether `docs/design_system.md`
   already exists. If it does not, write it and continue. **If that file already
   exists, STOP** and ask the user, quoting its line count and last-modified date so
   they can see what is at stake:
   - `1) overwrite` — replace it; the previous content survives only in git history.
   - `2) write alongside` — write `docs/design_system.extracted.md` instead and show a summary of how
     it differs from the current file. Nothing existing is touched.
   - `3) cancel` — stop `extend` mode here.
   **Do not write until the user answers.** A hand-maintained design system is the one
   artifact this mode can destroy, and "it's in git" is not consent.

   When transcribing the report into whichever file you write, preserve its tags
   verbatim:
   - `[CONFIRMED]` claims keep their `file:line` reference. Never promote an
     `[INFERRED]` claim to `[CONFIRMED]`, and never drop a tag when transcribing.
   - Carry over `Dead tokens`, `Gaps`, and undeclared-but-repeated values. These are
     findings about the host product, not noise to tidy away.
   - If the report says `extraction_verdict: insufficient`, tell the user verbatim and
     ask whether to continue in `extend` (mostly-`[INFERRED]` system) or fall back to
     `create`. Do not decide this silently.

   **What `extend` changes downstream** (the mode contract — apply all of it):
   - **Design philosophy**: do NOT commit to a new aesthetic direction. Name the
     aesthetic the codebase already has, and take the Signature Move from the
     agent's `signature_move` field. If it reported `none found`, say so to the user
     and agree on one derived from an existing recurring pattern — never invent one
     the codebase does not already show.
   - **Design interview**: reframe from "what should this be?" to "what should change,
     and what must stay?" Answers are constraints on the delta, not on the whole system.
   - **Pilot gate**: the specificity check becomes a **consistency check** — instead of
     "name 3 details that only make sense for THIS product", ask "name 3 details that
     match the extracted system, citing its `file:line` provenance". A pilot that reads
     as a redesign FAILS the gate even if it is distinctive.
   - **AI Tell sweep**: when the host codebase already uses a listed tell, record it as a
     `Brief overrides:` bullet quoting the source (`existing product convention —
     <file:line>`) instead of rewriting the product's own conventions.

### Phase 1.5 — Design Interview (CRITICAL — drives differentiation)
4.5) Ask the user the following questions to anchor the design direction.
   These answers become binding constraints for Phase 2.
   Present all questions at once (not one-by-one) and wait for answers.
   Also tell the user: "If any of these are hard to answer right now, just say 'skip'. You can also skip the entire interview."

   a) **Brand Personality**: "If this product were a person, who would they be?"
      (e.g., a luxury hotel concierge, a neighborhood cafe barista, a strict operating room nurse, a playful friend)

   b) **Emotional Target**: "What one emotion do you want users to feel when they see the first screen?"
      (e.g., trust, curiosity, relief, excitement, calm)

   c) **Anti-Reference**: "What competing product or design should this absolutely NOT look like?"
      (a feeling you want to avoid, or a specific product name)

   d) **Aspiration Reference**: "Is there a product or brand you'd like to reference for design? (doesn't have to be the same domain)"
      (e.g., Stripe's cleanliness, Nintendo's playfulness, Aesop's luxury)

5) Handle user response:

   **Case A — User answers (partially or fully)**:
   Record answers in memory — these become HARD CONSTRAINTS for Phase 2.
   If the user skips individual questions, note them as "unconstrained" but still avoid generic defaults.

   **Case B — User skips the entire interview** (says "skip", "pass", etc.):
   - Do NOT silently proceed with generic defaults.
   - Instead, the agent MUST auto-derive initial constraints from the PRD/UX spec:
     a) Brand Personality → infer from target user personas and product category in PRD
     b) Emotional Target → infer from the product's core value proposition
     c) Anti-Reference → infer from competitor analysis in PRD (if any), otherwise mark "unconstrained"
     d) Aspiration Reference → mark "unconstrained"
   - Present the auto-derived constraints to the user: "Since you skipped the interview, here's what I inferred from the PRD: [constraints]. Shall I proceed with these?"
   - If approved, proceed with these as soft constraints (not hard).
   - If rejected, re-offer the interview questions or accept corrections.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill uiux --phase context`
> Verifies `docs/ux_spec.md` exists. Also self-verify: PRD was read, interview answers (or auto-derived constraints) are recorded.
> If exit code ≠ 0 or any required input is missing: STOP and report to user.

### Phase 2 — Design Philosophy (CRITICAL — before any code)
6) Analyze the product's identity from PRD and UX spec:
   - Who are the users? What's the emotional tone?
   - What category does this product belong to? (SaaS, consumer, creative tool, enterprise, etc.)
   - Are there competitor/reference products mentioned?
6.5) **Reference Research — image-grounded only** (NO WebFetch for visual extraction).

   WebFetch returns parsed text, not pixels. Asking the model to extract hex values or font pairings from a Dribbble/Mobbin URL via WebFetch is fabrication. Visual references MUST arrive as actual images.

   Pick exactly ONE of three paths:

   - **Path (a) — user-provided images** (preferred):
     - The user supplies 1–3 image references (image URLs ending in `.png`/`.jpg`/`.webp` OR local file paths).
     - Read each image with the Read tool (image input). The model sees actual pixels.
     - For each image, extract concrete cues from what you actually see: dominant hex color guesses, font category guesses (serif/grotesque/mono with weight), composition (grid, density, alignment), background treatment, shadow style. Mark guesses with "≈" when sampling color from rendered output.

   - **Path (b) — page URLs**:
     - For each reference page URL, run:
       ```bash
       python3 scripts/capture_reference.py <url>
       ```
       This headless-captures the page to `docs/references/<slug>.png`. If the script exits non-zero (no browser backend installed), STOP this path and either install Playwright/Chromium OR switch to Path (a) OR Path (c).
     - Read every captured PNG via the Read tool.
     - Extract the same kinds of cues as Path (a), grounded in the captured image.

   - **Path (c) — no images available**:
     - Skip the Reference Anchors section entirely. Print this one-line warning to the user:
       `Reference Anchor skipped: no image provided. Pass 1–3 image paths or a page URL (with Playwright/Chrome installed) to populate this section.`
     - Proceed to Phase 2 step 7 (aesthetic direction) WITHOUT a Reference Anchors section. The Signature Move + Decision Matrix still anchor the design — references are an additional, not required, signal.

   **Anti-reference (separate from path choice)**: WebSearch is still acceptable for *titles* of anti-references (e.g., "what makes corporate B2B SaaS dashboards generic"). Anti-cues are written from the model's own knowledge of the pattern being avoided — they are not visual extractions and do not require image grounding.

   **Synthesis** (when Path (a) or (b) ran successfully — output goes into `docs/design_philosophy.md` "Reference Anchors"):
   - **2–3 strong cues to adopt**, each as a single bullet with: cue (≤12 words) — exact value or token (e.g., `#1A1A1A on #F5EFE6`, `Fraunces 96/0.92 + Inter Tight 14`) — **source image path under `docs/references/` OR the user-provided image URL**. Strong = present in the chosen images, specific enough that no Phase 5 implementer can fall back to a default. Fewer-and-deeper beats more-and-shallow: 5 cues averaged out as "generic premium SaaS"; 2–3 force a direction.
   - **1 literal quote** (MANDATORY when Phase 1.5 interview was NOT skipped): a specific word, number, or glyph drawn from the brand or domain that MUST appear **verbatim** in the rendered prototype. Format: `literal_quote: "<exact string>" — <where it appears>`. Examples:
     - `literal_quote: "조용한" — set in 168pt Fraunces, hero headline`
     - `literal_quote: "47.2-A" — sample order ID, shown in mono on the order detail screen`
     - `literal_quote: "회" — quantity unit in the picker`
     - Reject abstract concepts here (`"luxury"`, `"trust"`, `"premium"`) — the literal quote is text/digits/glyphs the prototype renders, not adjectives.
   - **3–5 cues to explicitly avoid**, each with one-line reason tied to the anti-reference.
   - Each adopted cue must be specific enough that a Phase 5 implementer cannot fall back to a default. Prose-only cues like "warm palette" or "bold type" are rejected — re-do them with numbers/tokens.
   - Never invent a hex value or font name without an image to point at. If an extracted detail is uncertain, mark it `≈` (approximate) and leave a comment about which image it came from.

   **Verbatim render check** — Phase 5B is required to render the `literal_quote` string verbatim in at least one HTML file under `prototype/screens/`. The Phase 2 CHECKPOINT below verifies the field is populated; Phase 5B verifies it actually appears in output.
7) Commit to a BOLD aesthetic direction. Choose one and execute with precision:
   - Brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined,
     playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel,
     industrial/utilitarian, dark/moody, lo-fi/zine, handcrafted/artisanal.
   - Or create a hybrid direction true to the product's identity.
8) Generate `docs/design_philosophy.md`:
   - Named aesthetic (2-3 words, e.g., "Brutalist Joy", "Chromatic Silence")
   - 2-3 paragraphs: how the philosophy manifests through space/form, color/material, scale/rhythm, composition
   - **Signature Move** (MANDATORY — the single biggest anti-slop anchor): one specific, non-default visual decision with exact numeric values or token names that MUST appear on every screen of the prototype. Must be:
     - **Numeric or token-named** (px / % / deg / ms / `var(--token)`) — never prose-only.
     - **Implementable in CSS via 1–3 properties** on a reusable class.
     - **Visible on every screen**, not just hero/landing.
     - Bad (rejected — too soft): "Bold typography", "Warm color palette", "Generous whitespace"
     - Good examples:
       - "All primary CTAs cast `box-shadow: -8px 16px 0 var(--accent)` — offset only, never blurred, never centered"
       - "Every card uses `border-radius: 14px 4px 14px 4px` (asymmetric)"
       - "Section dividers: `1px solid var(--accent)` with `margin-right: 12px` indent — never full-width rules"
       - "Screen titles: Fraunces 96/0.92, `letter-spacing: -0.04em`, `transform: skew(-2deg)`"
       - "All hover states: `translateY(-2px)` + `border-left: 4px solid var(--ink)` — no opacity changes"
   - **Reference Anchors** section (from step 6.5 image-grounded research): 2–3 strong adopted cues each pointing at an image (path under `docs/references/` or a user-provided image URL/path), 1 `literal_quote:` field (mandatory unless Phase 1.5 was skipped), 3–5 avoided cues with reasons. If step 6.5 took Path (c) and skipped this section, omit it here too and proceed.
   - What makes this design UNFORGETTABLE — the one thing someone will remember (should align with and reinforce the Signature Move).
9) Present the design philosophy to the user and ask for approval before proceeding.
   - If rejected, iterate on the direction.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill uiux --phase philosophy`
> The script verifies presence: the file, (a)'s Signature Move, (b), and the `literal_quote:` field. If exit code ≠ 0: STOP, fix, re-run. Depth stays model-side — self-verify below (ISSUE-057).
> Verify `docs/design_philosophy.md` exists with:
> (a) a **Signature Move** that is numeric/token-specific (not prose-only);
> (b) either a populated **Reference Anchors** section OR an explicit "Reference Anchors skipped (no image input)" line; AND
> (c) when Reference Anchors is present, exactly **2–3** adopted cues (not 1, not 4+), each citing an image path, plus a `literal_quote:` field with a concrete word/number/glyph (NOT an adjective like "luxury"). The literal_quote may only be omitted if Phase 1.5 interview was explicitly skipped — in which case `literal_quote: (skipped — interview not run)` must appear instead of the field being absent.
> If any of (a) / (b) / (c) fails: STOP and fix before proceeding.

### Phase 3 — Design System
9) Generate `docs/design_system.md` reflecting the chosen aesthetic:
   - **Color palette**: Hex values. Dominant colors with sharp accents — NOT timid, evenly-distributed palettes. Choose a direction: bold/saturated, moody/restrained, or high-contrast/minimal.
     - Ensure no semantic color (warning, error, etc.) shares the exact same hex value as a user-selectable/decorative color
   - **Typography**: Specific Google Fonts choices. Distinctive display font + refined body font. Extreme contrast in scale (3x+ ratio between heading and body). NEVER default to Inter, Roboto, Arial, Open Sans.
   - **Spacing**: 4px-based scale (4, 8, 12, 16, 24, 32, 48, 64)
   - **Components**: Buttons, inputs, cards, modals, navigation, tables, badges, toasts — each with variants and states (default, hover, active, focus, disabled, loading)
     - **ALL button variants** (primary, secondary, destructive, ghost) MUST have full CSS with ALL states — not just the primary variant in CSS and others in prose
     - **App-specific composite components** (e.g., FAB, list items, progress rings, pickers) MUST also be defined with full CSS — not just generic UI primitives
   - **Motion tokens**: Transition durations, easing curves, animation-delay stagger values
     - Performance rules: only `transform` and `opacity` are GPU-composited. Do NOT list `box-shadow`.
   - All values expressed as CSS custom properties
10) Ask the user if the design system direction looks right before proceeding.

### Phase 4 — Wireframes & Interaction Spec
11) Generate `docs/wireframes.md`:
    - Screen inventory (one section per screen from UX spec)
    - Layout description with component placement
    - Spatial composition: asymmetry, overlap, grid-breaking elements, negative space strategy
    - Content hierarchy and information architecture
    - Responsive behavior per breakpoint (mobile 375px / tablet 768px / desktop 1280px)
    - **Numeric layout commitments (MANDATORY)**: per screen, declare specific values, not prose. The screen entry MUST include:
      - `grid-template-columns` or column ratios — e.g., `7fr 3fr`, `1fr 2fr 1fr`, `repeat(12, 1fr)`
      - Gap / gutter in px — e.g., `gap: 64px`, `column-gap: 32px; row-gap: 96px`
      - Container max-width and side padding — e.g., `max-width: 1280px; padding: 0 80px`
      - Asymmetry deltas as exact values — e.g., `hero text overhangs column 1 by -120px`, `image overhangs viewport right edge by 48px`, `sidebar overlaps content by 24px`
      - Per-breakpoint overrides at mobile 375 / tablet 768 / desktop 1280 — list only the values that change
    - Reject prose-only layout phrases ("asymmetric grid", "wide layout", "generous whitespace"). Re-state every layout description with at least one numeric value tied to a CSS property.
    - **PRD feature cross-check**: After writing, verify EVERY PRD feature (including P2) has a corresponding wireframe element. P2 features should show placement with a "P2 — deferred" note.
12) Generate `docs/interactions.md`:
    - User flow diagrams (text-based state machines) — each with Trigger, Preconditions, Steps, Success/Error/Edge Cases
    - Screen transition map with animation descriptions
    - **Shared Element Transitions**: document candidates or explicitly state "none planned" with rationale
    - Loading / empty / error states per screen
    - Form validation rules
    - **Drag & Drop**: if PRD mentions reordering/dragging, include full spec (drag start, drag over, drop, cancel). If not applicable, state "N/A"
    - High-impact motion moments: page-load stagger reveals, scroll-triggered effects, hover surprises
    - **Template completeness check**: verify every section from the template is present. If not applicable, add "N/A — [reason]"

### Phase 4.5 — Copy Guide
12.5) Run the **copywriter** agent to generate `docs/copy_guide.md`:
    - Input: `docs/ux_spec.md`, `docs/design_philosophy.md`, `docs/wireframes.md`, `docs/interactions.md`, PRD
    - Output: Voice & tone definition, copy inventory per screen (labels, placeholders, empty/error/success states, confirmations, toasts), patterns, glossary
    - Retrieve the contents of `docs/ux_spec.md` and PRD already read in Phase 1, and the documents generated in Phase 2-4, from memory and include them in the subagent prompt — do not re-read the files.
    - The copy guide must align with the design philosophy's tone (e.g., "Ink & Paper" → restrained, precise language).
    - **Banned copy tells (enforce on every string)**: zero em-dashes (`—`/`–`) — use `-`, comma, period, or colon; no filler verbs (Elevate, Seamless, Unleash, Next-Gen, Revolutionize); no generic person names (John Doe) or startup-slop brand names (Acme, Nexus, SmartFlow); no fake-perfect numbers (`99.99%`, round `50%`) — use organic values. See "Specific AI Tells" in Anti-AI-Slop Rules.
    - This step MUST complete before Phase 5 so the prototype uses real copy, not placeholder text.

> **CHECKPOINT — MANDATORY — NEVER SKIP**
> Run: `bash scripts/checkpoint.sh --skill uiux --phase system`
> Verifies `docs/design_system.md` (or `docs/design_system.extracted.md` in extend mode), `docs/wireframes.md`, `docs/interactions.md`, and `docs/copy_guide.md` all exist.
> Cross-check (model-side): every component in wireframes has a definition in design_system.md.
> If exit code ≠ 0 or the cross-check fails: STOP and generate/fix it before proceeding.

### Phase 5A — Pilot Screen Gate (catches AI slop before full generation)
13) Ensure `prototype/` and `prototype/screens/` directories exist.
14) Generate `prototype/styles.css`:
    - CSS custom properties from design system (colors, spacing, typography, radii, shadows, motion tokens)
    - CSS reset / normalize
    - Utility classes (flex, grid, spacing, text alignment)
    - Component styles matching design system — every component with all states
    - Responsive breakpoint media queries (mobile-first)
    - Background & depth effects: gradient meshes, noise textures, layered transparencies, grain overlays (as appropriate for the aesthetic)
    - Dark mode via `prefers-color-scheme` (if appropriate for the aesthetic)
    - CSS keyframe animations for page-load reveals, stagger effects, hover transitions
    - **Layout positioning rule**: `.sidebar`, `.nav`, and similar layout-structural elements MUST use `position: static` (or `relative`/`sticky` if scroll-pinning is intended) — NEVER `position: fixed` or `position: absolute`. Fixed/absolute positioning pulls the element out of the document flow, collapsing the grid column it occupied. Sidebars participate in grid/flex layout as normal flow children; scroll-pinning should use `position: sticky` with a `top` value.
    - **Viewport-height rule**: full-height hero/section uses `min-height: 100dvh` — NEVER `100vh` / `height: 100vh`. `100vh` ignores the iOS Safari address bar and causes layout jump on mobile.
    - **Multi-column rule**: build column layouts with CSS Grid (`grid-template-columns`), NEVER flex percentage math (`width: calc(33% - 1rem)`), which breaks on gap rounding.
    - **Layout-safety mechanics (deterministic — all mandatory):**
      - `overflow-x: clip` on BOTH `html` and `body` (use `clip`, not `hidden` — `clip` preserves descendant `sticky`/`fixed`). The page must not scroll horizontally at any width 320–1920px.
      - Any `grid-template-columns`/`-rows` track that holds an image uses `minmax(0, 1fr)`, never bare `1fr` (bare `1fr` = `minmax(auto, 1fr)` → a large native image sets a huge min-width and overflows on phones).
      - Display headers (`h1`, `.hero__title`, section titles) set `overflow-wrap: anywhere; min-width: 0` so long compound words can break.
      - All-caps display type uses `line-height ≥ 1.0` (never < 1.0 — cap-tops collide with the line below when the heading wraps).
      - At most ONE `position: sticky; top: 0` element (the top nav). Any other sticky element offsets to `top: var(--banner-height)` and uses a lower z-index than the nav (split `--z-sticky` from `--z-sticky-nav`).
      - Flex rows mixing height-different children (button+text, icon+text) set `align-items: center`.
    - **Motion mechanics (deterministic — all mandatory):**
      - NEVER `transition: all` / `transition-all` — name the exact properties.
      - Animate only `transform` / `opacity` / `filter`; never animate `width`, `height`, `top`, `left`, `margin`, `padding`.
      - No uniform `scale` hover applied across unrelated elements; no stacking multiple hover effects (translate+scale+shadow+rotate) on one element.
      - Reserve bouncy/overshoot easings (`cubic-bezier(…, 1.56, …)`) for physical/drag interactions only — never on buttons, modals, or tooltips.
      - Focus rings appear INSTANTLY (no `transition` on `outline`) and are built from `outline`, never `border`.
    - **Input-state mechanics (8 states; fail on any):** `border-width` stays `1px` across default/hover/focus/error (state changes go to `outline`/`box-shadow`/`border-color`, never `border-width` — it shifts layout); focus ring is `outline: 2px solid var(--color-focus); outline-offset: 1px` (reserve `outline: 2px solid transparent` at rest); input height == adjacent button height (44px floor); reserve the helper/error slot with `min-height: 1lh` so an appearing error doesn't push the page; disabled needs `opacity` + `cursor: not-allowed` + the `disabled`/`aria-disabled` attribute (never opacity alone).
    - **Signature Move encoding** (MANDATORY): the Signature Move from `docs/design_philosophy.md` MUST be encoded as a reusable utility class or component variant (e.g., `.cta-primary { box-shadow: -8px 16px 0 var(--accent); }`). If no natural component owns it, create a dedicated class named `.signature-<move>`. This class must be referenced from at least one selector that will appear on every screen.
14.5) **Pilot screens selection & render (multi-archetype)**:
    - Classify every screen in `docs/wireframes.md` into one of these archetypes: `list/feed`, `detail/show`, `form/input`, `hub/dashboard`, `modal-wizard`, `content/long-form`, `empty/cold-start`.
    - Pick **TWO pilot screens from the two most-distinct archetypes** present in the inventory. Typically one consumption-oriented (list / detail / hub) plus one input-oriented (form / wizard). If only one archetype exists in the inventory, fall back to a single pilot and note this in the gate.
    - Generate ONLY these pilot HTML files in `prototype/screens/` following all the rules listed in step 15 below. Both pilots share `styles.css` from step 14.
    - Do NOT generate other screens or `prototype/index.html` yet.
14.6) **PILOT GATE — render → observe → critique → specificity → auto-correct → user HOLD**
    Generator-as-judge fails: the same context that produced the pilot will not reliably catch its own slop. This phase routes the critique through a separate sub-agent context and runs up to 3 auto-correction cycles before presenting to the user. Do not auto-proceed past Step 3.

    - **Step 1 — Render**: for each pilot HTML, run:
      ```
      python3 scripts/screenshot_pilot.py prototype/screens/<pilot>.html --viewport 1280x800 --full-page
      ```
      Produces `prototype/screens/<pilot>.png`. If the script exits "no screenshot backend available":
        - DO NOT silently skip the critique. Enter **degraded mode** for Steps 2.0–2.2: critique runs against the HTML/CSS *source* instead of the rendered PNG.
        - Record `pilot_degraded: no_screenshot_backend` in the critique log so the user sees the limitation.

    - **Step 2.0 — Neutral observation** (mandatory; do this BEFORE any judgment).
      For each pilot, write 5 plain factual statements about what you see in the PNG (or HTML in degraded mode).
      **Banned vocabulary in this step**: `signature move`, `aesthetic`, `archetype`, `philosophy`, `direction`, `taste`, `slop`, `generic`, `bold`, `restrained`, `premium`, brand names, the chosen aesthetic name. Use only colors, sizes, shapes, positions, counts, content categories.
      Output to `prototype/screens/<pilot>.observations.md` like:
      ```
      1. Top bar 64px tall, dark navy background, four icon buttons right-aligned.
      2. Hero headline reads "조용한", left-aligned, 168pt serif, off-white text.
      3. Below the hero, three cards in a row at 24% / 38% / 38% widths.
      4. Bottom-right floating action button, 56px, orange fill, no border.
      5. Sticky bottom toolbar with four state-switcher buttons.
      ```
      If you catch yourself reaching for a banned word, restart Step 2.0 — the observation is the input that prevents the critique from agreeing with itself.

    - **Step 2.1 — Separate-context critique** (mandatory). Invoke `design-auditor` via the Task tool to evaluate the pilot from a fresh context. **Do NOT inline-critique in the generator's context.**
      Pass the auditor:
        - the pilot PNG path (or HTML path in degraded mode)
        - `prototype/screens/<pilot>.observations.md`
        - `docs/design_philosophy.md` (so it knows the system claim it should check)
        - `docs/design_system.md`
      Ask it to return:
        - the 6-axis score (Philosophy / Hierarchy / Execution / Specificity / Restraint / Variety), each 1–5
        - one piece of cited evidence per axis, referencing observation indices (e.g., "Specificity 2 — observations 2,3 are interchangeable with any landing page")
        - a list of slop signals it flags
      Where ui-reviewer's scope applies (state coverage in pilots, copy usage), also invoke `ui-reviewer` via the Task tool with the same inputs. The two sub-agents' scopes are disjoint (per ISSUE-013) — do not deduplicate findings, surface both.
      Save the structured output to `prototype/screens/<pilot>.critique.md`.

    - **Step 2.2 — Specificity check** (mandatory). Ask the design-auditor (still in its separate context) to answer:
      *"Name 3 details visible in this pilot that ONLY make sense for THIS specific product / domain / user. Generic UI primitives ('a card', 'a hero', 'a button') do not count. Domain content does count (real entity names, the literal_quote from Reference Anchors, domain-specific units, brand-specific shortcuts). If you can list fewer than 3, the pilot FAILs specificity."*
      The literal_quote (from ISSUE-012) counts as exactly **1** of the 3 — not 0, not 2+. The other 2 must come from independent product/domain details.
      Specificity FAIL → treat as a critique failure feeding Step 2.3.

    - **Step 2.3 — Auto-correction cycle** (hard cap N=3 rounds). If any axis score < 3, OR Step 2.2 returns FAIL, OR slop signals are flagged:
      1. Identify the correct layer to patch:
         - Philosophy / Specificity < 3 → revisit Phase 2 step 8 (`docs/design_philosophy.md`).
         - Hierarchy / Execution / Restraint < 3 → revisit Phase 3 design system (`docs/design_system.md`) or Phase 4 layout numbers.
         - Variety < 3 → re-pick the pilot archetype or restructure the pilot itself.
         - Specificity FAIL → either add concrete product details to the pilot or, if Phase 1.5 was skipped, document that and proceed.
      2. Apply the patch.
      3. Re-screenshot (Step 1) → re-observe (Step 2.0) → re-critique (Step 2.1) → re-specificity (Step 2.2).
      4. Increment the cycle counter. Append a one-line summary to `prototype/screens/<pilot>.cycles.log`:
         `cycle N: layer=<L> change="<short summary>" scores=P5 H4 E5 S3 R5 V4 specificity=PASS|FAIL`.
      5. **Hard stop at N=3**. After the third unsuccessful cycle, freeze the pilot and surface to the user with the full cycle history. Do NOT loop indefinitely.
      Record the final scores as a one-line stamp at the top of `styles.css`: `/* pre-emit critique cycle=N: P5 H4 E5 S4 R5 V5 specificity=PASS */`.

    - **Step 3 — User gate**: present both pilots to the user.
      - Give the exact open commands: `open prototype/screens/<pilot1>.html` and `open prototype/screens/<pilot2>.html`.
      - Share `prototype/screens/<pilot>.critique.md` (Step 2.1 output) and `prototype/screens/<pilot>.cycles.log` (Step 2.3 history) so the user sees what was caught and what changed.
      - If Step 1 entered degraded mode, say so explicitly.
      - Ask: "Do both pilots match the design philosophy? Specifically:
        (a) Is the **Signature Move** (`<paste exact text>`) visible and applied in both?
        (b) Do they feel like `<aesthetic name>` and read as the same family across the two archetypes?
        (c) Do the 3 product-specific details from the specificity check belong to *this* product?"
      - WAIT for explicit approval before continuing to Phase 5B.

    - If rejected: identify which layer the problem lives at and fix there before regenerating the pilots:
      - Signature Move wrong/absent → revisit Phase 2 step 8.
      - Color / type / spacing tokens off → revisit Phase 3 design system.
      - Layout reads as generic → revisit Phase 4 numeric layout commitments.
      - Tokens and layout are right but implementation is generic → fix `styles.css` and pilot HTML only.
    - Do NOT proceed to Phase 5B with an unaddressed pilot rejection.

### Phase 5B — Full Prototype (after pilot approval)
15) Generate remaining screen HTML files in `prototype/screens/`:
    - One HTML file per remaining screen identified in wireframes (the pilots are already done).
    - **Use the approved pilots as the visual template** — match their component usage, spacing rhythm, Signature Move application, and overall composition language. New screens should feel like they belong to the same family across both consumption- and input-oriented archetypes. Do not re-explore the aesthetic mid-prototype.
    - Semantic HTML5 structure (`<nav>`, `<main>`, `<section>`, `<article>`, `<aside>`, `<header>`, `<footer>`)
    - Google Fonts loaded via `<link>` tag (single CDN exception — fonts only)
    - `<meta name="viewport">` for responsiveness
    - Linked to `../styles.css`
    - Responsive layout reflecting wireframe spatial composition
    - Use actual copy from `docs/copy_guide.md` — labels, placeholders, empty states, error messages. NOT placeholder text.
    - All states represented AND togglable via a visible state-switcher toolbar:
      - Add a small floating toolbar at the bottom of each screen with buttons: "Default", "Loading", "Empty", "Error"
      - Clicking each button shows the corresponding state — reviewers should NOT need the browser console
    - Accessibility:
      - NEVER use `outline: none` on `:focus` without `:focus-visible` fallback
      - All `role="button"` elements MUST have `keydown` handlers for Enter/Space
      - All `role="radiogroup"` elements MUST support arrow-key navigation
      - Placeholder text contrast >= 3:1
      - `alt` text, form `<label>`s, ARIA attributes, color contrast >= 4.5:1, keyboard navigable
    - **Signature Move per-screen check**: the Signature Move's reusable class/component must appear at least once on every screen.
16) Generate `prototype/index.html`:
    - Navigation hub linking to all screen prototypes
    - Product name, design philosophy name, screen list with descriptions
    - Styled consistently with the design system — this IS a designed page, not a plain list
    - Visibly applies the Signature Move (e.g., on screen cards or the hub title).

### Phase 5.5 — Verification (REQUIRED before presenting to user)
17) **Component cross-check**:
    - Every component referenced in `wireframes.md` MUST have a definition in `design_system.md`
    - List any gaps and add missing component definitions before proceeding
17.5) **Signature Move check**:
    - `docs/design_philosophy.md` must contain a Signature Move with numeric/token specificity (not prose-only).
    - `prototype/styles.css` must implement it as a reusable class or component variant.
    - Every HTML file in `prototype/screens/` (including the pilot) must apply that class/variant at least once.
    - If any check fails: list violations, fix, and re-verify before proceeding.
17.6) **Literal quote verbatim render check** (skip if Phase 1.5 was explicitly skipped):
    - Read `literal_quote:` from `docs/design_philosophy.md` Reference Anchors.
    - Grep `prototype/screens/*.html` for the literal string. The string MUST appear verbatim in at least one screen's rendered output.
    - If absent: name the screens that would naturally host it (per the anchor's "where it appears" hint), inject the quote into that screen's HTML, and re-grep. Do not skip this check by widening the search (no substring matches, no partial matches).
    - Example: `literal_quote: "47.2-A"` MUST appear as the literal characters `47.2-A` in at least one screen file — not `47-2-A`, not `47.2A`, not in a comment.
18) **PRD feature cross-check**:
    - Every feature in the PRD (F1, F2, ... including P2) MUST appear in wireframes and/or interactions
    - List any gaps and add missing features (P2 features as "deferred" notes)
19) **Token compliance check**:
    - CSS custom properties used in `styles.css` MUST match values in `design_system.md`
    - Check for hardcoded hex colors, font sizes, or spacing in `styles.css` that should use `var(--token)`
20) **Cross-document consistency check**:
    - Color token references in wireframes/interactions use CSS custom property names (not prose descriptions)
    - Hover/interaction states in interactions.md match component states in design_system.md
    - Container widths and breakpoints are consistent across all docs and CSS
21) **Accessibility check**:
    - No `outline: none` on `:focus` without `:focus-visible` coverage
    - Placeholder text contrast >= 3:1
    - All interactive elements have keyboard handlers
21.5) **Contrast sweep** (CRITICAL — catches the failures that ship most):
    - For every `(color, background-color)` pair on a screen, verify the WCAG ratio against its *computed* background: body text (<24px regular / <18px bold) needs ≥ 4.5:1; large text (≥24px / ≥18px bold), icons, and focus rings need ≥ 3:1.
    - Fail on any of: **button text ≈ button fill** (text colour within ~5% lightness of the fill — the black-on-black bug); `--color-accent` filling a text-bearing surface without a defined, verified `--color-accent-ink`; any **dark section** (background lightness < 50%) that did not also flip its text colour (ink-on-ink). Most-missed: text in a card that switched `background` but inherited `color`; muted text on a tinted surface.
    - List failing pairs as `file:selector`, fix, and re-check before proceeding.
22) **State demo check**:
    - Every screen has a visible state-switcher toolbar
    - Loading, empty, and error states are implemented and togglable
22.5) **issues.md coverage cross-check** (only if `issues.md` exists):
    - Read `issues.md` and extract titles, scope, and `UI` flag from each issue.
    - Compare against the design deliverables and produce a gap list:
      - **New screens**: `### Screen:` entries in `wireframes.md` not implied by any existing issue
      - **New components**: composite components defined in `design_system.md` (FAB, list items, pickers, etc.) that no existing issue produces
      - **New flows**: `### Flow:` entries in `interactions.md` not covered by an existing issue
      - **New states**: loading/empty/error states added in `interactions.md` or `copy_guide.md` beyond what was anticipated in `ux_spec.md`
    - Persist the gap list in memory for Phase 6 reporting. Do NOT modify `issues.md` — issue creation is `/issue`'s responsibility.
    - If `issues.md` does not exist, skip silently.
22.7) **AI Tell sweep** (CRITICAL):
    - Sweep every file in `prototype/screens/` and `prototype/styles.css` for the banned tells in "Specific AI Tells" (Anti-AI-Slop Rules): em-dash (`—`/`–`), `100vh`/`height: 100vh` on full-height sections, flex `calc()` column math, generic person/brand names, fake-perfect numbers, section-number eyebrows, hero version labels, three equal feature cards, `<div>`-based fake product UI, decorative status dots, locale/time strips, scroll cues, mono-caps decoration strips.
    - Before sweeping, read the `Brief overrides:` bullets in `docs/design_philosophy.md` (Anti-AI-Slop "The brief's own words win"). Exempt exactly the tells listed there and no others; report each exemption as `exempt: <tell> — <brief quote>` alongside the violation list. An unrecorded violation is never exempt.
    - List every violation as `file:line`, fix it, and re-sweep. **Zero tolerance on em-dash and div-based fake product UI** — these must be 0 before presenting unless a `Brief overrides:` bullet covers them. Match CSS patterns whitespace-insensitively (`height:100vh` ≡ `height: 100vh`).
22.8) **Slop-proof mechanics sweep** (deterministic — grep `prototype/styles.css` and screens):
    - Flag and fix: `transition: all` / `transition-all`; animating `width`/`height`/`top`/`left`/`margin`/`padding`; bare `1fr` tracks on image-bearing grids (must be `minmax(0, 1fr)`); `font-style: italic` on heading/display selectors; a second `position: sticky; top: 0` (only the nav may sit there); all-caps display with `line-height` < 1.0.
    - Confirm present: `overflow-x: clip` on BOTH `html` and `body`; input fields satisfy the 8-state rules (constant `border-width`, `outline`-based focus ring, reserved helper slot, multi-channel disabled) from Phase 5A step 14.
    - Match patterns **whitespace-insensitively** (normalize spaces first, and ignore matches inside CSS comments): `transition:all` ≡ `transition: all`, `top:0` ≡ `top: 0`, `overflow-x:clip` ≡ `overflow-x: clip`.
    - List every violation as `file:line`, fix, and re-sweep.

### Phase 6 — Review & Iterate
23) Present deliverables summary to the user:
    - List all generated files with brief descriptions
    - Highlight the design philosophy and key aesthetic choices
    - Report verification results from Phase 5.5 (component coverage, PRD coverage, token compliance)
    - **Report the issues.md gap list from Phase 5.5 step 22.5** under a "Suggested follow-up issues" heading. If gaps exist, suggest the exact command to run:
      ```
      /issue "uiux 산출물 기반으로 issues.md에 누락된 화면/컴포넌트/상태/플로우 작업을 batch로 추가해줘"
      ```
      If no gaps were found, state explicitly: "No issues.md gaps detected — design deliverables are fully covered by existing issues."
    - Suggest: `open prototype/index.html` to view in browser
    - Ask for feedback on any screen
24) Iterate based on user feedback:
    - Modify specific screens, adjust design system, add missing states
    - Each iteration updates both docs and prototype files consistently
    - If aesthetic direction needs major change, go back to Phase 2

## Shared Registry Files
- None directly written. This skill produces standalone design deliverables and does NOT modify `issues.md` or `STATUS.md`.
- However, design work routinely surfaces new screens, components, states, or flows that were not anticipated when `/kickoff` generated `issues.md`. Phase 5.5 step 22.5 detects these gaps and Phase 6 reports them.
- To convert the reported gaps into actual issues, run `/issue` with a gap-finder prompt — `/issue`'s batch mode automatically reads `design_system.md`, `wireframes.md`, `interactions.md`, and `copy_guide.md` (`has_design_docs` flag) and appends new issues without disturbing existing ones.
- Do NOT re-run `/kickoff` for this purpose — it overwrites all planning docs and resets issue numbering, Status, GH-Issue, and PR fields.

## Error Handling
- If `docs/ux_spec.md` not found: stop and suggest running `/kickoff` first (unless user explicitly opts to skip).
- If PRD file not found: stop immediately, report missing path.
- If `docs/` cannot be created: stop and report filesystem error.
- If existing UI code uses a framework (React, Vue, etc.): note the framework in `docs/design_system.md` for future `/implement` reference. Prototypes are still pure HTML/CSS for portability.
- If PRD is too vague for UI design (no user stories, no features): ask the user targeted questions about screens and user flows before proceeding.

## Rollback
- This skill is additive (writes new files/directories). No destructive rollback needed.
- Re-running `/uiux` overwrites all outputs — safe to retry.
- Prototype directory (`prototype/`) can be safely deleted if not needed.

## Anti-AI-Slop Rules (CRITICAL)

These rules prevent Claude from converging on generic, forgettable defaults.

**Primary anchor — the Signature Move.** The single most effective slop-blocker is the numeric/token-specific Signature Move defined in Phase 2 step 8 and enforced at Phase 5A pilot gate and Phase 5.5 step 17.5. Negative rules below are secondary; if the Signature Move is weak or missing, the rules below will not save the output.

**Calibration — the three current AI-design clusters.** Independent of subject, AI-generated design converges on three looks right now:
1. Warm cream ground (near `#F4F1EA`) + high-contrast serif display + terracotta accent.
2. Near-black ground + one bright acid-green or vermilion accent.
3. Broadsheet layout — hairline rules, zero corner radius, dense newspaper columns.
Each is legitimate for *some* brief. They are banned as **defaults**, not as choices: where the brief leaves an axis free, do not spend that freedom on one of these three. This list dates faster than the rest of this section — treat it as "what everyone is producing this year", not as a permanent ban.

**The brief's own words win.** Where the brief pins a direction, follow it exactly, including when it asks for one of the three clusters above and including when it contradicts a specific ban in this section. Record each such override in `docs/design_philosophy.md` under a `Brief overrides:` line, one bullet per overridden rule, quoting the brief. Any later sweep or reviewer honors recorded overrides and only recorded overrides — an unrecorded violation is still a violation.

**Self-similarity check — run before locking the design plan.** Strip the product-specific nouns out of the brief and ask what you would produce for that generic version. If your current plan is roughly where you land, it is a default wearing this product's content, not a choice made for this product. Revise the part that collapsed and say what you changed and why.

**NEVER:**
- Inter, Roboto, Arial, Open Sans as primary display font
- Purple gradients on white backgrounds
- Predictable centered layouts with uniform rounded corners
- Cookie-cutter component patterns without context-specific character
- Solid white/gray backgrounds without depth or texture
- Evenly-distributed, timid color palettes
- Space Grotesk as a "safe creative" choice

**INSTEAD:**
- Distinctive, characterful fonts that match the product's personality
- Cohesive color palette with dominant colors and sharp accents
- Unexpected spatial composition — asymmetry, overlap, diagonal flow, grid-breaking
- Atmosphere and depth — gradients, noise, textures, layered transparencies, dramatic shadows
- High-impact motion moments over scattered micro-interactions
- Implementation complexity matched to aesthetic vision

**Specific AI Tells (hard bans — sweep every screen before presenting).**
Concrete signatures LLMs default to. Banned unless the brief explicitly calls for one.

*Content & data:*
- Generic person names ("John Doe", "Sarah Chan") or startup-slop brand names ("Acme", "Nexus", "SmartFlow", "Cloudly") → invent contextual, locale-appropriate, real-sounding names.
- Fake-perfect numbers (`99.99%`, round `50%`, `1,234,567`) → organic messy values (`47.2%`, `+1 (312) 847-1928`).
- Filler verbs ("Elevate", "Seamless", "Unleash", "Next-Gen", "Revolutionize") → concrete verbs only.
- **Em-dash (`—`) and en-dash-as-separator (`–`): zero tolerance** everywhere visible (headlines, labels, body, captions, attribution). Use a regular hyphen `-`, comma, period, colon, or line break. The single most-violated tell.

*Fake product UI:*
- NEVER build a fake product UI out of styled `<div>` rectangles (fake dashboard, terminal, task list, chart) to fill a hero or preview. This is the #1 design tell. Use a real screenshot, generated image, real component preview, or skip the preview.
- No fake version footers / sync stamps inside previews (`v0.6.2-rc.1`, `last sync 4s ago`).

*Decorative meta (agency-portfolio clichés):*
- No section-number eyebrows (`001 · Capabilities`, `06 · how it works`) or `01 / 4` pagination labels. Name the topic in plain language.
- No hero version labels (`V0.6`, `BETA`, `EARLY ACCESS`, `ALPHA`) unless the brief is explicitly a launch/preview.
- No three identical equal-width feature cards in a row → 2-col zig-zag, asymmetric grid, or scroll-pinned alternative.
- No decorative status dots before every nav/list/badge (only for real semantic state, sparingly).
- No locale/time/weather strips (`Lisbon 14:23 · 18°C`), no scroll cues (`↓ Scroll to explore`), no mono-caps decoration strips (`BRAND. MOTION. SPATIAL.`).
- Ration the middle dot `·` to max 1 per metadata line; never as a universal separator.
- No fake photo-credit captions (`Frame XII · 35mm`, `Plate 03`) — real photographer credit only.

*CSS mechanics (web):*
- Full-height hero: use `min-height: 100dvh`, NEVER `100vh` / `height: 100vh` (iOS Safari address-bar jump).
- Multi-column layouts: use CSS Grid (`grid-template-columns`), NEVER flex percentage math (`width: calc(33% - 1rem)`).
- Selector-specificity collisions: a section-level class (`.section`) and an element-level class (`.cta`) that both set the same box property silently cancel each other out by source order. Section-to-section `padding`/`margin` is where this bites most. Give each box property exactly ONE owning selector; when two must coexist, raise the intended winner's specificity explicitly instead of relying on rule order.
- Full deterministic layout/motion/input rules live in Phase 5A step 14 ("Layout-safety / Motion / Input-state mechanics") and are swept in Phase 5.5.

*Typography & interaction tells:*
- **No italic headings.** `font-style: italic` on `h1`–`h6` / display / wordmark / hero stat / `<em>` inside a heading is a top tell. Emphasis = weight, accent colour, or a drawn underline. Italic only inside running body copy.
- No celebratory success toast for an action whose effect is already visible (silent success; reserve toasts for failures and invisible effects).
- Tooltip delays differ by input: hover delays 800–1000ms, keyboard focus shows at 0ms (never equal).
- Auto-rotating content (carousel, banner, stat ticker) must pause on hover AND focus (WCAG 2.2.2).

## Guidelines
- **Self-contained prototypes**: Opens via `file://` — no build tools, no npm, no frameworks.
- **One CDN exception**: Google Fonts `<link>` tags are allowed for typography.
- **Accessibility first**: WCAG 2.1 AA — contrast ratios, keyboard navigation, screen reader support.
- **Mobile-first**: Design for 375px first, then scale up.
- **Realistic content**: Domain-appropriate placeholder text, not lorem ipsum.
- **Intentional design**: Every choice (font, color, spacing, animation) must serve the design philosophy. No defaults.