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.
Workflow Calls and Todo Bootstrap
Read the registry → workflows.workflow-spec-to-mockup together with this skill. Call $start-workflow workflow-spec-to-mockup to resolve the selected mode, pre-actions and fingerprint.
Todo FIRST: before triage, analysis or step execution, create one todo per phase of the selected mode, in order, listing every occurrence of that phase as a line, including conditional/optional ones (a mode that declares no phases gets one todo per occurrence); preserve occurrence IDs, roles and barrier groups. Use native todo tools or an equivalent persistent ledger. Then mark the first todo in_progress; close each step line with its run or skip evidence, and complete a phase todo only when every line is closed and its applicable exit gates hold.
Mode selection and registry loading prepare tracking; any 'first action' below means the first substantive action after this bootstrap.
Call each step skill: start its linked SKILL.md through the active host's skill call with the registry args. When the host refuses that call (a user-only skill) or has no skill call, read the SKILL.md in full yourself (every line, with no line limit; in parts only when output is cut off) and follow it with the same args; that is the same execution, not a bypass. Naming a skill alone is not execution. After a context compaction, re-read the SKILL.md of the step in progress before continuing: compaction can drop or truncate a loaded skill. Required gates and core/optional flex follow the linked start-workflow Step Execution Protocol; keep this skill's quality gates, loops and evidence requirements.
Conditions: load each occurrence's registry applicability.when and skipReason verbatim, and record its run/skip evidence through the linked start-workflow protocol. Do not silently omit a todo or turn a conditional skill into an unconditional call; close, in one batch at triage, the todos whose condition is already false there. Declared parallel groups retain their all-return barrier.
Explicit step-skill calls by mode (registry order; roles and conditions remain owned by the registry):
Regenerate this block with node .claude/scripts/lib/workflow-skill-contract.cjs --write after registry edits; $sync-codex refreshes it before mirroring.
Quick Summary
Goal: Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.
Summary: Scope gate → triage → design spec → design review (--type=design) → mockup (--explore; it also renders the per-view evidence and links the spec's mockup: frontmatter) → UI review → close. Reuse reviewed journeys; record the user's direction before building the full app. A skip retains design review and workflow gates with explicit N/A mockup evidence.
Use when: a PO/BA/designer wants to click through a UI-bearing canonical spec before planned work or build. Adjacent routes: raw idea → workflow-planned-work --mode=idea-to-spec (or --mode=idea-to-tasks for planned work with mockups); spec + planned work → workflow-planned-work (spec-to-tasks); specified behavior to build → workflow-implement-spec; backend-only spec → no mockup.
Key Rules: Scope/pick stay in the main session; journey-first generation and review gates remain fixed; produce no task, story, plan or production code.
IMPORTANT MANDATORY Steps: $design-spec -> $work-item --mode=review --type=design --fix-loop -> $work-item --mode=mockup --explore -> $ui-design --mode=review -> $workflow-end -> $watzup
Step contract: Follow $start-workflow → Step Execution Protocol. The registry owns recommended order, roles and applicability; invoke each selected skill through the active host and log deviations. Gates (work-item --mode=review --type=design, ui-design --mode=review, workflow-end) always run; the optional step runs only when applicability.when holds. On a skip, UI review records N/A — no mockup to review.
Contents
0. Mockup Scope Gate (FIRST action of the run)
Run work-item --mode=mockup Step 0 before any reading, analysis or $design-spec; it owns the question, options and no-question-tool fallback. Record its answer once for the whole run; later --explore reuses it. Keep the question in the main session; delegated agents may build direction drafts. Asking first lets a skip save tokens and time.
Skip mockup → record Mockup: SKIPPED by user; run $design-spec, $work-item --mode=review --type=design, and the $ui-design --mode=review gate with N/A — no mockup to review, then $workflow-end (and $watzup only when its registry condition holds). Log $work-item --mode=mockup as an N/A deviation (no mockup exists). The §3 gates Direction selected, Releasable multi-view mock app, Render evidence, Journeys walked and Spec linked (mockup:) record N/A — Mockup: SKIPPED by user.
1. Triage (right after the §0 scope gate, before choosing steps)
Record the result as the first section of the run report.
| Check |
Verdict that changes the route |
| Source |
Resolve every spec path the user named, or search the business spec root (default docs/specs; specRoots.business.path in docs/project-config.json overrides). No canonical spec → stop and route to workflow-planned-work (idea-to-spec). |
| UI intent layer |
The spec carries the interaction surface (SYNC:ui-intent-layer: view inventory with information priority and container role, navigation map, observable states, per-story action flows) in the role its artifact profile declares. Missing → run spec [mode=update] on the spec first, or record the gap and derive it in design-spec with every derived item tagged INFERRED. Backend-only spec → stop: no mockup applies, state the reason. |
| Scope |
One spec → one run. Several specs → one mockup per spec; 3+ specs → one sub-agent per spec for design-spec, while the explore pick stays with the user per spec. |
| Direction authority |
The brief or the project design system pins colour, type and layout → --explore records the exemption and builds directly; the design system pins colour and type on a new page or flow → the option board's layout path (archetypes built from the project's components); nothing pinned → the style path (the design spec drafted earlier in this run is a proposal, not a pin; the pick updates its §0 and §4); brief adjectives are a feel, not a pin (VO-1); some axes pinned → the drafts share them and diverge only on the free axes. |
| Existing companions |
A linked design spec or mockup already exists → update it in place (design-spec / work-item --mode=mockup against that path) instead of creating a second one. |
2. Journey-First Design Order (BLOCKING — every generation step)
Follow SYNC:ux-journey-gate; read .claude/docs/ux-journey-process.md when generating or reviewing a surface. No wireframe, direction draft, token table or mockup HTML precedes the Journey Report.
design-spec Step 0a writes the Journey Report (UX-1) and design-authority record (UX-2).
work-item --mode=mockup reuses both at Step 2a/3, re-confirming only changes. Surface a journey conflicting with the reviewed design spec to the user; never silently re-derive it.
ui-design --mode=review walks every main journey (UX-8). The mockup closes with the UI/UX Gate Report (UX-11); fix any unserved step, orphan element or open FAIL before handoff.
3. Required Quality Gates
Rows marked (gate) are registry gate steps or outcome gates; the other rows are the quality bar of the core design-spec and work-item --mode=mockup --explore steps; §0 lists the rows a user-skipped mockup records as N/A.
| Gate |
Evidence that proves it |
Journey Report first (UX-1) |
The design spec's §0a Journey Report precedes every other design output; inferred critical claims confirmed with the user, or recorded INFERRED — unconfirmed (no question tool). |
Design authority read (UX-2) |
Design authority read: … or N/A recorded in the design spec header before any section. |
Design spec review converged (review-converged, gate) |
$work-item --mode=review --type=design PASS or WARN, including its UI/UX principles pass, the M1–M7 gate and the design_spec: link-back; validated findings fixed and re-reviewed. |
| Direction selected |
N rendered drafts (the §0 count) of the primary journey's key views under tmp/design/<run>/, sharing journeys, views and priority tiers, and in tmp/design/<run>/direction-approved.md one of: the user's verbatim pick (Selection: USER) · Selection: USER — 1 option · Selection: AUTO-SELECTED — <reason> (no question tool, drafts unshowable, or the question tool errored) · the recorded exemption when the brief or design system pins every axis; or Mockup: SKIPPED by user in the run report. Never pick while the user can be asked; "continue", "looks good" or silence is NOT a pick. |
| Design spec matches the pick |
When the pick differs from the design spec's §0, §3 or §4, the mockup step's Step 8 updated them in place (re-reviewed when §3 changed) and its Step 7 fidelity check confirms they match the mock app; the run report lists the change. |
| Releasable multi-view mock app |
One self-contained mockup per spec with every required view, navigation edge, component and state (empty, loading and error first) and a connected full-flow demo of each main journey (.claude/skills/shared/releasable-task-contract.md); one static or disconnected screen fails. |
Design-system page (PD-1–PD-6) |
The mockup step's Step 5b page beside the final mockup: tokens and every reusable control with variants, states, contract, views and owner; no control defined twice (M10) |
| Render evidence |
The mockup step's Step 7 render (html-export --to=png, required in this review-gated workflow) over the final mockup's journey views, passed to the UI review: exit 0 = per-view render evidence only · exit 4 = fix the mockup and re-render · exit 3 = NOT VERIFIABLE plus a setup pointer, never an install · exit 1/2 or any other code = tool failure, NOT VERIFIABLE. Only files the run's report.json files[] names count. |
Journeys walked (UX-8, gate) |
$ui-design --mode=review walkthrough log and traceability matrix with no unserved step and no orphan element, plus the UI-* / AD-* / DD-* / CL-* findings validated, fixed in the mockup and re-reviewed; the UI/UX Gate Report has no unresolved FAIL. |
| Spec linked |
The spec's companion-artifact frontmatter (design_spec: / mockup: in the portable fallback) points at the design spec and the final mockup — design-spec sets design_spec: and the mockup step sets mockup: (or the profile's native link, N/A with the reason when the profile declares none); frontmatter only, spec body untouched. |
Run closed (run-closed, gate) |
$workflow-end checked every outcome gate (top-level runs only). |
4. Recommended Skills
| Skill |
Earns its cost when |
Proves / feeds |
$design-spec |
always — the tech-agnostic UI spec seeded from the spec's UI intent layer; its Journey Report and design-authority read are the journey-first evidence every later step reuses |
UX-1, UX-2, design_spec: link |
$work-item --mode=review --type=design |
always (gate) — before any visual direction is drawn, so drafts inherit reviewed journeys and priority |
review-converged gate |
$work-item --mode=mockup --explore |
unless §0 recorded Mockup: SKIPPED by user; pass --source=<spec path> and the design-spec path as context. It reuses the §0 answer and owns the drafts, the user's recorded pick, the full mock app build, the Step 7 per-view render evidence (html-export --to=png; add --slides='[data-state]' to capture every screen state) that ui-design --mode=review inspects, and the spec's mockup: link |
direction pick + mock app + render evidence + spec linked |
$ui-design --mode=review |
always (gate) — scope = the final mockup file |
UX-8 walkthrough + UI-*/AD-*/DD-*/CL-* |
$workflow-end → $watzup |
$workflow-end always, last (prints the recap); $watzup only when its registry condition holds |
run-closed gate + handoff |
5. Orchestration Freedom
Choose inline/delegated work, batching and order through the Step Execution Protocol. Preserve these dependencies: reviewed design spec → direction drafts → recorded pick → full app → render → UI review; fixes land before re-review; $workflow-end closes the run.
Keep the explore pick and every user confirmation in the main session, never parallelized or auto-answered while the user can be asked. Auto-selection is limited to the recorded mockup-owner paths: no question tool, drafts unshowable, question tool error. For direction drafts, spawn all N in ONE message and wait for all returns. Each sub-agent brief carries the spec path, Journey Report, design-authority paths and Design Plan skeleton verbatim; it inherits no conversation context. Triage's 3+ spec rule also applies to design-spec delegation.
6. Memory, Reporting and Fix Path
- One task per phase with a row per step (rows per spec when several) so nothing is lost after compaction; write the run report
tmp/reports/workflow-spec-to-mockup-{YYMMDD}-{HHmm}-{slug}.md FIRST and append per step; after compaction re-read it, the current task list and tmp/design/<run>/direction-approved.md before continuing.
- Artifact placement: drafts, renders, product facts and run notes are disposable run output under
tmp/design/<run>/ (<run> = YYMMDD-HHmm-<slug>); the design spec lives under the team-artifacts root (default team-artifacts/; docsRoots.teamArtifacts.path in docs/project-config.json overrides); the final mockup lives at the work-item --mode=mockup spec-source output path, design-specs/ under the same team-artifacts root — never inside the business spec root, which holds canonical specs only.
- Fix path: findings are validated before fixing; fix journey, priority or rule findings in the design spec (and re-run
work-item --mode=review --type=design), visual or interaction findings in the mockup (and re-render, then re-run ui-design --mode=review), and spec-intent gaps in the spec through spec [mode=update]. Review loop: round 1 exits on zero open findings (LOW deferral); round 2 on zero CRITICAL/HIGH/MEDIUM with LOWs recorded as deferred; cap 3 review rounds; escalate via ask user question tool on no progress.
- Handoff at close: spec path(s), design-spec path(s), the final mockup path(s), the picked direction and its
Selection: line quoted from direction-approved.md (or Mockup: SKIPPED by user), the walkthrough verdict per main journey, render evidence or NOT VERIFIABLE, open questions below 80% confidence, and the next route — workflow-planned-work (spec-to-tasks) for planned work or workflow-implement-spec to build.
Protocol guides — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.
design-distinctiveness-gate — Design identity gate DD-1 to DD-8: subject, design plan, generic test, restraint; designing, implementing or reviewing a visual surface → .claude/skills/shared/protocols/design-distinctiveness-gate.md
incremental-persistence — Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.md
prototype-design-system — Prototype design-system page PD-1 to PD-6: tokens and a live catalog of reusable controls beside every mock-up, each control built once and planned before the pages; generating a mock-up or prototype, or planning or building one → .claude/skills/shared/protocols/prototype-design-system.md
session-goal-ledger — Keep the original goal and every user prompt of the session; running a long or multi-prompt session → .claude/skills/shared/protocols/session-goal-ledger.md
subagent-return-contract — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md
ui-action-density-gate — Action and attention gate AD-1 to AD-6: one primary text button, lighter forms for other actions, uniform groups, named icons, a copy budget, regular aligned grids; designing, mocking up, building or reviewing a user-facing surface with actions or text → .claude/skills/shared/protocols/ui-action-density-gate.md
ui-intent-layer — Tech-agnostic UI intent layer in every UI-bearing spec; writing a spec for a feature with a user interface → .claude/skills/shared/protocols/ui-intent-layer.md
ui-ux-design-principles — Forty usability and accessibility clauses, UI-1.1 to UI-9.4; designing, building or reviewing a user-facing interface → .claude/skills/shared/protocols/ui-ux-design-principles.md
ux-journey-gate — Journey-first UX gate UX-1 to UX-11: report journeys, read the design authority, generate, then check every UI/UX gate; generating, specifying, planning, mocking up or reviewing a user-facing surface → .claude/skills/shared/protocols/ux-journey-gate.md
visual-option-discovery — Research top styles and layouts, build options that each pair a different style with a different layout, and the owner picks or mixes; choosing the look, feel or layout of a new brand, product, page, flow or deck → .claude/skills/shared/protocols/visual-option-discovery.md
workflow-registry-binding — Read the workflow registry entry and the workflow skill together, since they must agree; executing or editing a workflow → .claude/skills/shared/protocols/workflow-registry-binding.md
- MANDATORY For UI-bearing specs, author/maintain the tech-agnostic interaction-surface layer (views with information priority now/later/not-here and container role + navigation map + observable states + user-action flows), resolving it through the configured profile's intent/evidence roles and logical IDs; an unresolved owner, role, ID, carrier, or link stays
UNKNOWN/BLOCKED. Strict portable fallback — only when neither config nor local references declares a native artifact contract: trace each flow to the default US-/OP-/BR- IDs and record the companion artifact in the design_spec:/mockup: frontmatter keys. Name ZERO frameworks/routes/CSS/component classes; skip ONLY for backend-only features with a stated reason.
- MUST ATTENTION journey-first, BLOCKING order: REPORT the main user journeys (
UX-1, evidence-tagged; confirm an inferred actor/job/outcome, or with no question tool record it INFERRED — unconfirmed and continue) → READ project design principles, design system, existing UI (UX-2) → generate → CHECK all gates. Checks: views = journey steps (UX-3) · important information first — one focal point, one primary action = next step, first viewport holds the primary tier (UX-4) · rules become prevention, states, recovery (UX-5) · the user's mental model (UX-6) · low-fi first (UX-7) · walkthrough + traceability, no unserved step or orphan (UX-8) · interaction cost per journey measured — steps, clicks, view changes, fields, decisions — every click confident, not a 3-click rule (UX-9) · wayfinding: where am I, where can I go, how do I get back, no dead ends (UX-10) · close with the UI/UX Gate Report covering UX-*, UI-*, AD-*, DD-*, CL-* and UI copy — an unresolved FAIL blocks hand-off (UX-11). Catalog: .claude/docs/ux-journey-process.md. Skip ONLY with no user-facing surface, stated.
- MUST ATTENTION taste is judged by seeing: after the Journey Report and the design-authority read, research top style families AND the best layout archetypes, then build N options (default 3) as real drafts, each a different style paired with a different layout (
VO-*, .claude/skills/ui-design/references/explore/option-discovery.md). Brief adjectives are a feel to explore, not a pin, and a real pin still wins (VO-1) · a design system adopts style, so only layout varies (VO-2) · at least half the families outside the brief's adjectives, divergent by family and archetype, tell risk shown (VO-3) · no style or layout used twice, style kept separable from layout so the owner can mix (VO-4) · same screens side by side at desktop and phone, labelled style and layout, the research board as evidence (VO-5) · phone, speed, accessibility and script support per option (VO-6) · one pick question after the drafts, recommended first; a mix ("style of B, layout of A") or a swap becomes one new draft, shown and confirmed; recorded verbatim; silence is not a pick (VO-7) · at most two mix and two broaden rounds (VO-8) · shared capture tools, one folder per worker, source and date recorded, patterns only, never published, no consent, bot-check, sign-in, form or download (VO-9). Runs only in explore and only in the main session; skip only with nothing to choose, every axis pinned, the research declined at the scope gate, or no question tool, and record which.
Apply UI-1.1–UI-9.4 only to applicable user-interface work. Resolve platform and project conventions first. Use WCAG 2.2 AA as the web accessibility baseline plus any stricter applicable legal/project requirement; non-web surfaces use the documented platform standard. Other web/mobile metrics and component tiers are defaults/examples only for matching surfaces. Skip N/A clauses and non-UI work explicitly. Project config, references, and accepted decisions govern; cite applicable findings by UI-<clause> + file:line.
- MUST ATTENTION apply the design distinctiveness gate (
DD-1–DD-8) to any user-facing visual surface: ground it in the named subject/audience/job and confirm when the brief is silent (DD-1) · every choice carries a WHY, token names included (DD-2) · write a design plan (colour 4–6 named hex · type families+roles+scale · layout prose+ASCII+alignment · principles) then run the BLOCKING generic test and state what you revised BEFORE coding (DD-3) · audit every free axis against the T1–T5 tell catalog — cream+serif+#D97757, acid-on-black, broadsheet, the SaaS-card kit, template chrome (ALL-CAPS eyebrows, A · B · C, spaced-em-dash labels, #0B0B0B, mono data labels, trailing →) — a match is a missed decision, never a defect (DD-4) · 1–2 clearly distinct families, real scale, <80ch, no single-word headline accent / ALL-CAPS labels / redundant eyebrows (DD-5) · numbering only on real sequences; hero = the subject's most characteristic thing, not big-number+gradient (DD-6) · one orchestrated motion moment, never per-section entrances plus universal card hovers (DD-7) · spend boldness once, critique the BUILT page, remove one accessory (DD-8). The brief's stated direction OUTRANKS the tell catalog; project design-system docs OUTRANK these clauses — genuine conflicts go to the user, NEVER resolved silently. Cite findings as DD-<clause> + file:line. Skip ONLY for surfaces with no user-facing visuals, stated explicitly.
- MANDATORY Session goal ledger per the
Task Planning Rules: pin Original goal:, keep User prompts this session: P1…Pn, and map the result to every prompt before claiming done; full text: .claude/skills/shared/protocols/session-goal-ledger.md.
- MUST ATTENTION actions and attention (
AD-1–AD-6): at most ONE filled text button per view, dialog, screenful or independent region, for the commit of its main task (parallel options may each carry it), with a fixed min-width; every other action takes the lightest form that keeps its meaning — a same-size quieter button, an icon-only button (named and tooltipped, only for universally understood icons), icon + short label, a text link, the whole row as target, or an overflow menu; destructive actions are never a bare icon (AD-1) · text-button groups share height, style, alignment and width, no filled/outlined mix in a repeated list (a footer, action bar or hero may add same-size quieter buttons), no filled or boxed button per row, by default one inline icon action per row (AD-2) · one icon family; every icon-only control has an accessible name, a tooltip on hover AND focus, the selected standard's minimum target and ≥ 3:1 contrast (AD-3) · one focal point; a row = title + by default one short meta line; no paragraph walls (AD-4) · measure per view and report the AD row of the UI/UX Gate Report; a finding resting only on an undeclared default caps at P3 (AD-5) · tiles in one collection grid share one size and baseline, the grid fills its width, actions align to their content edge (AD-6). Checks: checklist B16, C14–C20. Platform guidelines and the project design system outrank; report a defect once. Skip ONLY with no user-facing actions or text, stated.
- MUST ATTENTION every mock-up or prototype ships a self-contained design-system page beside it, in its medium (HTML mock-up:
<name>-design-system.html), linking to the project's living component catalog when one exists (PD-1): the tokens plus a live catalog of every reusable control and component (buttons, inputs, tables, grids, lists, cards, icons, states), each with its variants, states, a plain contract, the views that use it and its owner, an existing source path or new — build once (PD-2) · the prototype defines each recurring control once and reuses it in every view (PD-3) · brownfield entries are extracted from the project's own design system and components, found from repository evidence (PD-4) · a plan builds the shared components in a phase before the screens, and a control implemented twice is a finding (M10, PD-5) · a one-component change lists only the touched entries; explore drafts and decks get none (PD-6). Skip ONLY when no user-facing prototype is generated or implemented, stated.
Closing Reminders
IMPORTANT MUST ATTENTION Goal: Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.
MUST ATTENTION Main steps: scope gate → triage → $design-spec → $work-item --mode=review --type=design → $work-item --mode=mockup --explore (render evidence + mockup: link) → $ui-design --mode=review → $workflow-end → conditional $watzup.
- MUST ATTENTION report journeys (
UX-1) and read design authority (UX-2) before generating; walk every main journey with traceability (UX-8); no open UI/UX FAIL at handoff.
- MUST ATTENTION scope gate FIRST, before analysis or drafting. Keep scope and direction picks in the main session; record the
Selection: line and never choose while the user can be asked.
- MUST ATTENTION deliver the full multi-view app: every view, navigation edge, component and state, with a connected full-flow demo per journey; one static screen fails.
- MUST ATTENTION design review, UI review and workflow-end gates always run. A skip records UI review N/A; render exit 3 is
NOT VERIFIABLE, never an install.
- NEVER produce tasks, stories, plans or production code; keep drafts/renders in
tmp/design/<run>/ and edit only companion-artifact frontmatter in the spec.
| Evasion |
Required action |
| "The user said continue" |
Record an actual direction pick; continue, looks good and silence are not picks. |
| "One screen demonstrates it" |
Cover every required journey, view, state and navigation edge. |
| "No mockup, skip all gates" |
Run design review, the UI-review N/A gate, and workflow-end. |
1---2name: workflow-spec-to-mockup3description: '[Workflow] Turn UI-bearing canonical specs into reviewed, interactive multi-view HTML mockups; stop before planned work or production code.'4disable-model-invocation: false5metadata:6 source: https://skillmd.com/skills/duc01226/workflow-spec-to-mockup7---89> Codex compatibility note:10> - 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.11> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.12> - 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.13> - 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.14> - 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.15<!-- WORKFLOW-CALLS:START -->16## Workflow Calls and Todo Bootstrap1718Read [the registry](../../../.claude/workflows.json) → `workflows.workflow-spec-to-mockup` together with this skill. Call [`$start-workflow workflow-spec-to-mockup`](../start-workflow/SKILL.md) to resolve the selected mode, pre-actions and fingerprint.1920**Todo FIRST:** before triage, analysis or step execution, create one todo per phase of the selected mode, in order, listing every occurrence of that phase as a line, including conditional/optional ones (a mode that declares no phases gets one todo per occurrence); preserve occurrence IDs, roles and barrier groups. Use native todo tools or an equivalent persistent ledger. Then mark the first todo `in_progress`; close each step line with its run or skip evidence, and complete a phase todo only when every line is closed and its applicable exit gates hold.21Mode selection and registry loading prepare tracking; any 'first action' below means the first substantive action after this bootstrap.2223**Call each step skill:** start its linked SKILL.md through the active host's skill call with the registry args. When the host refuses that call (a user-only skill) or has no skill call, read the SKILL.md in full yourself (every line, with no line limit; in parts only when output is cut off) and follow it with the same args; that is the same execution, not a bypass. Naming a skill alone is not execution. After a context compaction, re-read the SKILL.md of the step in progress before continuing: compaction can drop or truncate a loaded skill. Required gates and core/optional flex follow the linked start-workflow Step Execution Protocol; keep this skill's quality gates, loops and evidence requirements.2425**Conditions:** load each occurrence's registry `applicability.when` and `skipReason` verbatim, and record its run/skip evidence through the linked start-workflow protocol. Do not silently omit a todo or turn a conditional skill into an unconditional call; close, in one batch at triage, the todos whose condition is already false there. Declared parallel groups retain their all-return barrier.2627Explicit step-skill calls by mode (registry order; roles and conditions remain owned by the registry):2829- Mode `default`: [`$design-spec`](../design-spec/SKILL.md) (core) → [`$work-item --mode=review --type=design --fix-loop`](../work-item/SKILL.md) (gate) → [`$work-item --mode=mockup --explore`](../work-item/SKILL.md) (core) → [`$ui-design --mode=review`](../ui-design/SKILL.md) (gate) → [`$workflow-end`](../workflow-end/SKILL.md) (gate) → [`$watzup`](../watzup/SKILL.md) (optional; conditional)30 Phase todos: Specify (3) → Review (1; exit review-converged) → Close (2; exit run-closed)31<!-- workflow-mode:default fingerprint:4d93e1c663cb488ac21baa7f6a687edade7884a88ef8f2f1721be6acddcf30c1 -->3233Regenerate this block with `node .claude/scripts/lib/workflow-skill-contract.cjs --write` after registry edits; [`$sync-codex`](../sync-codex/SKILL.md) refreshes it before mirroring.34<!-- WORKFLOW-CALLS:END -->3536## Quick Summary3738**Goal:** Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.3940**Summary:** Scope gate → triage → design spec → design review (`--type=design`) → mockup (`--explore`; it also renders the per-view evidence and links the spec's `mockup:` frontmatter) → UI review → close. Reuse reviewed journeys; record the user's direction before building the full app. A skip retains design review and workflow gates with explicit N/A mockup evidence.4142**Use when:** a PO/BA/designer wants to click through a UI-bearing canonical spec before planned work or build. **Adjacent routes:** raw idea → `workflow-planned-work --mode=idea-to-spec` (or `--mode=idea-to-tasks` for planned work with mockups); spec + planned work → `workflow-planned-work` (`spec-to-tasks`); specified behavior to build → `workflow-implement-spec`; backend-only spec → no mockup.4344**Key Rules:** Scope/pick stay in the main session; journey-first generation and review gates remain fixed; produce no task, story, plan or production code.4546**IMPORTANT MANDATORY Steps:** $design-spec -> $work-item --mode=review --type=design --fix-loop -> $work-item --mode=mockup --explore -> $ui-design --mode=review -> $workflow-end -> $watzup4748**Step contract:** Follow `$start-workflow` → Step Execution Protocol. The registry owns recommended order, roles and applicability; invoke each selected skill through the active host and log deviations. Gates (`work-item --mode=review --type=design`, `ui-design --mode=review`, `workflow-end`) always run; the optional step runs only when `applicability.when` holds. On a skip, UI review records `N/A — no mockup to review`.4950## Contents5152- [Workflow Calls and Todo Bootstrap](#workflow-calls-and-todo-bootstrap)53- [Quick Summary](#quick-summary)54- [0. Mockup Scope Gate (FIRST action of the run)](#0-mockup-scope-gate-first-action-of-the-run)55- [1. Triage (right after the §0 scope gate, before choosing steps)](#1-triage-right-after-the-0-scope-gate-before-choosing-steps)56- [2. Journey-First Design Order (BLOCKING — every generation step)](#2-journey-first-design-order-blocking--every-generation-step)57- [3. Required Quality Gates](#3-required-quality-gates)58- [4. Recommended Skills](#4-recommended-skills)59- [5. Orchestration Freedom](#5-orchestration-freedom)60- [6. Memory, Reporting and Fix Path](#6-memory-reporting-and-fix-path)61- [Closing Reminders](#closing-reminders)6263## 0. Mockup Scope Gate (FIRST action of the run)6465Run `work-item --mode=mockup` Step 0 before any reading, analysis or `$design-spec`; it owns the question, options and no-question-tool fallback. Record its answer once for the whole run; later `--explore` reuses it. Keep the question in the main session; delegated agents may build direction drafts. Asking first lets a skip save tokens and time.6667`Skip mockup` → record `Mockup: SKIPPED by user`; run `$design-spec`, `$work-item --mode=review --type=design`, and the `$ui-design --mode=review` gate with `N/A — no mockup to review`, then `$workflow-end` (and `$watzup` only when its registry condition holds). Log `$work-item --mode=mockup` as an N/A deviation (no mockup exists). The §3 gates Direction selected, Releasable multi-view mock app, Render evidence, Journeys walked and Spec linked (`mockup:`) record `N/A — Mockup: SKIPPED by user`.6869## 1. Triage (right after the §0 scope gate, before choosing steps)7071Record the result as the first section of the run report.7273| Check | Verdict that changes the route |74| --- | --- |75| **Source** | Resolve every spec path the user named, or search the business spec root (default `docs/specs`; `specRoots.business.path` in `docs/project-config.json` overrides). No canonical spec → stop and route to `workflow-planned-work` (`idea-to-spec`). |76| **UI intent layer** | The spec carries the interaction surface (`SYNC:ui-intent-layer`: view inventory with information priority and container role, navigation map, observable states, per-story action flows) in the role its artifact profile declares. Missing → run `spec [mode=update]` on the spec first, or record the gap and derive it in `design-spec` with every derived item tagged `INFERRED`. Backend-only spec → stop: no mockup applies, state the reason. |77| **Scope** | One spec → one run. Several specs → one mockup per spec; 3+ specs → one sub-agent per spec for `design-spec`, while the explore pick stays with the user per spec. |78| **Direction authority** | The brief or the project design system pins colour, type and layout → `--explore` records the exemption and builds directly; the design system pins colour and type on a new page or flow → the option board's layout path (archetypes built from the project's components); nothing pinned → the style path (the design spec drafted earlier in this run is a proposal, not a pin; the pick updates its §0 and §4); brief adjectives are a feel, not a pin (`VO-1`); some axes pinned → the drafts share them and diverge only on the free axes. |79| **Existing companions** | A linked design spec or mockup already exists → update it in place (`design-spec` / `work-item --mode=mockup` against that path) instead of creating a second one. |8081## 2. Journey-First Design Order (BLOCKING — every generation step)8283Follow `SYNC:ux-journey-gate`; read `.claude/docs/ux-journey-process.md` when generating or reviewing a surface. No wireframe, direction draft, token table or mockup HTML precedes the Journey Report.8485- `design-spec` Step 0a writes the Journey Report (`UX-1`) and design-authority record (`UX-2`).86- `work-item --mode=mockup` reuses both at Step 2a/3, re-confirming only changes. Surface a journey conflicting with the reviewed design spec to the user; never silently re-derive it.87- `ui-design --mode=review` walks every main journey (`UX-8`). The mockup closes with the UI/UX Gate Report (`UX-11`); fix any unserved step, orphan element or open `FAIL` before handoff.8889## 3. Required Quality Gates9091Rows marked **(gate)** are registry `gate` steps or outcome gates; the other rows are the quality bar of the core `design-spec` and `work-item --mode=mockup --explore` steps; §0 lists the rows a user-skipped mockup records as `N/A`.9293| Gate | Evidence that proves it |94| --- | --- |95| **Journey Report first** (`UX-1`) | The design spec's §0a Journey Report precedes every other design output; inferred critical claims confirmed with the user, or recorded `INFERRED — unconfirmed (no question tool)`. |96| **Design authority read** (`UX-2`) | `Design authority read: …` or `N/A` recorded in the design spec header before any section. |97| **Design spec review converged** (`review-converged`, gate) | `$work-item --mode=review --type=design` PASS or WARN, including its UI/UX principles pass, the M1–M7 gate and the `design_spec:` link-back; validated findings fixed and re-reviewed. |98| **Direction selected** | N rendered drafts (the §0 count) of the primary journey's key views under `tmp/design/<run>/`, sharing journeys, views and priority tiers, and in `tmp/design/<run>/direction-approved.md` one of: the user's verbatim pick (`Selection: USER`) · `Selection: USER — 1 option` · `Selection: AUTO-SELECTED — <reason>` (no question tool, drafts unshowable, or the question tool errored) · the recorded exemption when the brief or design system pins every axis; or `Mockup: SKIPPED by user` in the run report. Never pick while the user can be asked; "continue", "looks good" or silence is NOT a pick. |99| **Design spec matches the pick** | When the pick differs from the design spec's §0, §3 or §4, the mockup step's Step 8 updated them in place (re-reviewed when §3 changed) and its Step 7 fidelity check confirms they match the mock app; the run report lists the change. |100| **Releasable multi-view mock app** | One self-contained mockup per spec with every required view, navigation edge, component and state (empty, loading and error first) and a connected full-flow demo of each main journey (`.claude/skills/shared/releasable-task-contract.md`); one static or disconnected screen fails. |101| **Design-system page** (`PD-1`–`PD-6`) | The mockup step's Step 5b page beside the final mockup: tokens and every reusable control with variants, states, contract, views and owner; no control defined twice (`M10`) |102| **Render evidence** | The mockup step's Step 7 render (`html-export --to=png`, required in this review-gated workflow) over the final mockup's journey views, passed to the UI review: exit 0 = per-view render evidence only · exit 4 = fix the mockup and re-render · exit 3 = `NOT VERIFIABLE` plus a setup pointer, never an install · exit 1/2 or any other code = tool failure, `NOT VERIFIABLE`. Only files the run's `report.json` `files[]` names count. |103| **Journeys walked** (`UX-8`, gate) | `$ui-design --mode=review` walkthrough log and traceability matrix with no unserved step and no orphan element, plus the `UI-*` / `AD-*` / `DD-*` / `CL-*` findings validated, fixed in the mockup and re-reviewed; the UI/UX Gate Report has no unresolved `FAIL`. |104| **Spec linked** | The spec's companion-artifact frontmatter (`design_spec:` / `mockup:` in the portable fallback) points at the design spec and the final mockup — `design-spec` sets `design_spec:` and the mockup step sets `mockup:` (or the profile's native link, `N/A` with the reason when the profile declares none); frontmatter only, spec body untouched. |105| **Run closed** (`run-closed`, gate) | `$workflow-end` checked every outcome gate (top-level runs only). |106107## 4. Recommended Skills108109| Skill | Earns its cost when | Proves / feeds |110| --- | --- | --- |111| `$design-spec` | always — the tech-agnostic UI spec seeded from the spec's UI intent layer; its Journey Report and design-authority read are the journey-first evidence every later step reuses | `UX-1`, `UX-2`, `design_spec:` link |112| `$work-item --mode=review --type=design` | always (gate) — before any visual direction is drawn, so drafts inherit reviewed journeys and priority | review-converged gate |113| `$work-item --mode=mockup --explore` | unless §0 recorded `Mockup: SKIPPED by user`; pass `--source=<spec path>` and the design-spec path as context. It reuses the §0 answer and owns the drafts, the user's recorded pick, the full mock app build, the Step 7 per-view render evidence (`html-export --to=png`; add `--slides='[data-state]'` to capture every screen state) that `ui-design --mode=review` inspects, and the spec's `mockup:` link | direction pick + mock app + render evidence + spec linked |114| `$ui-design --mode=review` | always (gate) — scope = the final mockup file | `UX-8` walkthrough + `UI-*`/`AD-*`/`DD-*`/`CL-*` |115| `$workflow-end` → `$watzup` | `$workflow-end` always, last (prints the recap); `$watzup` only when its registry condition holds | run-closed gate + handoff |116117## 5. Orchestration Freedom118119Choose inline/delegated work, batching and order through the Step Execution Protocol. Preserve these dependencies: reviewed design spec → direction drafts → recorded pick → full app → render → UI review; fixes land before re-review; `$workflow-end` closes the run.120121Keep the explore pick and every user confirmation in the main session, never parallelized or auto-answered while the user can be asked. Auto-selection is limited to the recorded mockup-owner paths: no question tool, drafts unshowable, question tool error. For direction drafts, spawn all N in ONE message and wait for all returns. Each sub-agent brief carries the spec path, Journey Report, design-authority paths and Design Plan skeleton verbatim; it inherits no conversation context. Triage's 3+ spec rule also applies to `design-spec` delegation.122123## 6. Memory, Reporting and Fix Path124125- One task per phase with a row per step (rows per spec when several) so nothing is lost after compaction; write the run report `tmp/reports/workflow-spec-to-mockup-{YYMMDD}-{HHmm}-{slug}.md` FIRST and append per step; after compaction re-read it, the current task list and `tmp/design/<run>/direction-approved.md` before continuing.126- **Artifact placement:** drafts, renders, product facts and run notes are disposable run output under `tmp/design/<run>/` (`<run>` = `YYMMDD-HHmm-<slug>`); the design spec lives under the team-artifacts root (default `team-artifacts/`; `docsRoots.teamArtifacts.path` in `docs/project-config.json` overrides); the final mockup lives at the `work-item --mode=mockup` spec-source output path, `design-specs/` under the same team-artifacts root — never inside the business spec root, which holds canonical specs only.127- **Fix path:** findings are validated before fixing; fix journey, priority or rule findings in the design spec (and re-run `work-item --mode=review --type=design`), visual or interaction findings in the mockup (and re-render, then re-run `ui-design --mode=review`), and spec-intent gaps in the spec through `spec [mode=update]`. Review loop: round 1 exits on zero open findings (LOW deferral); round 2 on zero CRITICAL/HIGH/MEDIUM with LOWs recorded as deferred; cap 3 review rounds; escalate via `ask user question tool` on no progress.128- **Handoff at close:** spec path(s), design-spec path(s), the final mockup path(s), the picked direction and its `Selection:` line quoted from `direction-approved.md` (or `Mockup: SKIPPED by user`), the walkthrough verdict per main journey, render evidence or `NOT VERIFIABLE`, open questions below 80% confidence, and the next route — `workflow-planned-work` (`spec-to-tasks`) for planned work or `workflow-implement-spec` to build.129130<!-- PROTOCOL-GUIDES:START -->131132> **Protocol guides** — Apply each protocol only when its read-when condition holds. If a protocol's text is not in your context, read its file below before you act on it.133134- `design-distinctiveness-gate` — Design identity gate DD-1 to DD-8: subject, design plan, generic test, restraint; designing, implementing or reviewing a visual surface → .claude/skills/shared/protocols/design-distinctiveness-gate.md135- `incremental-persistence` — Persist results per file or section while the work proceeds; a sub-agent or heavy step processes more than three files → .claude/skills/shared/protocols/incremental-persistence.md136- `prototype-design-system` — Prototype design-system page PD-1 to PD-6: tokens and a live catalog of reusable controls beside every mock-up, each control built once and planned before the pages; generating a mock-up or prototype, or planning or building one → .claude/skills/shared/protocols/prototype-design-system.md137- `session-goal-ledger` — Keep the original goal and every user prompt of the session; running a long or multi-prompt session → .claude/skills/shared/protocols/session-goal-ledger.md138- `subagent-return-contract` — Sub-agents return a structured envelope and a report path, never an inline report; spawning a sub-agent → .claude/skills/shared/protocols/subagent-return-contract.md139- `ui-action-density-gate` — Action and attention gate AD-1 to AD-6: one primary text button, lighter forms for other actions, uniform groups, named icons, a copy budget, regular aligned grids; designing, mocking up, building or reviewing a user-facing surface with actions or text → .claude/skills/shared/protocols/ui-action-density-gate.md140- `ui-intent-layer` — Tech-agnostic UI intent layer in every UI-bearing spec; writing a spec for a feature with a user interface → .claude/skills/shared/protocols/ui-intent-layer.md141- `ui-ux-design-principles` — Forty usability and accessibility clauses, UI-1.1 to UI-9.4; designing, building or reviewing a user-facing interface → .claude/skills/shared/protocols/ui-ux-design-principles.md142- `ux-journey-gate` — Journey-first UX gate UX-1 to UX-11: report journeys, read the design authority, generate, then check every UI/UX gate; generating, specifying, planning, mocking up or reviewing a user-facing surface → .claude/skills/shared/protocols/ux-journey-gate.md143- `visual-option-discovery` — Research top styles and layouts, build options that each pair a different style with a different layout, and the owner picks or mixes; choosing the look, feel or layout of a new brand, product, page, flow or deck → .claude/skills/shared/protocols/visual-option-discovery.md144- `workflow-registry-binding` — Read the workflow registry entry and the workflow skill together, since they must agree; executing or editing a workflow → .claude/skills/shared/protocols/workflow-registry-binding.md145146<!-- PROTOCOL-GUIDES:END -->147148<!-- SYNC:ui-intent-layer:reminder -->149150- **MANDATORY** For UI-bearing specs, author/maintain the tech-agnostic interaction-surface layer (views with information priority now/later/not-here and container role + navigation map + observable states + user-action flows), resolving it through the configured profile's intent/evidence roles and logical IDs; an unresolved owner, role, ID, carrier, or link stays `UNKNOWN`/`BLOCKED`. **Strict portable fallback — only when neither config nor local references declares a native artifact contract:** trace each flow to the default `US-`/`OP-`/`BR-` IDs and record the companion artifact in the `design_spec:`/`mockup:` frontmatter keys. Name ZERO frameworks/routes/CSS/component classes; skip ONLY for backend-only features with a stated reason.151152<!-- /SYNC:ui-intent-layer:reminder -->153154<!-- SYNC:ux-journey-gate:reminder -->155156- **MUST ATTENTION** journey-first, BLOCKING order: REPORT the main user journeys (`UX-1`, evidence-tagged; confirm an inferred actor/job/outcome, or with no question tool record it `INFERRED — unconfirmed` and continue) → READ project design principles, design system, existing UI (`UX-2`) → generate → CHECK all gates. Checks: views = journey steps (`UX-3`) · important information first — one focal point, one primary action = next step, first viewport holds the primary tier (`UX-4`) · rules become prevention, states, recovery (`UX-5`) · the user's mental model (`UX-6`) · low-fi first (`UX-7`) · walkthrough + traceability, no unserved step or orphan (`UX-8`) · interaction cost per journey measured — steps, clicks, view changes, fields, decisions — every click confident, not a 3-click rule (`UX-9`) · wayfinding: where am I, where can I go, how do I get back, no dead ends (`UX-10`) · close with the **UI/UX Gate Report** covering `UX-*`, `UI-*`, `AD-*`, `DD-*`, `CL-*` and UI copy — an unresolved `FAIL` blocks hand-off (`UX-11`). Catalog: `.claude/docs/ux-journey-process.md`. Skip ONLY with no user-facing surface, stated.157158<!-- /SYNC:ux-journey-gate:reminder -->159160<!-- SYNC:visual-option-discovery:reminder -->161162- **MUST ATTENTION** taste is judged by seeing: after the Journey Report and the design-authority read, research top style families AND the best layout archetypes, then build N options (default 3) as real drafts, each a different style paired with a different layout (`VO-*`, `.claude/skills/ui-design/references/explore/option-discovery.md`). Brief adjectives are a feel to explore, not a pin, and a real pin still wins (`VO-1`) · a design system adopts style, so only layout varies (`VO-2`) · at least half the families outside the brief's adjectives, divergent by family and archetype, tell risk shown (`VO-3`) · no style or layout used twice, style kept separable from layout so the owner can mix (`VO-4`) · same screens side by side at desktop and phone, labelled style and layout, the research board as evidence (`VO-5`) · phone, speed, accessibility and script support per option (`VO-6`) · one pick question after the drafts, recommended first; a mix ("style of B, layout of A") or a swap becomes one new draft, shown and confirmed; recorded verbatim; silence is not a pick (`VO-7`) · at most two mix and two broaden rounds (`VO-8`) · shared capture tools, one folder per worker, source and date recorded, patterns only, never published, no consent, bot-check, sign-in, form or download (`VO-9`). Runs only in explore and only in the main session; skip only with nothing to choose, every axis pinned, the research declined at the scope gate, or no question tool, and record which.163164<!-- /SYNC:visual-option-discovery:reminder -->165166<!-- SYNC:ui-ux-design-principles:reminder -->167168Apply `UI-1.1`–`UI-9.4` only to applicable user-interface work. Resolve platform and project conventions first. Use WCAG 2.2 AA as the web accessibility baseline plus any stricter applicable legal/project requirement; non-web surfaces use the documented platform standard. Other web/mobile metrics and component tiers are defaults/examples only for matching surfaces. Skip N/A clauses and non-UI work explicitly. Project config, references, and accepted decisions govern; cite applicable findings by `UI-<clause>` + `file:line`.169170<!-- /SYNC:ui-ux-design-principles:reminder -->171172<!-- SYNC:design-distinctiveness-gate:reminder -->173174- **MUST ATTENTION** apply the design distinctiveness gate (`DD-1`–`DD-8`) to any user-facing visual surface: ground it in the named subject/audience/job and confirm when the brief is silent (`DD-1`) · every choice carries a WHY, token names included (`DD-2`) · write a design plan (colour 4–6 named hex · type families+roles+scale · layout prose+ASCII+alignment · principles) then run the BLOCKING generic test and state what you revised BEFORE coding (`DD-3`) · audit every free axis against the T1–T5 tell catalog — cream+serif+`#D97757`, acid-on-black, broadsheet, the SaaS-card kit, template chrome (ALL-CAPS eyebrows, `A · B · C`, spaced-em-dash labels, `#0B0B0B`, mono data labels, trailing `→`) — a match is a missed decision, never a defect (`DD-4`) · 1–2 clearly distinct families, real scale, <80ch, no single-word headline accent / ALL-CAPS labels / redundant eyebrows (`DD-5`) · numbering only on real sequences; hero = the subject's most characteristic thing, not big-number+gradient (`DD-6`) · one orchestrated motion moment, never per-section entrances plus universal card hovers (`DD-7`) · spend boldness once, critique the BUILT page, remove one accessory (`DD-8`). The brief's stated direction OUTRANKS the tell catalog; project design-system docs OUTRANK these clauses — genuine conflicts go to the user, NEVER resolved silently. Cite findings as `DD-<clause>` + `file:line`. Skip ONLY for surfaces with no user-facing visuals, stated explicitly.175176<!-- /SYNC:design-distinctiveness-gate:reminder -->177178179<!-- SYNC:session-goal-ledger:reminder -->180181- **MANDATORY** Session goal ledger per the `Task Planning Rules`: pin `Original goal:`, keep `User prompts this session: P1…Pn`, and map the result to every prompt before claiming done; full text: `.claude/skills/shared/protocols/session-goal-ledger.md`.182183<!-- /SYNC:session-goal-ledger:reminder -->184185<!-- SYNC:ui-action-density-gate:reminder -->186187- **MUST ATTENTION** actions and attention (`AD-1`–`AD-6`): at most ONE filled text button per view, dialog, screenful or independent region, for the commit of its main task (parallel options may each carry it), with a fixed min-width; every other action takes the lightest form that keeps its meaning — a same-size quieter button, an icon-only button (named and tooltipped, only for universally understood icons), icon + short label, a text link, the whole row as target, or an overflow menu; destructive actions are never a bare icon (`AD-1`) · text-button groups share height, style, alignment and width, no filled/outlined mix in a repeated list (a footer, action bar or hero may add same-size quieter buttons), no filled or boxed button per row, by default one inline icon action per row (`AD-2`) · one icon family; every icon-only control has an accessible name, a tooltip on hover AND focus, the selected standard's minimum target and ≥ 3:1 contrast (`AD-3`) · one focal point; a row = title + by default one short meta line; no paragraph walls (`AD-4`) · measure per view and report the `AD` row of the UI/UX Gate Report; a finding resting only on an undeclared default caps at P3 (`AD-5`) · tiles in one collection grid share one size and baseline, the grid fills its width, actions align to their content edge (`AD-6`). Checks: checklist `B16`, `C14`–`C20`. Platform guidelines and the project design system outrank; report a defect once. Skip ONLY with no user-facing actions or text, stated.188189<!-- /SYNC:ui-action-density-gate:reminder -->190191<!-- SYNC:prototype-design-system:reminder -->192193- **MUST ATTENTION** every mock-up or prototype ships a self-contained design-system page beside it, in its medium (HTML mock-up: `<name>-design-system.html`), linking to the project's living component catalog when one exists (`PD-1`): the tokens plus a live catalog of every reusable control and component (buttons, inputs, tables, grids, lists, cards, icons, states), each with its variants, states, a plain contract, the views that use it and its owner, an existing source path or `new — build once` (`PD-2`) · the prototype defines each recurring control once and reuses it in every view (`PD-3`) · brownfield entries are extracted from the project's own design system and components, found from repository evidence (`PD-4`) · a plan builds the shared components in a phase before the screens, and a control implemented twice is a finding (`M10`, `PD-5`) · a one-component change lists only the touched entries; explore drafts and decks get none (`PD-6`). Skip ONLY when no user-facing prototype is generated or implemented, stated.194195<!-- /SYNC:prototype-design-system:reminder -->196197## Closing Reminders198199**IMPORTANT MUST ATTENTION Goal:** Produce one reviewed, journey-validated, interactive multi-view HTML mock app per UI-bearing canonical spec, in the user's chosen direction (recorded fallback only when they cannot be asked), or no mockup when they skip; stop before planned work or implementation.200201**MUST ATTENTION Main steps:** scope gate → triage → `$design-spec` → `$work-item --mode=review --type=design` → `$work-item --mode=mockup --explore` (render evidence + `mockup:` link) → `$ui-design --mode=review` → `$workflow-end` → conditional `$watzup`.202203- **MUST ATTENTION** report journeys (`UX-1`) and read design authority (`UX-2`) before generating; walk every main journey with traceability (`UX-8`); no open UI/UX `FAIL` at handoff.204- **MUST ATTENTION** scope gate FIRST, before analysis or drafting. Keep scope and direction picks in the main session; record the `Selection:` line and never choose while the user can be asked.205- **MUST ATTENTION** deliver the full multi-view app: every view, navigation edge, component and state, with a connected full-flow demo per journey; one static screen fails.206- **MUST ATTENTION** design review, UI review and workflow-end gates always run. A skip records UI review N/A; render exit 3 is `NOT VERIFIABLE`, never an install.207- **NEVER** produce tasks, stories, plans or production code; keep drafts/renders in `tmp/design/<run>/` and edit only companion-artifact frontmatter in the spec.208209| Evasion | Required action |210| --- | --- |211| "The user said continue" | Record an actual direction pick; continue, looks good and silence are not picks. |212| "One screen demonstrates it" | Cover every required journey, view, state and navigation edge. |213| "No mockup, skip all gates" | Run design review, the UI-review N/A gate, and workflow-end. |