Claude-Code-Game-Studios/CCGS Skill Testing Framework/skills/authoring/ux-design.md

Skill Test Spec: /ux-design

Skill Summary

/ux-design authors UX documents section by section. The argument picks the mode and output file: hud → design/ux/hud.md; patterns → design/ux/interaction-patterns.md; accessibility → design/accessibility-requirements.md (the only mode that writes outside design/ux/); any other value → a screen/flow spec at design/ux/[kebab-name].md. With no argument it asks "What are we designing today?" instead of failing.

Phase 2 reads context before asking anything: the game concept (or game brief), the player journey, GDD UI Requirements, existing UX specs, the pattern library catalog, the art bible, accessibility requirements, and the input methods from the project.yaml platform block. If the output file already exists, the skill enters retrofit mode and fills only Empty or Placeholder sections. Otherwise it asks "May I create the skeleton file at [path]?" and writes the mode's skeleton.

Each section then runs Context → Questions → Options → Decision → Draft → Approval → Write: "Does this capture the [section name] correctly?", then "May I write the [section name] section to [filepath]?", then an Edit replacing the placeholder. Of the per-mode guidance files, only the active mode's is loaded, and a template guide is read one section at a time. After a cross-reference check, the handoff says the spec must pass /ux-review and ends with verdict COMPLETE. There are no director gates.

---

Static Assertions (Structural)

Checked against the SKILL.md by /skill-test spec — 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, and "May I create" for the skeleton
• Has a next-step handoff (/ux-review to validate the completed spec)
• Documents the four modes and their output paths, including design/accessibility-requirements.md for accessibility

---

Director Gate Checks

None. /ux-design resolves only automation, workflow and docs.density (not review_mode) and spawns no director gate. /ux-review is the separate validation step. Specialists (art-director, ui-programmer, game-designer, narrative-director) may be consulted for sub-topics; their output is presented to the user, and this session owns every file write.

---

Test Cases

Case 1: Happy Path — New HUD design

Fixture:

• No design/ux/hud.md
• design/gdd/combat.md and design/gdd/stamina.md have ## UI Requirements sections; design/gdd/save-system.md has none
• project.yaml has a platform block (targets: [PC], gamepad_support: Full)
• design/gdd/game-concept.md and design/player-journey.md exist

Input: /ux-design hud

Expected behavior:

