| name | open-design-game-ui-handoff |
| description | Build and validate Open Design handoffs from the real Darkbone Archer runtime — game UI (upgrade-only preservation contracts) AND VFX/skill/RIG design packages. Use whenever Codex must prepare, regenerate, or audit an Open Design handoff; feed an existing Claude Design handoff zip into Open Design; collect current screenshots, animation videos, keyframes, source anchors, assets, responsive states, or preservation boundaries; or prevent a standalone concept from deleting existing identity, motion, interaction, copy, or data that it does not show. |
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
-
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.
-
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 one = identity, 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.
-
Read the live owner source. Record searchable source anchors for identity, motion, interaction, copy, and data.
-
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.
-
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.
-
Write preservation-contract.json. For every component, assign one treatment (preserve, upgrade,
redesign, or untouched) and authority for layout, , , , , and
. Declare explicitly; it must exactly equal the axes whose authority is not .
Every axis outside is frozen even when the standalone omits or statically proxies it.
must remain runtime-owned. Also record , , and concrete
. Runtime-owned motion must use plus
; the standalone is showing placement, not replacement behavior.
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.
