mirror of
https://github.com/Donchitos/Claude-Code-Game-Studios.git
synced 2026-10-16 01:37:05 +00:00
Release 1.1.2 — the default path works end to end
Fix release for 1.1.1: the minimal path end to end, engine commands that run on Godot, Unity and Unreal, hook warnings you can see, and verdicts that say when they could not check. Details in CHANGELOG.md; upgrade steps in UPGRADING.md (v1.1.1 → v1.1.2). Fixes #67 Fixes #131 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WuJn2FdynEybfL5KC697nJ
This commit is contained in:
Donchitos
co-authored by
Claude Opus 5.5
Claude Opus 5.5
parent
7ed2c3e9c4
commit
b21fa0f7f2
+1
-1
@@ -60,7 +60,7 @@ Story Author — Decomposes game design epics into atomic, testable user stories
|
||||
- `production/qa/evidence/` (creates test evidence stubs)
|
||||
|
||||
**Cannot Touch:**
|
||||
- `src/` (no game code)
|
||||
- The code root — `src/`, `Assets/` or `Source/` by engine (no game code)
|
||||
- `assets/` (no asset modifications)
|
||||
- Source data files (read-only)
|
||||
|
||||
|
||||
+7
-5
@@ -3,7 +3,7 @@
|
||||
> Authoring guidance: .claude/docs/templates/guidance/accessibility-requirements-guide.md (load per-section as you author — do not read entirely).
|
||||
|
||||
> **Status**: Draft | Committed | Audited | Certified
|
||||
> **Author**: [ux-designer / producer]
|
||||
> **Author**: [user + ux-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Accessibility Tier Target**: [Basic / Standard / Comprehensive / Exemplary]
|
||||
> **Platform(s)**: [PC / Xbox / PlayStation 5 / Nintendo Switch / iOS / Android]
|
||||
@@ -19,10 +19,12 @@
|
||||
> **Why this document exists**: Per-screen accessibility annotations belong in
|
||||
> UX specs. This document captures the project-wide accessibility commitments,
|
||||
> the feature matrix across all systems, the test plan, and the audit history.
|
||||
> It is created once during Technical Setup by the UX designer and producer,
|
||||
> then updated as features are added and audits are completed. If a feature
|
||||
> conflicts with a commitment made here, this document wins — change the feature,
|
||||
> not the commitment, unless the producer approves a formal revision.
|
||||
> It is created once during Technical Setup by the UX designer with
|
||||
> `/ux-design accessibility` — you pick the tier, against the criteria
|
||||
> accessibility-specialist sets and audits against — then updated as features
|
||||
> are added and audits are completed. If a feature conflicts with a commitment
|
||||
> made here, this document wins — change the feature, not the commitment,
|
||||
> unless the producer approves a formal revision.
|
||||
>
|
||||
> **When to update**: After each `/gate-check` pass, after any accessibility
|
||||
> audit, and whenever a new game system is added to `systems-index.md`.
|
||||
|
||||
+5
-4
@@ -42,7 +42,7 @@ chosen approach.]
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
|
||||
| **Domain** | [Physics / Rendering / UI / Audio / Navigation / Animation / Networking / Core / Input / Scripting] |
|
||||
| **Layer** | [Foundation / Core / Feature / Presentation] |
|
||||
| **Knowledge Risk** | [LOW — in training data / MEDIUM — near cutoff, verify / HIGH — post-cutoff, must verify] |
|
||||
@@ -54,12 +54,13 @@ chosen approach.]
|
||||
> project upgrades engine versions. Flag it as "Superseded" and write a new ADR.
|
||||
|
||||
> **`Layer` is the ADR's own layer, not the referencing epic's — and it is a
|
||||
> different taxonomy from `Domain`.** Four sites branch on whether an ADR is
|
||||
> different taxonomy from `Domain`.** Several sites branch on whether an ADR is
|
||||
> *critical (Foundation-layer)*: `/create-stories`, `/create-epics`,
|
||||
> `/architecture-decision`, and `gate-pre-production.md`. At `standard`,
|
||||
> `/architecture-decision`, `/story-readiness`, `/propagate-design-change` and
|
||||
> `gate-pre-production.md`; a missing row counts as critical. At `standard`,
|
||||
> `/create-stories` **stops** for a missing critical ADR and only **warns** for a
|
||||
> non-critical one, so this row decides whether a run halts. Earlier revisions of
|
||||
> this template recorded no layer at all, leaving those four sites to infer one from
|
||||
> this template recorded no layer at all, leaving those sites to infer one from
|
||||
> the referencing epic — which gives the wrong answer whenever a Foundation-layer
|
||||
> ADR is referenced by a Core-layer epic, the common case.
|
||||
>
|
||||
|
||||
Vendored
+46
-59
@@ -1,80 +1,67 @@
|
||||
# Art Bible: [Game Title]
|
||||
|
||||
## Document Status
|
||||
- **Version**: 1.0
|
||||
- **Last Updated**: [Date]
|
||||
- **Owned By**: art-director
|
||||
- **Status**: [Draft / Under Review / Approved]
|
||||
> **Status**: [Draft / Under Review / Approved]
|
||||
> **Owned By**: art-director
|
||||
> **Last Updated**: [Date]
|
||||
> **Art Director Sign-Off (AD-ART-BIBLE)**: [Not yet reviewed]
|
||||
|
||||
## Visual Identity Summary
|
||||
[2-3 sentences describing the overall visual identity]
|
||||
`/art-bible` writes these nine sections in this order and replaces each
|
||||
section's `[To be designed]` line as that section is approved. A section still
|
||||
holding its placeholder is incomplete; a later run fills only those.
|
||||
|
||||
## Reference Board
|
||||
[List reference games, films, art, and what specific visual quality each represents]
|
||||
## 1. Visual Identity Statement
|
||||
|
||||
| Reference | Medium | What We're Taking |
|
||||
| --------- | ------ | ----------------- |
|
||||
| [Name] | [Game/Film/Art] | [Specific quality] |
|
||||
[To be designed] — a one-line visual rule that resolves any visual ambiguity,
|
||||
plus 2–3 supporting principles, each with a design test ("when X is ambiguous,
|
||||
choose Y") and the pillar it serves.
|
||||
|
||||
## Color Palette
|
||||
## 2. Mood & Atmosphere
|
||||
|
||||
### Primary Palette
|
||||
| Name | Hex | Usage |
|
||||
| ---- | --- | ----- |
|
||||
| [Color Name] | #XXXXXX | [Where and when to use] |
|
||||
[To be designed] — for each major game state (exploration, combat, victory,
|
||||
defeat, menus — whichever this game has): the emotional target, lighting
|
||||
character (time of day, colour temperature, contrast), 3–5 atmospheric
|
||||
descriptors, and energy level. Each state must look distinct from the others.
|
||||
|
||||
### Emotional Color Mapping
|
||||
| Game State | Dominant Colors | Mood |
|
||||
| ---------- | --------------- | ---- |
|
||||
| Exploration | [Colors] | [Feeling] |
|
||||
| Combat | [Colors] | [Feeling] |
|
||||
| Safe zones | [Colors] | [Feeling] |
|
||||
| Danger | [Colors] | [Feeling] |
|
||||
## 3. Shape Language
|
||||
|
||||
## Art Style
|
||||
[To be designed] — character silhouette philosophy (readable at thumbnail
|
||||
size, one distinguishing trait per archetype), environment geometry, UI shape
|
||||
grammar, and hero versus supporting shapes.
|
||||
|
||||
### Rendering Style
|
||||
[Realistic / Stylized / Pixel / Cel-shaded / etc.]
|
||||
## 4. Color System
|
||||
|
||||
### Proportions
|
||||
[Character proportions, environment scale, UI scale relationships]
|
||||
[To be designed] — a primary palette of 5–7 colours with their meaning in this
|
||||
world, semantic colour usage, per-area colour temperature rules, the UI palette
|
||||
and where it diverges, and colourblind safety: which semantic colours need a
|
||||
shape, icon or sound backup.
|
||||
|
||||
### Level of Detail
|
||||
[How detailed are characters, environments, UI elements?]
|
||||
## 5. Character Design Direction
|
||||
|
||||
### Visual Hierarchy
|
||||
[How do we guide the player's eye? What's always most prominent?]
|
||||
[To be designed] — the player character's visual archetype, how players tell
|
||||
enemies, NPCs and allies apart at a glance, expression and pose style, and how
|
||||
much detail survives at game camera distance (LOD philosophy).
|
||||
|
||||
## Character Art Standards
|
||||
[Silhouette requirements, color coding, animation style, proportions]
|
||||
## 6. Environment Design Language
|
||||
|
||||
## Environment Art Standards
|
||||
[Tilesets, modularity, lighting, atmospheric effects, scale]
|
||||
[To be designed] — architectural style and its tie to the world's culture,
|
||||
texture philosophy (painted, PBR or stylised, and why), prop density rules per
|
||||
area type, and environmental storytelling guidelines.
|
||||
|
||||
## UI Art Standards
|
||||
[Button styles, typography, icon style, menu layout principles, HUD density]
|
||||
## 7. UI/HUD Visual Direction
|
||||
|
||||
## VFX Standards
|
||||
[Particle style, screen effects, impact feedback, color coding]
|
||||
[To be designed] — diegetic versus screen-space HUD, typography (personality,
|
||||
weight, size hierarchy, minimum readable size), iconography style, UI animation
|
||||
feel, and any art-direction versus readability conflict and how it was decided.
|
||||
|
||||
## Asset Production Standards
|
||||
## 8. Asset Standards
|
||||
|
||||
### Naming Convention
|
||||
`[category]_[name]_[variant]_[size].[ext]`
|
||||
[To be designed] — file formats, naming convention, texture resolution tiers,
|
||||
LOD levels, export settings, and the engine's hard limits (poly budgets per
|
||||
asset category, texture memory, material slots). Where an art preference and a
|
||||
technical limit disagree, record both and the trade-off chosen.
|
||||
|
||||
### Texture Standards
|
||||
| Category | Max Resolution | Format | Color Space |
|
||||
| -------- | -------------- | ------ | ----------- |
|
||||
| Characters | [Size] | [Format] | [Space] |
|
||||
| Environments | [Size] | [Format] | [Space] |
|
||||
| UI | [Size] | [Format] | [Space] |
|
||||
| VFX | [Size] | [Format] | [Space] |
|
||||
## 9. Reference Direction
|
||||
|
||||
### Animation Standards
|
||||
[Frame rates, blend times, animation graph structure]
|
||||
|
||||
## Accessibility
|
||||
- Colorblind-safe UI elements required
|
||||
- Minimum text size: [X]px at 1080p
|
||||
- High contrast mode specifications
|
||||
- Icon + color (never color alone) for game state
|
||||
[To be designed] — 3–5 references (games, films, art styles or artists). For
|
||||
each: the specific element to take from it, and what to avoid so the result
|
||||
does not read as a copy.
|
||||
|
||||
+40
-23
@@ -17,6 +17,13 @@
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
[2–3 sentences: what this system is, what it does for the player, why it
|
||||
exists — inferred from code; mark `[inferred — confirm]`]
|
||||
|
||||
---
|
||||
|
||||
## 1. Overview
|
||||
|
||||
**Purpose**: [What problem does this system solve?]
|
||||
@@ -32,9 +39,17 @@
|
||||
|
||||
---
|
||||
|
||||
## 2. Detailed Design
|
||||
## 2. Player Fantasy
|
||||
|
||||
### 2.1 Core Mechanics
|
||||
[What the player should FEEL when using this system. Code does not record this:
|
||||
infer it from the player-facing effects above, then CONFIRM it with the designer
|
||||
and mark it `[inferred — confirm]` until they do.]
|
||||
|
||||
---
|
||||
|
||||
## 3. Detailed Design
|
||||
|
||||
### 3.1 Core Mechanics
|
||||
|
||||
[Describe the mechanics as implemented, organized clearly]
|
||||
|
||||
@@ -50,20 +65,7 @@
|
||||
- **Design Rationale**: [Why it exists]
|
||||
- **Player-Facing**: [Player experience]
|
||||
|
||||
### 2.2 Rules and Formulas
|
||||
|
||||
**Formulas Discovered in Code**:
|
||||
|
||||
| Formula | Expression | Purpose | Verified? |
|
||||
|---------|-----------|---------|-----------|
|
||||
| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
|
||||
| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
|
||||
|
||||
**Clarifications**:
|
||||
- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
|
||||
- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
|
||||
|
||||
### 2.3 State and Data
|
||||
### 3.2 State and Data
|
||||
|
||||
**Data Structures** (from code):
|
||||
- [Data structure 1]: `[fields/properties]`
|
||||
@@ -78,7 +80,7 @@
|
||||
- Saved: [What is saved to player save file]
|
||||
- Not saved: [What is session-only or recalculated]
|
||||
|
||||
### 2.4 Integration Points
|
||||
### 3.3 Integration Points
|
||||
|
||||
**Dependencies** (systems this depends on):
|
||||
- [System 1]: [What it provides]
|
||||
@@ -94,7 +96,22 @@
|
||||
|
||||
---
|
||||
|
||||
## 3. Edge Cases
|
||||
## 4. Formulas
|
||||
|
||||
**Formulas Discovered in Code**:
|
||||
|
||||
| Formula | Expression | Purpose | Verified? |
|
||||
|---------|-----------|---------|-----------|
|
||||
| [Formula 1] | `[mathematical expression]` | [What it calculates] | ✅ / ⚠️ needs tuning |
|
||||
| [Formula 2] | `[expression]` | [Purpose] | ✅ / ⚠️ needs tuning |
|
||||
|
||||
**Clarifications**:
|
||||
- [Formula X]: Originally [value/approach], user clarified intent is [corrected intent]
|
||||
- [Formula Y]: Implemented as [X], but should be [Y] — flagged for update
|
||||
|
||||
---
|
||||
|
||||
## 5. Edge Cases
|
||||
|
||||
**Handled in Code**:
|
||||
- ✅ [Edge case 1]: [How it's handled]
|
||||
@@ -109,7 +126,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 4. Dependencies
|
||||
## 6. Dependencies
|
||||
|
||||
**Technical Dependencies**:
|
||||
- [Dependency 1]: [Why needed]
|
||||
@@ -125,7 +142,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 5. Balance and Tuning
|
||||
## 7. Tuning Knobs
|
||||
|
||||
**Current Values** (as implemented):
|
||||
|
||||
@@ -144,7 +161,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 6. Acceptance Criteria
|
||||
## 8. Acceptance Criteria
|
||||
|
||||
**What Exists** (implemented):
|
||||
- ✅ [Criterion 1]
|
||||
@@ -162,7 +179,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 7. Open Questions and Follow-Up Work
|
||||
## Open Questions and Follow-Up Work
|
||||
|
||||
### Questions Needing User Decision
|
||||
1. **[Question 1]**: [What needs to be decided?]
|
||||
@@ -180,7 +197,7 @@
|
||||
|
||||
---
|
||||
|
||||
## 8. Version History
|
||||
## Version History
|
||||
|
||||
| Date | Author | Changes |
|
||||
|------|--------|---------|
|
||||
|
||||
Vendored
+3
-1
@@ -4,7 +4,7 @@
|
||||
THE ONE-PAGE BRIEF. At the `minimal` workflow tier this is the ENTIRE design doc —
|
||||
it replaces the full concept doc, systems decomposition, and per-system GDDs.
|
||||
Keep it to one screen. If a field needs a second paragraph, you're writing a GDD,
|
||||
not a brief. Fill every REQUIRED field; the two RECOMMENDED one-liners are cheap
|
||||
not a brief. Fill every REQUIRED field; the three RECOMMENDED one-liners are cheap
|
||||
but optional. Engine is set separately (project.yaml / /setup-engine) — don't restate it.
|
||||
|
||||
Field set grounded in industry practice — Tim Ryan (*Anatomy of a Design Document*),
|
||||
@@ -39,3 +39,5 @@ thinking and cuts ceremony), and lean/agile GDD practice.
|
||||
**Who it's for / what they feel:** [One line: the player and the feeling. e.g. "solo puzzle fans who want a cozy 20-minute sitting."]
|
||||
|
||||
**Art & audio direction:** [One line of aesthetic intent — drives asset choices. e.g. "flat pastel vector art, lo-fi ambient."]
|
||||
|
||||
**Reference game:** [One shipped game this is closest to, and the ~10% of it the MVP keeps. e.g. "Vampire Survivors — the auto-attack loop on one map; no meta-progression." Scoping against a real game is the fastest honest MVP check.]
|
||||
|
||||
+3
-3
@@ -289,7 +289,7 @@ so it can be cited in design reviews.]
|
||||
|
||||
---
|
||||
|
||||
## Section 10 — Accessibility (HUD Specific)
|
||||
## Section 10 — Accessibility
|
||||
|
||||
> **Why this section exists**: HUD accessibility failures are the most visible
|
||||
> accessibility failures in games — players encounter the HUD in every session,
|
||||
@@ -374,7 +374,7 @@ Example: "Health bar numerical label grows with text scale — bar expands sligh
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ui-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
|
||||
| [e.g., Should the minimap show enemy positions by default, or only after a detection skill is unlocked?] | [systems-designer + ux-designer] | [Sprint 5, Day 2] | [Pending — depends on progression GDD decision] |
|
||||
| [e.g., Does the game have a boss health bar, or do bosses use the standard enemy health bar? Bosses need a visually distinct treatment if they are significantly more important than normal enemies.] | [game-designer] | [Sprint 5, Day 1] | [Pending] |
|
||||
| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ui-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
|
||||
| [e.g., Damage numbers: diegetic (floating in world space, occluded by geometry) or screen space (always readable, overlaid on HUD layer)?] | [ux-designer + lead-programmer] | [Sprint 4, Day 5] | [Pending — architecture decision affects rendering layer choice] |
|
||||
| [e.g., Mobile portrait vs. landscape: does the game support both orientations? If yes, each requires its own zone layout.] | [producer] | [Sprint 3, Day 3] | [Pending — platform scope decision required first] |
|
||||
|
||||
+5
-5
@@ -154,7 +154,7 @@ Example:
|
||||
└──────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
**Worked example — zone definitions table (5.2)**:
|
||||
**Worked example — layout zones table (5.2)**:
|
||||
|
||||
| Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
|
||||
|-----------|-------------|-----------------|-------------|-------------------|
|
||||
@@ -286,7 +286,7 @@ Example:
|
||||
|
||||
---
|
||||
|
||||
## Section 10 — Transition & Animation
|
||||
## Section 10 — Transitions & Animations
|
||||
|
||||
> **Why this section exists**: Transitions are not decoration — they communicate
|
||||
> hierarchy and causality. A screen that slides in from the right implies the
|
||||
@@ -320,7 +320,7 @@ Example:
|
||||
|
||||
---
|
||||
|
||||
## Section 12 — Screen-Level Accessibility Requirements
|
||||
## Section 12 — Accessibility
|
||||
|
||||
> **Why this section exists**: Accessibility requirements must be specified at design
|
||||
> time because retrofitting them is expensive and often architecturally impractical.
|
||||
@@ -437,7 +437,7 @@ and independently verifiable:
|
||||
|
||||
| Question | Owner | Deadline | Resolution |
|
||||
|----------|-------|----------|-----------|
|
||||
| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ui-designer] | [Sprint 4, Day 3] | [Pending] |
|
||||
| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ui-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
|
||||
| [e.g., Should item comparison be automatic (always showing equipped stats) or player-triggered (press Compare)?] | [ux-designer] | [Sprint 4, Day 3] | [Pending] |
|
||||
| [e.g., Do we support controller cursor (free aim) in the item grid, or d-pad-only grid navigation?] | [lead-programmer + ux-designer] | [Sprint 4, Day 3] | [Pending — depends on ADR-0015 input model decision] |
|
||||
| [e.g., What is the game's item drop policy — permanent loss or drop-to-world?] | [systems-designer] | [Requires GDD update] | [Blocked on inventory GDD Edge Cases section] |
|
||||
| [e.g., Maximum inventory size — does the grid have a hard cap or is it infinite-scroll?] | [economy-designer] | [Sprint 3, Day 5] | [Pending] |
|
||||
|
||||
Vendored
+4
-3
@@ -3,13 +3,14 @@
|
||||
> Authoring guidance: .claude/docs/templates/guidance/hud-design-guide.md (load per-section as you author — do not read entirely).
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Name or agent — e.g., ui-designer]
|
||||
> **Author**: [Name or agent — e.g., ux-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Game**: [Game name — this is a single document per game, not per element]
|
||||
> **Platform Targets**: [All platforms this HUD must work on — e.g., PC, PS5, Xbox Series X, Steam Deck]
|
||||
> **Related GDDs**: [Every system that exposes information through the HUD — e.g., `design/gdd/combat.md`, `design/gdd/progression.md`, `design/gdd/quests.md`]
|
||||
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
|
||||
> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § HUD Visual Language`]
|
||||
> **Style Reference**: [Link to art bible HUD section if it exists — e.g., `design/art/art-bible.md § 7. UI/HUD Visual Direction`]
|
||||
> **Template**: HUD Design
|
||||
|
||||
> **Note — Scope boundary**: This document specifies all elements that overlay the
|
||||
> game world during active gameplay — health bars, ammo counters, minimaps, quest
|
||||
@@ -204,7 +205,7 @@ Repositioning saves to player profile, not to a single slot. Applies across play
|
||||
|
||||
---
|
||||
|
||||
## 10. Accessibility — HUD Specific
|
||||
## 10. Accessibility
|
||||
|
||||
> HUD-specific requirements only — refer to the project's
|
||||
> `design/accessibility-requirements.md` for the full project standard.
|
||||
|
||||
+1
-1
@@ -1,6 +1,6 @@
|
||||
# Incident Response: [Incident Title]
|
||||
|
||||
**Severity**: [S1-Critical / S2-Major / S3-Moderate / S4-Minor]
|
||||
**Severity**: [S1-Critical / S2-High / S3-Medium / S4-Low]
|
||||
**Status**: [Active / Mitigated / Resolved / Post-Mortem Complete]
|
||||
**Detected**: [Date Time UTC]
|
||||
**Resolved**: [Date Time UTC or ONGOING]
|
||||
|
||||
+4
-1
@@ -12,6 +12,8 @@
|
||||
> - `design/art/art-bible.md` — visual standards (colors, typography, iconography)
|
||||
> - `design/accessibility-requirements.md` — accessibility commitments per feature
|
||||
> - `docs/ux/ux-spec-[screen].md` — individual screen specs that reference patterns
|
||||
>
|
||||
> **Template**: Interaction Pattern Library
|
||||
|
||||
> **Why this document exists**: Every UI screen spec should be able to say
|
||||
> "uses Button (Primary) pattern" rather than re-specifying hover states,
|
||||
@@ -686,7 +688,8 @@ These three patterns define how screens enter and exit the navigation stack.
|
||||
|
||||
> Every interactive event should have audio feedback. Sound is a primary feedback
|
||||
> channel, not a decoration. The sounds defined here are event categories — the
|
||||
> specific audio assets are defined in `docs/sound-bible.md`. This table maps
|
||||
> specific audio assets are defined in `design/audio/sound-bible.md` (or
|
||||
> `design/gdd/sound-bible.md`, where earlier versions put it). This table maps
|
||||
> interaction events to sound categories so the sound designer and UI programmer
|
||||
> use the same vocabulary.
|
||||
|
||||
|
||||
+1
-1
@@ -49,7 +49,7 @@ these are met.]
|
||||
| Frame rate | > [X] FPS on min spec | Performance profiling |
|
||||
| Load time | < [X] seconds | Automated timing |
|
||||
| Critical bugs | 0 open S1 | Bug tracker |
|
||||
| Major bugs | < [X] open S2 | Bug tracker |
|
||||
| High-severity bugs | < [X] open S2 High | Bug tracker |
|
||||
| Test coverage | > [X]% | Test framework report |
|
||||
|
||||
## Risk Register
|
||||
|
||||
+6
-5
@@ -2,6 +2,7 @@
|
||||
|
||||
**Generated**: [DATE]
|
||||
**Stage**: [Concept | Systems Design | Technical Setup | Pre-Production | Production | Polish | Release]
|
||||
**Stage Confidence**: [PASS / CONCERNS / NOT ASSESSED / FAIL — reason]
|
||||
**Analysis Scope**: [Full project | Specific role: programmer/designer/producer]
|
||||
|
||||
---
|
||||
@@ -30,11 +31,11 @@
|
||||
|
||||
### Source Code
|
||||
- **Status**: [X%] complete
|
||||
- **Files Found**: [N] source files in `src/`
|
||||
- **Files Found**: [N] source files in `[code root]/` (`src/` Godot, `Assets/` Unity, `Source/` Unreal)
|
||||
- **Major Systems Identified**:
|
||||
- ✅ [System 1] (`src/path/`) — [brief status]
|
||||
- ✅ [System 2] (`src/path/`) — [brief status]
|
||||
- ⚠️ [System 3] (`src/path/`) — [issue or incomplete]
|
||||
- ✅ [System 1] (`[code root]/path/`) — [brief status]
|
||||
- ✅ [System 2] (`[code root]/path/`) — [brief status]
|
||||
- ⚠️ [System 3] (`[code root]/path/`) — [issue or incomplete]
|
||||
- **Key Gaps**:
|
||||
- [ ] [Missing system 1 + impact]
|
||||
- [ ] [Missing system 2 + impact]
|
||||
@@ -174,7 +175,7 @@ design/
|
||||
narrative/ [N] files
|
||||
levels/ [N] files
|
||||
|
||||
src/
|
||||
[code root]/ (src/, Assets/ or Source/<Module>/)
|
||||
core/ [N] files
|
||||
gameplay/ [N] files
|
||||
ai/ [N] files
|
||||
|
||||
+1
-1
@@ -51,7 +51,7 @@ directly where possible.]
|
||||
|
||||
---
|
||||
|
||||
## Recommendation: [PROCEED / PIVOT / KILL]
|
||||
## Recommendation: [PROCEED / PIVOT / KILL / NOT ASSESSED — built but nobody has played it]
|
||||
|
||||
[One paragraph explaining the recommendation with evidence from the result above.]
|
||||
|
||||
|
||||
+6
-1
@@ -22,7 +22,12 @@
|
||||
|
||||
### Critical Bugs
|
||||
- [ ] Zero S1 (Critical) bugs open
|
||||
- [ ] Zero S2 (Major) bugs -- or documented exceptions below:
|
||||
- [ ] Zero S2 (High) bugs -- or documented exceptions below (no exceptions at `workflow: full`):
|
||||
- [ ] Zero S3 (Medium) bugs open -- required at `workflow: full`
|
||||
|
||||
> The release gate (`/gate-check release`) blocks any open S1–S3 bug at `workflow: full`,
|
||||
> with no exceptions; at `standard` and `minimal` it blocks open S1 only, and an open
|
||||
> S2 or S3 is a risk to record here.
|
||||
|
||||
| Bug ID | Description | Exception Rationale | Approved By |
|
||||
| ---- | ---- | ---- | ---- |
|
||||
|
||||
+4
-2
@@ -6,7 +6,7 @@
|
||||
This file has TWO regions and they are not interchangeable:
|
||||
|
||||
1. The CHECKPOINT region below (STATUS + CHECKPOINT blocks) is the part
|
||||
machines read. Hooks inject it verbatim into the context, so it is
|
||||
machines read. session-start.sh shows it verbatim in the context, so it is
|
||||
BOUNDED BY CONSTRUCTION: keep it under ~25 lines. It is OVERWRITTEN on
|
||||
every update, never appended to.
|
||||
|
||||
@@ -41,6 +41,7 @@ Task:
|
||||
**Next step:** [one line — the very next action, concrete enough to resume cold]
|
||||
**Blocked on:** [one line, or `nothing`]
|
||||
**Files in progress:** [paths, comma-separated, or `none`]
|
||||
**Run result:** [`/dev-story` writes its `Run result:` line here, verbatim, for `/story-done` to read; other writers leave this line out]
|
||||
**Open questions:** [one line each, or `none`]
|
||||
<!-- /CHECKPOINT -->
|
||||
|
||||
@@ -64,7 +65,8 @@ or agent picking this up cold.]
|
||||
|
||||
CHECKPOINT block
|
||||
The recovery payload. `session-start.sh` shows it when a previous session
|
||||
left state; `pre-compact.sh` injects it before compaction. Both read THIS
|
||||
left state, and again after a compaction (SessionStart runs then too).
|
||||
`pre-compact.sh` reads it as well, for the debug log. Both read THIS
|
||||
region and nothing else, which is what keeps the cost fixed no matter how
|
||||
long the narrative gets.
|
||||
|
||||
|
||||
+3
@@ -1,5 +1,8 @@
|
||||
# Sound Bible: [Project Name]
|
||||
|
||||
> **Location**: `design/audio/sound-bible.md` — not `design/gdd/`, where the GDD checks count every file as a system GDD
|
||||
> **Owned By**: audio-director
|
||||
|
||||
## Audio Vision
|
||||
|
||||
### Sonic Identity
|
||||
|
||||
+1
-1
@@ -56,7 +56,7 @@
|
||||
|
||||
- [ ] All Must Have tasks completed
|
||||
- [ ] All tasks pass acceptance criteria
|
||||
- [ ] QA plan exists (`production/qa/qa-plan-sprint-[N].md`)
|
||||
- [ ] QA plan exists (`production/qa/qa-plan-[sprint-slug]-[date].md`, from `/qa-plan sprint`)
|
||||
- [ ] All Logic/Integration stories have passing unit/integration tests
|
||||
- [ ] Smoke check passed (`/smoke-check sprint`)
|
||||
- [ ] QA sign-off report: APPROVED or APPROVED WITH CONDITIONS (`/team-qa sprint`)
|
||||
|
||||
+1
-1
@@ -142,5 +142,5 @@ These should be prototyped early regardless of priority tier.]
|
||||
- [ ] Review and approve this systems enumeration
|
||||
- [ ] Design MVP-tier systems first (use `/design-system [system-name]`)
|
||||
- [ ] Run `/design-review` on each completed GDD
|
||||
- [ ] Run `/gate-check pre-production` when MVP systems are designed
|
||||
- [ ] Run `/gate-check technical-setup` when MVP systems are designed
|
||||
- [ ] Validate the highest-risk systems with `/vertical-slice` before committing to Production
|
||||
|
||||
+1
-1
@@ -12,7 +12,7 @@
|
||||
|
||||
| Field | Value |
|
||||
|-------|-------|
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.4] |
|
||||
| **Engine** | [e.g. Godot 4.6 / Unity 6 / Unreal Engine 5.7] |
|
||||
| **APIs Depended On** | [Specific classes/methods/nodes used, version-pinned — e.g. `CharacterBody3D.move_and_slide() (Godot 4.x)`] |
|
||||
| **References Consulted** | [engine-reference docs read before writing this — e.g. `docs/engine-reference/godot/modules/physics.md`] |
|
||||
| **Post-Cutoff Features Used** | [Features from engine versions beyond LLM training cutoff, or "None"] |
|
||||
|
||||
+11
-9
@@ -69,19 +69,21 @@ If nothing notable: *No significant observations.*
|
||||
|
||||
## Sign-Off
|
||||
|
||||
All roles must sign off before the story can be marked COMPLETE via `/story-done`.
|
||||
Visual/Feel stories require the designer or art-lead sign-off. UI stories require
|
||||
the UX lead or designer sign-off.
|
||||
A **Visual/Feel** story needs the lead sign-off below — the art-director, or the
|
||||
designer who owns the feature — before `/story-done` marks it COMPLETE. A **UI**
|
||||
story is closed by the retained screenshot of each screen it touched; a sign-off
|
||||
here is welcome but not required (`.claude/docs/coding-standards.md`).
|
||||
|
||||
**Solo developers**: all sign-offs may be by the same person in each role. The
|
||||
intent is that someone deliberately reviews the evidence before marking complete —
|
||||
not that three separate people must participate.
|
||||
**Solo developers**: you may sign as the lead yourself. The intent is that
|
||||
someone deliberately reviews the evidence before marking complete.
|
||||
|
||||
| Role | Name | Date | Signature |
|
||||
|------|------|------|-----------|
|
||||
| Developer (implemented) | | | [ ] Approved |
|
||||
| Designer / Art Lead / UX Lead | | | [ ] Approved |
|
||||
| QA Lead | | | [ ] Approved |
|
||||
| Lead (art-director / designer) | | | [ ] Approved |
|
||||
|
||||
*Optional:* add a row for anyone else whose review your team wants, such as the
|
||||
developer or the QA lead. `/story-done` and `/test-evidence-review` treat every
|
||||
row in this table as required, so add one only for someone who will sign.
|
||||
|
||||
**Any sign-off can be marked "Deferred — [reason]"** if the person is
|
||||
unavailable. Deferred sign-offs must be resolved before the story advances
|
||||
|
||||
Vendored
+7
-6
@@ -15,7 +15,7 @@
|
||||
| [story title] | Logic | Unit test — `tests/unit/[system]/` | None |
|
||||
| [story title] | Integration | Integration test — `tests/integration/[system]/` | Smoke check |
|
||||
| [story title] | Visual/Feel | None (not automatable) | Screenshot + lead sign-off |
|
||||
| [story title] | UI | None (not automatable) | Manual step-through |
|
||||
| [story title] | UI | None (verified by its screenshots) | Retained screenshot of each screen touched |
|
||||
| [story title] | Config/Data | Data validation (optional) | Spot-check in-game values |
|
||||
|
||||
**Totals**: [N] Logic, [N] Integration, [N] Visual/Feel, [N] UI, [N] Config/Data
|
||||
@@ -57,17 +57,17 @@
|
||||
|
||||
### [Story Title] — Visual/Feel
|
||||
|
||||
**Verification method**: Screenshot + [designer / art-lead] sign-off
|
||||
**Verification method**: Screenshot + [designer / art-director] sign-off
|
||||
**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
|
||||
**Who must sign off**: [designer / lead-programmer / art-lead]
|
||||
**Who must sign off**: [art-director / owning designer]
|
||||
|
||||
- [ ] [Specific observable condition — e.g., "hit flash appears on frame of impact, not the frame after"]
|
||||
- [ ] [Another falsifiable condition]
|
||||
|
||||
### [Story Title] — UI
|
||||
|
||||
**Verification method**: Manual step-through
|
||||
**Evidence file**: `production/qa/evidence/[story-slug]-evidence.md`
|
||||
**Verification method**: Retained screenshot of each screen touched
|
||||
**Evidence**: `production/qa/evidence/[story-slug]/[NN]-[what-it-shows].png`, one per screen
|
||||
|
||||
- [ ] [Every acceptance criterion translated into a manual check item]
|
||||
|
||||
@@ -104,7 +104,8 @@ A story is DONE when ALL of the following are true:
|
||||
|
||||
- [ ] All acceptance criteria verified — automated test result OR documented manual evidence
|
||||
- [ ] Test file exists for all Logic and Integration stories and passes
|
||||
- [ ] Manual evidence document exists for all Visual/Feel and UI stories
|
||||
- [ ] Retained screenshot of each screen touched, in `production/qa/evidence/`, for all Visual/Feel and UI stories
|
||||
- [ ] Signed-off evidence doc at `production/qa/evidence/[story-slug]-evidence.md` for all Visual/Feel stories
|
||||
- [ ] Smoke check passes (run `/smoke-check sprint` before QA hand-off)
|
||||
- [ ] No regressions introduced — previous sprint's features still pass
|
||||
- [ ] Code reviewed (via `/code-review` or documented peer review)
|
||||
|
||||
Vendored
+11
-5
@@ -3,7 +3,7 @@
|
||||
> Authoring guidance: .claude/docs/templates/guidance/ux-spec-guide.md (load per-section as you author — do not read entirely).
|
||||
|
||||
> **Status**: Draft | In Review | Approved | Implemented
|
||||
> **Author**: [Name or agent — e.g., ui-designer]
|
||||
> **Author**: [Name or agent — e.g., ux-designer]
|
||||
> **Last Updated**: [Date]
|
||||
> **Screen / Flow Name**: [Short identifier used in code and tickets — e.g., `InventoryScreen`, `NewGameFlow`]
|
||||
> **Platform Target**: [PC | Console | Mobile | All — list all that this spec covers]
|
||||
@@ -11,6 +11,7 @@
|
||||
> **Related ADRs**: [Any architectural decisions that constrain this screen — e.g., `ADR-0012: UI Framework Selection`]
|
||||
> **Related UX Specs**: [Sibling and parent screens — e.g., `ux-spec-pause-menu.md`, `ux-spec-settings.md`]
|
||||
> **Accessibility Tier**: Basic | Standard | Comprehensive | Exemplary
|
||||
> **Template**: UX Spec
|
||||
|
||||
> **Note — Scope boundary**: This template covers discrete screens and flows (menus,
|
||||
> dialogs, inventory, settings, cutscene UI, etc.). For persistent in-game overlays
|
||||
@@ -100,7 +101,7 @@
|
||||
|
||||
## 5. Layout Specification
|
||||
|
||||
### 5.1 Wireframe
|
||||
### 5.1 ASCII Wireframe
|
||||
|
||||
```
|
||||
[Draw the screen layout using ASCII art. Suggested characters:
|
||||
@@ -114,7 +115,7 @@
|
||||
See guide Section 5 for a completed example wireframe.]
|
||||
```
|
||||
|
||||
### 5.2 Zone Definitions
|
||||
### 5.2 Layout Zones
|
||||
|
||||
| Zone Name | Description | Approximate Size | Scrollable? | Overflow Behavior |
|
||||
|-----------|-------------|-----------------|-------------|-------------------|
|
||||
@@ -131,6 +132,11 @@ See guide Section 5 for a completed example wireframe.]
|
||||
|
||||
**Primary focus element on open**: [Element that receives focus when the screen opens, including deep-link and empty-state cases]
|
||||
|
||||
### 5.4 Information Hierarchy
|
||||
|
||||
[What the player must see first on this screen, what second, and what can wait
|
||||
behind a tab, a scroll or a button — in that order, with the reason for each.]
|
||||
|
||||
---
|
||||
|
||||
## 6. States & Variants
|
||||
@@ -197,7 +203,7 @@ See guide Section 5 for a completed example wireframe.]
|
||||
|
||||
---
|
||||
|
||||
## 10. Transition & Animation
|
||||
## 10. Transitions & Animations
|
||||
|
||||
> Specify at least the screen enter and exit transitions, plus reduced-motion
|
||||
> behavior for each. See guide Section 10 for a worked example.
|
||||
@@ -242,7 +248,7 @@ See guide Section 5 for a completed example wireframe.]
|
||||
|
||||
---
|
||||
|
||||
## 12. Screen-Level Accessibility Requirements
|
||||
## 12. Accessibility
|
||||
|
||||
> Project-wide standards live in `design/accessibility-requirements.md` — consult it
|
||||
> before filling this section so you do not duplicate or contradict project-level
|
||||
|
||||
+19
-5
@@ -90,12 +90,14 @@ encounter, 0.5 days per UI screen"]
|
||||
|
||||
---
|
||||
|
||||
## Recommendation: [PROCEED / PIVOT / KILL]
|
||||
## Recommendation: [PROCEED / PIVOT / KILL / NOT ASSESSED — the slice was built but nobody has played it]
|
||||
|
||||
[One paragraph with evidence — reference the validation question directly. Did a
|
||||
player experience the core fantasy within the target time, without developer guidance?
|
||||
Can the team build at this quality on the projected schedule?]
|
||||
|
||||
**Creative Director review (CD-PLAYTEST):** [APPROVE / CONCERNS / REJECT / NOT ASSESSED — the director's reason; or "not run — [review mode]"]
|
||||
|
||||
---
|
||||
|
||||
## If Proceeding
|
||||
@@ -116,13 +118,25 @@ Can the team build at this quality on the projected schedule?]
|
||||
**Performance targets:** [Confirmed / Revised — list changes if revised]
|
||||
|
||||
**Playtest note:** Run `/playtest-report` to structure additional session data
|
||||
before running `/gate-check pre-production`.
|
||||
before running `/gate-check production`.
|
||||
|
||||
**Next steps:**
|
||||
1. `/gate-check pre-production` — formally advance to Production
|
||||
2. `/create-epics layer:foundation` — plan Foundation layer epics
|
||||
3. `/create-epics layer:core` — plan Core layer epics
|
||||
1. `/create-epics layer:foundation` — plan Foundation layer epics
|
||||
2. `/create-epics layer:core` — plan Core layer epics
|
||||
3. `/create-stories [epic-slug]` — break each epic into stories
|
||||
4. `/sprint-plan` — use velocity data from this report in the estimate
|
||||
5. `/gate-check production` — formally advance to Production
|
||||
|
||||
---
|
||||
|
||||
## If Not Assessed
|
||||
|
||||
[The slice was built but nobody has played it through, so there is no evidence
|
||||
for PROCEED, PIVOT or KILL yet.]
|
||||
|
||||
**Next step:** play the slice unguided (at least one documented session), then
|
||||
re-run `/vertical-slice` — it resumes from the checkpoint in
|
||||
`production/session-state/active.md`.
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user