1. Mode is HUD design; output file design/ux/hud.md
2. UI Requirements are collected with one Grep across design/gdd/*.md; the skill counts the three system GDDs — game-concept.md sits in design/gdd/ but is not one — lists save-system.md as unmatched, and confirms with the user it is headless before excluding it
3. Input methods are derived from the platform block (keyboard/mouse and gamepad) — the user is not asked
4. The context summary is shown, then "Anything else I should read before we start, or shall we proceed?"
5. No existing file, so: "May I create the skeleton file at design/ux/hud.md?" — on yes, writes the HUD skeleton and updates production/session-state/active.md. The skeleton carries every section /ux-review's HUD checklist requires, so the finished spec can pass that review
6. Phase 4 reads .claude/skills/ux-design/references/sections-hud.md and never the other two per-mode files (sections-ux-spec.md, sections-patterns.md); if a section needs depth, the HUD design guide is read one section at a time, never whole
7. Each section: draft → "Does this capture the [section name] correctly?" → "May I write the [section name] section to design/ux/hud.md?" → Edit replacing that section's placeholder
8. Phase 5 presents the Cross-Reference Check results
9. Phase 6 states the spec should be validated with /ux-review before implementation, then asks with four options (run /ux-review now / design another screen / update the pattern library / stop); verdict COMPLETE

Assertions:

• A GDD without a UI Requirements section is listed and confirmed with the user, not silently excluded
• game-concept.md is not counted as a system GDD, so it is not listed as unmatched
• Input methods come from the project.yaml platform block, without asking the user
• The skeleton is written only after the "May I create the skeleton file at design/ux/hud.md?" approval
• The HUD skeleton includes the sections /ux-review Phase 3B checks for: HUD Philosophy, Information Architecture, Layout Zones, HUD element specifications, HUD States by Gameplay Context, Information Hierarchy, Visual Budget, Feedback & Notification Systems, Platform Adaptation, Tuning Knobs, Acceptance Criteria
• Of the three per-mode guidance files only sections-hud.md is loaded, and no guide is read whole
• Each section is approved and then gets its own "May I write the [section name] section…" ask before it is written
• The handoff names /ux-review as required before implementation, and the verdict is COMPLETE

---

Case 2: Existing Document — Retrofit of incomplete sections only

Fixture:

• Scenario (a): design/ux/main-menu.md exists, built from the UX spec skeleton; Purpose & Player Need, Player Context on Arrival, Navigation Position and Entry & Exit Points have real content; every other section is [To be designed]
• Scenario (b): design/accessibility-requirements.md exists, built from the accessibility skeleton; Accessibility Tier Definition commits the Standard tier; every other section is [To be designed]

Input: (a) /ux-design main-menu (b) /ux-design accessibility

Expected behavior:

1. Before any skeleton step, the skill Globs the output path — in (b) design/accessibility-requirements.md, not a path under design/ux/ — and finds the file
2. It reads the file, classifies each section as Complete / Empty / Placeholder, and shows the status table, ending "I'll work on the [N] incomplete sections only — existing content will not be overwritten."
3. Skeleton creation is skipped
4. Phase 4 authors only the Empty/Placeholder sections, filling each placeholder in place with Edit after its "May I write" approval
5. (a) The four complete sections are not changed; (b) the committed tier is not changed

Assertions:

• The existing file is detected and no skeleton is written
• The status table and the "incomplete sections only" message are shown before authoring
• Only Empty or Placeholder sections are authored; complete sections are not overwritten
• Each filled section is written with Edit after its own "May I write" approval
• (a) The status table rows use the section names of the UX spec skeleton (e.g., Purpose & Player Need, Layout Specification, States & Variants, Input Method Completeness Checklist)
• (b) The status table rows use the accessibility skeleton's section names (e.g., Accessibility Tier Definition, Visual Accessibility, Motor Accessibility), and the file stays at design/accessibility-requirements.md

---

Case 3: Missing Context — No game concept and no player journey

Fixture:

• No design/gdd/game-concept.md and no design/game-brief.md
• No design/player-journey.md
• No design/ux/inventory.md

Input: /ux-design inventory

Expected behavior:

1. The skill warns: "No game concept found. Run /brainstorm first to establish the game's foundation before designing UX." and continues only if the user asks
2. It notes the missing journey: "No player journey map found at design/player-journey.md. Designing without it means we'll be making assumptions about player context…"
3. The context summary shows "Journey phase(s): unknown — no journey map"
4. The spec's Open Questions section records: "Player journey map not yet created. Author it from the template at .claude/docs/templates/player-journey.md…"
5. The skill never tells the user to run /ux-design Phase 2b to create the journey map

Assertions:

• The missing concept produces the /brainstorm warning, and the skill proceeds only on the user's say-so
• The missing player journey is noted in the conversation and recorded in Open Questions with the template path
• The remediation points at the template, never back at /ux-design
• The context summary marks the journey phase as unknown

---

Case 4: No Argument Provided — Ask instead of failing

Fixture:

• No argument
• Neither design/ux/main-menu.md nor design/accessibility-requirements.md exists, so both scenarios author fresh files
• Scenario (a): the user types "Main Menu"
• Scenario (b): the user picks "The project-wide accessibility requirements"

Input: /ux-design

Expected behavior:

1. The skill does not fail; it asks "What are we designing today?" with: "A specific screen or flow (I'll name it)", "The game HUD", "The interaction pattern library", "The project-wide accessibility requirements", "I'm not sure — help me figure it out"
2. (a) The name is normalized to kebab-case; the output file is design/ux/main-menu.md
3. (b) The output file is design/accessibility-requirements.md, and the skeleton ask names that path, not a path under design/ux/
4. (b) The Accessibility Tier Definition section is authored first
5. No file is created before the skeleton approval

Assertions:

• No usage error; the "What are we designing today?" question is asked with the five options
• (a) A typed screen name becomes a kebab-case filename under design/ux/
• (b) Accessibility mode writes to design/accessibility-requirements.md
• (b) The tier definition is authored before the other accessibility sections
• No file is written before the skeleton approval

---

Case 5: No Director Gate — /ux-review is the separate review

Fixture:

• project.yaml has modes.review_mode: full and a platform block (targets: [PC, Console], gamepad_support: Full)
• No design/ux/settings-menu.md

Input: /ux-design settings-menu

Expected behavior:

1. The skill authors the screen spec as usual; the review mode is not resolved and nothing branches on it
2. The UX spec skeleton's header carries > **Platform Target**: filled from Phase 2h — PC and Console, keyboard/mouse and gamepad — the line /ux-review checks for
3. No director gate agent is spawned, and no gate ID or skip note appears
4. If a specialist is consulted (e.g., ui-programmer on feasibility), its output is shown to the user, and the session — not the agent — writes the file
5. The run ends with the /ux-review statement and verdict COMPLETE

Assertions:

• The skeleton header's Platform Target line names the targets and input methods from the platform block
• No director gate is invoked and no gate skip messages appear
• modes.review_mode: full does not change the skill's behavior
• Specialist output is presented to the user; agents never write files
• The verdict is COMPLETE, with /ux-review named as the validation step

---

Protocol Compliance

• Once the mode is known — with no argument, the mode question comes first (Case 4) — reads context before asking the user anything else
• Checks for an existing output file before creating a skeleton; retrofit fills only Empty or Placeholder sections
• The skeleton is created only after "May I create the skeleton file at [path]?"
• Sections are drafted one at a time; each is approved, then "May I write the [section name] section to [filepath]?" is asked before the write
• Loads the per-mode guidance file for the active mode and never the other two; a template guide is read one section at a time, never whole
• Ends with the /ux-review handoff and verdict COMPLETE

---

Coverage Notes

• Pattern-library mode (patterns) is not fixture-tested.
• The input-methods question when neither project.yaml nor technical-preferences.md configures the platform is not tested.
• The Phase 5 prompt for a pattern not yet in the pattern library is not individually tested.
• guided and autonomous automation modes, docs.density depth, and recovery after an interrupted session are not tested.