@playcraft/cli 0.0.39 → 0.0.41

package/project-template/templates/atom-plan.template.md

@@ -0,0 +1,76 @@
+# Atom Plan — DAG Definition
+
+<!--
+  **Canonical DAG**: `docs/atom-plan.json` — skillsMatch + atoms[] + dagRevisions.
+  **This Markdown (Gate #1)**: Acceptance Criteria only + empty Context placeholders + DAG Revisions.
+  Do NOT mirror atoms[] here at Gate #1 — no Atom List table, no DAG Order (dependsOn lives in JSON).
+  Format: docs/team/atom-plan-format.md | PM workflow: refs/pm-workflow-detail.md § Step 8
+-->
+
+> **Canonical**: [`docs/atom-plan.json`](atom-plan.json) — PM edits JSON; hook runs `validate-atom-plan` on STOP.
+
+> **Living Document**: Designer / TA / Developer enrich **their** sections below without overwriting PM's JSON.
+
+## JSON 主文件（PM Gate #1）
+
+```bash
+playcraft skills match --intent "<gameplayType>,<mechanic>,<keywords>" --json   # → skillsMatch
+playcraft skills validate-atom-plan
+playcraft skills link --from-atom-plan --prune
+```
+
+- **Never** use `playcraft-*` in `skillRef`; values must come from `skillsMatch.items[].atomId` (or `null` + `dagRevisions` gap)
+
+---
+
+## Acceptance Criteria
+
+| atomId      | Criteria                                                       |
+| ----------- | -------------------------------------------------------------- |
+| {{atom_id}} | {{one short line — reference other docs, do not repeat specs}} |
+
+<!--
+Gate #1 — one line per atom in atoms[]; point elsewhere for details:
+  ✅ "tile_atlas: layout-spec § assetMapping tiles_atlas + frameId satisfied"
+  ✅ "match3_gameplay: first level 100% clearable per design-brief § Level Configuration"
+  ❌ WxH, hex, gradient prose, or paths already in layout-spec
+-->
+
+---
+
+## Asset Skill Context
+
+> **Designer fills** after Phase 1 Skill Discovery.
+
+(Pending Designer Phase 1)
+
+---
+
+## TA Skill Context
+
+> **Technical Artist fills** during production Wave 2.
+
+(Pending Technical Artist Phase 1)
+
+---
+
+## Impl Skill Context
+
+> **Developer fills** during integration Skill Preflight.
+
+(Pending Developer Phase 1)
+
+---
+
+## DAG Revisions
+
+> Record structural changes to `atom-plan.json` → `atoms[]`. Reviewer audits these.
+
+<!--
+### Revision {{N}} — {{Agent}} ({{add/remove/modify}})
+- **atomId**: {{atom_id}}
+- **reason**: {{why}}
+- **change**: {{what changed in JSON}}
+-->
+
+(No revisions yet)

package/project-template/templates/design-brief.template.md

@@ -0,0 +1,195 @@
+# Design Brief
+
+<!--
+  PM only. CONTRACT doc — keep concise (see agent-conduct § PM four-doc discipline).
+  Put here: five-axis outcome, gameplay choice, Style Direction, experience-flow (mechanics only), level knobs.
+  Do NOT paste: hex colors / element ids (→ layout-spec § Color Palette + assetMapping);
+  per-stage emotions / audio-visual signals (→ Style Direction § Emotional Arc Intent only);
+  MC/ASR paths, prompts, research dumps (→ style-exploration + designer-log).
+-->
+
+## Intent Analysis
+
+| Dimension               | Tags                                                                | Classification           |
+| ----------------------- | ------------------------------------------------------------------- | ------------------------ |
+| Visual Style            | {{visual_style_tags}}                                               | {{cared/uncared/locked}} |
+| Core Gameplay           | {{gameplay_type}}                                                   | {{cared/uncared/locked}} |
+| Element Theme           | {{element_theme}}                                                   | {{cared/uncared/locked}} |
+| Pace/Feel               | {{pace_tags}}                                                       | {{cared/uncared/locked}} |
+| Color Mood              | {{color_mood}}                                                      | {{cared/uncared/locked}} |
+| Target Audience         | {{audience_tags}}                                                   | {{cared/uncared/locked}} |
+| Target Platform         | {{platform}}                                                        | {{cared/uncared/locked}} |
+| Promoted Product        | {{product_type}}                                                    | {{cared/uncared/locked}} |
+| **User Motivation Job** | {{stress-relief / challenge / collection / creativity / immersion}} | {{cared/uncared}}        |
+
+<!-- User Motivation Job: the psychological "job" the target user hires this ad/game to do (JTBD).
+     No signal → default "stress-relief"; strategy RPG → infer "challenge". -->
+
+## Gameplay Selection
+
+- **Selected gameplay**: {{gameplay_type}} ({{gameplay_subtype}})
+- **Rationale**: {{selection_rationale}}
+- **Risk level**: {{low/medium/high}} — {{risk_explanation}}
+- **Alternative considered**: {{alternative}} — {{why_not_chosen}}
+
+## Fusion Strategy
+
+<!-- Only fill for fusion gameplay (Type A/B1/B2/C/D). Delete this section for single gameplay. -->
+
+### Mechanic Fusion
+
+- **Primary Mechanic**: {{primary_gameplay_type}}
+- **Secondary Mechanic**: {{secondary_gameplay_type}}
+- **Fusion Type**: {{A / B1 / B2 / C / D}} — {{one-line description of how mechanics fuse}}
+- **Integration Point**: {{where the two systems connect, e.g., "elimination count drives monster HP bar"}}
+- **Tutorial Approach**: {{how to teach both mechanics within the Tutorial phase}}
+- **Fusion Depth Limit**: {{secondary mechanic ≤ Xs to learn / no more than N simultaneous hotspots}}
+- **Mechanic Risk Level**: {{Low / Medium / High / Extreme}}
+- **Downgrade Applied**: {{whether downgraded from user's original request; if so, explain why}}
+
+<!-- Dimension / 2.5D / True 3D: declare once in Style Direction § Dimension — do NOT duplicate here. -->
+
+## Style Direction
+
+<!--
+THIS IS THE MOST CRITICAL SECTION FOR DESIGNER.
+Be specific, visual, and reference-based. NOT just adjectives.
+The first four fields (Dimension / Interaction Modality / Emotional Arc / Emotional Arc Intent)
+are mandatory explicit declarations — not implied within Art Style or Mood.
+-->
+
+### Dimension
+
+{{Flat 2D / 2.5D Visual / Isometric / True 3D}}
+
+<!-- Explain why this dimension was chosen, and its impact on Designer (asset types) and Developer (rendering pipeline).
+     Example: "Flat 2D — broadest audience, no extra Designer cost, existing PGS fully compatible."
+     Example: "2.5D Visual — stronger visual impact, Designer needs 3D-feel rendering assets (~3x cost), logic stays 2D grid." -->
+
+### Interaction Modality
+
+{{Tap Only / Tap + Swipe / Drag / Tap + Hold}}
+
+<!-- Explain why this modality was chosen, estimated Tutorial time, and target audience width.
+     Example: "Tap Only — pure tap, Tutorial ~1s, broadest audience (includes elderly, children)."
+     Example: "Drag — draw-path interaction, Tutorial ~5s, more intuitive visually but narrower audience." -->
+
+### Emotional Arc
+
+{{Competence / Challenge / Curiosity / Relaxation / Urgency}}
+
+<!-- Explain how this arc threads through Hook→Tutorial→Gameplay→EndCard. Gives Designer atmosphere reference.
+     Example: "Competence Arc — Hook shows 'looks hard but has a pattern' → Tutorial guarantees success → Gameplay generous flow → EndCard 'easy and fun, keep playing'"
+     This arc aligns with User Motivation Job 'stress-relief', broadest audience coverage path." -->
+
+### Emotional Arc Intent
+
+Per-stage emotional beats for Designer to design asset atmosphere:
+
+| Stage             | Emotional Beat       | Visual Signal       | Audio Signal       |
+| ----------------- | -------------------- | ------------------- | ------------------ |
+| Hook              | {{hook_emotion}}     | {{hook_visual}}     | {{hook_audio}}     |
+| Tutorial          | {{tutorial_emotion}} | {{tutorial_visual}} | {{tutorial_audio}} |
+| Gameplay Flow     | {{flow_emotion}}     | {{flow_visual}}     | {{flow_audio}}     |
+| Gameplay Near-Win | {{nearwin_emotion}}  | {{nearwin_visual}}  | {{nearwin_audio}}  |
+| End Card          | {{endcard_emotion}}  | {{endcard_visual}}  | {{endcard_audio}}  |
+
+<!-- Example rows:
+| Hook | Curiosity + mild anxiety | Near-win board close-up, finger hesitation | Brief silence + suspense SFX |
+| Tutorial | Low-pressure mastery | Soft-glow guide arrows | Light upbeat BGM |
+| Gameplay Flow | Smooth satisfaction | Fluid elimination animation + particles | BGM tempo increases |
+| Gameplay Near-Win | Tension + anticipation | Screen focus + subtle shake | Peak emotion SFX |
+| End Card | Satisfaction + incompleteness | Reward display + CTA highlight | Completion chime + BGM fade |
+-->
+
+### Art Style
+
+{{detailed_art_style_description}}
+
+<!-- Example: "2D flat illustration with soft drop shadows. All elements have rounded
+corners (8px radius feel). Slight 3D depth via subtle top-light gradient on interactive
+elements. NOT glossy/realistic — closer to paper cutout aesthetic.
+Reference: Candy Crush Saga's clean readability but with more illustration warmth." -->
+
+### Color Strategy
+
+{{detailed_color_strategy — strategy prose only; NO hex codes}}
+
+<!-- Prose only: saturation, contrast, warm/cool, accent usage rules.
+     Canonical hex + element ids → layout-spec § Color Palette + assetMapping only.
+     Example: "High-sat warm palette; analogous green background gradient; primaries on tiles;
+     gold accent reserved for score moments — see layout-spec for hex." -->
+
+### Element Design
+
+{{detailed_element_design}}
+
+<!-- Example: "Fruits rendered as cute characters: each has two dot-eyes and a tiny
+curve smile. Body is 80% signature color with 15% lighter gradient and 5% white
+highlight. Proportions: slightly wider than tall (aspect ~1.1:1 within tile).
+Consistent shadow: 2px bottom offset, 20% opacity of fruit color.
+Strawberry = red with green leaf crown. Blueberry = round, deep blue, cluster of 3.
+Kiwi = brown fuzzy exterior, shown in cross-section (green center with black seeds)." -->
+
+### Visual Hierarchy
+
+{{visual_hierarchy_description}}
+
+<!-- Example: "Board is the dominant visual focus (47% of screen area). Background
+is atmospheric but LOW contrast/detail in board region — avoid competing with tiles.
+HUD is minimal: score number + small progress bar, white on 60% opacity black strip.
+CTA area: clean separation, dark gradient footer with centered bright button." -->
+
+### Mood & Feeling
+
+{{mood_description}}
+
+<!-- Example: "Cheerful and rewarding. Every interaction should feel 'juicy' — elements
+look like they want to be tapped. Relaxing tropical vacation vibe, not competitive stress.
+Audio should reinforce: light ukulele/marimba BGM, satisfying pop/chime on match." -->
+
+### Visual References
+
+{{references}}
+
+<!-- Example:
+"LIKE: Tropicats (lush green mood), Royal Match (clean board readability),
+Candy Crush (element clarity and juiciness)
+NOT LIKE: Bejeweled (too glossy 3D), Tetris (too geometric/minimal),
+Gardenscapes (too realistic/detailed)" -->
+
+## Experience Flow Design
+
+<!-- Mechanics + narrative tasks only. Per-stage emotions / visual-audio signals → Style Direction § Emotional Arc Intent (do NOT repeat here). -->
+
+### Hook (0-3s)
+
+- **Narrative Task**: {{narrative_task}}
+- **Mechanic Expression**: {{mechanic_expression}}
+- **Trigger Type**: {{trigger_type}}
+  <!-- Near-Win / Failure Display / Success Demo / Unexpected Conflict / Reward Reveal -->
+
+### Tutorial (3-10s)
+
+- **Narrative Task**: {{narrative_task}}
+- **Mechanic Expression**: {{mechanic_expression}}
+- **Success Guarantee**: ✅ First interaction must succeed at 100%
+
+### Gameplay (10-25s)
+
+- **Narrative Task**: {{narrative_task}}
+- **Near-Win Design**: {{near_win_design}}
+- **Mechanic Expression**: {{mechanic_expression}}
+
+### End Card (25-30s)
+
+- **Narrative Task**: {{narrative_task}}
+- **CTA Emotion Logic**: {{cta_emotion_logic}}
+  <!-- Sequel feeling / reward inheritance — NOT "download now" -->
+
+## Level Configuration
+
+- Total levels: {{total_levels}}
+- Difficulty progression: {{difficulty_curve_description}}
+- First level guaranteed success: ✅
+- Time constraint: {{time_constraint_if_any}}

package/project-template/templates/design-lens-checklist.reference.md

@@ -0,0 +1,117 @@
+# Design Lens Checklist
+
+> **Used by**: Reviewer Agent — after the five-dimension evaluation (mechanic / dimension / interaction / narrative / emotional arc),
+> apply these 8 design lenses for a quality audit of the design-brief.
+>
+> **Source**: Jesse Schell's *The Art of Game Design* core lenses, streamlined and adapted for playable ads.
+>
+> Each lens is a set of concrete questions — not a score, but forced thinking.
+> If 2+ lenses have "❌ No" answers, Reviewer should flag specific design-brief items for PM revision.
+
+---
+
+## Lens 1 — The Essential Experience
+
+> "Is every mechanic serving that one core feeling?"
+
+- [ ] What feeling should the user carry away when the ad ends? (fill in: ___)
+- [ ] Does the design-brief's Emotional Arc clearly describe this feeling?
+- [ ] Is every design decision in Hook / Gameplay / EndCard reinforcing this core feeling?
+- [ ] Is any design element "consuming time" without serving the core feeling?
+
+---
+
+## Lens 2 — The Toy
+
+> "Is the basic interaction inherently satisfying, even without goals?"
+
+- [ ] Does the base operation (eliminate/tap/drag) come with inherently pleasing instant feedback (visual + audio)?
+- [ ] During the first interaction (Tutorial), does the user feel satisfied by the action itself, not just the goal?
+- [ ] Does the element design (size, animation, sound) make users want to tap/interact more?
+- [ ] If all game rules and win/lose conditions were removed, leaving only interaction feedback — is it still fun?
+
+---
+
+## Lens 3 — Curiosity
+
+> "Is the user continuously drawn to find out what's next?"
+
+- [ ] Does the Hook successfully open a cognitive gap ("What is this? What happens next?")?
+- [ ] At Tutorial end, does the user want to know "what does it feel like one level harder?"
+- [ ] During Gameplay, are there continuous small surprises (new mechanic / effects / near-win) to sustain curiosity?
+- [ ] Does the EndCard leave "there's more to explore" suspense (cognitive gap NOT closed)?
+
+---
+
+## Lens 4 — The Hook
+
+> "What makes the user start and stay for 30s? Is the reason consistent?"
+
+- [ ] Do the first 3s have a strong enough stimulus to stop the user from scrolling?
+- [ ] Is this stimulus related to the product/game's core value (not pure clickbait)?
+- [ ] From Hook → Tutorial → Gameplay, is the main thread (core conflict or goal) consistent?
+- [ ] After completing Tutorial, does the user understand "why do I want to win?"
+
+---
+
+## Lens 5 — Skill
+
+> "Does a zero-skill user succeed on first try? Is the flow zone reasonable?"
+
+- [ ] Does the Tutorial design guarantee zero-skill users succeed on the very first interaction?
+- [ ] Is the difficulty of the first 3 interactions at the flow zone lower bound (success rate ≥ 95%)?
+- [ ] Is the difficulty ramp reasonable (no more than 1 new challenge per 5s)?
+- [ ] Is the Near-Win difficulty designed as "solvable, not unsolvable"? (avoid frustration)
+
+---
+
+## Lens 6 — The Near Win
+
+> "Is a near-win moment deliberately designed? Does the scenario have a solution?"
+
+- [ ] Does the design-brief's Gameplay stage explicitly describe the Near-Win design (which step / what scenario)?
+- [ ] Does the Near-Win scenario have a clear solution (player can see the "just one more step" path)?
+- [ ] Is the Near-Win duration appropriate (≤ 5s, to avoid turning into frustration)?
+- [ ] After Near-Win resolution, is there sufficient emotional peak reinforcement (effects / audio / animation)?
+
+---
+
+## Lens 7 — Emotion
+
+> "Does each mechanic trigger the intended emotion? Aligned with the overall arc?"
+
+- [ ] Does the selected Emotional Arc (Competence / Challenge / Curiosity / Relaxation / Urgency) match the User Motivation Job (JTBD)?
+- [ ] Is the emotion triggered by the Hook consistent with the arc's starting point?
+- [ ] Do Gameplay emotions form a complete arc (starting point → peak → landing), not a flat line?
+- [ ] Is the EndCard emotion a combination of "satisfaction + incompleteness", not an abrupt ending?
+- [ ] Does any mechanic trigger unintended negative emotions (frustration / confusion / boredom)?
+
+---
+
+## Lens 8 — The Memorable Moment
+
+> "What will the user remember 10 minutes later?"
+
+- [ ] Is there 1 sufficiently unique visual/mechanic moment in the 30s experience that the user can describe 10 minutes later?
+- [ ] Does this memorable moment occur at the emotional peak (typically Near-Win or EndCard)?
+- [ ] Is this memorable moment related to the promoted product's core value (user can associate memory with install motivation)?
+- [ ] Does the design avoid "too many highlights so nothing is remembered" (focus on 1-2 peak moments)?
+
+---
+
+## Summary
+
+| Lens | Pass ✅ | Needs Work ❌ | Key Issue |
+|------|--------|-------------|-----------|
+| 1 Essential Experience | | | |
+| 2 The Toy | | | |
+| 3 Curiosity | | | |
+| 4 The Hook | | | |
+| 5 Skill | | | |
+| 6 The Near Win | | | |
+| 7 Emotion | | | |
+| 8 Memorable Moment | | | |
+
+**Reviewer Conclusion**: {{overall_assessment}}
+
+<!-- If any ❌: list specific design-brief items that PM should revise -->

package/project-template/templates/design-methodology.md

@@ -0,0 +1,99 @@
+# Design Methodology Foundations
+
+> **When to read**: PM reads this before Step 4 (Five-Axis Evaluation) to ground decisions in theory.
+> Designer and Reviewer may also reference this for context on emotional intent.
+
+---
+
+## A. MDA Framework (Mechanics-Dynamics-Aesthetics)
+
+Core insight: **designers build upward from mechanics; players experience downward from emotion** — opposite starting points.
+
+```
+Designer's perspective (build direction):  Mechanics → Dynamics → Aesthetics
+Player's perspective (experience direction): Aesthetics ← Dynamics ← Mechanics
+```
+
+8 Aesthetics emotion types (starred = most relevant to playable ads):
+
+| Relevance | Aesthetic | Role in Playable Ads |
+|-----------|----------|---------------------|
+| ★★★★★ | **Sensation** | Visual juice + audio feedback — the baseline for every ad |
+| ★★★★★ | **Challenge** | Theoretical basis for Near-Win design; drives "one more try" |
+| ★★★★ | **Submission** | Healing/relaxing emotion in casual ads; low-pressure flow |
+| ★★★ | **Discovery** | The "aha, that's how it works!" moment; core of the Curiosity Arc |
+| ★★ | Fellowship | Social proof in ad context (rarely applicable in 30s) |
+| ★★ | Fantasy | World-building for RPG/adventure ads (requires L2+ narrative) |
+| ★ | Narrative | Story-driven ads — almost never fits in 30s |
+| ★ | Expression | Dress-up/customization ads — niche |
+
+**Key principle**: A tiny change in mechanics → amplified by dynamics → dramatic shift in aesthetics. Example: changing the match threshold from 3 to 2 completely transforms the rhythm and sense of achievement.
+
+---
+
+## B. JTBD — Jobs-to-be-Done (User Motivation Framework)
+
+Users don't "play a game" — they **hire** the game to do a psychological job. The same game targeting different motivation types requires completely different Hook strategies:
+
+| Motivation Type | Signal Words | Hook Emotion Strategy | Default Arc |
+|----------------|-------------|----------------------|------------|
+| **Stress Relief** | "casual", "relaxing", "zen", "mindless" | Show smooth, satisfying elimination flow | Relaxation Arc |
+| **Challenge / Mastery** | "hard", "strategic", "brain teaser" | Show high-difficulty board + near-win tension | Challenge Arc |
+| **Collection / Growth** | "collect", "upgrade", "rewards", "evolve" | Show reward cascade / evolution moment | Competence Arc |
+| **Creativity / Expression** | "customize", "dress up", "design", "create" | Show rich personalization options + beautiful results | Curiosity Arc |
+| **Immersion / Escape** | "story", "world", "RPG", "adventure" | Show grand scene entry + immersion hook | Curiosity Arc |
+
+**Default rule**: If the prompt has no clear motivation signal → assume **Stress Relief** (broadest audience coverage).
+
+---
+
+## C. Three Key Emotional Mechanisms
+
+These are the non-negotiable tools in your emotional design toolkit:
+
+### 1. Near-Win
+
+Deliberately design a "one step away from success" situation — the peak emotion trigger.
+
+**Critical constraint**: Near-Win **must have a solution**. A visible path to victory creates excitement; a dead end creates frustration. The difference between "thrilling" and "rage-quit" is whether the player can see the way out.
+
+### 2. Emotional Breather
+
+The Tutorial phase's low-pressure onboarding is a **mandatory buffer zone** — it cannot be compressed or skipped.
+
+**Flow theory basis**: Place zero-skill new users at the bottom of the flow channel. The first interaction must succeed at 100% — no exceptions. This is the entry ramp to flow state; skip it and you lose the user.
+
+### 3. Curiosity Gap Closure
+
+The End Card **does not close the gap** — the user installs to "continue this story", not to "buy a product."
+
+**CTA is a sequel entrance, not an ad cutoff.** "Continue playing" > "Download now". The cognitive gap opened in the Hook should remain partially open at the End Card — closure happens after install.
+
+---
+
+## D. Hook-Body-CTA Advertising Framework
+
+Standard ad creative structure, mapped to playable ad stages:
+
+| Ad Stage | Playable Ad Stage | Duration | Job |
+|----------|------------------|----------|-----|
+| **Hook** | Hook | 0-3s | Stop the scroll — create immediate emotional stimulus |
+| **Body** | Tutorial + Gameplay | 3-25s | Deliver the core experience — build and peak the emotional arc |
+| **CTA** | End Card | 25-30s | Convert emotion to action — sequel feeling, not sales pitch |
+
+**Key insight**: The Hook's emotion must be **consistent** with the Body and CTA. If the Hook creates curiosity but the Body delivers relaxation, the experience fractures. The Emotional Arc must be a single throughline across all three stages.
+
+---
+
+## E. Design Lenses (Quick Reference)
+
+Jesse Schell's 8 most relevant lenses for playable ads (full checklist in `templates/design-lens-checklist.reference.md`):
+
+1. **Essential Experience** — Is every mechanic serving the core feeling?
+2. **The Toy** — Is the basic interaction inherently satisfying, even without goals?
+3. **Curiosity** — Is the user continuously drawn to find out what's next?
+4. **The Hook** — Is the reason to start and stay consistent throughout?
+5. **Skill** — Does a zero-skill user succeed on first try? Is the flow zone reasonable?
+6. **Near-Win** — Is a near-win moment deliberately designed? Does it have a solution?
+7. **Emotion** — Does each mechanic trigger the intended emotion? Aligned with the arc?
+8. **Memorable Moment** — What will the user remember 10 minutes later?

package/project-template/templates/designer-log.template.md

@@ -0,0 +1,98 @@
+# Designer Log
+
+## Delivery Summary
+
+- **Assigned**: {{total_assigned}}
+- **Completed**: {{total_completed}}
+- **Skipped**: {{total_skipped}}
+- **Blocked**: {{total_blocked}}
+
+## Per-Atom Delivery
+
+### {{atom_id}} — {{slot_name}}
+
+- **Status**: {{status}}
+- **Method**: {{AI generation / existing asset / manual}}
+- **Model**: {{model_name_if_generated}}
+- **Prompt**: {{full_generation_prompt}}
+- **Output path**: {{file_path}}
+- **Dimensions/Size**: {{WxH, file_size}}
+- **Post-processing**: {{resize/crop/compress steps if any}}
+- **Recipe Record**:
+  | Field | Value |
+  |-------|-------|
+  | Prompt | {{full_generation_prompt}} |
+  | Model | {{model_name}} |
+  | Seed | {{seed_if_applicable}} |
+  | Reference Image | {{reference_image_path_or_none}} |
+  | Aspect Ratio | {{aspect_ratio}} |
+  | Style Constraint | {{style_keywords}} |
+  | Generation Time | {{seconds}} |
+- **Consistency check**: {{how this relates to other atoms}}
+- **Style Intent Notes** (供 TA 补全时参考):
+  - 主色调：{{dominant color and why}}
+  - 光影方向：{{light source direction and quality}}
+  - 边缘处理：{{hard/soft/outline style}}
+  - 质感特征：{{matte/glossy/textured}}
+  - 与整体概念图的关系：{{how this element fits the full mockup}}
+- **Anti-Pattern Notes** (明确告诉 TA 不要做什么):
+  - 不要：{{specific style choice to avoid}}
+  - 不要：{{another anti-pattern}}
+- **Reference Usage Guide** (告诉 TA 这个样本怎么用):
+  - 适用元素类型：{{which element types this sample can guide}}
+  - 不适用元素类型：{{which types should NOT use this reference}}
+  - 需要额外注意的属性：{{e.g., "UI 元素需要更高对比度，不能直接用 tile 的柔和处理"}}
+
+<!--
+Repeat this section for each atom.
+Fill in details as you complete each one.
+-->
+
+## ASR Coverage Matrix (designer-handoff-v2 — 100% contract rows)
+
+> UI: `assets/images/reference/ui_state_sheet_{{option}}.png`  
+> Element: `assets/images/reference/element_state_sheet_{{option}}.png`
+
+| Contract id                      | Type   | ASR sheet    | Grid (row,col) | State(s)    | TA extends? |
+| -------------------------------- | ------ | ------------ | -------------- | ----------- | ----------- |
+| {{element_id_from_assetMapping}} | visual | ui / element | {{1,1}}        | {{default}} | {{yes/no}}  |
+| {{static_text_id}}               | text   | ui / MC-crop | —              | baked       | {{yes/no}}  |
+
+<!--
+One row per layout-spec assetMapping elementId and per static text id.
+TA crop index + Phase 2 VisualAtom actualOutput: ASR:sheet:R#C#
+-->
+
+## Palette Locked (from MC option {{option}})
+
+| Role          | Hex         | Notes |
+| ------------- | ----------- | ----- |
+| bg_primary    | {{#______}} |       |
+| accent        | {{#______}} |       |
+| cta           | {{#______}} |       |
+| {{element_1}} | {{#______}} |       |
+
+**Delta vs layout-spec Color Palette**: {{match | PM update: one line}}
+
+## Style Consistency Self-Check
+
+- [ ] All visual assets share the same art style?
+- [ ] Color temperature consistent with layout-spec palette?
+- [ ] Audio mood matches visual atmosphere?
+- [ ] File naming matches asset-mapping exactly?
+- [ ] All assets within size budget?
+
+## Size Budget Tracking
+
+| Asset          | Budget       | Actual          | Status      |
+| -------------- | ------------ | --------------- | ----------- |
+| {{asset_name}} | {{max_size}} | {{actual_size}} | {{ok/over}} |
+
+<!--
+Total project budget: <= 5MB
+Individual budgets:
+- Background: < 500KB
+- Tile/icon: < 100KB
+- BGM: < 300KB
+- SFX: < 50KB
+-->