0
# Storybook Design Token
1

2
Storybook Design Token is a comprehensive addon that enables teams to display design token documentation directly within Storybook, parsing stylesheets (CSS, SCSS, LESS) and icon files to automatically generate visual design token previews. It provides multiple presentation modes including animations, colors, borders, typography, spacing, and shadows with customizable presenters and filtering capabilities.
3

4
## Package Information
5

6
- **Package Name**: storybook-design-token
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install storybook-design-token`
10

11
## Core Imports
12

13
```typescript
14
import { DesignTokenDocBlock } from "storybook-design-token";
15
```
16

17
For doc blocks specifically:
18

19
```typescript
20
import { DesignTokenDocBlock } from "storybook-design-token/doc-blocks";
21
```
22

23
CommonJS:
24

25
```javascript
26
const { DesignTokenDocBlock } = require("storybook-design-token");
27
```
28

29
## Basic Usage
30

31
```typescript
32
import { DesignTokenDocBlock } from "storybook-design-token";
33

34
// Embed in Storybook docs page
35
export default {
36
  title: "Design System/Tokens",
37
  parameters: {
38
    docs: { 
39
      page: () => (
40
        <DesignTokenDocBlock
41
          categoryName="Colors"
42
          viewType="table"
43
          showSearch={true}
44
        />
45
      )
46
    }
47
  }
48
};
49

50
// Use in story with custom configuration
51
export const TokenPreview = {
52
  parameters: {
53
    designToken: {
54
      showSearch: true,
55
      defaultTab: "Colors",
56
      pageSize: 10,
57
      tabs: ["Colors", "Typography", "Spacing"]
58
    }
59
  }
60
};
61
```
62

63
## Architecture
64

65
Storybook Design Token is built around several key components:
66

67
- **Storybook Integration**: Seamless addon panel and doc block integration using Storybook's official APIs
68
- **File Parser System**: Automatic token extraction from CSS, SCSS, LESS, SVG, and image files using glob patterns
69
- **Presenter System**: 15 built-in visual presenters for different design token types with extensibility for custom presenters
70
- **Configuration System**: Flexible options for tabs, search, pagination, and custom styling
71
- **Type System**: Complete TypeScript support with interfaces for Token, Category, and configuration options
72
- **Build Integration**: Support for both Webpack and Vite build systems through dedicated plugins
73

74
## Capabilities
75

76
### Doc Block Components
77

78
Embeddable React components for displaying design tokens in Storybook documentation pages and stories. Perfect for design system documentation and token showcases.
79

80
```typescript { .api }
81
function DesignTokenDocBlock(props: DesignTokenDocBlockProps): JSX.Element;
82

83
interface DesignTokenDocBlockProps {
84
  categoryName: string;
85
  maxHeight?: number;
86
  showValueColumn?: boolean;
87
  viewType: TokenViewType;
88
  filterNames?: string[];
89
  usageMap?: Record<string, string[]>;
90
  theme?: string;
91
  showSearch?: boolean;
92
  pageSize?: number;
93
  presenters?: PresenterMapType;
94
}
95

96
type TokenViewType = "table" | "card";
97
```
98

99
[Doc Block Components](./doc-blocks.md)
100

101
### Token Presenters
102

103
Visual presentation components for different types of design tokens including colors, typography, spacing, animations, and more. Supports both built-in presenters and custom presenter extensions.
104

105
```typescript { .api }
106
function TokenPreview(props: TokenPreviewProps): JSX.Element;
107

108
interface TokenPreviewProps {
109
  token: Token;
110
  presenters?: PresenterMapType;
111
}
112

113
interface PresenterMapType {
114
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
115
}
116

117
interface PresenterProps {
118
  token: Token;
119
}
120
```
121

122
[Token Presenters](./presenters.md)
123

124
### Configuration System
125

126
Comprehensive configuration options for customizing the addon behavior, including tab management, search functionality, pagination, and style injection.
127

128
```typescript { .api }
129
interface Config {
130
  showSearch?: boolean;
131
  defaultTab?: string;
132
  styleInjection?: string;
133
  pageSize?: number;
134
  presenters?: PresenterMapType;
135
  tabs?: string[];
136
}
137
```
138

139
[Configuration System](./configuration.md)
140

141
### Build System Integration
142

143
Webpack and Vite plugins for automatic design token file discovery and processing during the build process.
144

145
```typescript { .api }
146
function managerEntries(entry?: any[]): any[];
147
function viteFinal(viteConfig: Record<string, any>, options: any): Promise<Record<string, any>>;
148
function webpackFinal(config: any, options: AddonOptions): Promise<any>;
149
```
150

151
[Build System Integration](./build-integration.md)
152

153
## Core Types
154

155
```typescript { .api }
156
interface Token {
157
  name: string;
158
  value: string;
159
  rawValue: string;
160
  description?: string;
161
  isAlias?: boolean;
162
  categoryName?: string;
163
  presenter?: TokenPresenter;
164
  sourceType: TokenSourceType;
165
  sourcePath: string;
166
}
167

168
interface Category {
169
  name: string;
170
  tokens: Token[];
171
  presenter?: TokenPresenter;
172
  range?: CategoryRange;
173
  source?: string;
174
}
175

176
interface Tab {
177
  label: string;
178
  categories: Category[];
179
}
180

181
enum TokenPresenter {
182
  ANIMATION = "Animation",
183
  BORDER = "Border",
184
  BORDER_RADIUS = "BorderRadius",
185
  COLOR = "Color",
186
  EASING = "Easing",
187
  FONT_FAMILY = "FontFamily",
188
  FONT_SIZE = "FontSize",
189
  FONT_WEIGHT = "FontWeight",
190
  LINE_HEIGHT = "LineHeight",
191
  LETTER_SPACING = "LetterSpacing",
192
  OPACITY = "Opacity",
193
  SHADOW = "Shadow",
194
  SPACING = "Spacing",
195
  SVG = "Svg",
196
  IMAGE = "Image"
197
}
198

199
enum TokenSourceType {
200
  CSS = "CSS",
201
  LESS = "Less",
202
  SCSS = "SCSS",
203
  SVG = "SVG",
204
  THEO = "THEO",
205
  IMAGE = "IMAGE"
206
}
207
```