Centralized Documentation Hub (apps/histoire)

The core idea is to strictly separate your development libraries and design tokens from your documentation tooling. By creating a single, dedicated application (apps/histoire), you build a unified showcase for your entire monorepo—handling both interactive components and pre-built static assets.

Architecture Overview

• apps/histoire (The Hub): A dedicated workspace application. It exclusively houses the Histoire dependencies, global configuration, development server, and specific wrapper stories (like an iframe container).
• packages/ui-* (The Component Libraries): Your ui-core and ui-domain packages remain "pure." They contain only their source code, runtime dependencies, and colocated .story.vue files.
• packages/config-tailwind (The Design Tokens): Manages its own build process and outputs a static preview/ folder (index.html, style.css).

The Mechanism

1. Colocated Authoring: Developers write and maintain Vue stories directly next to the source components inside the packages/ui-* directories.
2. Cross-Package Scanning: The hub is configured to traverse the monorepo, scoop up any .story.vue files it finds in the UI packages, and dynamically import them.
3. Static Serving & Embedding: The hub serves the pre-built config-tailwind/preview folder as a static asset. A dedicated story inside the hub embeds this index.html via an iframe.
4. Unified Aggregation: When you run the hub, it seamlessly aggregates the interactive Vue components and the static Tailwind design tokens into a single, cohesive interactive dashboard.

Core Benefits

• Zero Tooling Sprawl: You maintain exactly one Histoire configuration, one theme, and one set of dev dependencies for the entire ecosystem.
• Clean Packages: Your UI and config packages remain lean, ensuring they aren't bloated with documentation tooling when consumed or built.
• Global Visibility: You get a single, holistic dashboard to view, test, and interact with every layer of your design system—from static base tokens to complex domain components.

---

Story Authoring Guide

Theme scopes are defined in config-tailwind. For the architectural reasoning see design-system architecture.

Side-by-Side Variants (Recommended)

Render all three environments simultaneously so changes in ui-core are instantly visible across all contexts:

<script setup>
import { Button } from '@busflow/ui-core'
</script>

<template>
  <Story title="Core/Button">
    <Variant title="Passenger (B2C)">
      <div class="theme-passenger bg-background text-foreground p-8 min-h-[200px]">
        <Button>Book Ticket</Button>
      </div>
    </Variant>

    <Variant title="Dispatcher (B2B)">
      <div class="theme-dispatcher bg-background text-foreground p-8 min-h-[200px]">
        <Button>Assign Driver</Button>
      </div>
    </Variant>

    <Variant title="Driver (Mobile Cockpit)">
      <div class="theme-driver dark bg-background text-foreground p-8 min-h-[200px]">
        <Button>Complete Route</Button>
      </div>
    </Variant>
  </Story>
</template>

Apply bg-background text-foreground to the wrapper div so the canvas adopts the theme's root colors for an accurate preview.

Global Theme Toggle (For interactive testing)

For complex domain components (e.g., <ScheduleTimeline>), use a global wrapper that dynamically flips the theme for the entire canvas. Register a ThemeWrapper.vue component in the Histoire setup file that provides a <select> toggle between the three scopes.

Regression Testing Rules

• Altering base logic in ui-core must be visually verified across all three variants before merging.
• Ensure contrast ratios hold (especially for .theme-driver night-mode backgrounds).
• Test both dark and light mode via the Histoire toolbar toggle.