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] Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, $start-workflow → Workflow-step mode bounds this rule.
[BLOCKING] Before each step or sub-skill call, update todo tracking: set in_progress when step starts, set completed when step ends.
[BLOCKING] Every completed/skipped step MUST include brief evidence or explicit skip reason.
[BLOCKING] If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.
Quick Summary
Goal: Produce a complete, tech-agnostic UI/UX design spec that lets a developer rebuild the source outcome on ANY stack, preserving every required view, navigation path, component, state, token, responsive rule, accessibility need, demo journey, and governing-spec link.
Summary:
- Journey Report (
UX-1) → existing UI/connected flows and governing intent → design-authority read (UX-2) precede every spec section. Reuse reviewed companion evidence and governing view/state vocabulary; confirm inferred actor/job/outcome, or record unconfirmed when no question tool exists.
- Route input (design link → exported frames; image → visual analysis; sketch →
--mode=wireframe; task/text → requirements), then choose Quick, Full, or Full + Flow Diagram. Specify components, applicable states, tokens, responsive/accessibility behavior and the complete releasable flow.
- Walk every main journey and trace its steps, interaction cost and wayfinding (
UX-8–UX-10); finish the UI/UX Gate Report (UX-11). Save the design-spec/audit/component variant, update governing-spec companion frontmatter only, and satisfy M1–M5/M7 and logical-ID traceability.
Workflow:
- Journey Report — Report main user journeys (
UX-1) before any spec section
- Ground Source — Inventory UI/flows; seed governing §6 vocabulary; record design-authority read (
UX-2)
- Route Input — Choose visual, wireframe, task, or text path
- Set Scope — Choose Quick / Full / Flow Diagram
- Specify — Components, 7 states, tokens, responsive/accessibility/full-flow rules
- Walk + Trace — Walk each main journey; §8 traceability matrix (
UX-8)
- Save + Link — Save artifact; update Feature Spec frontmatter only
Key Rules:
- [BLOCKING] Journey-first order: Journey Report (
UX-1) → design-authority read (UX-2) → only then spec sections; every view hosts a journey step (UX-3) and §1b priority is computed per decision point (UX-4). Catalog: .claude/docs/ux-journey-process.md.
- Input routing: design link (e.g. a Figma URL)→ask the user to export the frames as images, then visual analysis; wireframe/sketch→
--mode=wireframe; screenshot→visual analysis.
- Reuse
design-system/ tokens and frontend-patterns-reference.md component patterns from the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides); include keyboard navigation, ARIA labels, and contrast.
- [BLOCKING] Tech-agnostic output: spec prose/headings follow
spec-principles.md §3 under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) — describe components by UX role, not framework/library names; source paths and class names appear ONLY in evidence fields (**Evidence**, [Source:]), frontmatter, and Mermaid.
- [BLOCKING] Releasable UI surface: apply
.claude/skills/shared/releasable-task-contract.md; the design spec must deepen, not reduce, the task/mockup page/view, navigation, component, state, and full-flow inventories.
Releasable outcome contract — Preserve one complete actor-facing journey (entry/context → action/input → validation/decision → visible or persisted result → exit/next path) with every required view, navigation edge, component, and state; incomplete or ambiguous outcomes stay blocked.
MUST ATTENTION READ .claude/skills/shared/releasable-task-contract.md for the full contract.
Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).
Contents
Design Specification
Create structured UI/UX design specification documents from requirements or tasks for developer handoff.
When to Use
- A task or user story needs a design spec before implementation
- Requirements need concrete layout, states, tokens, and responsive behavior
- A component inventory and interaction patterns need documentation
When NOT to Use
- Wireframes run internally via
--mode=wireframe — no separate skill call
- Building UI — use
ui-design --lane=marketing (marketing/creative) or ui-design --lane=product (product UIs)
- Reviewing UI code — use
web-design-guidelines
Prerequisites
Read before executing:
- The source task, user story, or requirements document
design-system/ under the reference-docs root (default docs/project-reference; docsRoots.projectReference.path in docs/project-config.json overrides) -- project design tokens (if applicable)
- Existing design specs in
design-specs/ under the team-artifacts root (default team-artifacts/; docsRoots.teamArtifacts.path in docs/project-config.json overrides) for format consistency
Frontend/UI Context
For frontend/UI work, read:
All three live under the reference-docs root (default docs/project-reference; a docsRoots.projectReference.path entry in docs/project-config.json overrides the path):
- Frontend patterns:
frontend-patterns-reference.md
- Styling reference:
configured styling reference
- Design system tokens:
design-system/README.md
Workflow
[BLOCKING] Step 0a — Journey Report (UX-1). Before ANY spec section, wireframe, design plan or token table, write §0a User Journeys (Output Format below; full template .claude/docs/ux-journey-process.md §4): frame (problem · business goal · success signal · constraints) · actors with context, expertise and frequency · one job statement per actor · the main journeys ranked by frequency × business value × risk × first-use criticality (catalog §5) · a step table per journey (intent · decision/action · information needed · business rule · system response · failure → recovery) · derived design requirements · assumptions and open questions.
- Evidence first: when a governing Feature Spec exists, its profile-resolved interaction flows and view inventory (strict-default §6.5 and §6.2) are the primary evidence — read them here (Step 0b reuses the same read), then stories/acceptance criteria, business logic in code, and the existing UI (catalog §3). Tag every claim
SOURCED (<location>) or INFERRED (<reason>).
- Companion mockup (reuse): when a
$work-item --mode=mockup run for the same feature already produced a reviewed Journey Report — tmp/design/<run>/journey-report.md (with its direction-approved.md and Design authority read: record), the Journey Report in its report, or a path the caller supplies — that report is the starting evidence: reuse it, re-confirm only what the source changed since, and surface (never silently re-derive) any journey that disagrees. An approved direction-approved.md seeds the §0 Design Plan (colour · type · layout recorded ADOPTED, still passing the DD-3 generic test). With no companion mockup available (standalone run) derive the report and plan as above. When this run's recorded mock-up scope answer is the option board and no design system or brief pins colour and type, mark §0 colour and type PROPOSED — the explore pick decides (still a complete, measured direction); the pick then updates §0, §3 and §4 in place (VO-1). With no answer recorded yet, any other answer, or no mock-up in the run, write §0 as this spec's own decided direction: a later mock-up in the run treats it as a proposal (its seed or shortlist place) and its pick updates the spec the same way.
- Confirm before generating: an INFERRED primary actor, main job or success outcome is confirmed with the user via
ask user question tool before any spec section is authored; with no question tool, record it INFERRED — unconfirmed (no question tool) in §0a assumptions and continue — never block.
- Depth by spec size (catalog §10): Quick Spec → actors + 1–2 main journeys with step tables for the view(s) in scope; Full Spec → the full template, 3–5 main journeys; multi-page flow → full template plus the cross-view navigation path. Never zero for a new or reshaped view.
Skip ONLY when the feature has no user-facing surface — state that explicitly.
[BLOCKING] Step 0 — Inventory existing UI + map connected flows (per SYNC:existing-ui-research). Before authoring, inventory related existing screens/components/pages and every connected feature flow (links, embeds, navigates to/from); record matched UI + flows in §1 so the spec fits the live UI system. Skip only backend-only work; state that explicitly.
[BLOCKING] Step 0b — Seed from governing interaction intent (when a spec exists). Resolve specArtifacts through the shared SDD contract before locating the canonical owner. Search the configured business spec root for this capability. Strict-default profile: read §6.2 View Inventory, §6.3 Navigation Map, §6.4 Key UI States and §6.5 Per-Story Interaction Flow. Declared native profile: read its configured intent sections and native interaction carriers; preserve owner-qualified scenario IDs and carrier cardinality. Malformed or unsupported declarations stop without fallback. Do not require §6 headings or add duplicate strict-default registries to a valid native owner.
- Reuse vocabulary verbatim: carry over the SAME view and observable-state names from the resolved owner. NEVER rename or repartition; both artifacts MUST use one language so the navigable hub works.
- Deepen, never diverge: keep intent tech-agnostic; add visual fidelity (layout, tokens, pixel detail). Map each resolved interaction step/state to visual treatment and preserve its native or strict-default logical-ID cross-refs.
- This coupling is the
SYNC:ui-intent-layer contract below; use that block for the full rule instead of restating it.
Skip ONLY when no governing Feature Spec exists; author the interaction frame from the source task/story and state which case applies.
[BLOCKING] Design-authority read (UX-2). Step 0 + Step 0b, together with reading design-system/ under the reference-docs root and the project's design principles/guidelines, styling conventions and accepted design ADRs (resolved from docs/project-config.json and its reference docs), form the design-authority read. Record it in the spec header as Design authority read: <paths> or N/A — none configured (checked: <paths>) BEFORE authoring any spec section; adopt house patterns and never invent a token or component the project already defines.
Read source input & route by type
| Input Detected |
Detection |
Action |
| Design-tool link |
A design-tool URL (e.g. figma.com) in text |
Ask the user via ask user question tool to export the frames as images, then continue on the image path |
| Image/screenshot |
Image file attached to prompt |
Use visual analysis tooling to extract design guidelines, then continue |
| Hand-drawn wireframe |
Image + "wireframe"/"sketch" keyword |
Run --mode=wireframe (internal — see "Mode: wireframe" section) |
| Task/story text |
Acceptance criteria present |
Extract UI requirements from text, continue |
| Verbal/text requirements |
No image, no URL, no task |
Clarify with user, then continue |
For ANY visual input, extract design context FIRST, then generate the spec.
Determine spec complexity
IF single form or simple component → Quick Spec (sections 0a compact, 1, 1b, 2-4, 8 walkthrough of those journeys, 9 UI/UX Gate Report)
IF full page or multi-component view → Full Spec (sections 0a, 0, 1-9)
IF multi-page flow → Full Spec + Flow Diagram
Build component inventory
- List needed UI components; classify reusable vs feature-specific; note existing shared-library/design-system components.
Define states and interactions
- Document applicable default, hover, active, focus, disabled, error, loading and empty states; user interactions, transitions and animations. Mark unsupported platform/input states N/A.
Extract design tokens
- Colors, typography, spacing, shadows, and border-radius; reference existing design-system tokens where possible.
Document responsive behavior
- Use configured/content-driven breakpoints; mobile 320–767px, tablet 768–1023px and desktop 1024px+ are web starting examples, not universal thresholds. Document layout, visibility and sizing changes at each applicable breakpoint.
- Small-screen minimum bar (spec it explicitly): the layout MUST stay usable on mobile. Preferred = reflow (rows
flex-wrap / row → column, grids collapse to one column). Where a component genuinely can't reflow (data tables, canvases, wide grids), specify a min-width/min-height + overflow: auto scroll as the accepted fallback — scrolling is OK. Hard requirement = nothing broken (no clipped, cut-off, or unreachable content/controls). If a component needs a large redesign to work on mobile, flag it for the user rather than assuming a rewrite.
6b. Walk the journeys (UX-8) — step through every §0a main journey on the spec as the named actor and answer the four walkthrough questions per step (knows the step is needed? sees the action? links it to the goal? sees progress?); fill §8 Journey Traceability. Fix every unserved step (no view/element) and orphan element (traces to no step, need or rule) before saving; record any remaining "no" in §7. Then fill §8's interaction-cost row per main journey (UX-9) and wayfinding check per view (UX-10), and close with §9 UI/UX Gate Report (UX-11) — every gate PASS / FAIL → fixed / N/A with evidence; an unresolved FAIL blocks saving as Approved.
Save artifact — pick the filename variant by artifact type; every path below is relative to the team-artifacts root (default team-artifacts/; a docsRoots.teamArtifacts.path entry in docs/project-config.json overrides the path):
- Design spec:
design-specs/{YYMMDD}-ux-designspec-{feature-slug}.md
- Accessibility audit:
design-specs/{YYMMDD}-ux-audit-{feature-slug}.md
- Single-component doc:
design-specs/{YYMMDD}-ux-component-{component-name}.md
Link back to the governing Feature Spec (when one exists). After saving the artifact, keep the spec the navigable hub: open the governing Feature Spec under the business spec root (default docs/specs/**; specRoots.business.path in docs/project-config.json overrides) and set its frontmatter design_spec: key to this design-spec's saved path (add the key if absent, update it if stale). If a mockup was also produced (e.g. via $work-item --mode=mockup), set the mockup: key the same way. Edit frontmatter only — never touch the canonical intent/contracts/evidence body (strict-default §1–§8). This satisfies the work-item --mode=review --type=design link-back gate, which fails when a design-spec exists but its path is not recorded in the spec's design_spec: frontmatter. Skip ONLY when no governing Feature Spec exists (the design-spec is standalone) — state that.
Role Context & Artifact Path (canonical)
Applies to writes under design-specs/ in the team-artifacts root (default team-artifacts/; docsRoots.teamArtifacts.path in docs/project-config.json overrides).
- Active Role: ui-ux-designer · Skill: design-spec
- Path:
design-specs/ under the team-artifacts root (default team-artifacts/; docsRoots.teamArtifacts.path in docs/project-config.json overrides) · Type: designspec · Role token: ux
- Template:
.claude/docs/team-artifacts/templates/design-spec-template.md (framework-owned path — NOT the configurable team-artifacts root in docs/project-config.json)
- Naming:
{YYMMDD}-ux-{type}-{slug}.md (general artifact-path pattern: {YYMMDD}-{role}-{type}-{slug}.md)
- Context: DESIGN SPEC — include component states, design tokens, accessibility requirements.
- Quality checklist:
- [ ] Journey Report (§0a, UX-1) precedes every other section, claims SOURCED/INFERRED · - [ ] Design authority read: recorded or N/A (UX-2) · - [ ] Every view hosts a journey step; information priority (UX-4 tiers) + container recorded per view · - [ ] §8 traceability matrix: no unserved step, no orphan element (UX-8) · - [ ] Interaction cost per journey + wayfinding per view (UX-9, UX-10) · - [ ] §9 UI/UX Gate Report complete, no open FAIL (UX-11) · - [ ] Action forms per view + AD-5 counts recorded (AD-1–AD-6) · - [ ] All states documented · - [ ] Design tokens specified · - [ ] Accessibility notes included · - [ ] Responsive breakpoints defined
Mode: wireframe (image → spec)
Read references/wireframe.md in full when --mode=wireframe is selected. It owns image analysis, business-operation mapping, task-section versus standalone output, confidence and human-review rules. This input adapter preserves Step 0a and continues through the normal output and M1–M5/M7 gates.
Output Format
# Design Spec: {Feature Name}
**Source:** {task/story reference}
**Date:** {YYMMDD}
**Status:** Draft | Review | Approved
**Design authority read (`UX-2`):** {design principles · design-system docs · styling conventions · design ADRs · existing screens read} | `N/A — none configured (checked: {paths})`
## 0a. User Journeys (`UX-1`)
**Frame:** {problem} · **Business goal:** {goal} · **Success signal:** {metric} · **Constraints:** {platform, rules, legacy, budget}
**Sources read:** {profile-resolved interaction flows/view inventory (strict-default §6.5/§6.2), task/story, business-rule sources, existing screens} · **Confidence:** {%}
| Actor | Context · expertise · frequency | Job statement (When…, I want to…, so I can…) | Source |
| ----- | ------------------------------- | --------------------------------------------- | ------ |
| {actor} | {device, interruptions · novice/expert · daily/rare} | {job} | SOURCED ({location}) / INFERRED ({reason}) |
**Main journeys (ranked by frequency × value × risk × first-use):**
| # | Journey | Actor | Trigger → outcome | Why main |
| - | ------- | ----- | ----------------- | -------- |
| J1 | {name} | {actor} | {trigger} → {outcome} | {score reason} |
**J1 — {name}** · Entry: {where from} · Exit: {where next}
| Step | Intent | Decision / action | Information needed | Business rule (logical ID) | System response | Failure → recovery |
| ---- | ------ | ----------------- | ------------------ | -------------------------- | --------------- | ------------------ |
| J1.1 | {intent} | {action} | {info} | BR-XX | {response} | {failure} → {recovery} |
**Derived design requirements:** views (step → view · container) · priority per view (top items · primary action) · rules → interaction treatment · critical states per view.
**Assumptions & open questions:** `INFERRED:` {assumption — confirmed?} · `OPEN:` {question}
## 0. Design Plan (`DD-1`–`DD-3`)
**Subject / audience / job:** {the concrete product, the actual person using it and where they are, and the verb they came to do}
| Part | Decision | Why — traced to the subject |
| -------------- | ------------------------------------------------- | ------------------------------------------------- |
| **Color** | {4–6 named hex values, named for this product's world} | {why these, for THIS subject} |
| **Type** | {1–2 clearly distinct families + roles + scale} | {why this voice suits the subject} |
| **Layout** | {one-sentence concept + alignment: left/centered/justified} | {what the proportions are saying} |
| **Principles** | {the ONE memorable element; what stays quiet around it} | {why this is what the user will remember} |
**Generic test:** {what you REVISED because it read like the default for any comparable screen — or `axes pinned by {brief | design-system doc path}`}
> **Adoption shortcut:** where the project has a design system / `interface-system.md` / token files, this section reads `ADOPTED — {doc path}` plus any axis re-decided WITH its reason. Re-deciding a settled axis silently is the incoherence this section prevents.
## 1. Overview
{1-2 sentence summary of what this UI does}
## 1b. Information Priority & Container
| View | Journey steps hosted | Primary task | Container (why) | Now — shown / asked here | Later — deferred to | Not here — owned by |
| ---- | -------------------- | ------------ | --------------- | ------------------------ | ------------------- | ------------------- |
| {view role} | {J1.1, J1.2} | {verb} | {full view / dialog / side panel / stepped flow / inline — why} | {items, tagged P / S / D} | {step or view} | {view} |
**Priority scoring (`UX-4`, catalog §6):** score each item and action per decision point on need-at-the-decision × frequency × cost-of-missing (1–3 each); tag `now` items **P** Primary (one focal point, ONE primary action = the journey's next step) · **S** Secondary · **D** On demand (progressive disclosure); the rest go to Later / Not here. Order within a tier follows the journey's step order; §3 Layout implements this rank, never reshuffles it.
**Inputs at creation vs deferred:** {the smallest set that makes a valid, useful record; everything else and where it is enriched later}
**Complexity budget:** {counts per view/step} vs `uiReview.complexityBudget` when the project declares one; otherwise the counts plus the reasoning for the primary user.
**Action forms (`AD-1`–`AD-2`):** {per view: the ONE filled primary commit · every other action → icon-only / icon + label / link / row target / overflow, and why · button groups with their shared min-width}
**Collection grids (`AD-6`):** {per grid: tile size and aspect ratio · title line clamp · the content edge its actions align to}
## 2. Component Inventory
| Component | Type | Owner (source path or `new — build once`) | Used in | Notes |
| --------- | -------- | ----------------------------------------- | ------- | --------------------------- |
| UserCard | New | new — build once | {views} | Displays user avatar + name |
| DataTable | Existing | {shared library path} | {views} | Reuse with custom columns |
Each reusable component here becomes an entry of the mock-up's design-system page (`PD-2`).
## 3. Layout
{Description or ASCII wireframe of layout structure}
- Desktop: {layout description}
- Tablet: {layout changes}
- Mobile: {layout changes}
## 4. Design Tokens
Every token traces to a §0 Design Plan decision. Names evoke this product's world, not a numeric ramp — a reader seeing only the token names should be able to guess what the product is (`DD-2`). Values come from the project's token files where they exist; a raw hex here that is not in §0's palette is a leak.
| Token | Value | Usage |
| ------------- | ------------------------ | --------------------- |
| $signal | #1976D2 | Action buttons, links |
| $text-body | 14px/1.5 {body family} | Body text |
| $gap-md | 16px | Section spacing |
## 5. States & Interactions
| Element | Default | Hover | Active | Disabled | Error |
| -------- | ---------- | ---------- | ---------- | ---------------- | ----- |
| Save btn | Blue/white | Darken 10% | Scale 0.98 | Gray/50% opacity | -- |
## 6. Accessibility
- Keyboard navigation order
- ARIA labels for interactive elements
- Icon-only controls: accessible name + tooltip on hover and focus, full-size hit target, 3:1 icon contrast (`AD-3`)
- Color contrast compliance notes
## 7. Open Questions
- {Any unresolved design decisions}
## 8. Journey Traceability (`UX-8`)
| Journey · step | View | Element(s) serving it | Information shown (tier) | Rule enforced | States covered | Walkthrough result |
| -------------- | ---- | --------------------- | ------------------------ | ------------- | -------------- | ------------------ |
| J1.1 | {view role} | {UX-role element} | {item (P/S/D)} | BR-XX | {empty, loading, error, success} | PASS / {which of the 4 questions failed → fix} |
**Unserved steps:** {none | step → fix} · **Orphan elements:** {none | element → removed or justified}
**Interaction cost (`UX-9`):**
| Journey | Steps | Clicks/taps | View changes | Fields | Decisions | vs baseline |
| ------- | ----- | ----------- | ------------ | ------ | --------- | ----------- |
| J1 | {n} | {n} | {n} | {n} | {n} | {same / −n / +n with reason} |
**Wayfinding (`UX-10`):** per view — where am I · where can I go · how do I get back · dead ends: {none | view → fix}
## 9. UI/UX Gate Report (`UX-11`)
| Gate | Result | Evidence |
| ---- | ------ | -------- |
| UX-1–UX-10 journey-first | PASS / FAIL → fixed / N/A | {section refs} |
| UI-1.1–UI-9.4 floor (applicable) | … | {measured values} |
| AD-1–AD-6 actions & attention | … | {§1b action forms · counts per view} |
| DD-1–DD-8 identity | … | {§0 generic test} |
| CL-1–CL-6 checklist (CL-5 triage minimum) | … | {findings} |
| UI copy | … | … |
Design-Principles Obligations (per spec section)
The spec is where the 40 UI/UX Design Principles (UI-1.1–UI-9.4, the SYNC:ui-ux-design-principles block below) become INHERITABLE — a downstream implementer builds what the spec SAYS, so an unstated clause is an unbuilt clause. Every spec this skill emits MUST carry these obligations in the named Output Format sections. Project design-system docs OUTRANK the clauses; a genuine conflict is surfaced to the user with both sides, NEVER resolved silently.
| Spec section |
Clause obligation the section MUST carry |
| §0a User Journeys |
Written FIRST, before §0 and every other section (UX-1): frame, actors + job statements, main journeys ranked by the catalog §5 score, a step table per journey (intent · decision · information needed · business rule · response · failure → recovery), derived requirements, assumptions. Every claim SOURCED (<location>) or INFERRED; an inferred primary actor, main job or success outcome is confirmed with the user (no question tool → recorded INFERRED — unconfirmed (no question tool)). The spec header records Design authority read: or N/A (UX-2). Depth follows Quick/Full (catalog §10), never zero. |
| §0 Design Plan |
The identity layer the 40 clauses do not cover (SYNC:design-distinctiveness-gate): name the subject/audience/job (DD-1), give all four plan parts a WHY traced to that subject (DD-2), and record the Generic test result — what you revised, or which axes the brief/design system already pinned (DD-3). A downstream implementer who receives no design plan supplies their own defaults, so an unstated direction is a templated build. |
| §1 Overview |
Name the ONE focal point of the screen (UI-1.1), and name the surface(s) in scope (web / mobile / both) so the mobile clauses (UI-8.1–UI-8.4) are either binding or explicitly skipped. |
| §1b Information Priority & Container |
Seed from the governing spec's View Inventory priority/container record when one exists (SYNC:ui-intent-layer); never repartition it silently. Every view names the §0a journey steps it hosts and every main-journey step lands on a view (UX-3); now items carry the UX-4 tier (Primary / Secondary / On demand) from the need-at-the-decision × frequency × cost-of-missing score, with ONE primary action matching the journey's next step. Every view names its primary task and a container that fits it — a long or multi-section entry task is a full view or stepped flow, not a dialog (checklist E9). Every input is justified at THIS step or deferred (UI-7.1, checklist §R1–R2); creation asks only for the smallest valid record. Alternate entry modes are a first explicit choice, not stacked in one view (B14). A spec whose now set exceeds the task FAILS this gate. Every view also names its ONE filled primary and each other action's AD-1 form; rows state their one meta line (AD-4). |
| §3 Layout |
Group by proximity and shared alignment edges; add a border or container only where it encodes a real boundary (UI-1.3, UI-1.4); justify each breakpoint by where the CONTENT stops working, not by a device name (UI-4.4). |
| §4 Design Tokens |
Adopt the project’s type scale, readable sizes, measures, line spacing, families/weights and spacing/grid tokens (UI-2.1–UI-2.5, UI-4.1). Otherwise choose purposeful, consistent values for the target platform and record why; example values are not universal fail thresholds. Container-owned spacing and clear group relationships remain required (UI-4.2–UI-4.3). |
| §4 Design Tokens (colour) |
Record the selected accessibility standard and its source, applicable contrast targets and measured values (UI-3.1); unavailable measurements stay NOT VERIFIABLE. Use the WCAG 2.2 AA web baseline plus stricter applicable requirements; non-web uses its documented standard. One accent with one job (UI-3.2); when dark mode applies, specify lifted surfaces and softened white text rather than inversion (UI-3.4). |
| §5 States & Interactions |
Author empty/loading/error before populated states (UI-1.5). Document supported default, hover, focus, active, disabled, error and loading states; mark unsupported states N/A (UI-5.2). Give immediate perceivable feedback and meaningful motion under documented platform/project timing and easing; honor reduced motion (UI-5.1, UI-5.4). Prefer undo, confirm only irreversible actions (UI-5.3). Keep labels visible, associate useful correction with the input at the appropriate validation point, and preserve entered data (UI-7.2–UI-7.5). |
| §6 Accessibility |
Preserve perceivable focus for supported focus navigation (UI-5.5); never convey meaning by colour alone (UI-3.3). On touch/mobile surfaces, meet the selected platform/accessibility target-size and spacing requirements; place actions where reachable, provide required alternatives to gesture-only actions, and respect safe areas and keyboards (UI-8.1–UI-8.4). Record applicable constraints and evidence; unsupported capabilities are N/A. |
| §7 Open Questions |
Every clause deliberately deviated from, with the project doc or user decision that authorises it — an undocumented deviation is a spec defect, not a style choice. |
| §8 Journey Traceability |
One row per §0a journey step: view → element → information tier → rule → states → walkthrough result from the four cognitive-walkthrough questions (UX-8). An unserved step or an orphan element FAILS this gate until fixed or justified; Quick Spec walks only the journeys §0a covers. Also carries the interaction-cost table (UX-9) and per-view wayfinding check (UX-10). |
| §9 UI/UX Gate Report |
One row per gate family — UX-*, applicable UI-*, AD-*, DD-*, CL-* (at least the CL-5 triage), UI copy — with result and evidence (UX-11). A gate missing from the table counts as not checked; an unresolved FAIL blocks Approved. |
Keep every clause obligation written in observable UX language so it survives the M1-M5/M7 gate below — state the visible outcome, never a CSS property or framework prop.
Skip ONLY when the feature has no user-facing surface — state that explicitly so the skip is auditable, not an omission.
M1-M5/M7 Compliance for UI Specs
AI-SDD artifact contract — M1-M7 require tech-agnostic, traceable, observable, rebuildable specs; logical IDs lead prose, implementation identifiers stay in evidence carriers, and business-tree cases must be demoable.
MUST ATTENTION READ .claude/skills/shared/sdd-artifact-contract.md for the full "AI-SDD Mandates (M1-M7)" gate.
A UI spec MUST satisfy these criteria before handoff:
- M1 — Business-level component names. Name every component by its UX role — Primary Button, Secondary Button, Modal Dialog, Data Table, Dropdown, Toast — NEVER by a framework component class name or library import. FAIL on tech-term prose.
- M2 — No code-prop refs in prose. Describe behavior and appearance in plain UX language. NEVER reference component-state props, CSS class names, framework directives, or selectors in prose. Those belong only in
**Evidence**/[Source:] carriers, frontmatter, and Mermaid.
- M3 — Cross-reference by logical ID. For every behavior driven by feature logic, cite the driving operation or rule by its logical ID (
OP-/BR-/FR-) — link UI behavior back to the feature spec, not to handler code. Keep any [Source: namespace/service/id] abstract anchor strictly in the Evidence carrier — never physical code coordinates or repository-root paths.
- M4 — Testable, unambiguous behavior. Every state and interaction MUST have exactly one valid interpretation and an observable completion marker. Replace vague phrases ("handle appropriately", "show feedback") with the concrete observable result.
- M5 — Rebuild-from-spec. A reader with zero codebase knowledge MUST be able to rebuild this UI on ANY framework from the spec alone. If a marker is only resolvable by reading source, it fails M5 — restate it as a visual/textual observable.
- M7 — Business-visibility. A UI spec is a business-tree artifact, so apply the demo test to each case's BODY: "what would a stakeholder SEE change?" — no answer → FAIL as TECHNICAL-ONLY. Every
Given = a state a user could arrange; every When = an action a user could take; every Then = an outcome a user could see. FAIL a When that is an invocation (a handler runs, a consumer receives, a job fires, data syncs) or a Then asserting schema/type/nullability/call-count. Judge the BODY, never the title or ID. ⚠️ A UI state a user can SEE is business and PASSES M7 — a spinner, an empty placeholder, an error border, a disabled control are all demoable outcomes, not technical cases. Only invocation-shaped or schema-asserting cases fail.
M1 vs M7 — they are not the same gate. M1 governs vocabulary; M7 governs subject matter. A technical case in impeccably tech-free prose satisfies M1 while violating M7 — "the view correctly reflects the synchronized record" names no framework, passes M1, and is still a technical case wearing a business costume. That gap is the most common way business specs rot. Ask what a user could SEE, not which words were used.
Observable State Definitions
Define every state by what a user can SEE (color, icon, position, text), the business meaning, and the operation/rule that triggers it — NEVER by CSS class or component-state prop:
| State |
Visual Markers (observable) |
Business Meaning |
Triggering Operation / Rule (logical ID) |
| Default |
Primary fill color, enabled label, no spinner |
Action available to the actor |
OP-XX (entry state) |
| Loading |
Spinner icon replaces label, control non-interactive |
Operation in progress, awaiting result |
OP-XX (request submitted) |
| Disabled |
Muted/gray fill, label dimmed, no pointer affordance |
Precondition not met / actor not permitted |
BR-XX (authorization or guard rule) |
| Error |
Error-color border, inline message text, alert icon |
Operation rejected or validation failed |
BR-XX (validation rule) |
| Empty |
Placeholder illustration + guidance text, no data rows |
No records exist for the current view |
OP-XX (query returned zero results) |
| Success |
Confirmation toast/checkmark, updated visible data |
Operation completed and persisted |
OP-XX (operation succeeded) |
Component States Checklist
Every interactive component MUST document each applicable state below by its observable appearance and business meaning, marking unsupported states N/A — never by CSS class or framework prop (see M2):
- Default — resting appearance; action available to the actor
- Hover — pointer-over affordance change (cursor / elevation / color shift)
- Active — pressed/engaged feedback during interaction
- Focus — keyboard-focus indicator (visible ring/outline) for a11y traversal
- Disabled — muted/non-interactive; precondition or permission not met
- Error — validation/operation failure with inline message + alert affordance
- Loading — in-progress indicator (spinner / skeleton); control non-interactive
Accessibility Audit
Read [references/accessibility-audit.md](references/accessibility-a
…(truncated)
1---2name: design-spec-43description: '[Project Management] Use when a workflow step or the user asks for UI/UX specs for views, flows, states and accessibility. --mode=wireframe converts sketches or wireframes.'4metadata:5 source: https://skillmd.com/skills/duc01226/design-spec-46---78> Codex compatibility note:9> - 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.10> - Track steps before execution and keep progress/evidence current. Explicit skill requests execute their protocol. Use the native question tool for required questions.11> - 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.12> - 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.13> - 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.14<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:START -->1516> **[BLOCKING]** Execute skill steps in declared order. NEVER skip, reorder, or merge steps without explicit user approval. Inside a workflow run, `$start-workflow` → Workflow-step mode bounds this rule.17> **[BLOCKING]** Before each step or sub-skill call, update todo tracking: set `in_progress` when step starts, set `completed` when step ends.18> **[BLOCKING]** Every completed/skipped step MUST include brief evidence or explicit skip reason.19> **[BLOCKING]** If Task tools are unavailable, create and maintain an equivalent step-by-step plan tracker with the same status transitions.2021<!-- PROMPT-ENHANCE:STEP-TASK-ANCHOR:END -->2223## Quick Summary2425**Goal:** Produce a complete, tech-agnostic UI/UX design spec that lets a developer rebuild the source outcome on ANY stack, preserving every required view, navigation path, component, state, token, responsive rule, accessibility need, demo journey, and governing-spec link.2627**Summary:**2829- Journey Report (`UX-1`) → existing UI/connected flows and governing intent → design-authority read (`UX-2`) precede every spec section. Reuse reviewed companion evidence and governing view/state vocabulary; confirm inferred actor/job/outcome, or record unconfirmed when no question tool exists.30- Route input (design link → exported frames; image → visual analysis; sketch → `--mode=wireframe`; task/text → requirements), then choose Quick, Full, or Full + Flow Diagram. Specify components, applicable states, tokens, responsive/accessibility behavior and the complete releasable flow.31- Walk every main journey and trace its steps, interaction cost and wayfinding (`UX-8`–`UX-10`); finish the UI/UX Gate Report (`UX-11`). Save the design-spec/audit/component variant, update governing-spec companion frontmatter only, and satisfy M1–M5/M7 and logical-ID traceability.3233**Workflow:**34351. **Journey Report** — Report main user journeys (`UX-1`) before any spec section362. **Ground Source** — Inventory UI/flows; seed governing §6 vocabulary; record design-authority read (`UX-2`)373. **Route Input** — Choose visual, wireframe, task, or text path384. **Set Scope** — Choose Quick / Full / Flow Diagram395. **Specify** — Components, 7 states, tokens, responsive/accessibility/full-flow rules406. **Walk + Trace** — Walk each main journey; §8 traceability matrix (`UX-8`)417. **Save + Link** — Save artifact; update Feature Spec frontmatter only4243**Key Rules:**4445- **[BLOCKING] Journey-first order:** Journey Report (`UX-1`) → design-authority read (`UX-2`) → only then spec sections; every view hosts a journey step (`UX-3`) and §1b priority is computed per decision point (`UX-4`). Catalog: `.claude/docs/ux-journey-process.md`.46- Input routing: design link (e.g. a Figma URL)→ask the user to export the frames as images, then visual analysis; wireframe/sketch→`--mode=wireframe`; screenshot→visual analysis.47- Reuse `design-system/` tokens and `frontend-patterns-reference.md` component patterns from the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides); include keyboard navigation, ARIA labels, and contrast.48- **[BLOCKING] Tech-agnostic output:** spec prose/headings follow `spec-principles.md` §3 under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) — describe components by UX role, not framework/library names; source paths and class names appear ONLY in evidence fields (`**Evidence**`, `[Source:]`), frontmatter, and Mermaid.49- **[BLOCKING] Releasable UI surface:** apply `.claude/skills/shared/releasable-task-contract.md`; the design spec must deepen, not reduce, the task/mockup page/view, navigation, component, state, and full-flow inventories.5051> **Releasable outcome contract** — Preserve one complete actor-facing journey (entry/context → action/input → validation/decision → visible or persisted result → exit/next path) with every required view, navigation edge, component, and state; incomplete or ambiguous outcomes stay blocked.52>53> **MUST ATTENTION READ** `.claude/skills/shared/releasable-task-contract.md` for the full contract.5455**Be skeptical. Apply critical thinking, sequential thinking. Every claim needs traced proof, confidence percentages (Idea should be more than 80%).**5657## Contents5859- [Quick Summary](#quick-summary)60- [Design Specification](#design-specification)61- [When to Use](#when-to-use)62- [When NOT to Use](#when-not-to-use)63- [Prerequisites](#prerequisites)64- [Workflow](#workflow)65- [Mode: wireframe (image → spec)](#mode-wireframe-image--spec)66- [Output Format](#output-format)67- [Design-Principles Obligations (per spec section)](#design-principles-obligations-per-spec-section)68- [M1-M5/M7 Compliance for UI Specs](#m1-m5m7-compliance-for-ui-specs)69- [Component States Checklist](#component-states-checklist)70- [Accessibility Audit](#accessibility-audit)71- [Examples](#examples)72- [Related Skills](#related-skills)73- [Next Steps](#next-steps)74- [Prompt-Enhance Closing Anchors](#prompt-enhance-closing-anchors)75- [Closing Reminders](#closing-reminders)7677# Design Specification7879Create structured UI/UX design specification documents from requirements or tasks for developer handoff.8081## When to Use8283- A task or user story needs a design spec before implementation84- Requirements need concrete layout, states, tokens, and responsive behavior85- A component inventory and interaction patterns need documentation8687## When NOT to Use8889- Wireframes run internally via `--mode=wireframe` — no separate skill call90- Building UI — use `ui-design --lane=marketing` (marketing/creative) or `ui-design --lane=product` (product UIs)91- Reviewing UI code — use `web-design-guidelines`9293## Prerequisites9495Read before executing:9697- The source task, user story, or requirements document98- `design-system/` under the reference-docs root (default `docs/project-reference`; `docsRoots.projectReference.path` in `docs/project-config.json` overrides) -- project design tokens (if applicable)99- Existing design specs in `design-specs/` under the team-artifacts root (default `team-artifacts/`; `docsRoots.teamArtifacts.path` in `docs/project-config.json` overrides) for format consistency100101### Frontend/UI Context102103> For frontend/UI work, read:104105All three live under the reference-docs root (default `docs/project-reference`; a `docsRoots.projectReference.path` entry in `docs/project-config.json` overrides the path):106107- Frontend patterns: `frontend-patterns-reference.md`108- Styling reference: `configured styling reference`109- Design system tokens: `design-system/README.md`110111## Workflow112113> **[BLOCKING] Step 0a — Journey Report (`UX-1`).** Before ANY spec section, wireframe, design plan or token table, write §0a User Journeys (Output Format below; full template `.claude/docs/ux-journey-process.md` §4): frame (problem · business goal · success signal · constraints) · actors with context, expertise and frequency · one job statement per actor · the main journeys ranked by frequency × business value × risk × first-use criticality (catalog §5) · a step table per journey (intent · decision/action · information needed · business rule · system response · failure → recovery) · derived design requirements · assumptions and open questions.114>115> - **Evidence first:** when a governing Feature Spec exists, its profile-resolved interaction flows and view inventory (strict-default §6.5 and §6.2) are the primary evidence — read them here (Step 0b reuses the same read), then stories/acceptance criteria, business logic in code, and the existing UI (catalog §3). Tag every claim `SOURCED (<location>)` or `INFERRED (<reason>)`.116> - **Companion mockup (reuse):** when a `$work-item --mode=mockup` run for the same feature already produced a reviewed Journey Report — `tmp/design/<run>/journey-report.md` (with its `direction-approved.md` and `Design authority read:` record), the Journey Report in its report, or a path the caller supplies — that report is the starting evidence: reuse it, re-confirm only what the source changed since, and surface (never silently re-derive) any journey that disagrees. An approved `direction-approved.md` seeds the §0 Design Plan (colour · type · layout recorded `ADOPTED`, still passing the `DD-3` generic test). With no companion mockup available (standalone run) derive the report and plan as above. When this run's recorded mock-up scope answer is the option board and no design system or brief pins colour and type, mark §0 colour and type `PROPOSED — the explore pick decides` (still a complete, measured direction); the pick then updates §0, §3 and §4 in place (`VO-1`). With no answer recorded yet, any other answer, or no mock-up in the run, write §0 as this spec's own decided direction: a later mock-up in the run treats it as a proposal (its seed or shortlist place) and its pick updates the spec the same way.117> - **Confirm before generating:** an INFERRED primary actor, main job or success outcome is confirmed with the user via `ask user question tool` before any spec section is authored; with no question tool, record it `INFERRED — unconfirmed (no question tool)` in §0a assumptions and continue — never block.118> - **Depth by spec size (catalog §10):** Quick Spec → actors + 1–2 main journeys with step tables for the view(s) in scope; Full Spec → the full template, 3–5 main journeys; multi-page flow → full template plus the cross-view navigation path. Never zero for a new or reshaped view.119>120> **Skip ONLY** when the feature has no user-facing surface — state that explicitly.121122> **[BLOCKING] Step 0 — Inventory existing UI + map connected flows** (per `SYNC:existing-ui-research`). Before authoring, inventory related existing screens/components/pages and every connected feature flow (links, embeds, navigates to/from); record matched UI + flows in §1 so the spec fits the live UI system. Skip only backend-only work; state that explicitly.123124> **[BLOCKING] Step 0b — Seed from governing interaction intent (when a spec exists).** Resolve `specArtifacts` through the shared SDD contract before locating the canonical owner. Search the configured business spec root for this capability. Strict-default profile: read §6.2 View Inventory, §6.3 Navigation Map, §6.4 Key UI States and §6.5 Per-Story Interaction Flow. Declared native profile: read its configured intent sections and native interaction carriers; preserve owner-qualified scenario IDs and carrier cardinality. Malformed or unsupported declarations stop without fallback. Do not require §6 headings or add duplicate strict-default registries to a valid native owner.125>126> - **Reuse vocabulary verbatim:** carry over the SAME view and observable-state names from the resolved owner. NEVER rename or repartition; both artifacts MUST use one language so the navigable hub works.127> - **Deepen, never diverge:** keep intent tech-agnostic; add visual fidelity (layout, tokens, pixel detail). Map each resolved interaction step/state to visual treatment and preserve its native or strict-default logical-ID cross-refs.128> - This coupling is the `SYNC:ui-intent-layer` contract below; use that block for the full rule instead of restating it.129>130> **Skip ONLY** when no governing Feature Spec exists; author the interaction frame from the source task/story and state which case applies.131132> **[BLOCKING] Design-authority read (`UX-2`).** Step 0 + Step 0b, together with reading `design-system/` under the reference-docs root and the project's design principles/guidelines, styling conventions and accepted design ADRs (resolved from `docs/project-config.json` and its reference docs), form the design-authority read. Record it in the spec header as `Design authority read: <paths>` or `N/A — none configured (checked: <paths>)` BEFORE authoring any spec section; adopt house patterns and never invent a token or component the project already defines.1331341. **Read source input & route by type**135136 | Input Detected | Detection | Action |137 | ------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------ |138 | Design-tool link | A design-tool URL (e.g. `figma.com`) in text | Ask the user via `ask user question tool` to export the frames as images, then continue on the image path |139 | Image/screenshot | Image file attached to prompt | Use `visual analysis tooling` to extract design guidelines, then continue |140 | Hand-drawn wireframe | Image + "wireframe"/"sketch" keyword | Run `--mode=wireframe` (internal — see "Mode: wireframe" section) |141 | Task/story text | Acceptance criteria present | Extract UI requirements from text, continue |142 | Verbal/text requirements | No image, no URL, no task | Clarify with user, then continue |143144For ANY visual input, extract design context FIRST, then generate the spec.1451462. **Determine spec complexity**147148 ```149 IF single form or simple component → Quick Spec (sections 0a compact, 1, 1b, 2-4, 8 walkthrough of those journeys, 9 UI/UX Gate Report)150 IF full page or multi-component view → Full Spec (sections 0a, 0, 1-9)151 IF multi-page flow → Full Spec + Flow Diagram152 ```1531543. **Build component inventory**155 - List needed UI components; classify reusable vs feature-specific; note existing shared-library/design-system components.1561574. **Define states and interactions**158 - Document applicable default, hover, active, focus, disabled, error, loading and empty states; user interactions, transitions and animations. Mark unsupported platform/input states N/A.1591605. **Extract design tokens**161 - Colors, typography, spacing, shadows, and border-radius; reference existing design-system tokens where possible.1621636. **Document responsive behavior**164 - Use configured/content-driven breakpoints; mobile 320–767px, tablet 768–1023px and desktop 1024px+ are web starting examples, not universal thresholds. Document layout, visibility and sizing changes at each applicable breakpoint.165 - **Small-screen minimum bar (spec it explicitly):** the layout MUST stay usable on mobile. Preferred = reflow (rows `flex-wrap` / `row → column`, grids collapse to one column). Where a component genuinely can't reflow (data tables, canvases, wide grids), specify a `min-width`/`min-height` + `overflow: auto` scroll as the accepted fallback — scrolling is OK. Hard requirement = nothing broken (no clipped, cut-off, or unreachable content/controls). If a component needs a large redesign to work on mobile, flag it for the user rather than assuming a rewrite.1661676b. **Walk the journeys (`UX-8`)** — step through every §0a main journey on the spec as the named actor and answer the four walkthrough questions per step (knows the step is needed? sees the action? links it to the goal? sees progress?); fill §8 Journey Traceability. Fix every unserved step (no view/element) and orphan element (traces to no step, need or rule) before saving; record any remaining "no" in §7. Then fill §8's interaction-cost row per main journey (`UX-9`) and wayfinding check per view (`UX-10`), and close with §9 UI/UX Gate Report (`UX-11`) — every gate `PASS` / `FAIL → fixed` / `N/A` with evidence; an unresolved `FAIL` blocks saving as `Approved`.1681697. **Save artifact** — pick the filename variant by artifact type; every path below is relative to the team-artifacts root (default `team-artifacts/`; a `docsRoots.teamArtifacts.path` entry in `docs/project-config.json` overrides the path):170 - Design spec: `design-specs/{YYMMDD}-ux-designspec-{feature-slug}.md`171 - Accessibility audit: `design-specs/{YYMMDD}-ux-audit-{feature-slug}.md`172 - Single-component doc: `design-specs/{YYMMDD}-ux-component-{component-name}.md`1731748. **Link back to the governing Feature Spec (when one exists).** After saving the artifact, keep the spec the navigable hub: open the governing Feature Spec under the business spec root (default `docs/specs/**`; `specRoots.business.path` in `docs/project-config.json` overrides) and set its frontmatter `design_spec:` key to this design-spec's saved path (add the key if absent, update it if stale). If a mockup was also produced (e.g. via `$work-item --mode=mockup`), set the `mockup:` key the same way. Edit **frontmatter only** — never touch the canonical intent/contracts/evidence body (strict-default §1–§8). This satisfies the `work-item --mode=review --type=design` link-back gate, which fails when a design-spec exists but its path is not recorded in the spec's `design_spec:` frontmatter. Skip ONLY when no governing Feature Spec exists (the design-spec is standalone) — state that.175176### Role Context & Artifact Path (canonical)177178> Applies to writes under `design-specs/` in the team-artifacts root (default `team-artifacts/`; `docsRoots.teamArtifacts.path` in `docs/project-config.json` overrides).179180- **Active Role:** ui-ux-designer · **Skill:** design-spec181- **Path:** `design-specs/` under the team-artifacts root (default `team-artifacts/`; `docsRoots.teamArtifacts.path` in `docs/project-config.json` overrides) · **Type:** designspec · **Role token:** ux182- **Template:** `.claude/docs/team-artifacts/templates/design-spec-template.md` (framework-owned path — NOT the configurable team-artifacts root in `docs/project-config.json`)183- **Naming:** `{YYMMDD}-ux-{type}-{slug}.md` (general artifact-path pattern: `{YYMMDD}-{role}-{type}-{slug}.md`)184- **Context:** DESIGN SPEC — include component states, design tokens, accessibility requirements.185- **Quality checklist:** `- [ ]` Journey Report (§0a, `UX-1`) precedes every other section, claims `SOURCED`/`INFERRED` · `- [ ]` `Design authority read:` recorded or `N/A` (`UX-2`) · `- [ ]` Every view hosts a journey step; information priority (`UX-4` tiers) + container recorded per view · `- [ ]` §8 traceability matrix: no unserved step, no orphan element (`UX-8`) · `- [ ]` Interaction cost per journey + wayfinding per view (`UX-9`, `UX-10`) · `- [ ]` §9 UI/UX Gate Report complete, no open `FAIL` (`UX-11`) · `- [ ]` Action forms per view + `AD-5` counts recorded (`AD-1`–`AD-6`) · `- [ ]` All states documented · `- [ ]` Design tokens specified · `- [ ]` Accessibility notes included · `- [ ]` Responsive breakpoints defined186187## Mode: wireframe (image → spec)188189Read [references/wireframe.md](references/wireframe.md) in full when `--mode=wireframe` is selected. It owns image analysis, business-operation mapping, task-section versus standalone output, confidence and human-review rules. This input adapter preserves Step 0a and continues through the normal output and M1–M5/M7 gates.190191## Output Format192193```markdown194# Design Spec: {Feature Name}195196**Source:** {task/story reference}197**Date:** {YYMMDD}198**Status:** Draft | Review | Approved199**Design authority read (`UX-2`):** {design principles · design-system docs · styling conventions · design ADRs · existing screens read} | `N/A — none configured (checked: {paths})`200201## 0a. User Journeys (`UX-1`)202203**Frame:** {problem} · **Business goal:** {goal} · **Success signal:** {metric} · **Constraints:** {platform, rules, legacy, budget}204**Sources read:** {profile-resolved interaction flows/view inventory (strict-default §6.5/§6.2), task/story, business-rule sources, existing screens} · **Confidence:** {%}205206| Actor | Context · expertise · frequency | Job statement (When…, I want to…, so I can…) | Source |207| ----- | ------------------------------- | --------------------------------------------- | ------ |208| {actor} | {device, interruptions · novice/expert · daily/rare} | {job} | SOURCED ({location}) / INFERRED ({reason}) |209210**Main journeys (ranked by frequency × value × risk × first-use):**211212| # | Journey | Actor | Trigger → outcome | Why main |213| - | ------- | ----- | ----------------- | -------- |214| J1 | {name} | {actor} | {trigger} → {outcome} | {score reason} |215216**J1 — {name}** · Entry: {where from} · Exit: {where next}217218| Step | Intent | Decision / action | Information needed | Business rule (logical ID) | System response | Failure → recovery |219| ---- | ------ | ----------------- | ------------------ | -------------------------- | --------------- | ------------------ |220| J1.1 | {intent} | {action} | {info} | BR-XX | {response} | {failure} → {recovery} |221222**Derived design requirements:** views (step → view · container) · priority per view (top items · primary action) · rules → interaction treatment · critical states per view.223**Assumptions & open questions:** `INFERRED:` {assumption — confirmed?} · `OPEN:` {question}224225## 0. Design Plan (`DD-1`–`DD-3`)226227**Subject / audience / job:** {the concrete product, the actual person using it and where they are, and the verb they came to do}228229| Part | Decision | Why — traced to the subject |230| -------------- | ------------------------------------------------- | ------------------------------------------------- |231| **Color** | {4–6 named hex values, named for this product's world} | {why these, for THIS subject} |232| **Type** | {1–2 clearly distinct families + roles + scale} | {why this voice suits the subject} |233| **Layout** | {one-sentence concept + alignment: left/centered/justified} | {what the proportions are saying} |234| **Principles** | {the ONE memorable element; what stays quiet around it} | {why this is what the user will remember} |235236**Generic test:** {what you REVISED because it read like the default for any comparable screen — or `axes pinned by {brief | design-system doc path}`}237238> **Adoption shortcut:** where the project has a design system / `interface-system.md` / token files, this section reads `ADOPTED — {doc path}` plus any axis re-decided WITH its reason. Re-deciding a settled axis silently is the incoherence this section prevents.239240## 1. Overview241242{1-2 sentence summary of what this UI does}243244## 1b. Information Priority & Container245246| View | Journey steps hosted | Primary task | Container (why) | Now — shown / asked here | Later — deferred to | Not here — owned by |247| ---- | -------------------- | ------------ | --------------- | ------------------------ | ------------------- | ------------------- |248| {view role} | {J1.1, J1.2} | {verb} | {full view / dialog / side panel / stepped flow / inline — why} | {items, tagged P / S / D} | {step or view} | {view} |249250**Priority scoring (`UX-4`, catalog §6):** score each item and action per decision point on need-at-the-decision × frequency × cost-of-missing (1–3 each); tag `now` items **P** Primary (one focal point, ONE primary action = the journey's next step) · **S** Secondary · **D** On demand (progressive disclosure); the rest go to Later / Not here. Order within a tier follows the journey's step order; §3 Layout implements this rank, never reshuffles it.251252**Inputs at creation vs deferred:** {the smallest set that makes a valid, useful record; everything else and where it is enriched later}253**Complexity budget:** {counts per view/step} vs `uiReview.complexityBudget` when the project declares one; otherwise the counts plus the reasoning for the primary user.254255**Action forms (`AD-1`–`AD-2`):** {per view: the ONE filled primary commit · every other action → icon-only / icon + label / link / row target / overflow, and why · button groups with their shared min-width}256**Collection grids (`AD-6`):** {per grid: tile size and aspect ratio · title line clamp · the content edge its actions align to}257258## 2. Component Inventory259260| Component | Type | Owner (source path or `new — build once`) | Used in | Notes |261| --------- | -------- | ----------------------------------------- | ------- | --------------------------- |262| UserCard | New | new — build once | {views} | Displays user avatar + name |263| DataTable | Existing | {shared library path} | {views} | Reuse with custom columns |264265Each reusable component here becomes an entry of the mock-up's design-system page (`PD-2`).266267## 3. Layout268269{Description or ASCII wireframe of layout structure}270271- Desktop: {layout description}272- Tablet: {layout changes}273- Mobile: {layout changes}274275## 4. Design Tokens276277Every token traces to a §0 Design Plan decision. Names evoke this product's world, not a numeric ramp — a reader seeing only the token names should be able to guess what the product is (`DD-2`). Values come from the project's token files where they exist; a raw hex here that is not in §0's palette is a leak.278279| Token | Value | Usage |280| ------------- | ------------------------ | --------------------- |281| $signal | #1976D2 | Action buttons, links |282| $text-body | 14px/1.5 {body family} | Body text |283| $gap-md | 16px | Section spacing |284285## 5. States & Interactions286287| Element | Default | Hover | Active | Disabled | Error |288| -------- | ---------- | ---------- | ---------- | ---------------- | ----- |289| Save btn | Blue/white | Darken 10% | Scale 0.98 | Gray/50% opacity | -- |290291## 6. Accessibility292293- Keyboard navigation order294- ARIA labels for interactive elements295- Icon-only controls: accessible name + tooltip on hover and focus, full-size hit target, 3:1 icon contrast (`AD-3`)296- Color contrast compliance notes297298## 7. Open Questions299300- {Any unresolved design decisions}301302## 8. Journey Traceability (`UX-8`)303304| Journey · step | View | Element(s) serving it | Information shown (tier) | Rule enforced | States covered | Walkthrough result |305| -------------- | ---- | --------------------- | ------------------------ | ------------- | -------------- | ------------------ |306| J1.1 | {view role} | {UX-role element} | {item (P/S/D)} | BR-XX | {empty, loading, error, success} | PASS / {which of the 4 questions failed → fix} |307308**Unserved steps:** {none | step → fix} · **Orphan elements:** {none | element → removed or justified}309310**Interaction cost (`UX-9`):**311312| Journey | Steps | Clicks/taps | View changes | Fields | Decisions | vs baseline |313| ------- | ----- | ----------- | ------------ | ------ | --------- | ----------- |314| J1 | {n} | {n} | {n} | {n} | {n} | {same / −n / +n with reason} |315316**Wayfinding (`UX-10`):** per view — where am I · where can I go · how do I get back · dead ends: {none | view → fix}317318## 9. UI/UX Gate Report (`UX-11`)319320| Gate | Result | Evidence |321| ---- | ------ | -------- |322| UX-1–UX-10 journey-first | PASS / FAIL → fixed / N/A | {section refs} |323| UI-1.1–UI-9.4 floor (applicable) | … | {measured values} |324| AD-1–AD-6 actions & attention | … | {§1b action forms · counts per view} |325| DD-1–DD-8 identity | … | {§0 generic test} |326| CL-1–CL-6 checklist (CL-5 triage minimum) | … | {findings} |327| UI copy | … | … |328```329330## Design-Principles Obligations (per spec section)331332The spec is where the 40 UI/UX Design Principles (`UI-1.1`–`UI-9.4`, the `SYNC:ui-ux-design-principles` block below) become INHERITABLE — a downstream implementer builds what the spec SAYS, so an unstated clause is an unbuilt clause. Every spec this skill emits MUST carry these obligations in the named Output Format sections. Project design-system docs OUTRANK the clauses; a genuine conflict is surfaced to the user with both sides, NEVER resolved silently.333334| Spec section | Clause obligation the section MUST carry |335| --- | --- |336| **§0a User Journeys** | Written FIRST, before §0 and every other section (`UX-1`): frame, actors + job statements, main journeys ranked by the catalog §5 score, a step table per journey (intent · decision · information needed · business rule · response · failure → recovery), derived requirements, assumptions. Every claim `SOURCED (<location>)` or `INFERRED`; an inferred primary actor, main job or success outcome is confirmed with the user (no question tool → recorded `INFERRED — unconfirmed (no question tool)`). The spec header records `Design authority read:` or `N/A` (`UX-2`). Depth follows Quick/Full (catalog §10), never zero. |337| **§0 Design Plan** | The identity layer the 40 clauses do not cover (`SYNC:design-distinctiveness-gate`): name the subject/audience/job (`DD-1`), give all four plan parts a WHY traced to that subject (`DD-2`), and record the **Generic test** result — what you revised, or which axes the brief/design system already pinned (`DD-3`). A downstream implementer who receives no design plan supplies their own defaults, so an unstated direction is a templated build. |338| **§1 Overview** | Name the ONE focal point of the screen (`UI-1.1`), and name the surface(s) in scope (web / mobile / both) so the mobile clauses (`UI-8.1`–`UI-8.4`) are either binding or explicitly skipped. |339| **§1b Information Priority & Container** | Seed from the governing spec's View Inventory priority/container record when one exists (`SYNC:ui-intent-layer`); never repartition it silently. Every view names the §0a journey steps it hosts and every main-journey step lands on a view (`UX-3`); `now` items carry the `UX-4` tier (Primary / Secondary / On demand) from the need-at-the-decision × frequency × cost-of-missing score, with ONE primary action matching the journey's next step. Every view names its primary task and a container that fits it — a long or multi-section entry task is a full view or stepped flow, not a dialog (checklist `E9`). Every input is justified at THIS step or deferred (`UI-7.1`, checklist `§R1`–`R2`); creation asks only for the smallest valid record. Alternate entry modes are a first explicit choice, not stacked in one view (`B14`). A spec whose `now` set exceeds the task FAILS this gate. Every view also names its ONE filled primary and each other action's `AD-1` form; rows state their one meta line (`AD-4`). |340| **§3 Layout** | Group by proximity and shared alignment edges; add a border or container only where it encodes a real boundary (`UI-1.3`, `UI-1.4`); justify each breakpoint by where the CONTENT stops working, not by a device name (`UI-4.4`). |341| **§4 Design Tokens** | Adopt the project’s type scale, readable sizes, measures, line spacing, families/weights and spacing/grid tokens (`UI-2.1`–`UI-2.5`, `UI-4.1`). Otherwise choose purposeful, consistent values for the target platform and record why; example values are not universal fail thresholds. Container-owned spacing and clear group relationships remain required (`UI-4.2`–`UI-4.3`). |342| **§4 Design Tokens (colour)** | Record the selected accessibility standard and its source, applicable contrast targets and measured values (`UI-3.1`); unavailable measurements stay `NOT VERIFIABLE`. Use the WCAG 2.2 AA web baseline plus stricter applicable requirements; non-web uses its documented standard. One accent with one job (`UI-3.2`); when dark mode applies, specify lifted surfaces and softened white text rather than inversion (`UI-3.4`). |343| **§5 States & Interactions** | Author empty/loading/error before populated states (`UI-1.5`). Document supported default, hover, focus, active, disabled, error and loading states; mark unsupported states N/A (`UI-5.2`). Give immediate perceivable feedback and meaningful motion under documented platform/project timing and easing; honor reduced motion (`UI-5.1`, `UI-5.4`). Prefer undo, confirm only irreversible actions (`UI-5.3`). Keep labels visible, associate useful correction with the input at the appropriate validation point, and preserve entered data (`UI-7.2`–`UI-7.5`). |344| **§6 Accessibility** | Preserve perceivable focus for supported focus navigation (`UI-5.5`); never convey meaning by colour alone (`UI-3.3`). On touch/mobile surfaces, meet the selected platform/accessibility target-size and spacing requirements; place actions where reachable, provide required alternatives to gesture-only actions, and respect safe areas and keyboards (`UI-8.1`–`UI-8.4`). Record applicable constraints and evidence; unsupported capabilities are N/A. |345| **§7 Open Questions** | Every clause deliberately deviated from, with the project doc or user decision that authorises it — an undocumented deviation is a spec defect, not a style choice. |346| **§8 Journey Traceability** | One row per §0a journey step: view → element → information tier → rule → states → walkthrough result from the four cognitive-walkthrough questions (`UX-8`). An unserved step or an orphan element FAILS this gate until fixed or justified; Quick Spec walks only the journeys §0a covers. Also carries the interaction-cost table (`UX-9`) and per-view wayfinding check (`UX-10`). |347| **§9 UI/UX Gate Report** | One row per gate family — `UX-*`, applicable `UI-*`, `AD-*`, `DD-*`, `CL-*` (at least the `CL-5` triage), UI copy — with result and evidence (`UX-11`). A gate missing from the table counts as not checked; an unresolved `FAIL` blocks `Approved`. |348349Keep every clause obligation written in observable UX language so it survives the M1-M5/M7 gate below — state the visible outcome, never a CSS property or framework prop.350351**Skip ONLY** when the feature has no user-facing surface — state that explicitly so the skip is auditable, not an omission.352353## M1-M5/M7 Compliance for UI Specs354355> **AI-SDD artifact contract** — M1-M7 require tech-agnostic, traceable, observable, rebuildable specs; logical IDs lead prose, implementation identifiers stay in evidence carriers, and business-tree cases must be demoable.356>357> **MUST ATTENTION READ** `.claude/skills/shared/sdd-artifact-contract.md` for the full "AI-SDD Mandates (M1-M7)" gate.358359A UI spec MUST satisfy these criteria before handoff:360361- **M1 — Business-level component names.** Name every component by its UX role — Primary Button, Secondary Button, Modal Dialog, Data Table, Dropdown, Toast — NEVER by a framework component class name or library import. FAIL on tech-term prose.362- **M2 — No code-prop refs in prose.** Describe behavior and appearance in plain UX language. NEVER reference component-state props, CSS class names, framework directives, or selectors in prose. Those belong only in `**Evidence**`/`[Source:]` carriers, frontmatter, and Mermaid.363- **M3 — Cross-reference by logical ID.** For every behavior driven by feature logic, cite the driving operation or rule by its logical ID (`OP-`/`BR-`/`FR-`) — link UI behavior back to the feature spec, not to handler code. Keep any `[Source: namespace/service/id]` abstract anchor strictly in the Evidence carrier — never physical code coordinates or repository-root paths.364- **M4 — Testable, unambiguous behavior.** Every state and interaction MUST have exactly one valid interpretation and an observable completion marker. Replace vague phrases ("handle appropriately", "show feedback") with the concrete observable result.365- **M5 — Rebuild-from-spec.** A reader with zero codebase knowledge MUST be able to rebuild this UI on ANY framework from the spec alone. If a marker is only resolvable by reading source, it fails M5 — restate it as a visual/textual observable.366- **M7 — Business-visibility.** A UI spec is a business-tree artifact, so apply the demo test to each case's BODY: *"what would a stakeholder SEE change?"* — no answer → FAIL as TECHNICAL-ONLY. Every `Given` = a state a user could arrange; every `When` = an action a user could take; every `Then` = an outcome a user could see. FAIL a `When` that is an invocation (a handler runs, a consumer receives, a job fires, data syncs) or a `Then` asserting schema/type/nullability/call-count. Judge the BODY, never the title or ID. ⚠️ **A UI state a user can SEE is business and PASSES M7** — a spinner, an empty placeholder, an error border, a disabled control are all demoable outcomes, not technical cases. Only invocation-shaped or schema-asserting cases fail.367368> **M1 vs M7 — they are not the same gate.** M1 governs **vocabulary**; M7 governs **subject matter**. A technical case in impeccably tech-free prose satisfies M1 while violating M7 — *"the view correctly reflects the synchronized record"* names no framework, passes M1, and is still a technical case wearing a business costume. That gap is the most common way business specs rot. Ask what a user could SEE, not which words were used.369370### Observable State Definitions371372Define every state by what a user can SEE (color, icon, position, text), the business meaning, and the operation/rule that triggers it — NEVER by CSS class or component-state prop:373374| State | Visual Markers (observable) | Business Meaning | Triggering Operation / Rule (logical ID) |375| -------- | -------------------------------------------------------- | ----------------------------------------- | ---------------------------------------- |376| Default | Primary fill color, enabled label, no spinner | Action available to the actor | OP-XX (entry state) |377| Loading | Spinner icon replaces label, control non-interactive | Operation in progress, awaiting result | OP-XX (request submitted) |378| Disabled | Muted/gray fill, label dimmed, no pointer affordance | Precondition not met / actor not permitted | BR-XX (authorization or guard rule) |379| Error | Error-color border, inline message text, alert icon | Operation rejected or validation failed | BR-XX (validation rule) |380| Empty | Placeholder illustration + guidance text, no data rows | No records exist for the current view | OP-XX (query returned zero results) |381| Success | Confirmation toast/checkmark, updated visible data | Operation completed and persisted | OP-XX (operation succeeded) |382383## Component States Checklist384385Every interactive component MUST document each applicable state below by its **observable appearance and business meaning**, marking unsupported states `N/A` — never by CSS class or framework prop (see M2):386387- **Default** — resting appearance; action available to the actor388- **Hover** — pointer-over affordance change (cursor / elevation / color shift)389- **Active** — pressed/engaged feedback during interaction390- **Focus** — keyboard-focus indicator (visible ring/outline) for a11y traversal391- **Disabled** — muted/non-interactive; precondition or permission not met392- **Error** — validation/operation failure with inline message + alert affordance393- **Loading** — in-progress indicator (spinner / skeleton); control non-interactive394395## Accessibility Audit396397Read [references/accessibility-audit.md](references/accessibility-a398399…(truncated)