Open Design Game UI Handoff

Open Design Game UI Handoff

Package what the game already does before asking Open Design to change it. Treat runtime omission from a standalone as unspecified, never as permission to simplify.

Read docs/hard-rules/ui-adaptation-upgrade-only-contract.md and preservation-contract.md before capturing evidence.

Package content standard = claude-design-handoff-generate (owner benchmark)

The battle-tested claude-design-handoff-generate skill is the CONTENT standard for every Open Design handoff — Open Design gets the same package a Claude Design session would get, plus an Open-Design delta. Do not reinvent a thinner brief.

For VFX / skill / weapon / enemy / boss / RIG packages, build the package WITH claude-design-handoff-generate first (or reuse an existing .handoff/*.zip produced by it): README with the Owner Summary Matrix, brief with approved mechanics, visual orthogonality table (existing identities the design must NOT read as, with reference screenshots of those neighbors), timing/beat sequence, 5+ real mobile #game WebP proof states, reference/ contracts (owner decisions, runtime excerpts, performance budget + annotation template, review contract, onboarding checklist, scenario JSONs), density 0-100 with 100/80/50/30/0% anchors, fanout/texture tables, icon requirements, and level-up card copy inputs. A brief without the orthogonality table produces designs that collide with shipped identities (measured: two engines independently reinvented the shipped 镇魂瓮 teal-vial identity when the table was omitted).

Feeding an existing Claude Design handoff zip into Open Design: unzip it as-is, change nothing inside, and ADD only the Open Design delta files alongside:

• DESIGN.md — aspiration-first creative cover (identity, craft bar, what gorgeous looks like), pointing to the original README/brief for scope and to the craft docs below;
• darkbone-visual-language.md + exemplar-craft.html (from open-design-game-ui-concept/references/) — Open Design engines need the craft scaffolding that the Claude Design product ships built-in;
• a placeholder artifact file named for the expected deliverable;
• source-manifest.json with the generation contract (codex / gpt-5.6-sol / ultra / no override);
• for interactive VFX labs: require a scriptable review API (window.DARKBONE_VFX_LAB: playBeat/playCycle/ setDensity/setFloor/setTargets/setSpeed/state, every method returning truthy) so acceptance can be driven and recorded per beat.

The kickoff message orders reading: DESIGN.md → craft docs → original README/brief → reference contracts. For UI surfaces, the preservation-contract workflow below still applies on top.

The canonical step-by-step for VFX/skill packages is references/vfx-handoff-recipe.md — the owner-approved recipe (proven 2026-07-19 on the real 巫毒魂瓶 handoff: 91/100 blind score, owner-preferred). Follow it verbatim: package composition, DESIGN.md cover template, launch/kickoff wording, engine defaults, driven-video acceptance, and the handover into takeover.

Workflow

0. Branch by surface type. UI surfaces (#home/mapselect/talent/masks/fusion/victory/steam-title/HUD) follow the full preservation-contract workflow below (steps 1-9). VFX / skill / weapon / RIG / enemy / boss packages skip the preservation contract and instead follow the content standard above (claude-design-handoff-generate package + Open Design delta); their validation path is the CD checker, not the Open Design packager:

   make claude-design-check ARGS="validate-handoff .handoff/<id>.zip --kind=skill_vfx"
   

   The Open Design packager (package_open_design_handoff.mjs) hard-requires a preservation contract and a UI contract profile — it is the gate for UI handoffs only. A VFX package still carries the generation contract in od-source-manifest.json and the DARKBONE_VFX_LAB API requirement in DESIGN.md.

1. Name the affected surfaces and the player job of each surface. Copy open-design-game-ui-concept/references/darkbone-visual-language.md and exemplar-craft.html into the handoff folder, and structure DESIGN.md aspiration-first: page craft bar ("match the exemplar"), what gorgeous looks like for this surface; preservation/authority language comes after. A constraints-first brief reliably produces stiff web-dashboard output.

2. Read the live owner source. Record searchable source anchors for identity, motion, interaction, copy, and data.

3. Capture the current runtime at every target viewport and locale. Use at least two states per upgraded or redesigned surface. A genuinely new surface may use baselinePolicy: new-surface-no-runtime only under the steam-title contract profile. It must keep baselineStills empty and provide at least two real Home contextStills; this exception cannot be applied to an existing runtime surface.

4. Capture motion-critical behavior with real runtime video and timestamped keyframes. Home, Talent investment, Fusion reveal, and Victory/settlement reveal are motion-critical by default.

5. Write preservation-contract.json. For every component, assign one treatment (preserve, upgrade, redesign, or untouched) and authority for layout, identity, motion, interaction, copy, and data. Declare changeScope explicitly; it must exactly equal the axes whose authority is not runtime. Every axis outside changeScope is frozen even when the standalone omits or statically proxies it. data must remain runtime-owned. Also record standaloneMotionPolicy, runtimeMotionImplementation, and concrete runtimeOwnerAnchors. Runtime-owned motion must use placeholder-only-preserve-runtime plus reuse-existing-runtime; the standalone is showing placement, not replacement behavior.

6. List signatures that must survive, forbidden regressions, untouched details, and an executable rendered comparison plan with target viewports, locales, states, motion states, and required beats.

7. Bundle all referenced evidence inside one .handoff/<timestamp>-<feature>/ folder. Never reference an absolute local path from the contract. source-manifest.json must contain the exact non-overridable generation contract { "agentId": "codex", "model": "gpt-5.6-sol", "reasoning": "ultra", "allowOverride": false }.

8. Validate before Open Design import:

   node .agents/skills/open-design-game-ui-handoff/scripts/validate_preservation_contract.mjs \
     --contract=.handoff/<timestamp>-<feature>/preservation-contract.json
   

9. Run the parent handoff packager. It must invoke the same semantic validator; a zip that bypasses this step is not a valid handoff.

Evidence Rules

• Use the real running app, not reconstructed HTML or source inspection alone.
• Dev-server capture prerequisites (the capture gates block on console errors and broken images): index.html registers /sw.js, which is a build artifact — drop an uncommitted no-op stub at apps/game-runtime/public/sw.js before capturing against vite dev, or every scenario fails with an unsupported-MIME console error. Mask art referenced as /masks/mask-*.webp is R2-hosted — populate apps/game-runtime/public/masks/ (uncommitted) from the publicUrl entries in data/artifact-manifest.json or Home/Masks/Fusion image assertions fail.
• Store screenshots and keyframes as compressed WebP. Store motion as WebM or MP4.
• Capture setup, peak/transformation, and settled/result beats at minimum. Add interaction and recovery beats when they carry meaning.
• Record active animation names or runtime source anchors as supporting evidence, never as a substitute for video.
• Capture reduced-motion separately when the component has a reduced-motion branch.
• Keep artifacts local/gitignored unless the owner explicitly requests archival.

Rejection Conditions

Reject the handoff when any of these are true:

• darkbone-visual-language.md or exemplar-craft.html is missing from the folder, or DESIGN.md opens with constraints/authority instead of creative direction;
• a redesigned surface has fewer than two current-runtime stills;
• a motion-critical surface has no video or fewer than three timestamped keyframes;
• a component grants Open Design authority implicitly;
• changeScope is missing, broader than the assigned authority, or narrower than it;
• a layout-only task grants Open Design identity, motion, interaction, copy, or data authority;
• runtime-owned motion is not explicitly marked as a placeholder-only standalone representation backed by the existing runtime implementation;
• Home, Talent, Fusion, or Victory omits one of its known protected runtime components from the contract;
• source anchors, evidence files, must-retain signatures, or forbidden regressions are missing;
• the brief describes an existing dynamic component as disposable because the standalone cannot render it;
• the comparison plan cannot align current, standalone, and future integrated renders by viewport/state/beat.

The deliverable is a validated preservation contract plus a self-contained handoff. It is not runtime code.