Storybook / Design Explorer

In-app design explorer for comparing, selecting, and adopting UI variations across prompt surfaces. Stories render real components — footer, input, header, action dialog variants — in a browsable, comparable format with persistent selection.

Key Concepts

File Map

Adding a New Story

1. •Create struct implementing Story trait in src/stories/
2. •Return stable id(), descriptive name(), category(), and surface()
3. •Implement variants() returning Vec<StoryVariant> with stable IDs
4. •Implement render_variant(&self, variant) to render each variant
5. •Register in ALL_STORIES in src/stories/mod.rs

pub struct MyStory;
impl Story for MyStory {
    fn id(&self) -> &'static str { "my-component-variations" }
    fn name(&self) -> &'static str { "My Component Variations" }
    fn category(&self) -> &'static str { "Components" }
    fn surface(&self) -> StorySurface { StorySurface::Component }
    fn variants(&self) -> Vec<StoryVariant> {
        vec![
            StoryVariant::default_named("variant-a", "Variant A"),
            StoryVariant::default_named("variant-b", "Variant B"),
        ]
    }
    fn render_variant(&self, variant: &StoryVariant) -> AnyElement {
        match variant.stable_id() {
            "variant-a" => /* render A */,
            "variant-b" => /* render B */,
            _ => self.render(),
        }
    }
}

Adding a New Variation System (Footer/Input Pattern)

Follow the footer_variations or input_variations pattern:

1. •Define an ID enum with stable_id() -> &'static str and from_stable_id()
2. •Define a declarative spec struct with design properties
3. •Create a const array of specs
4. •Implement story_variants() converting specs to StoryVariant
5. •Implement render_preview(stable_id) rendering real components
6. •Implement adopted_*_variation() reading from StorySelectionStore
7. •Add tests for unique IDs, round-trip, and resolution

CLI Usage

# Interactive browser
cargo run --bin storybook

# Pre-select story + compare mode
cargo run --bin storybook -- --story footer-layout-variations --compare

# Non-interactive adoption (JSON output, exit code 0/2)
cargo run --bin storybook -- --adopt --story footer-layout-variations --variant minimal

# Machine-readable catalog
cargo run --bin storybook -- --catalog-json

# Screenshot capture
cargo run --bin storybook -- --story footer-layout-variations --screenshot

Selection Persistence

• •File: ~/.kit/design-explorer-selections.json
• •Format: { "selections": { "<story_id>": "<variant_id>" } }
• •Atomic writes via temp file + rename
• •StorySelectionStore in selection.rs handles load/save
• •save_selected_story_variant() returns StorySelectionWriteResult with previous value

Live Adoption Wiring

Footer adoption: config_from_storybook_footer_selection() reads persisted selection, resolves via resolve_footer_selection_spec(), falls back to RaycastExact.

Input adoption: adopted_input_variation() reads persisted selection, falls back to Bare.

Both are called at render time in live prompt surfaces.

Surface Wiring Map

Use this map before claiming that a Storybook edit changes the real app.

Rule of thumb:

• •src/storybook/... only: usually Storybook-only
• •Shared presenter/component/theme code: affects both
• •Adopted variation/spec code: can affect live surfaces that read that selection

Chrome Audit System

PromptChromeAudit in prompt_layout_shell.rs validates minimal chrome compliance:

• •PromptChromeAudit::minimal(...) for standard surfaces
• •PromptChromeAudit::exception(surface, reason) for rich-chrome exceptions
• •emit_prompt_chrome_audit() logs once per unique audit (deduped via HashSet)
• •Warns if a non-exception surface uses prompt_footer mode

Testing

cargo test footer          # Footer adoption + resolution
cargo test storybook       # Browser, catalog, errors
cargo test chrome_audit    # Audit dedup + emission
cargo test source_audit    # Minimal chrome compliance
cargo test input_variation # Input adoption + resolution

References

• •references/architecture.md — Detailed type definitions, browser state, rendering pipeline, keyboard shortcuts