# ux-and-i/storybook-design-token architecture

> Architecture diagram of the GitHub repository ux-and-i/storybook-design-token, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-06-02). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/ux-and-i/storybook-design-token
- Repository: https://github.com/ux-and-i/storybook-design-token

## Overview

##### File Structure Analysis
- Top-level files: README, LICENSE, config files (.gitignore, .prettierrc, tsconfig.json, vite.config.ts).
- “addon/”: All source code for the Storybook addon lives here.
- src/hooks/: custom React hooks for token filtering, tabs, search.
- src/components/: React UI components (Panel, TokenCards, TokenTable, presenters).
- src/plugin.ts, manager.ts, preview.ts: Storybook integration points.
- stories/, demo/: sample usage and docs accompanying the addon.
- Build configs: tsup.config.ts, tsup.node.config.ts.
- Storybook config in “addon/.storybook”: local presets for development.

##### Key README Insights
- The addon registers itself in Storybook via manager.js and preview.js.
- It parses annotated CSS/SCSS/LESS and SVG files at build time or runtime.
- Provides two surfaces: an “Addon Panel” (UI sidebar) and “DesignTokenDocBlock” (for MDX).
- Configuration via `.storybook/main.js` and `parameters.designToken`.

a. Main Components
- File Ingestion Layer
– CSS/SCSS/LESS files
- Parser Modules
– postcss.parser
– image.parser
- Token Store & API
– Internal data structure holding parsed tokens, categories, presenters
– Exposed via Storybook addon channel
- Storybook Addon Manager (manager.js)
– Registers addon panel tab
- Storybook Preview (preview.js)
– Injects runtime code, styleInjection, parameters
- React UI Surface
– Panel.tsx (sidebar panel)
– DesignTokenDocBlock (MDX doc block)
– Presenters (ColorPresenter, BorderPresenter, etc.)
- Custom Hooks (useTokenSearch, useFilteredTokens, etc.)
- Build & Bundler (tsup, Vite)
b. Interactions
1. At build time or Storybook startup, parser modules scan files (glob) → extract tokens
2. Parsed tokens → populate Token Store → exposed via Storybook’s channel API
3. In manager.js, a panel is registered; in preview.js, parameters are read
4. User opens Storybook UI → Panel component subscribes to channel → renders tabs, search, and card/table view using components and hooks
5. When a user uses DesignTokenDocBlock in MDX, it pulls from the same Token Store and renders an isolated block
c. Architectural Patterns
- Modular parsers (Strategy Pattern): each parser handles one file type
- Pub/Sub via Storybook channel for communication between manager, preview, and UI
- React component library for UI, custom hooks for state management
- Build-time code splitting and bundling via tsup + Vite config
d. Key Technologies & Libraries
- Storybook Addon API (manager.js, preview.js, plugin.ts)
- React + JSX/TSX for UI components
- postcss for CSS parsing
- TypeScript for type safety
- tsup for bundling
- Vite for local dev (`addon/vite.config.ts`)

