Dune Zone Storybook content and isolation boundary

storybook-content-and-isolation-boundary.md

Dune Zone Storybook content and isolation boundary

Status

Accepted planning decision for Choose the public Storybook content and isolation boundary. This supersedes the earlier repair-all-364 decision.

Domain language

• Capability story: an intentionally authored Storybook example that demonstrates a meaningful use case, visual mode, composition, or interaction of a reusable component.
• Legacy capture specimen: a story whose purpose was to instantiate one concrete game asset for the retired image-generation pipeline. It is not evidence that the underlying component is defunct.
• Source asset: a checked-in primitive under the shared /image/** or /vector/** namespaces that may participate in a live component composition.
• Generated output: terminal bytes produced by browser capture. Generated output may never become an input to another rendered component or asset.
• Isolated story: a story using the real component with deliberately authored local fixtures and mocks, without database, authentication, or other live-service access.

Catalogue boundary

The existing Storybook is already mostly organized around reusable components. Preserve that structure by default and target the legacy per-output clusters rather than redesigning the whole catalogue.

• Keep the reusable renderer components.
• Completely overhaul affected stories instead of deleting components merely because their capture specimens are obsolete.
• Organize navigation around component capabilities, not the historical generated-output hierarchy.
• Consolidate per-output families such as weapon, defense, unique-card, token, and named-background specimens into the owning component's story module.
• A concrete-asset story remains only when it communicates a materially distinct component use case. A different data instance alone is not a distinct capability.
• Prefer several intentionally authored, named use cases per component. Every story also exposes useful controls, but controls are secondary to the authored examples and there is no special Playground story.
• Aim for a strong representative showcase, not a percentage coverage target or exhaustive state/permutation matrix.
• Prefer a few real game examples when they communicate the component well. Use synthetic fixtures for useful boundary cases. Do not enumerate the complete game inventory.
• For example, Background should demonstrate capabilities such as color layering, linear and radial gradients, texture influence, inversion, and striped treatment rather than publishing one sidebar entry per named background.

Strict source-schema migration

/generated/** no longer exists and is forbidden throughout repository source, including indexed stories, excluded stories, component TSX, and CSS.

• Use one canonical Background schema everywhere: application data, renderer components, fixtures, and stories. Remove the duplicate legacy definition.
• Migrate composited background inputs such as card heads, card backs, icon grounds, and token backgrounds from image/CSS strings to the canonical structured Background value rendered through the shared background renderer.
• Make component APIs schema-only in one step. Do not accept a compatibility union of structured backgrounds and legacy strings.
• Restrict the background texture primitive to the checked-in source texture catalogue so external URLs, /generated/**, and nonexistent texture paths fail validation.
• Primitive static artwork may still use the shared /image/** and /vector/** namespaces.
• Generated output is terminal. No renderer component, story, CSS rule, rulebook composition, or other source module may consume it as input.

Runtime isolation

Production Storybook is public even though its primary use is internal component development.

• Storybook is disconnected from the database and authentication, and from every other live data service.
• Stories use deliberately authored deterministic fixtures chosen to best demonstrate the component. They never copy production users, private factions, sessions, credentials, or signed-in state.
• Retain the proven global manual mocks for convex/react and convex/browser. Connected components may render normally, while each story configures fixture-backed query, mutation, or action behavior. Unmocked Convex APIs fail immediately rather than falling through to the real client.
• Prototype evidence: commit 719971e5e23b7a3f43234d02fcf41a94fe23f9f2.
• Share same-origin /font/**, /image/**, and /vector/** resources with the application so both surfaces use the same URLs and browser cache entries.
• Storybook-owned build resources remain under /__storybook/**.
• Removing redundant copied static directories from the assembled Storybook artifact is an optional downstream deployment-size optimization; runtime use of the shared root URLs is mandatory.

Migration verification

During this overhaul, build the static Storybook, read its generated index.json, and open the resulting intentional stories in a real browser to verify that the migrated catalogue works well.

Verify that:

• affected stories render their intended use cases;
• controls are available and useful;
• there are no runtime or console errors;
• there are no missing static resources;
• there are no /generated/** requests;
• no database, authentication, Convex deployment, or other live backend is contacted.

This exhaustive browser sweep is a temporary migration tool, not a permanent per-commit requirement. Do not preserve the count of 364, introduce a second inventory manifest, or reproduce the legacy output hierarchy. Exact ongoing release automation remains a downstream release-contract decision.

Consequences

This is a deliberate component and story migration, not a story-exclusion exercise. It may require changing renderer component APIs and all their callers before the static Storybook can ship. The corrected boundary unblocks the assembly and route contract without pretending the current Storybook index is already production-ready.