Kit Preamble — 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

Kit Preamble — uiux

Kit Update Check

Run silently at the start:

python3 scripts/kit_update_check.py 2>/dev/null

If exit code is 1 (update available), show the output to the user once. Do not block the workflow.

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.

Behavioral Rules

• Verify gh auth status before any GitHub operation.
• Never commit secrets, API keys, or credentials. Use environment variables.
• Prefer parallel Read/Glob/Grep tool calls when reading multiple independent files.
• When uncertain about intent, ask the user rather than guessing.
• Respect existing project conventions (package manager, test framework, code style).

Contributor Mode

At the start of this skill, check if contributor mode is enabled:

python3 scripts/kit_config.py get contributor_mode

If the result is true:

1. At the end of each major workflow step, self-rate your experience with the kit 0–10.
2. If rating < 10 and there is an actionable improvement, file a field report:

   python3 scripts/contributor_report.py --skill <name> --step "<step>" --rating <N> --notes "<friction or suggestion>"
   

3. Maximum 3 reports per session. Skip if a report for the same step already exists.
4. Do NOT stop the workflow to file reports — do it inline.
5. Only report kit/skill issues (unclear instructions, missing checkpoints, bad ergonomics). Do NOT report user-app bugs or network errors.

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:

   • Glob for **/*.html, **/*.css, **/*.tsx, **/*.jsx, **/*.vue, **/*.svelte
   • If found, read key files to understand current design patterns and tech stack.

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 Verify Phase 1 outputs: docs/ux_spec.md exists, PRD was read, interview answers (or auto-derived constraints) are recorded. If 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:

       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 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 Verify docs/design_system.md, docs/wireframes.md, docs/interactions.md, and docs/copy_guide.md all exist. Cross-check: every component in wireframes has a definition in design_system.md. If any output is missing: STOP and generate 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.
    • 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. 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.

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)).
• 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.