##### Essential Elements
- Clear labels for each component and sub-module.
- Parsers vs. State vs. UI vs. Build Tools.
- Notes on configuration overrides (styleInjection, tabs, defaultTab, preserveCSSVars).

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "File Ingestion Layer"
        direction TB
        IngressCSS["CSS/SCSS/LESS Files"]:::ingestion
        IngressSVG["SVG Icon Files"]:::ingestion
    end

    subgraph "Parser Modules"
        direction TB
        P1["postcss.parser"]:::ingestion
        P2["svg-icon.parser"]:::ingestion
        P3["image.parser"]:::ingestion
    end

    subgraph "Token Store & API"
        direction TB
        TS["Token Store & API"]:::store
        Plugin["plugin.ts / index.ts"]:::store
    end

    subgraph "Storybook Integration"
        direction TB
        Manager["manager.js / src/manager.ts"]:::integration
        Preview["preview.js / src/preview.ts"]:::integration
    end

    subgraph "React UI Surface"
        direction TB
        Panel["Panel.tsx"]:::ui
        DocBlock["DesignTokenDocBlock.tsx"]:::ui

        subgraph "Components"
            direction TB
            Tabs["TokenTab.tsx"]:::ui
            Cards["TokenCards.tsx"]:::ui
            Table["TokenTable.tsx"]:::ui
        end

        subgraph "Presenters"
            direction TB
            AP["AnimationPresenter.tsx"]:::ui
            BP["BorderPresenter.tsx"]:::ui
            BRP["BorderRadiusPresenter.tsx"]:::ui
            CP["ColorPresenter.tsx"]:::ui
            EP["EasingPresenter.tsx"]:::ui
            EmP["EmptyPresenter.tsx"]:::ui
            FP["FontFamilyPresenter.tsx"]:::ui
            FSP["FontSizePresenter.tsx"]:::ui
            FWP["FontWeightPresenter.tsx"]:::ui
            IP["ImagePresenter.tsx"]:::ui
            LSP["LetterSpacingPresenter.tsx"]:::ui
            LHP["LineHeightPresenter.tsx"]:::ui
            OP["OpacityPresenter.tsx"]:::ui
            SP["ShadowPresenter.tsx"]:::ui
            SPP["SpacingPresenter.tsx"]:::ui
            SVGP["SvgPresenter.tsx"]:::ui
        end

        subgraph "Custom Hooks"
            direction TB
            HS["useTokenSearch.ts"]:::ui
            HF["useFilteredTokens.ts"]:::ui
            HT["useTokenTabs.ts"]:::ui
            HD["useDebounce.ts"]:::ui
        end
    end

    subgraph "Build & Bundler"
        direction TB
        TSup["tsup.config.ts / tsup.node.config.ts"]:::build
        Vite["vite.config.ts"]:::build
    end

    IngressCSS -->|"parse → emit tokens"| P1
    IngressSVG -->|"parse → emit tokens"| P2
    IngressSVG -->|"load images"| P3
    P1 -->|"tokens"| TS
    P2 -->|"tokens"| TS
    P3 -->|"tokens"| TS
    Plugin -->|"initialize store"| TS
    TS -->|"expose via channel"| Manager
    TS -->|"expose via channel"| Preview
    Manager -->|"register panel"| Panel
    Preview -->|"inject runtime"| Panel
    Preview -->|"inject runtime"| DocBlock
    Panel -->|"renders"| Tabs
    Panel -->|"renders"| Cards
    Panel -->|"renders"| Table
    Panel -->|"uses presenters"| AP & BP & BRP & CP & EP & EmP & FP & FSP & FWP & IP & LSP & LHP & OP & SP & SPP & SVGP
    Panel -->|"uses hooks"| HS & HF & HT & HD
    DocBlock -->|"uses presenters"| AP & BP & BRP & CP & EP & EmP & FP & FSP & FWP & IP & LSP & LHP & OP & SP & SPP & SVGP
    DocBlock -->|"uses hooks"| HS & HF & HT & HD
    TSup -->|"bundle code"| Plugin
    Vite -->|"dev server"| Plugin

    click P1 "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/parsers/postcss.parser.ts"
    click P2 "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/parsers/svg-icon.parser.ts"
    click P3 "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/parsers/image.parser.ts"
    click Plugin "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/plugin.ts"
    click TS "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/index.ts"
    click Manager "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/manager.js"
    click Manager "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/manager.ts"
    click Preview "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/preview.js"
    click Preview "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/preview.ts"
    click Panel "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/Panel.tsx"
    click DocBlock "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/DesignTokenDocBlock.tsx"
    click AP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/AnimationPresenter.tsx"
    click BP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/BorderPresenter.tsx"
    click BRP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/BorderRadiusPresenter.tsx"
    click CP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/ColorPresenter.tsx"
    click EP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/EasingPresenter.tsx"
    click EmP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/EmptyPresenter.tsx"
    click FP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/FontFamilyPresenter.tsx"
    click FSP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/FontSizePresenter.tsx"
    click FWP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/FontWeightPresenter.tsx"
    click IP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/ImagePresenter.tsx"
    click LSP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/LetterSpacingPresenter.tsx"
    click LHP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/LineHeightPresenter.tsx"
    click OP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/OpacityPresenter.tsx"
    click SP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/ShadowPresenter.tsx"
    click SPP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/SpacingPresenter.tsx"
    click SVGP "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/components/presenter/SvgPresenter.tsx"
    click HS "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/hooks/useTokenSearch.ts"
    click HF "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/hooks/useFilteredTokens.ts"
    click HT "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/hooks/useTokenTabs.ts"
    click HD "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/src/hooks/useDebounce.ts"
    click TSup "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/tsup.config.ts"
    click TSup "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/tsup.node.config.ts"
    click Vite "https://github.com/ux-and-i/storybook-design-token/blob/master/addon/vite.config.ts"

    classDef ingestion fill:#D0E6FF,stroke:#4A90E2,color:#000
    classDef store fill:#DBF6DB,stroke:#3C763D,color:#000
    classDef integration fill:#FFE8CC,stroke:#C47A00,color:#000
    classDef ui fill:#F3E6FF,stroke:#8E44AD,color:#000
    classDef build fill:#ECECEC,stroke:#888,color:#000
```
