6.3 KiB
Skill Test Spec: /ux-design
Skill Summary
/ux-design is a guided, section-by-section UX spec authoring skill. It produces
user flow diagrams (described textually), interaction state definitions, wireframe
descriptions, and accessibility notes for a specified screen or HUD element. The
skill follows the skeleton-first pattern: it creates the file with all section
headers immediately, then fills each section through discussion and writes each
section to disk after user approval.
The skill has no inline director gates — /ux-review is the separate review step.
Each section requires a "May I write section [N] to [filepath]?" ask. If a UX spec
already exists for the named screen, the skill offers to retrofit individual sections
rather than replace. Verdict is COMPLETE when all sections are written.
Static Assertions (Structural)
Verified automatically by /skill-test static — no fixture needed.
- Has required frontmatter fields:
name,description,argument-hint,user-invocable,allowed-tools - Has ≥2 phase headings
- Contains verdict keyword: COMPLETE
- Contains "May I write" language per section
- Has a next-step handoff (e.g.,
/ux-reviewto validate the completed spec)
Director Gate Checks
None. /ux-design has no inline director gates. /ux-review is the separate
review skill invoked after this skill completes.
Test Cases
Case 1: Happy Path — New HUD spec, all sections authored and written
Fixture:
- No existing HUD UX spec in
design/ux/ - Engine and rendering preferences configured
Input: /ux-design hud
Expected behavior:
- Skill creates a skeleton file
design/ux/hud.mdwith all section headers - Skill discusses and drafts each section: User Flows, Interaction States (normal/hover/focus/disabled), Wireframe Description, Accessibility Notes
- After each section is drafted and user confirms, skill asks "May I write
section [N] to
design/ux/hud.md?" - Each section is written in sequence after approval
- After all sections are written, verdict is COMPLETE
- Skill suggests running
/ux-reviewas the next step
Assertions:
- Skeleton file is created first (with empty section bodies)
- "May I write section [N]" is asked per section (not once at the end)
- All required sections are present: User Flows, Interaction States, Wireframe Description, Accessibility Notes
- Handoff to
/ux-reviewis at the end - Verdict is COMPLETE
Case 2: Existing UX Spec — Retrofit: user picks section to update
Fixture:
design/ux/hud.mdalready exists with all sections populated- User wants to update only the Accessibility Notes section
Input: /ux-design hud
Expected behavior:
- Skill reads existing
design/ux/hud.mdand detects all sections are populated - Skill reports: "UX spec already exists for HUD — offering to retrofit"
- Skill lists all sections and asks which to update
- User selects Accessibility Notes
- Skill drafts updated accessibility content and asks "May I write section
Accessibility Notes to
design/ux/hud.md?" - Only that section is updated; other sections are preserved; verdict is COMPLETE
Assertions:
- Existing spec is detected and retrofit is offered
- User selects which section(s) to update
- Only the selected section is updated — other sections unchanged
- "May I write" is asked for the updated section
- Verdict is COMPLETE
Case 3: Dependency Gap — Spec references a system with no design doc
Fixture:
- User is authoring a UX spec for the inventory screen
design/gdd/inventory.mddoes not exist
Input: /ux-design inventory-screen
Expected behavior:
- Skill begins authoring the inventory screen UX spec
- During the User Flows section, skill attempts to reference inventory system rules
- Skill detects: "No GDD found for inventory system — UX spec has a DEPENDENCY GAP"
- The dependency gap is flagged in the spec (noted inline: "DEPENDENCY GAP: inventory GDD")
- Skill continues authoring with placeholder notes for the missing rules
- Verdict is COMPLETE with advisory note about the dependency gap
Assertions:
- DEPENDENCY GAP label appears in the spec for the missing system doc
- Skill does NOT block on the missing GDD — it continues with placeholders
- Dependency gap is also noted in the skill output (not just in the file)
- Handoff suggests both
/ux-reviewand writing the missing GDD
Case 4: No Argument Provided — Usage error
Fixture:
- No argument provided with the skill invocation
Input: /ux-design
Expected behavior:
- Skill detects no screen name or argument provided
- Skill outputs a usage error: "Screen name required. Usage:
/ux-design [screen-name]" - Skill provides examples:
/ux-design hud,/ux-design main-menu,/ux-design inventory - No file is created; no "May I write" is asked
Assertions:
- Usage error is clearly stated
- Example invocations are provided
- No file is created
- Skill does not attempt to proceed without an argument
Case 5: Director Gate Check — No gate; ux-review is the separate review skill
Fixture:
- New screen spec with argument provided
Input: /ux-design settings-menu
Expected behavior:
- Skill authors all sections of the settings menu UX spec
- No director agents are spawned
- No gate IDs appear in output during authoring
Assertions:
- No director gate is invoked during ux-design
- No gate skip messages appear
- Verdict is COMPLETE without any gate check
Protocol Compliance
- Creates skeleton file with all section headers before discussing content
- Discusses and drafts one section at a time
- Asks "May I write section [N]" after each section is approved
- Detects existing spec and offers retrofit path
- Ends with handoff to
/ux-review - Verdict is COMPLETE when all sections are written
Coverage Notes
- Interaction state enumeration (normal/hover/focus/disabled/error) is a core
requirement of each spec; the
/ux-reviewskill checks for completeness. - Wireframe descriptions are text-only (no images); image references may be added manually by a designer after the fact.
- Responsive layout concerns (different screen sizes) are noted as optional content and not assertion-tested here.