# UI Design

> [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.

- Skill: `duc01226/ui-design` (Agent Skill, multi-file: 104 files)
- Install (CLI): `npx get-skill add duc01226/ui-design`
- Raw SKILL.md: https://api.skillmd.com/api/skills/duc01226/ui-design/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Marketing & Growth
- Author: duc01226 (https://skillmd.com/u/duc01226)
- Updated: 2026-11-14
- Page: https://skillmd.com/skills/duc01226/ui-design

---


> Codex compatibility note:
> - Invoke `$skill-name`: load the registered `.agents/skills/<name>/SKILL.md` and execute it with Codex tools; no separate `Skill` tool or Claude mode switch is needed. When a workflow step or another skill names a skill, read that file in full yourself (every line, with no line limit; in parts only when output is cut off): a skill whose implicit invocation is off is never loaded for you. Author `.claude/**`; mirrors are generated.
> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.
> - Map foreign tool names to available host capabilities. A name mismatch needs no approval; an actually unavailable required capability stops with its step/evidence and a user question before adaptation.
> - Subagent authorization: when a skill is user-invoked or AI-detected and its protocol requires subagents, that skill activation authorizes use of the required `spawn_agent` subagent(s) for that task.
> - Preserve protocol order unless the user approves a deviation. Workflows use `$start-workflow`: gates stay fixed; other steps may flex with logged reasons and evidence.
> **[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):**

1. **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.
2. **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>)`.
3. **Research** — Run this skill's design-intelligence search, framed by the Journey Report; results are candidates only, never project authority.
4. **Ingest** — For visual modes (`describe`/`screenshot`/`video`), use `visual analysis tooling` to analyze the screenshot/video in super-detail.
5. **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.
6. **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.
7. **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.
8. **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).
9. **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

- [Quick Summary](#quick-summary)
- [Arguments & Mode Dispatch](#arguments--mode-dispatch)
- [Required Skills (Priority Order)](#required-skills-priority-order)
- [Shared First Step (ALL design modes)](#shared-first-step-all-design-modes)
- [Design Intelligence Research Contract](#design-intelligence-research-contract)
- [UX Journey Contract (all design modes)](#ux-journey-contract-all-design-modes)
- [Design Principles Contract (all design modes)](#design-principles-contract-all-design-modes)
- [Action & Attention Contract (all design modes)](#action--attention-contract-all-design-modes)
- [Design-System Page Contract (prototype-producing modes)](#design-system-page-contract-prototype-producing-modes)
- [Mode Branches](#mode-branches)
- [Notes (all design modes)](#notes-all-design-modes)
- [Closing Reminders](#closing-reminders)

## 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)

1. **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.
2. **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.
3. **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`.
4. **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:

```bash
# 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.

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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:**

1. **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).
2. **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).
3. **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).
4. **Low-fi before hi-fi (`UX-7`)** — walk the main journeys on the ASCII structure before layering the `DD-3` Design Plan.
5. **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.
6. **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).
7. **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:**

1. **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`).
2. **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`).
3. **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.
4. **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.
5. **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

1. **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).
2. Run the shared design-intelligence searches above.
3. 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`).
4. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
5. **Walk the main journeys (`UX-8`)** on the built design with the traceability matrix; fix every unserved step and orphan element.
6. 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.
7. 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):

1. **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).
2. Run comprehensive design-intelligence searches across the applicable domains.
3. Use `researcher` subagent to research design style, trends, fonts, colors, borders, spacing, elements' positions, etc.
4. 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`).
5. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
6. **Walk the main journeys (`UX-8`)** on the built design with the traceability matrix; fix every unserved step and orphan element.
7. Report back with a summary, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.
8. 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 <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).

1. **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.
2. **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.
3. **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.
4. **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.
5. **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.
6. **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.
7. **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.
8. **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.

1. **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.
2. 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.
3. 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).
4. **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.
5. 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.

1. **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.
2. 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.
3. 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).
4. Implement the plan step by step.
5. If the user doesn't specify, create the design in pure HTML/CSS/JS, with its design-system page (Design-System Page Contract).
6. **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.
7. Report back with a summary, the walkthrough result and the UI/UX Gate Report (`UX-11`); ask the user to review and approve.
8. 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.

1. **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.
2. 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.
3. 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).

…(truncated)
