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.

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