[BLOCKING] Mode routing — detect FIRST. An explicit mode wins; omitted --mode defaults to fast, except that a request to see or choose between design options routes to explore. --mode=review runs standalone or in a workflow: read references/mode-review.md in full and follow it instead of the design spine, search, lanes and design branches below.
Quick Summary
Review modes: For review/audit work, standalone defaults to --review-only (--report-only alias); --fix-loop enables review → validate → authorized fix → fresh re-review, default cap 3. --fix-loop --loop-owner=caller returns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carried review-policy contract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.
Goal: Create (or describe) a UI design using design-intelligence databases and subagents, dispatched by --mode (input carrier) × --lane (design lane); --mode=review instead reviews existing UI for content fit, supported-size layout, styling conventions, layering, accessibility and async states.
Summary:
- Route: parse
--mode={fast|good|explore|describe|screenshot|video|review} and --lane={product|marketing}; default to fast × product, except that a request to see or choose between design options with no explicit mode routes to explore. review replaces the design spine with references/mode-review.md (--lane does not apply).
- Spine (BLOCKING order, every design mode — not
review): Journey Report (UX-1) → design authority read — principles, design system, existing UI (UX-2) → design-intelligence search (candidates only) → ingest visual evidence when applicable → low-fi structure walked against the journeys (UX-7) → design with ui-ux-designer (DD-3 plan + UI-*/DD-*) → implement unless describe → validate by walking the journeys + traceability (UX-8) → report and seek approval.
- Quality floor: apply project tokens/components plus
UI-*/AD-*/DD-*/CL-*; design states, interaction feedback, declared scales, measured contrast, touch targets, responsive reflow, and subject-grounded copy before the happy path.
- Ownership: the design modes author the visual direction and implementation contract;
--mode=review owns source findings and review evidence; the local index supplies candidates only.
Command routing: Use /ui-design with these values; the old commands do not resolve.
| Old command |
Current invocation |
/design-fast, /design-good, /design-describe, /design-screenshot, /design-video |
/ui-design --mode=<same suffix> |
/ui-review |
/ui-design --mode=review [scope] [--report-only] — read references/mode-review.md when selected |
frontend-design, interface-design |
/ui-design --lane=marketing, /ui-design --lane=product — read the selected references/lane-{marketing,product}/lane-guide.md |
Mode dispatch: --mode={fast|good|explore|describe|screenshot|video|review} — default fast when omitted (a request to see or choose between design options → explore).
Lane dispatch: --lane={product|marketing} — default product when omitted. Lane (the design tradition) is orthogonal to mode (the input carrier); any mode combines with any lane.
| Lane |
Use for |
Full body |
product (default) |
dashboards, admin panels, SaaS apps, tools, settings, data interfaces |
references/lane-product/lane-guide.md |
marketing |
landing pages, marketing sites, campaigns, distinctive creative pieces |
references/lane-marketing/lane-guide.md |
| Mode |
Input carrier |
Output |
fast (default) |
text brief |
quick prototype implementation |
good |
text brief |
immersive, researched, higher-quality implementation |
explore |
text brief |
Research of top styles and layouts (offered first for a new brand, product, page or flow) → 1–3 divergent drafts, each a different style with a different layout → user picks one or mixes → continues as good (Slide → deck builder) |
describe |
screenshot / video |
super-detailed written description + implementation plan (NO code) |
screenshot |
screenshot |
design recreated from the image as functional code |
video |
video |
design + interactions recreated from the video as functional code |
review |
changed UI files / surfaces |
read-only review report (findings, severity, fix guidance; fixes only via the validated fix loop, none under --report-only) — formerly /ui-review |
Shared workflow (journey-first spine — BLOCKING order, every design mode; review runs its own reference instead):
- Journey Report (
UX-1) — Analyze and REPORT the main user journeys BEFORE any other output (template: .claude/docs/ux-journey-process.md §4, depth per §10). Confirm an inferred primary actor, main job or success outcome with the user before generating.
- Design authority read (
UX-2) — Read the project's design principles/guidelines, the design system resolved from docs/project-config.json (designSystem.canonicalDoc, tokenFiles, appMappings[]) and the existing related UI (SYNC:existing-ui-research); record Design authority read: <paths> or N/A — none configured (checked: <paths>).
- Research — Run this skill's design-intelligence search, framed by the Journey Report; results are candidates only, never project authority.
- Ingest — For visual modes (
describe/screenshot/video), use visual analysis tooling to analyze the screenshot/video in super-detail.
- Low-fi structure (
UX-7) — Sketch flow and views (ASCII is enough) from the journey steps (UX-3) and per-decision-point priority (UX-4); walk the main journeys on it before any styling.
- Design — Use
ui-ux-designer subagent to layer the DD-3 Design Plan and visual design (or, for describe, an implementation plan) on the validated structure, applying UI-*/DD-* and the selected lane's craft body.
- Implement — Build as code following the selected lane guide:
references/lane-product/lane-guide.md (product UIs) or references/lane-marketing/lane-guide.md (marketing/creative). Skipped in describe mode.
- Validate (
UX-8) — Cognitive walkthrough of every main journey on the produced design plus a traceability matrix (journey step → view → element → information tier → rule → states); fix every unserved step and orphan element before hand-off. Measure interaction cost per main journey (UX-9) and check wayfinding on every view (UX-10) (catalog §12).
- Report — Close with the UI/UX Gate Report (
UX-11, catalog §13): one row per gate (UX-*, applicable UI-*, AD-*, DD-*, CL-* with at least the CL-5 triage, UI copy), each PASS / FAIL → fixed / N/A with evidence; an unresolved FAIL blocks hand-off. Present to user for approval with the Journey Report, walkthrough result, matrix and Gate Report; update ./docs/design-guidelines.md if needed.
Key Rules:
- Report the main user journeys (
UX-1) first, then resolve the project's design principles, accepted design system and existing UI (UX-2); only then use this skill's local design-intelligence index as candidate input.
- Default to pure HTML/CSS/JS if the user doesn't specify a framework
- Use
visual analysis tooling for generating AND reviewing real visual assets
- Use media processing tooling (RMBG) to remove backgrounds from generated assets when needed
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Contents
Arguments & Mode Dispatch
/ui-design --mode={fast|good|explore|describe|screenshot|video|review} --lane={product|marketing} <brief | screenshot | video | review scope>
- When
--mode is omitted, default to --mode=fast.
- A request to see or choose between design options, with no explicit mode, goes to
--mode=explore.
- An explicit
--mode always wins; --mode=review is never inferred from the brief and is never the default.
- When
--lane is omitted, default to --lane=product (the dominant task/app use). Pick marketing for landing pages, campaigns, and distinctive creative pieces.
--mode (input carrier) and --lane (design tradition) are orthogonal — e.g. --mode=screenshot --lane=product recreates a dashboard screenshot in the product-UI craft tradition.
$ARGUMENTS carries the full input after the command. Interpret it per mode: fast/good/explore → a text design brief; describe/screenshot → a screenshot reference (path/URL/attachment); video → a video reference; review → the review scope (files, directories or surfaces; empty = all uncommitted UI changes) plus the optional --report-only flag.
Lane selection (apply the chosen lane's craft body at stages 6-7)
--lane=product (default) — product UIs: dashboards, admin panels, SaaS apps, tools. Domain-driven craft (intent → domain exploration → signature → layered surfaces/tokens). Full body: references/lane-product/lane-guide.md.
--lane=marketing — marketing/creative: landing pages, campaigns, screenshot replication. Bold aesthetic direction (distinctive type, cohesive palette, atmosphere, motion). Full body: references/lane-marketing/lane-guide.md.
Do NOT inline the lane bodies here — read the matching lane-guide.md when the lane is selected.
Required Skills (Priority Order)
- In-skill design-intelligence search/data — Query
scripts/search.py after the Journey Report (UX-1) and the design-authority/existing-UI read (UX-2); results are candidate input, not project authority.
- In-skill lane references —
references/lane-{product|marketing}/lane-guide.md (+ their reference files) own implementation, screenshot/video analysis, and design replication for the selected lane.
- In-skill explore references —
references/explore/workflow.md (+ option-discovery.md, briefs.md, gate-files.md, brand-asset-protocol.md) own the --mode=explore flow; read them only when that mode is selected. The option board shortlists from data/style-families.csv and data/layout-archetypes.csv (read the whole small family catalog; search.py --domain family|layout ranks rows that match the brief), assembles with scripts/build-board.cjs, and checks typefaces with scripts/check-font-subsets.cjs.
- In-skill review reference —
references/mode-review.md owns --mode=review; read it only when that mode is selected. scripts/audit-actions.cjs collects the action & attention evidence (AD-5) on a rendered local page: each count with the elements behind it and what was excluded and why, for the reviewer to confirm by eye; it never passes or fails a page. A tint is a low-emphasis near-neutral wash; saturated brand fills count as filled primaries.
Shared First Step (ALL design modes)
[BLOCKING] Step 0 — Journey Report (UX-1). Before any wireframe, mockup, design plan, token table, search result or code, analyze and PRESENT the main user journeys, per SYNC:ux-journey-gate and the template in .claude/docs/ux-journey-process.md §4: frame · actors + job statements · 3–5 ranked main journeys with step tables (intent · decision/action · information needed · business rule · system response · failure → recovery) · derived design requirements · assumptions and open questions, each claim tagged SOURCED (location) or INFERRED. Depth scales with scope (§10), never to zero for a new or reshaped view. Confirm an inferred primary actor, main job or success outcome with the user before generating.
[BLOCKING] Step 0b — Design authority read + existing UI (UX-2). Resolve from docs/project-config.json and its reference docs, then read the project's design principles/guidelines, the design system (designSystem.canonicalDoc, tokenFiles, appMappings[]), accepted design ADRs, and the existing related UI — inventory the screens and components already serving this feature/domain and map every connected flow that links to / embeds / navigates to-or-from it (SYNC:existing-ui-research). Record Design authority read: <paths> or N/A — none configured (checked: <paths>). Adopt house patterns; never invent tokens or components the project already defines.
Skip Steps 0 and 0b ONLY for work with no user-facing surface, stated explicitly.
THEN, after Steps 0 and 0b, run focused design-intelligence searches — framed by the Journey Report — to gather candidate input:
# Windows: py -3 · macOS/Linux: python3 (same arguments)
py -3 .claude/skills/ui-design/scripts/search.py "<product-type>" --domain product
py -3 .claude/skills/ui-design/scripts/search.py "<style-keywords>" --domain style
py -3 .claude/skills/ui-design/scripts/search.py "<mood>" --domain typography
py -3 .claude/skills/ui-design/scripts/search.py "<industry>" --domain color
Design Intelligence Research Contract
The local index is a research aid owned by this skill. It supplies structured candidates; it never outranks the adopter project's accepted brief, design system, tokens, components, frontend conventions, or accessibility requirements.
- Frame the query. Derive the product type, audience and job-to-be-done from the Journey Report (
UX-1: frame, actors, job statements, main journeys), then add industry, desired style, platform, implementation stack, and constraints before searching.
- Search deliberately. Query
product, style, typography, and color first; add landing, chart, ux, prompt, and the relevant --stack query when the surface needs them. Use specific domain terms and more than one query when the brief has multiple concerns.
- Resolve and record authority. Read
docs/project-config.json and resolve designSystem.canonicalDoc, tokenFiles, and appMappings[] when present. Reconcile candidates against the accepted brief, existing-UI inventory, shared UI-*/DD-*/CL-* contracts, and the selected lane. Record why important candidates were selected or rejected; never invent tokens, components, breakpoints, or stack defaults when the project has not declared them.
- Keep implementation quality explicit. Use the project's icon system or one consistent accessible SVG set; do not use emoji as UI icons; give each view ONE filled primary commit and render every other action by the
AD-1 table (icon-only named and tooltipped, icon + label, link, row target, overflow) in uniform groups; verify official brand marks. Define stable hover, focus, active, disabled, and loading feedback without layout shift, using the project's cursor and motion conventions.
- Design state coverage before the happy path. Specify
Default, Loading, Disabled, Error, Empty, and Success where applicable. Errors need human-readable recovery, empty states need a meaningful next action, in-flight actions must prevent duplicate submission, and successful actions need acknowledgment.
- Design for reachable reflow. Use the project's content breakpoints. If none are declared, smoke-check 320, 768, 1024, and 1440 widths: rows reflow, grids collapse, non-reflow content has an intentional reachable scroll fallback, and nothing is clipped or unreachable. Surface any large refactor or new breakpoint as an explicit decision.
--mode=review remains the owner of source-level findings, evidence, severity, component ownership, and review procedure. This contract makes the same quality floor explicit while authoring a design; it does not duplicate or replace the review mode.
UX Journey Contract (all design modes)
The journey-first gate (UX-1–UX-11, SYNC:ux-journey-gate; deep catalog .claude/docs/ux-journey-process.md) binds EVERY design mode (--mode=review applies it through its own reference) and runs BEFORE UI-*/DD-*/CL-*, because those judge a surface whose purpose it defines. Steps 0 and 0b above deliver UX-1 and UX-2.
Generative modes (fast, good, explore) — DERIVE the design from the journeys:
- Views are journey steps (
UX-3) — every view hosts ≥1 main-journey step and names its primary task; every step lands on a view; the container fits the task (catalog §2 S5).
- Priority per decision point (
UX-4) — rank each item and action by need-at-the-decision × frequency × cost-of-missing into Primary · Secondary · On demand · Not here; ONE focal point and ONE primary action = the journey's next step (catalog §6).
- Rules become interaction (
UX-5) — map each business rule to the lightest treatment that prevents the error before one that reports it; design each step's failure → recovery (catalog §7).
- Low-fi before hi-fi (
UX-7) — walk the main journeys on the ASCII structure before layering the DD-3 Design Plan.
- Walk before reporting (
UX-8) — cognitive walkthrough of every main journey plus the traceability matrix (catalog §9); an unserved step or orphan element is fixed before hand-off.
- Interaction cost and wayfinding (
UX-9, UX-10) — per main journey record steps · clicks · view changes · fields · decisions against the existing flow or spec, and cut what does not advance the job (every click confident — no "3-click rule"). Every view answers where am I / where can I go / how do I get back, with no dead ends. The primary tier sits in the first viewport (catalog §12).
- Check every UI/UX gate (
UX-11) — every mode's final walk step also runs items 5–6 and ends with the UI/UX Gate Report (catalog §13) before the report to the user; a gate missing from the report counts as not checked.
Recreation modes (describe, screenshot, video) — INFER and REPORT: the Journey Report names the journeys the observed UI serves (tagged INFERRED unless a spec or the user sources them); the walk RECORDS every violation it exposes (UX-3/UX-4/UX-5) — describe carries it into the implementation plan as a correction, screenshot/video fix it in the recreation and confirm with the user any fix that changes the visual match.
Design Principles Contract (all design modes)
The 40 UI/UX Design Principles (UI-1.1–UI-9.4) carried as the SYNC:ui-ux-design-principles block below bind EVERY mode of this skill; --mode=review applies them as fail-conditions through its own reference. Project design-system docs OUTRANK them — surface a genuine conflict to the user with both sides, NEVER resolve it silently.
Generative modes (fast, good, explore) — APPLY the clauses as an output contract on the design you produce:
- States first. Design and build the empty, loading and error state BEFORE the populated state (
UI-1.5), and reserve space for anything that loads so nothing shifts in (UI-9.3).
- Supported interaction states. Specify states for the platform/input modes (for example default, focus, active, disabled and loading); hover applies only where supported (
UI-5.2). Preserve a visible focus indicator wherever focus navigation applies (UI-5.5).
- Declare purposeful type and spacing. Use project/platform tokens, readable text measures and consistent scales (
UI-2.2–UI-2.5, UI-4.1). Report those decisions at stage 9; do not impose a fixed step count, pixel base or font minimum without an authoritative requirement.
- Measure contrast. State the selected accessibility standard, its applicable targets and measured results (
UI-3.1); colour never carries meaning alone (UI-3.3). Catalog ratios are standard-specific examples, not universal values.
- Touch surfaces. Meet the applicable platform/accessibility target-size and spacing requirements (
UI-8.1); place primary actions for the actual device/orientation/input reachability (UI-8.2). Record N/A when touch is absent.
Reporting modes (describe, and the analysis pass of screenshot / video) — REPORT against the clauses: the super-detailed description MUST name which clauses the OBSERVED design SATISFIES and which it VIOLATES, cited by ID — e.g. type-scale drift (UI-2.5), contrast failure with the measured ratio (UI-3.1), undersized touch targets (UI-8.1), missing empty/loading/error states (UI-1.5), a removed focus ring (UI-5.5). A violation is RECORDED, never silently reproduced: describe carries it into the implementation plan as a correction; screenshot / video then apply the five generative obligations above so the recreation FIXES the violation rather than inheriting it — flag any correction that changes the visual match and confirm it with the user before shipping it.
Action & Attention Contract (all design modes)
The action & attention gate (AD-1–AD-6, SYNC:ui-action-density-gate; measurable checks B16, C14–C20 in .claude/docs/design-review-checklist.md) binds every mode; --mode=review runs it as Phase 3D of its reference. Project design-system docs and the platform's guidelines outrank it. When its text is not in context, read .claude/skills/shared/protocols/ui-action-density-gate.md first.
Generative modes (fast, good, explore) — BUILD to it: each view has at most ONE filled text button, for its main commit, with a fixed min-width; every other action takes its AD-1 form; button groups share height, style and width; a list row is one target with at most one inline icon action; every icon-only control has a name, a tooltip on hover and focus, a full-size hit target and 3:1 contrast; a row carries a title plus one short meta line; one tile size and title baseline per collection-grid row, actions aligned to their content edge (AD-6). Record the AD-5 counts in the UI/UX Gate Report.
Reporting and recreation modes (describe, screenshot, video) — REPORT, then correct: name every observed violation by its check ID (C14–C20, B16). describe carries each one into the plan as a correction; screenshot/video fix it in the recreation and confirm with the user any fix that changes the visual match.
Design-System Page Contract (prototype-producing modes)
The prototype design-system page (PD-1–PD-6, SYNC:prototype-design-system) binds every mode that emits a working design. When its text is not in context, read .claude/skills/shared/protocols/prototype-design-system.md first.
fast, good, screenshot, video producing a prototype or mock-up (the default pure HTML/CSS/JS): build the design from one catalog of tokens and reusable controls, each control defined once and reused in every view (PD-3), and save the design-system page beside the design, in the design's medium (HTML by default: <design file name>-design-system.html): the tokens plus a live catalog of every reusable control and component with its variants, states, plain contract, the views that use it, and its owner (existing source path, or new — build once) (PD-2). Brownfield entries come from the project's own design system and components, found from repository evidence (PD-4). Link the page in the report.
- Production code in the project's stack: no page beside the source; add or update the shared components and the project's living catalog (when it keeps one) instead, each control built once (
PD-1, PD-5).
describe: no page; the implementation plan lists the same catalog (each entry with its owner) and orders the shared components before the pages (PD-5).
explore: drafts get no page (PD-6); the build after the pick ships one.
review: a control implemented twice, or a catalog control re-styled locally, is checklist M10.
Mode Branches
--mode=review — UI review (read-only; replaces the design spine)
[BLOCKING] When --mode=review, read references/mode-review.md in full FIRST and follow it as the whole invocation: Phase 0 load UI rules → scope and surfaces → blast radius → surface composition → surface UX pass → six UI categories plus the UI/UX principles and design-distinctiveness passes and the action-density pass → report → why-review validation → validated fix loop (none under --report-only). It carries its own protocols inline; do not run the design-spine steps, the design-intelligence search or a lane for it. Workflow invocation (--mode=review --report-only) and standalone both run it.
--mode=fast (default) — quick design
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above; present the report and confirm an inferred primary actor/job/outcome before continuing (no question tool → record it INFERRED — unconfirmed and continue).
- Run the shared design-intelligence searches above.
- Use
ui-ux-designer subagent to start the design process — brief it with the Journey Report and the Design authority read: paths; low-fi structure walked against the journeys first (UX-7).
- If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
- Walk the main journeys (
UX-8) on the built design with the traceability matrix; fix every unserved step and orphan element.
- Report back with a brief summary of the changes, the walkthrough result and the UI/UX Gate Report (
UX-11); ask the user to review and approve.
- On approval, update
./docs/design-guidelines.md if needed.
--mode=good — immersive, high-quality design
Same spine as fast, raised to a higher quality bar (iterate on details):
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above at full depth for the scope (catalog §10); present the report and confirm an inferred primary actor/job/outcome before continuing (no question tool → record it INFERRED — unconfirmed and continue).
- Run comprehensive design-intelligence searches across the applicable domains.
- Use
researcher subagent to research design style, trends, fonts, colors, borders, spacing, elements' positions, etc.
- Use
ui-ux-designer subagent to implement the design step by step based on the Journey Report, the design authority and the research — low-fi structure walked against the journeys first (UX-7).
- If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
- Walk the main journeys (
UX-8) on the built design with the traceability matrix; fix every unserved step and orphan element.
- Report back with a summary, the walkthrough result and the UI/UX Gate Report (
UX-11); ask the user to review and approve.
- On approval, update
./docs/design-guidelines.md if needed.
- ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.
- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.
--mode=explore — research, 1–3 style × layout drafts, user picks or mixes, then good
Opt-in. Use when the visual direction is genuinely open and the user wants to choose it by looking, when the owner asks to see design options (route such a request here from fast or good), or for a rebrand ("a new look for ": the design system's look is then free for the run) or a layout-only change ("keep the look, new layout"). Read references/explore/workflow.md first and follow its steps (Step 0 draft count, then 1–10), one task each. First action: its Step 0 asks Option board → 3 drafts / 3 drafts / 1 draft / skip (no question tool → ONE auto-selected draft). --explore=styles or --explore=layouts from a caller forces the board and its path (styles never frees a pinned colour or type on its own: explore Step 1 asks the owner). A picked Slide direction goes to a deck builder, not good (item 8).
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above, produced ONCE before any seed and shared by all N drafts; confirm an inferred primary actor/job/outcome first (no question tool → record it INFERRED — unconfirmed and continue). The design-authority read also resolves authority per axis (colour · type · layout). Explicit tokens, named fonts or a stated "must use" in the brief pin an axis; adjectives and moods are a target feel to explore, not a pin (VO-1). A brief or project design system pinning all three axes → record it as ADOPTED, log the exemption, and run --mode=good instead; a design system pinning colour and type on a new page or flow → the option board's layout path. Partial pins → the drafts share the pinned axes and diverge only on the free ones.
- Ground before diverging — fact-check named products/specs; with option discovery, run
references/explore/option-discovery.md (research the top style families and layout archetypes at desktop and phone size, one numbered research board, and 3 combinations each pairing a different style with a different layout, recorded in option-board.md; no question before the drafts), otherwise ask once for reference designs the user likes or dislikes; run references/explore/brand-asset-protocol.md when a real brand is named, gather ONE shared content-imagery set (licensed, sources recorded) or labelled placeholders, answer the five form questions, fix the deliverable type and pixel canvas, write the DD-3 Design Plan skeleton.
- N seeds (take the first N) — with option discovery, its combinations (one style family and one layout archetype per draft, none repeated); otherwise a random style row from
node .claude/skills/ui-design/scripts/pick-style.cjs (after changing a script or catalog, run its test in .claude/skills/ui-design/tests/, for example node .claude/skills/ui-design/tests/pick-style.test.cjs), the user's liked reference or a web-verified real-world reference, a studio persona described by traits only. Seeds are divergence seeds, never taste: each draft translates its seed into THIS subject (DD-1) and passes the DD-3 generic test, or it is revised.
- Fan out — N
ui-ux-designer sub-agents in ONE message → tmp/design/<run>/direction-{a,b,c}.html; layout FREE → structurally different layout skeletons, layout ADOPTED → the pinned layout is shared and drafts diverge on the free axes only. Every draft serves the SAME main journeys and information-priority tiers (UX-3/UX-4) — drafts diverge on visual axes and layout skeleton, never on the journeys or the priority tier of content. No sub-agents → build serially; each later draft names what it avoided from the earlier ones.
- Render after all return — per draft,
node .claude/skills/html-export/scripts/export.cjs --to=png --viewport=<canvas> --out=tmp/design/<run>/renders/<draft>/ <file>; handle exits 0/4/3/1-2 per workflow step 8, re-render after the DD-8 edit. NEVER run install commands.
- Present side by side, open every draft in the default browser, and ASK — each draft with how it serves the primary journey; open each with
node .claude/scripts/open-report.cjs tmp/design/<run>/direction-<x>.html, then, with 2–3 drafts, ask user question tool with one option per draft and your evidence-backed (Recommended) draft first (explore step 9); one draft → no question (Selection: USER — 1 option, or AUTO-SELECTED — no question tool (1 draft) set at Step 0); drafts cannot be shown or the question tool errors → AUTO-SELECT the recommended draft; record why either way (explore step 9 fallback). Never pick for the user while they can be asked; never offer a text-only style choice; "continue" is not a pick.
- Record the user's verbatim choice, or the
Selection: line, in tmp/design/<run>/direction-approved.md (template: references/explore/gate-files.md), with the chosen draft's Design Plan tokens in its ## Design Plan tokens section.
- Walk the main journeys (
UX-8) on the chosen draft with the traceability matrix, record the gaps in the ## Journey fixes (UX-8) table of run-notes.md as inputs, then continue as --mode=good from the chosen draft — except a Slide deliverable: hand two files, direction-approved.md (carrying the tokens) and run-notes.md, to a deck builder instead (/presentation-builder for a general deck — command-only, so stop and tell the user to run it; feature-presentation for a feature review deck; explore step 10).
--mode=describe — describe only (NO implementation)
Treat $ARGUMENTS as the screenshot/video to describe.
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above: infer and report the journeys the observed UI serves (tagged INFERRED unless sourced), and read the project design authority the implementation must adopt.
- Use
visual analysis tooling to describe super-details of the screenshot/video so a developer can implement it easily.
- Be specific about design style, every element, elements' positions, every interaction, every animation, every transition, every color, every border, every icon, every font style/size/weight, every spacing/padding/margin, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc.
- IMPORTANT: Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.
- Use
ui-ux-designer subagent to create a design implementation plan following the progressive-disclosure structure so the result matches the screenshot/video:
- Create a directory using the naming pattern from the
## Naming section.
- Save the overview access point at
plan.md, keep it generic, under 80 lines, listing each phase with status/progress and links.
- For each phase, add
phase-XX-phase-name.md with sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).
- Walk the main journeys (
UX-8) on the observed UI with the traceability matrix; record every violation the walk exposes and carry it into the plan as a correction.
- Report back with a summary of the plan, the Journey Report, the walkthrough findings and the UI/UX Gate Report (
UX-11, recording the violations observed). Do NOT implement.
--mode=screenshot — recreate from image as code
Treat $ARGUMENTS as the screenshot to recreate exactly.
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above: infer and report the journeys the observed UI serves (tagged INFERRED unless sourced), and read the project design authority the recreation must adopt.
- Use
visual analysis tooling to describe super-details of the screenshot (design style, trends, fonts, colors, border, spacing, elements' positions, size, shape, texture, material, light, shadow, reflection, refraction, blur, glow, image, background transparency, transition, etc.).
- IMPORTANT: Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.
- Use
ui-ux-designer subagent to create a design plan following the progressive-disclosure structure (as in describe) so the final result matches the screenshot. Keep every research markdown report concise (≤150 lines).
- Implement the plan step by step.
- If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
- Walk the main journeys (
UX-8) on the recreation with the traceability matrix; fix every violation the walk exposes and confirm with the user any fix that changes the visual match.
- Report back with a summary, the walkthrough result and the UI/UX Gate Report (
UX-11); ask the user to review and approve.
- On approval, update
./docs/design-guidelines.md if needed.
- ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.
- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.
--mode=video — recreate from video as code
Treat $ARGUMENTS as the video to recreate exactly. Same as --mode=screenshot, but ingest a VIDEO and capture BOTH static layout AND interaction/animation/transition patterns.
- Journey Report (
UX-1) + design authority (UX-2) — Steps 0 and 0b above: infer and report the journeys the observed flow serves (the video's interaction sequence is direct evidence; tag INFERRED unless sourced), and read the project design authority the recreation must adopt.
- Use
visual analysis tooling to describe super-details of the video: every element, every interaction, every animation, every transition, every color, every font, every border, every spacing, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc.
- IMPORTANT: Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.
- Use
ui-ux-designer subagent to create a design plan following the progressive-disclosure structure so the final result matches the video. Keep every research markdown report concise (≤150 lines).
- Implement the plan step by step.
- If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
- Walk the main journeys (
UX-8) on the recreation with the traceability matrix; fix every violation the walk exposes and confirm with the user any fix that changes the visual match.
- Report back with a summary, the walkthrough result and the UI/UX Gate Report (
UX-11); ask the user to review and approve.
- On approval, update
./docs/design-guidelines.md if needed.
- ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.
- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.
Notes (all design modes)
- Design system (canonical): When implementing UI — HTML, CSS, or SCSS — read
docs/project-config.json first, then resolve designSystem.canonicalDoc, tokenFiles, and appMappings[]. Read every configured authority before choosing tokens, component patterns, breakpoints, or BEM conventions. If the project has no configured authority, record N/A and follow the selected lane plus t
…(truncated)
1---2name: ui-design-23version: 1.2.04description: '[Design] Use when a workflow step or the user asks for UI creation, exploration or description from briefs, screenshots or videos for product/marketing interfaces. --mode=review checks layout, styling, accessibility and async states.'5disable-model-invocation: false6metadata:7 source: https://skillmd.com/skills/duc01226/ui-design-28---910> **[BLOCKING] Mode routing — detect FIRST.** An explicit mode wins; omitted `--mode` defaults to `fast`, except that a request to see or choose between design options routes to `explore`. `--mode=review` runs standalone or in a workflow: read `references/mode-review.md` in full and follow it instead of the design spine, search, lanes and design branches below.1112## Quick Summary1314> **Review modes:** For review/audit work, standalone defaults to `--review-only` (`--report-only` alias); `--fix-loop` enables review → validate → authorized fix → fresh re-review, default cap 3. `--fix-loop --loop-owner=caller` returns a read-only pass to the caller that owns fixes/re-review. Create triage, review, validation and re-review todo tasks first; apply the carried `review-policy` contract for LOW deferral and user-approved bounded extensions. Non-review modes and terminal findings validation keep their own dispatch.1516**Goal:** Create (or describe) a UI design using design-intelligence databases and subagents, dispatched by `--mode` (input carrier) × `--lane` (design lane); `--mode=review` instead reviews existing UI for content fit, supported-size layout, styling conventions, layering, accessibility and async states.1718**Summary:**1920- **Route:** parse `--mode={fast|good|explore|describe|screenshot|video|review}` and `--lane={product|marketing}`; default to `fast` × `product`, except that a request to see or choose between design options with no explicit mode routes to `explore`. `review` replaces the design spine with `references/mode-review.md` (`--lane` does not apply).21- **Spine (BLOCKING order, every design mode — not `review`):** Journey Report (`UX-1`) → design authority read — principles, design system, existing UI (`UX-2`) → design-intelligence search (candidates only) → ingest visual evidence when applicable → low-fi structure walked against the journeys (`UX-7`) → design with `ui-ux-designer` (`DD-3` plan + `UI-*`/`DD-*`) → implement unless `describe` → validate by walking the journeys + traceability (`UX-8`) → report and seek approval.22- **Quality floor:** apply project tokens/components plus `UI-*`/`AD-*`/`DD-*`/`CL-*`; design states, interaction feedback, declared scales, measured contrast, touch targets, responsive reflow, and subject-grounded copy before the happy path.23- **Ownership:** the design modes author the visual direction and implementation contract; `--mode=review` owns source findings and review evidence; the local index supplies candidates only.2425**Command routing:** Use `/ui-design` with these values; the old commands do not resolve.2627| Old command | Current invocation |28| --- | --- |29| `/design-fast`, `/design-good`, `/design-describe`, `/design-screenshot`, `/design-video` | `/ui-design --mode=<same suffix>` |30| `/ui-review` | `/ui-design --mode=review [scope] [--report-only]` — read `references/mode-review.md` when selected |31| `frontend-design`, `interface-design` | `/ui-design --lane=marketing`, `/ui-design --lane=product` — read the selected `references/lane-{marketing,product}/lane-guide.md` |3233**Mode dispatch:** `--mode={fast|good|explore|describe|screenshot|video|review}` — default `fast` when omitted (a request to see or choose between design options → `explore`).34**Lane dispatch:** `--lane={product|marketing}` — default `product` when omitted. Lane (the design tradition) is orthogonal to mode (the input carrier); any mode combines with any lane.3536| Lane | Use for | Full body |37| --------------------- | ----------------------------------------------------------------------- | --------- |38| `product` (default) | dashboards, admin panels, SaaS apps, tools, settings, data interfaces | `references/lane-product/lane-guide.md` |39| `marketing` | landing pages, marketing sites, campaigns, distinctive creative pieces | `references/lane-marketing/lane-guide.md` |4041| Mode | Input carrier | Output |42| --------------------- | --------------------------- | ----------------------------------------------------------- |43| `fast` (default) | text brief | quick prototype implementation |44| `good` | text brief | immersive, researched, higher-quality implementation |45| `explore` | text brief | Research of top styles and layouts (offered first for a new brand, product, page or flow) → 1–3 divergent drafts, each a different style with a different layout → user picks one or mixes → continues as `good` (Slide → deck builder) |46| `describe` | screenshot / video | super-detailed written description + implementation plan (NO code) |47| `screenshot` | screenshot | design recreated from the image as functional code |48| `video` | video | design + interactions recreated from the video as functional code |49| `review` | changed UI files / surfaces | read-only review report (findings, severity, fix guidance; fixes only via the validated fix loop, none under `--report-only`) — formerly `/ui-review` |5051**Shared workflow (journey-first spine — BLOCKING order, every design mode; `review` runs its own reference instead):**52531. **Journey Report (`UX-1`)** — Analyze and REPORT the main user journeys BEFORE any other output (template: `.claude/docs/ux-journey-process.md` §4, depth per §10). Confirm an inferred primary actor, main job or success outcome with the user before generating.542. **Design authority read (`UX-2`)** — Read the project's design principles/guidelines, the design system resolved from `docs/project-config.json` (`designSystem.canonicalDoc`, `tokenFiles`, `appMappings[]`) and the existing related UI (`SYNC:existing-ui-research`); record `Design authority read: <paths>` or `N/A — none configured (checked: <paths>)`.553. **Research** — Run this skill's design-intelligence search, framed by the Journey Report; results are candidates only, never project authority.564. **Ingest** — For visual modes (`describe`/`screenshot`/`video`), use `visual analysis tooling` to analyze the screenshot/video in super-detail.575. **Low-fi structure (`UX-7`)** — Sketch flow and views (ASCII is enough) from the journey steps (`UX-3`) and per-decision-point priority (`UX-4`); walk the main journeys on it before any styling.586. **Design** — Use `ui-ux-designer` subagent to layer the `DD-3` Design Plan and visual design (or, for `describe`, an implementation plan) on the validated structure, applying `UI-*`/`DD-*` and the selected lane's craft body.597. **Implement** — Build as code following the selected lane guide: `references/lane-product/lane-guide.md` (product UIs) or `references/lane-marketing/lane-guide.md` (marketing/creative). Skipped in `describe` mode.608. **Validate (`UX-8`)** — Cognitive walkthrough of every main journey on the produced design plus a traceability matrix (journey step → view → element → information tier → rule → states); fix every unserved step and orphan element before hand-off. Measure interaction cost per main journey (`UX-9`) and check wayfinding on every view (`UX-10`) (catalog §12).619. **Report** — Close with the **UI/UX Gate Report** (`UX-11`, catalog §13): one row per gate (`UX-*`, applicable `UI-*`, `AD-*`, `DD-*`, `CL-*` with at least the `CL-5` triage, UI copy), each `PASS` / `FAIL → fixed` / `N/A` with evidence; an unresolved `FAIL` blocks hand-off. Present to user for approval with the Journey Report, walkthrough result, matrix and Gate Report; update `./docs/design-guidelines.md` if needed.6263**Key Rules:**6465- Report the main user journeys (`UX-1`) first, then resolve the project's design principles, accepted design system and existing UI (`UX-2`); only then use this skill's local design-intelligence index as candidate input.66- Default to pure HTML/CSS/JS if the user doesn't specify a framework67- Use `visual analysis tooling` for generating AND reviewing real visual assets68- Use media processing tooling (RMBG) to remove backgrounds from generated assets when needed6970**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**7172## Contents7374- [Quick Summary](#quick-summary)75- [Arguments & Mode Dispatch](#arguments--mode-dispatch)76- [Required Skills (Priority Order)](#required-skills-priority-order)77- [Shared First Step (ALL design modes)](#shared-first-step-all-design-modes)78- [Design Intelligence Research Contract](#design-intelligence-research-contract)79- [UX Journey Contract (all design modes)](#ux-journey-contract-all-design-modes)80- [Design Principles Contract (all design modes)](#design-principles-contract-all-design-modes)81- [Action & Attention Contract (all design modes)](#action--attention-contract-all-design-modes)82- [Design-System Page Contract (prototype-producing modes)](#design-system-page-contract-prototype-producing-modes)83- [Mode Branches](#mode-branches)84- [Notes (all design modes)](#notes-all-design-modes)85- [Closing Reminders](#closing-reminders)8687## Arguments & Mode Dispatch8889`/ui-design --mode={fast|good|explore|describe|screenshot|video|review} --lane={product|marketing} <brief | screenshot | video | review scope>`9091- When `--mode` is omitted, default to `--mode=fast`.92- A request to see or choose between design options, with no explicit mode, goes to `--mode=explore`.93- An explicit `--mode` always wins; `--mode=review` is never inferred from the brief and is never the default.94- When `--lane` is omitted, default to `--lane=product` (the dominant task/app use). Pick `marketing` for landing pages, campaigns, and distinctive creative pieces.95- `--mode` (input carrier) and `--lane` (design tradition) are orthogonal — e.g. `--mode=screenshot --lane=product` recreates a dashboard screenshot in the product-UI craft tradition.96- `$ARGUMENTS` carries the full input after the command. Interpret it per mode: `fast`/`good`/`explore` → a text design brief; `describe`/`screenshot` → a screenshot reference (path/URL/attachment); `video` → a video reference; `review` → the review scope (files, directories or surfaces; empty = all uncommitted UI changes) plus the optional `--report-only` flag.9798### Lane selection (apply the chosen lane's craft body at stages 6-7)99100- **`--lane=product` (default)** — product UIs: dashboards, admin panels, SaaS apps, tools. Domain-driven craft (intent → domain exploration → signature → layered surfaces/tokens). Full body: `references/lane-product/lane-guide.md`.101- **`--lane=marketing`** — marketing/creative: landing pages, campaigns, screenshot replication. Bold aesthetic direction (distinctive type, cohesive palette, atmosphere, motion). Full body: `references/lane-marketing/lane-guide.md`.102103Do NOT inline the lane bodies here — read the matching `lane-guide.md` when the lane is selected.104105## Required Skills (Priority Order)1061071. **In-skill design-intelligence search/data** — Query `scripts/search.py` after the Journey Report (`UX-1`) and the design-authority/existing-UI read (`UX-2`); results are candidate input, not project authority.1082. **In-skill lane references** — `references/lane-{product|marketing}/lane-guide.md` (+ their reference files) own implementation, screenshot/video analysis, and design replication for the selected lane.1093. **In-skill explore references** — `references/explore/workflow.md` (+ `option-discovery.md`, `briefs.md`, `gate-files.md`, `brand-asset-protocol.md`) own the `--mode=explore` flow; read them only when that mode is selected. The option board shortlists from `data/style-families.csv` and `data/layout-archetypes.csv` (read the whole small family catalog; `search.py --domain family|layout` ranks rows that match the brief), assembles with `scripts/build-board.cjs`, and checks typefaces with `scripts/check-font-subsets.cjs`.1104. **In-skill review reference** — `references/mode-review.md` owns `--mode=review`; read it only when that mode is selected. `scripts/audit-actions.cjs` collects the action & attention evidence (`AD-5`) on a rendered local page: each count with the elements behind it and what was excluded and why, for the reviewer to confirm by eye; it never passes or fails a page. A tint is a low-emphasis near-neutral wash; saturated brand fills count as filled primaries.111112## Shared First Step (ALL design modes)113114> **[BLOCKING] Step 0 — Journey Report (`UX-1`).** Before any wireframe, mockup, design plan, token table, search result or code, analyze and PRESENT the main user journeys, per `SYNC:ux-journey-gate` and the template in `.claude/docs/ux-journey-process.md` §4: frame · actors + job statements · 3–5 ranked main journeys with step tables (intent · decision/action · information needed · business rule · system response · failure → recovery) · derived design requirements · assumptions and open questions, each claim tagged `SOURCED (location)` or `INFERRED`. Depth scales with scope (§10), never to zero for a new or reshaped view. **Confirm an inferred primary actor, main job or success outcome with the user before generating.**115>116> **[BLOCKING] Step 0b — Design authority read + existing UI (`UX-2`).** Resolve from `docs/project-config.json` and its reference docs, then read the project's design principles/guidelines, the design system (`designSystem.canonicalDoc`, `tokenFiles`, `appMappings[]`), accepted design ADRs, and the existing related UI — inventory the screens and components already serving this feature/domain and map every connected flow that links to / embeds / navigates to-or-from it (`SYNC:existing-ui-research`). Record `Design authority read: <paths>` or `N/A — none configured (checked: <paths>)`. Adopt house patterns; never invent tokens or components the project already defines.117>118> Skip Steps 0 and 0b ONLY for work with no user-facing surface, stated explicitly.119120**THEN**, after Steps 0 and 0b, run focused design-intelligence searches — framed by the Journey Report — to gather candidate input:121122```bash123# Windows: py -3 · macOS/Linux: python3 (same arguments)124py -3 .claude/skills/ui-design/scripts/search.py "<product-type>" --domain product125py -3 .claude/skills/ui-design/scripts/search.py "<style-keywords>" --domain style126py -3 .claude/skills/ui-design/scripts/search.py "<mood>" --domain typography127py -3 .claude/skills/ui-design/scripts/search.py "<industry>" --domain color128```129130## Design Intelligence Research Contract131132The local index is a research aid owned by this skill. It supplies structured candidates; it never outranks the adopter project's accepted brief, design system, tokens, components, frontend conventions, or accessibility requirements.1331341. **Frame the query.** Derive the product type, audience and job-to-be-done from the Journey Report (`UX-1`: frame, actors, job statements, main journeys), then add industry, desired style, platform, implementation stack, and constraints before searching.1352. **Search deliberately.** Query `product`, `style`, `typography`, and `color` first; add `landing`, `chart`, `ux`, `prompt`, and the relevant `--stack` query when the surface needs them. Use specific domain terms and more than one query when the brief has multiple concerns.1363. **Resolve and record authority.** Read `docs/project-config.json` and resolve `designSystem.canonicalDoc`, `tokenFiles`, and `appMappings[]` when present. Reconcile candidates against the accepted brief, existing-UI inventory, shared `UI-*`/`DD-*`/`CL-*` contracts, and the selected lane. Record why important candidates were selected or rejected; never invent tokens, components, breakpoints, or stack defaults when the project has not declared them.1374. **Keep implementation quality explicit.** Use the project's icon system or one consistent accessible SVG set; do not use emoji as UI icons; give each view ONE filled primary commit and render every other action by the `AD-1` table (icon-only named and tooltipped, icon + label, link, row target, overflow) in uniform groups; verify official brand marks. Define stable hover, focus, active, disabled, and loading feedback without layout shift, using the project's cursor and motion conventions.1385. **Design state coverage before the happy path.** Specify `Default`, `Loading`, `Disabled`, `Error`, `Empty`, and `Success` where applicable. Errors need human-readable recovery, empty states need a meaningful next action, in-flight actions must prevent duplicate submission, and successful actions need acknowledgment.1396. **Design for reachable reflow.** Use the project's content breakpoints. If none are declared, smoke-check 320, 768, 1024, and 1440 widths: rows reflow, grids collapse, non-reflow content has an intentional reachable scroll fallback, and nothing is clipped or unreachable. Surface any large refactor or new breakpoint as an explicit decision.140141`--mode=review` remains the owner of source-level findings, evidence, severity, component ownership, and review procedure. This contract makes the same quality floor explicit while authoring a design; it does not duplicate or replace the review mode.142143## UX Journey Contract (all design modes)144145The journey-first gate (`UX-1`–`UX-11`, `SYNC:ux-journey-gate`; deep catalog `.claude/docs/ux-journey-process.md`) binds EVERY design mode (`--mode=review` applies it through its own reference) and runs BEFORE `UI-*`/`DD-*`/`CL-*`, because those judge a surface whose purpose it defines. Steps 0 and 0b above deliver `UX-1` and `UX-2`.146147**Generative modes (`fast`, `good`, `explore`) — DERIVE the design from the journeys:**1481491. **Views are journey steps (`UX-3`)** — every view hosts ≥1 main-journey step and names its primary task; every step lands on a view; the container fits the task (catalog §2 S5).1502. **Priority per decision point (`UX-4`)** — rank each item and action by need-at-the-decision × frequency × cost-of-missing into Primary · Secondary · On demand · Not here; ONE focal point and ONE primary action = the journey's next step (catalog §6).1513. **Rules become interaction (`UX-5`)** — map each business rule to the lightest treatment that prevents the error before one that reports it; design each step's failure → recovery (catalog §7).1524. **Low-fi before hi-fi (`UX-7`)** — walk the main journeys on the ASCII structure before layering the `DD-3` Design Plan.1535. **Walk before reporting (`UX-8`)** — cognitive walkthrough of every main journey plus the traceability matrix (catalog §9); an unserved step or orphan element is fixed before hand-off.1546. **Interaction cost and wayfinding (`UX-9`, `UX-10`)** — per main journey record steps · clicks · view changes · fields · decisions against the existing flow or spec, and cut what does not advance the job (every click confident — no "3-click rule"). Every view answers where am I / where can I go / how do I get back, with no dead ends. The primary tier sits in the first viewport (catalog §12).1557. **Check every UI/UX gate (`UX-11`)** — every mode's final walk step also runs items 5–6 and ends with the UI/UX Gate Report (catalog §13) before the report to the user; a gate missing from the report counts as not checked.156157**Recreation modes (`describe`, `screenshot`, `video`) — INFER and REPORT:** the Journey Report names the journeys the observed UI serves (tagged `INFERRED` unless a spec or the user sources them); the walk RECORDS every violation it exposes (`UX-3`/`UX-4`/`UX-5`) — `describe` carries it into the implementation plan as a correction, `screenshot`/`video` fix it in the recreation and confirm with the user any fix that changes the visual match.158159## Design Principles Contract (all design modes)160161The 40 UI/UX Design Principles (`UI-1.1`–`UI-9.4`) carried as the `SYNC:ui-ux-design-principles` block below bind EVERY mode of this skill; `--mode=review` applies them as fail-conditions through its own reference. Project design-system docs OUTRANK them — surface a genuine conflict to the user with both sides, NEVER resolve it silently.162163**Generative modes (`fast`, `good`, `explore`) — APPLY the clauses as an output contract on the design you produce:**1641651. **States first.** Design and build the empty, loading and error state BEFORE the populated state (`UI-1.5`), and reserve space for anything that loads so nothing shifts in (`UI-9.3`).1662. **Supported interaction states.** Specify states for the platform/input modes (for example default, focus, active, disabled and loading); hover applies only where supported (`UI-5.2`). Preserve a visible focus indicator wherever focus navigation applies (`UI-5.5`).1673. **Declare purposeful type and spacing.** Use project/platform tokens, readable text measures and consistent scales (`UI-2.2`–`UI-2.5`, `UI-4.1`). Report those decisions at stage 9; do not impose a fixed step count, pixel base or font minimum without an authoritative requirement.1684. **Measure contrast.** State the selected accessibility standard, its applicable targets and measured results (`UI-3.1`); colour never carries meaning alone (`UI-3.3`). Catalog ratios are standard-specific examples, not universal values.1695. **Touch surfaces.** Meet the applicable platform/accessibility target-size and spacing requirements (`UI-8.1`); place primary actions for the actual device/orientation/input reachability (`UI-8.2`). Record N/A when touch is absent.170171**Reporting modes (`describe`, and the analysis pass of `screenshot` / `video`) — REPORT against the clauses:** the super-detailed description MUST name which clauses the OBSERVED design SATISFIES and which it VIOLATES, cited by ID — e.g. type-scale drift (`UI-2.5`), contrast failure with the measured ratio (`UI-3.1`), undersized touch targets (`UI-8.1`), missing empty/loading/error states (`UI-1.5`), a removed focus ring (`UI-5.5`). A violation is RECORDED, never silently reproduced: `describe` carries it into the implementation plan as a correction; `screenshot` / `video` then apply the five generative obligations above so the recreation FIXES the violation rather than inheriting it — flag any correction that changes the visual match and confirm it with the user before shipping it.172173## Action & Attention Contract (all design modes)174175The action & attention gate (`AD-1`–`AD-6`, `SYNC:ui-action-density-gate`; measurable checks `B16`, `C14`–`C20` in `.claude/docs/design-review-checklist.md`) binds every mode; `--mode=review` runs it as Phase 3D of its reference. Project design-system docs and the platform's guidelines outrank it. When its text is not in context, read `.claude/skills/shared/protocols/ui-action-density-gate.md` first.176177**Generative modes (`fast`, `good`, `explore`) — BUILD to it:** each view has at most ONE filled text button, for its main commit, with a fixed min-width; every other action takes its `AD-1` form; button groups share height, style and width; a list row is one target with at most one inline icon action; every icon-only control has a name, a tooltip on hover and focus, a full-size hit target and 3:1 contrast; a row carries a title plus one short meta line; one tile size and title baseline per collection-grid row, actions aligned to their content edge (`AD-6`). Record the `AD-5` counts in the UI/UX Gate Report.178179**Reporting and recreation modes (`describe`, `screenshot`, `video`) — REPORT, then correct:** name every observed violation by its check ID (`C14`–`C20`, `B16`). `describe` carries each one into the plan as a correction; `screenshot`/`video` fix it in the recreation and confirm with the user any fix that changes the visual match.180181## Design-System Page Contract (prototype-producing modes)182183The prototype design-system page (`PD-1`–`PD-6`, `SYNC:prototype-design-system`) binds every mode that emits a working design. When its text is not in context, read `.claude/skills/shared/protocols/prototype-design-system.md` first.184185- **`fast`, `good`, `screenshot`, `video` producing a prototype or mock-up (the default pure HTML/CSS/JS):** build the design from one catalog of tokens and reusable controls, each control defined once and reused in every view (`PD-3`), and save the design-system page beside the design, in the design's medium (HTML by default: `<design file name>-design-system.html`): the tokens plus a live catalog of every reusable control and component with its variants, states, plain contract, the views that use it, and its owner (existing source path, or `new — build once`) (`PD-2`). Brownfield entries come from the project's own design system and components, found from repository evidence (`PD-4`). Link the page in the report.186- **Production code in the project's stack:** no page beside the source; add or update the shared components and the project's living catalog (when it keeps one) instead, each control built once (`PD-1`, `PD-5`).187- **`describe`:** no page; the implementation plan lists the same catalog (each entry with its owner) and orders the shared components before the pages (`PD-5`).188- **`explore`:** drafts get no page (`PD-6`); the build after the pick ships one.189- **`review`:** a control implemented twice, or a catalog control re-styled locally, is checklist `M10`.190191## Mode Branches192193### `--mode=review` — UI review (read-only; replaces the design spine)194195**[BLOCKING] When `--mode=review`, read `references/mode-review.md` in full FIRST** and follow it as the whole invocation: Phase 0 load UI rules → scope and surfaces → blast radius → surface composition → surface UX pass → six UI categories plus the UI/UX principles and design-distinctiveness passes and the action-density pass → report → why-review validation → validated fix loop (none under `--report-only`). It carries its own protocols inline; do not run the design-spine steps, the design-intelligence search or a lane for it. Workflow invocation (`--mode=review --report-only`) and standalone both run it.196197### `--mode=fast` (default) — quick design1981991. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above; present the report and confirm an inferred primary actor/job/outcome before continuing (no question tool → record it `INFERRED — unconfirmed` and continue).2002. Run the shared design-intelligence searches above.2013. Use `ui-ux-designer` subagent to start the design process — brief it with the Journey Report and the `Design authority read:` paths; low-fi structure walked against the journeys first (`UX-7`).2024. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).2035. **Walk the main journeys (`UX-8`)** on the built design with the traceability matrix; fix every unserved step and orphan element.2046. Report back with a brief summary of the changes, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.2057. On approval, update `./docs/design-guidelines.md` if needed.206207### `--mode=good` — immersive, high-quality design208209Same spine as `fast`, raised to a higher quality bar (iterate on details):2102111. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above at full depth for the scope (catalog §10); present the report and confirm an inferred primary actor/job/outcome before continuing (no question tool → record it `INFERRED — unconfirmed` and continue).2122. Run comprehensive design-intelligence searches across the applicable domains.2133. Use `researcher` subagent to research design style, trends, fonts, colors, borders, spacing, elements' positions, etc.2144. Use `ui-ux-designer` subagent to implement the design step by step based on the Journey Report, the design authority and the research — low-fi structure walked against the journeys first (`UX-7`).2155. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).2166. **Walk the main journeys (`UX-8`)** on the built design with the traceability matrix; fix every unserved step and orphan element.2177. Report back with a summary, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.2188. On approval, update `./docs/design-guidelines.md` if needed.219220- **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.**221- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.222223### `--mode=explore` — research, 1–3 style × layout drafts, user picks or mixes, then `good`224225Opt-in. Use when the visual direction is genuinely open and the user wants to choose it by looking, when the owner asks to see design options (route such a request here from `fast` or `good`), or for a rebrand ("a new look for <existing product>": the design system's look is then free for the run) or a layout-only change ("keep the look, new layout"). **Read `references/explore/workflow.md` first and follow its steps (Step 0 draft count, then 1–10), one task each.** First action: its Step 0 asks `Option board → 3 drafts` / `3 drafts` / `1 draft` / skip (no question tool → ONE auto-selected draft). `--explore=styles` or `--explore=layouts` from a caller forces the board and its path (`styles` never frees a pinned colour or type on its own: explore Step 1 asks the owner). A picked Slide direction goes to a deck builder, not `good` (item 8).2262271. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above, produced ONCE before any seed and shared by all N drafts; confirm an inferred primary actor/job/outcome first (no question tool → record it `INFERRED — unconfirmed` and continue). The design-authority read also resolves **authority per axis** (colour · type · layout). Explicit tokens, named fonts or a stated "must use" in the brief pin an axis; adjectives and moods are a target feel to explore, not a pin (`VO-1`). A brief or project design system pinning all three axes → record it as `ADOPTED`, log the exemption, and run `--mode=good` instead; a design system pinning colour and type on a new page or flow → the option board's layout path. Partial pins → the drafts share the pinned axes and diverge only on the free ones.2282. **Ground before diverging** — fact-check named products/specs; with option discovery, run `references/explore/option-discovery.md` (research the top style families and layout archetypes at desktop and phone size, one numbered research board, and 3 combinations each pairing a different style with a different layout, recorded in `option-board.md`; no question before the drafts), otherwise ask once for reference designs the user likes or dislikes; run `references/explore/brand-asset-protocol.md` when a real brand is named, gather ONE shared content-imagery set (licensed, sources recorded) or labelled placeholders, answer the five form questions, fix the deliverable type and pixel canvas, write the `DD-3` Design Plan skeleton.2293. **N seeds (take the first N)** — with option discovery, its combinations (one style family and one layout archetype per draft, none repeated); otherwise a random style row from `node .claude/skills/ui-design/scripts/pick-style.cjs` (after changing a script or catalog, run its test in `.claude/skills/ui-design/tests/`, for example `node .claude/skills/ui-design/tests/pick-style.test.cjs`), the user's liked reference or a web-verified real-world reference, a studio persona described by traits only. Seeds are divergence seeds, never taste: each draft translates its seed into THIS subject (`DD-1`) and passes the `DD-3` generic test, or it is revised.2304. **Fan out** — N `ui-ux-designer` sub-agents in ONE message → `tmp/design/<run>/direction-{a,b,c}.html`; layout FREE → structurally different layout skeletons, layout ADOPTED → the pinned layout is shared and drafts diverge on the free axes only. Every draft serves the SAME main journeys and information-priority tiers (`UX-3`/`UX-4`) — drafts diverge on visual axes and layout skeleton, never on the journeys or the priority tier of content. No sub-agents → build serially; each later draft names what it avoided from the earlier ones.2315. **Render after all return** — per draft, `node .claude/skills/html-export/scripts/export.cjs --to=png --viewport=<canvas> --out=tmp/design/<run>/renders/<draft>/ <file>`; handle exits 0/4/3/1-2 per workflow step 8, re-render after the `DD-8` edit. NEVER run install commands.2326. **Present side by side, open every draft in the default browser, and ASK** — each draft with how it serves the primary journey; open each with `node .claude/scripts/open-report.cjs tmp/design/<run>/direction-<x>.html`, then, with 2–3 drafts, `ask user question tool` with one option per draft and your evidence-backed `(Recommended)` draft first (explore step 9); one draft → no question (`Selection: USER — 1 option`, or `AUTO-SELECTED — no question tool (1 draft)` set at Step 0); drafts cannot be shown or the question tool errors → AUTO-SELECT the recommended draft; record why either way (explore step 9 fallback). Never pick for the user while they can be asked; never offer a text-only style choice; "continue" is not a pick.2337. **Record** the user's verbatim choice, or the `Selection:` line, in `tmp/design/<run>/direction-approved.md` (template: `references/explore/gate-files.md`), with the chosen draft's Design Plan tokens in its `## Design Plan tokens` section.2348. **Walk the main journeys (`UX-8`)** on the chosen draft with the traceability matrix, record the gaps in the `## Journey fixes (UX-8)` table of `run-notes.md` as inputs, then continue as `--mode=good` from the chosen draft — except a Slide deliverable: hand two files, `direction-approved.md` (carrying the tokens) and `run-notes.md`, to a deck builder instead (`/presentation-builder` for a general deck — command-only, so stop and tell the user to run it; `feature-presentation` for a feature review deck; explore step 10).235236### `--mode=describe` — describe only (NO implementation)237238Treat `$ARGUMENTS` as the screenshot/video to describe.2392401. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above: infer and report the journeys the observed UI serves (tagged `INFERRED` unless sourced), and read the project design authority the implementation must adopt.2412. Use `visual analysis tooling` to describe super-details of the screenshot/video so a developer can implement it easily.242 - Be specific about design style, every element, elements' positions, every interaction, every animation, every transition, every color, every border, every icon, every font style/size/weight, every spacing/padding/margin, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc.243 - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.2443. Use `ui-ux-designer` subagent to create a design implementation **plan** following the progressive-disclosure structure so the result matches the screenshot/video:245 - Create a directory using the naming pattern from the `## Naming` section.246 - Save the overview access point at `plan.md`, keep it generic, under 80 lines, listing each phase with status/progress and links.247 - For each phase, add `phase-XX-phase-name.md` with sections (Context links, Overview with date/priority/statuses, Key Insights, Requirements, Architecture, Related code files, Implementation Steps, Todo list, Success Criteria, Risk Assessment, Security Considerations, Next steps).2484. **Walk the main journeys (`UX-8`)** on the observed UI with the traceability matrix; record every violation the walk exposes and carry it into the plan as a correction.2495. Report back with a summary of the plan, the Journey Report, the walkthrough findings and the UI/UX Gate Report (`UX-11`, recording the violations observed). **Do NOT implement.**250251### `--mode=screenshot` — recreate from image as code252253Treat `$ARGUMENTS` as the screenshot to recreate exactly.2542551. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above: infer and report the journeys the observed UI serves (tagged `INFERRED` unless sourced), and read the project design authority the recreation must adopt.2562. Use `visual analysis tooling` to describe super-details of the screenshot (design style, trends, fonts, colors, border, spacing, elements' positions, size, shape, texture, material, light, shadow, reflection, refraction, blur, glow, image, background transparency, transition, etc.).257 - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.2583. Use `ui-ux-designer` subagent to create a design plan following the progressive-disclosure structure (as in `describe`) so the final result matches the screenshot. Keep every research markdown report concise (≤150 lines).2594. Implement the plan step by step.2605. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).2616. **Walk the main journeys (`UX-8`)** on the recreation with the traceability matrix; fix every violation the walk exposes and confirm with the user any fix that changes the visual match.2627. Report back with a summary, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.2638. On approval, update `./docs/design-guidelines.md` if needed.264265- **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.**266- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.267268### `--mode=video` — recreate from video as code269270Treat `$ARGUMENTS` as the video to recreate exactly. Same as `--mode=screenshot`, but ingest a VIDEO and capture BOTH static layout AND interaction/animation/transition patterns.2712721. **Journey Report (`UX-1`) + design authority (`UX-2`)** — Steps 0 and 0b above: infer and report the journeys the observed flow serves (the video's interaction sequence is direct evidence; tag `INFERRED` unless sourced), and read the project design authority the recreation must adopt.2732. Use `visual analysis tooling` to describe super-details of the video: every element, every interaction, every animation, every transition, every color, every font, every border, every spacing, every size/shape/texture/material/light/shadow/reflection/refraction/blur/glow/image, background transparency, etc.274 - **IMPORTANT:** Predict the font name (Google Fonts) and font size — don't just use Inter or Poppins.2753. Use `ui-ux-designer` subagent to create a design plan following the progressive-disclosure structure so the final result matches the video. Keep every research markdown report concise (≤150 lines).2764. Implement the plan step by step.2775. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).2786. **Walk the main journeys (`UX-8`)** on the recreation with the traceability matrix; fix every violation the walk exposes and confirm with the user any fix that changes the visual match.2797. Report back with a summary, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.2808. On approval, update `./docs/design-guidelines.md` if needed.281282- **ALWAYS REMEMBER you have the skills of a top-tier UI/UX Designer who won many awards on Dribbble, Behance, Awwwards, Mobbin, TheFWA.**283- Create storytelling designs, immersive 3D experiences, micro-interactions, and interactive interfaces.284285## Notes (all design modes)286287- **Design system (canonical):** When implementing UI — HTML, CSS, or SCSS — read `docs/project-config.json` first, then resolve `designSystem.canonicalDoc`, `tokenFiles`, and `appMappings[]`. Read every configured authority before choosing tokens, component patterns, breakpoints, or BEM conventions. If the project has no configured authority, record `N/A` and follow the selected lane plus t288289…(truncated)