添加 claude code game studios 到项目
This commit is contained in:
panw
263
.claude/skills/ux-review/SKILL.md
Normal file
263
.claude/skills/ux-review/SKILL.md
Normal file
@@ -0,0 +1,263 @@
|
||||
---
|
||||
name: ux-review
|
||||
description: "Validates a UX spec, HUD design, or interaction pattern library for completeness, accessibility compliance, GDD alignment, and implementation readiness. Produces APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED verdict with specific gaps."
|
||||
argument-hint: "[file-path or 'all' or 'hud' or 'patterns']"
|
||||
user-invocable: true
|
||||
allowed-tools: Read, Glob, Grep
|
||||
model: sonnet
|
||||
agent: ux-designer
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Validates UX design documents before they enter the implementation pipeline.
|
||||
Acts as the quality gate between UX Design and Visual Design/Implementation in
|
||||
the `/team-ui` pipeline.
|
||||
|
||||
**Run this skill:**
|
||||
- After completing a UX spec with `/ux-design`
|
||||
- Before handing off to `ui-programmer` or `art-director`
|
||||
- Before the Pre-Production to Production gate check (which requires key screens
|
||||
to have reviewed UX specs)
|
||||
- After major revisions to a UX spec
|
||||
|
||||
**Verdict levels:**
|
||||
- **APPROVED** — spec is complete, consistent, and implementation-ready
|
||||
- **NEEDS REVISION** — specific gaps found; fix before handoff but not a full redesign
|
||||
- **MAJOR REVISION NEEDED** — fundamental issues with scope, player need, or
|
||||
completeness; needs significant rework
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Parse Arguments
|
||||
|
||||
- **Specific file path** (e.g., `/ux-review design/ux/inventory.md`): validate
|
||||
that one document
|
||||
- **`all`**: find all files in `design/ux/` and validate each
|
||||
- **`hud`**: validate `design/ux/hud.md` specifically
|
||||
- **`patterns`**: validate `design/ux/interaction-patterns.md` specifically
|
||||
- **No argument**: ask the user which spec to validate
|
||||
|
||||
For `all`, output a summary table first (file | verdict | primary issue) then
|
||||
full detail for each.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Load Cross-Reference Context
|
||||
|
||||
Before validating any spec, load:
|
||||
|
||||
1. **Input & Platform config**: Read `.claude/docs/technical-preferences.md` and
|
||||
extract `## Input & Platform`. This is the authoritative source for which input
|
||||
methods the game supports — use it to drive the Input Method Coverage checks in
|
||||
Phase 3A, not the spec's own header. If unconfigured, fall back to the spec header.
|
||||
2. The accessibility tier committed to in `design/accessibility-requirements.md`
|
||||
(if it exists)
|
||||
3. The interaction pattern library at `design/ux/interaction-patterns.md` (if
|
||||
it exists)
|
||||
4. The GDDs referenced in the spec's header (read their UI Requirements sections)
|
||||
5. The player journey map at `design/player-journey.md` (if it exists) for
|
||||
context-arrival validation
|
||||
|
||||
---
|
||||
|
||||
## Phase 3A: UX Spec Validation Checklist
|
||||
|
||||
Run all checks against a `ux-spec.md`-based document.
|
||||
|
||||
### Completeness (required sections)
|
||||
|
||||
- [ ] Document header present with Status, Author, Platform Target
|
||||
- [ ] Purpose & Player Need — has a player-perspective need statement (not
|
||||
developer-perspective)
|
||||
- [ ] Player Context on Arrival — describes player's state and prior activity
|
||||
- [ ] Navigation Position — shows where screen sits in hierarchy
|
||||
- [ ] Entry & Exit Points — all entry sources and exit destinations documented
|
||||
- [ ] Layout Specification — zones defined, component inventory table present
|
||||
- [ ] States & Variants — at minimum: loading, empty/populated, and error states
|
||||
documented
|
||||
- [ ] Interaction Map — covers all target input methods (check platform target
|
||||
in header)
|
||||
- [ ] Data Requirements — every displayed data element has a source system and owner
|
||||
- [ ] Events Fired — every player action has a corresponding event or null
|
||||
explanation
|
||||
- [ ] Transitions & Animations — at least enter/exit transitions specified
|
||||
- [ ] Accessibility Requirements — screen-level requirements present
|
||||
- [ ] Localization Considerations — max character counts for text elements
|
||||
- [ ] Acceptance Criteria — at least 5 specific testable criteria
|
||||
|
||||
### Quality Checks
|
||||
|
||||
**Player Need Clarity**
|
||||
- [ ] Purpose is written from player perspective, not system/developer perspective
|
||||
- [ ] Player goal on arrival is unambiguous ("The player arrives wanting to ___")
|
||||
- [ ] The player context on arrival is specific (not just "they opened the
|
||||
inventory")
|
||||
|
||||
**Completeness of States**
|
||||
- [ ] Error state is documented (not just happy path)
|
||||
- [ ] Empty state is documented (no data scenario)
|
||||
- [ ] Loading state is documented if the screen fetches async data
|
||||
- [ ] Any state with a timer or auto-dismiss is documented with duration
|
||||
|
||||
**Input Method Coverage**
|
||||
- [ ] If platform includes PC: keyboard-only navigation is fully specified
|
||||
- [ ] If platform includes console/gamepad: d-pad navigation and face button
|
||||
mapping documented
|
||||
- [ ] No interaction requires mouse-like precision on gamepad
|
||||
- [ ] Focus order is defined (Tab order for keyboard, d-pad order for gamepad)
|
||||
|
||||
**Data Architecture**
|
||||
- [ ] No data element has "UI" listed as the owner (UI must not own game state)
|
||||
- [ ] Update frequency is specified for all real-time data (not just "realtime" —
|
||||
what triggers update?)
|
||||
- [ ] Null handling is specified for all data elements (what shows when data is
|
||||
unavailable?)
|
||||
|
||||
**Accessibility**
|
||||
- [ ] Accessibility tier from `accessibility-requirements.md` is matched or exceeded
|
||||
- [ ] If Basic tier: no color-only information indicators
|
||||
- [ ] If Standard tier+: focus order documented, text contrast ratios specified
|
||||
- [ ] If Comprehensive tier+: screen reader announcements for key state changes
|
||||
- [ ] Colorblind check: any color-coded elements have non-color alternatives
|
||||
|
||||
**GDD Alignment**
|
||||
- [ ] Every GDD UI Requirement referenced in the header is addressed in this spec
|
||||
- [ ] No UI element displays or modifies game state without a corresponding GDD
|
||||
requirement
|
||||
- [ ] No GDD UI Requirement is missing from this spec (cross-check the referenced
|
||||
GDD sections)
|
||||
|
||||
**Pattern Library Consistency**
|
||||
- [ ] All interactive components reference the pattern library (or note they are
|
||||
new patterns)
|
||||
- [ ] No pattern behavior is re-specified from scratch if it already exists in
|
||||
the pattern library
|
||||
- [ ] Any new patterns invented in this spec are flagged for addition to the
|
||||
pattern library
|
||||
|
||||
**Localization**
|
||||
- [ ] Character limit warnings present for all text-heavy elements
|
||||
- [ ] Any layout-critical text has been flagged for 40% expansion accommodation
|
||||
|
||||
**Acceptance Criteria Quality**
|
||||
- [ ] Criteria are specific enough for a QA tester who hasn't seen the design docs
|
||||
- [ ] Performance criterion present (screen opens within Xms)
|
||||
- [ ] Resolution criterion present
|
||||
- [ ] No criterion requires reading another document to evaluate
|
||||
|
||||
---
|
||||
|
||||
## Phase 3B: HUD Validation Checklist
|
||||
|
||||
Run all checks against a `hud-design.md`-based document.
|
||||
|
||||
### Completeness
|
||||
|
||||
- [ ] HUD Philosophy defined
|
||||
- [ ] Information Architecture table covers ALL systems with UI Requirements in GDDs
|
||||
- [ ] Layout Zones defined with safe zone margins for all target platforms
|
||||
- [ ] Every HUD element has a full specification (zone, visibility trigger, data
|
||||
source, priority)
|
||||
- [ ] HUD States by Gameplay Context covers at minimum: exploration, combat,
|
||||
dialogue/cutscene, paused
|
||||
- [ ] Visual Budget defined (max simultaneous elements, max screen %)
|
||||
- [ ] Platform Adaptation covers all target platforms
|
||||
- [ ] Tuning Knobs present for player-adjustable elements
|
||||
|
||||
### Quality Checks
|
||||
|
||||
- [ ] No HUD element covers the center play area without a visibility rule to
|
||||
hide it
|
||||
- [ ] Every information item that exists in any GDD is either in the HUD or
|
||||
explicitly categorized as "hidden/demand"
|
||||
- [ ] All color-coded HUD elements have colorblind variants
|
||||
- [ ] HUD elements in the Feedback & Notification section have queue/priority
|
||||
behavior defined
|
||||
- [ ] Visual Budget compliance: total simultaneous elements is within budget
|
||||
|
||||
### GDD Alignment
|
||||
|
||||
- [ ] All systems in `design/gdd/systems-index.md` with UI category have
|
||||
representation in HUD (or justified absence)
|
||||
|
||||
---
|
||||
|
||||
## Phase 3C: Pattern Library Validation Checklist
|
||||
|
||||
- [ ] Pattern catalog index is current (matches actual patterns in document)
|
||||
- [ ] All standard control patterns are specified: button variants, toggle,
|
||||
slider, dropdown, list, grid, modal, dialog, toast, tooltip, progress bar,
|
||||
input field, tab bar, scroll
|
||||
- [ ] All game-specific patterns needed by current UX specs are present
|
||||
- [ ] Each pattern has: When to Use, When NOT to Use, full state specification,
|
||||
accessibility spec, implementation notes
|
||||
- [ ] Animation Standards table present
|
||||
- [ ] Sound Standards table present
|
||||
- [ ] No conflicting behaviors between patterns (e.g., "Back" behavior consistent
|
||||
across all navigation patterns)
|
||||
|
||||
---
|
||||
|
||||
## Phase 4: Output the Verdict
|
||||
|
||||
```markdown
|
||||
## UX Review: [Document Name]
|
||||
**Date**: [date]
|
||||
**Reviewer**: ux-review skill
|
||||
**Document**: [file path]
|
||||
**Platform Target**: [from header]
|
||||
**Accessibility Tier**: [from header or accessibility-requirements.md]
|
||||
|
||||
### Completeness: [X/Y sections present]
|
||||
- [x] Purpose & Player Need
|
||||
- [ ] States & Variants — MISSING: error state not documented
|
||||
|
||||
### Quality Issues: [N found]
|
||||
1. **[Issue title]** [BLOCKING / ADVISORY]
|
||||
- What's wrong: [specific description]
|
||||
- Where: [section name]
|
||||
- Fix: [specific action to take]
|
||||
|
||||
### GDD Alignment: [ALIGNED / GAPS FOUND]
|
||||
- GDD [name] UI Requirements — [X/Y requirements covered]
|
||||
- Missing: [list any uncovered GDD requirements]
|
||||
|
||||
### Accessibility: [COMPLIANT / GAPS / NON-COMPLIANT]
|
||||
- Target tier: [tier]
|
||||
- [list specific accessibility findings]
|
||||
|
||||
### Pattern Library: [CONSISTENT / INCONSISTENCIES FOUND]
|
||||
- [findings]
|
||||
|
||||
### Verdict: APPROVED / NEEDS REVISION / MAJOR REVISION NEEDED
|
||||
**Blocking issues**: [N] — must be resolved before implementation
|
||||
**Advisory issues**: [N] — recommended but not blocking
|
||||
|
||||
[For APPROVED]: This spec is ready for handoff to `/team-ui` Phase 2
|
||||
(Visual Design).
|
||||
|
||||
[For NEEDS REVISION]: Address the [N] blocking issues above, then re-run
|
||||
`/ux-review`.
|
||||
|
||||
[For MAJOR REVISION NEEDED]: The spec has fundamental gaps in [areas].
|
||||
Recommend returning to `/ux-design` to rework [sections].
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Phase 5: Collaborative Protocol
|
||||
|
||||
This skill is READ-ONLY — it never edits or writes files. It reports findings only.
|
||||
|
||||
After delivering the verdict:
|
||||
- For **APPROVED**: suggest running `/team-ui` to begin implementation coordination
|
||||
- For **NEEDS REVISION**: offer to help fix specific gaps ("Would you like me to
|
||||
help draft the missing error state?") — but do not auto-fix; wait for user
|
||||
instruction
|
||||
- For **MAJOR REVISION NEEDED**: suggest returning to `/ux-design` with the
|
||||
specific sections to rework
|
||||
|
||||
Never block the user from proceeding — the verdict is advisory. Document risks,
|
||||
present findings, let the user decide whether to proceed despite concerns. A user
|
||||
who chooses to proceed with a NEEDS REVISION spec takes on the documented risk.
|
||||
Reference in New Issue
Block a user