How ux-and-i/storybook-design-token works
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).