design-spec

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

1. Journey Report — Report main user journeys (UX-1) before any spec section
2. Ground Source — Inventory UI/flows; seed governing §6 vocabulary; record design-authority read (UX-2)
3. Route Input — Choose visual, wireframe, task, or text path
4. Set Scope — Choose Quick / Full / Flow Diagram
5. Specify — Components, 7 states, tokens, responsive/accessibility/full-flow rules
6. Walk + Trace — Walk each main journey; §8 traceability matrix (UX-8)
7. 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.