177 lines
6.3 KiB
Markdown
177 lines
6.3 KiB
Markdown
# 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-review` to 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:**
|
|
1. Skill creates a skeleton file `design/ux/hud.md` with all section headers
|
|
2. Skill discusses and drafts each section: User Flows, Interaction States
|
|
(normal/hover/focus/disabled), Wireframe Description, Accessibility Notes
|
|
3. After each section is drafted and user confirms, skill asks "May I write
|
|
section [N] to `design/ux/hud.md`?"
|
|
4. Each section is written in sequence after approval
|
|
5. After all sections are written, verdict is COMPLETE
|
|
6. Skill suggests running `/ux-review` as 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-review` is at the end
|
|
- [ ] Verdict is COMPLETE
|
|
|
|
---
|
|
|
|
### Case 2: Existing UX Spec — Retrofit: user picks section to update
|
|
|
|
**Fixture:**
|
|
- `design/ux/hud.md` already exists with all sections populated
|
|
- User wants to update only the Accessibility Notes section
|
|
|
|
**Input:** `/ux-design hud`
|
|
|
|
**Expected behavior:**
|
|
1. Skill reads existing `design/ux/hud.md` and detects all sections are populated
|
|
2. Skill reports: "UX spec already exists for HUD — offering to retrofit"
|
|
3. Skill lists all sections and asks which to update
|
|
4. User selects Accessibility Notes
|
|
5. Skill drafts updated accessibility content and asks "May I write section
|
|
Accessibility Notes to `design/ux/hud.md`?"
|
|
6. 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.md` does not exist
|
|
|
|
**Input:** `/ux-design inventory-screen`
|
|
|
|
**Expected behavior:**
|
|
1. Skill begins authoring the inventory screen UX spec
|
|
2. During the User Flows section, skill attempts to reference inventory system rules
|
|
3. Skill detects: "No GDD found for inventory system — UX spec has a DEPENDENCY GAP"
|
|
4. The dependency gap is flagged in the spec (noted inline: "DEPENDENCY GAP: inventory GDD")
|
|
5. Skill continues authoring with placeholder notes for the missing rules
|
|
6. 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-review` and writing the missing GDD
|
|
|
|
---
|
|
|
|
### Case 4: No Argument Provided — Usage error
|
|
|
|
**Fixture:**
|
|
- No argument provided with the skill invocation
|
|
|
|
**Input:** `/ux-design`
|
|
|
|
**Expected behavior:**
|
|
1. Skill detects no screen name or argument provided
|
|
2. Skill outputs a usage error: "Screen name required. Usage: `/ux-design [screen-name]`"
|
|
3. Skill provides examples: `/ux-design hud`, `/ux-design main-menu`, `/ux-design inventory`
|
|
4. 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:**
|
|
1. Skill authors all sections of the settings menu UX spec
|
|
2. No director agents are spawned
|
|
3. 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-review` skill 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.
|