0
# Configuration System
1

2
Comprehensive configuration options for customizing the addon behavior, including tab management, search functionality, pagination, style injection, and presenter customization. Configure at story, global, or component level.
3

4
## Capabilities
5

6
### Story-Level Configuration
7

8
Configure addon behavior for individual stories using the `designToken` parameter key in story parameters.
9

10
```typescript { .api }
11
interface StoryParameters {
12
  /** Design token addon configuration */
13
  designToken?: Config;
14
}
15

16
interface Config {
17
  /** Enable/disable search functionality (default: true) */
18
  showSearch?: boolean;
19
  /** Default selected tab name */
20
  defaultTab?: string;
21
  /** Custom CSS injection for styling */
22
  styleInjection?: string;
23
  /** Number of items displayed per page */
24
  pageSize?: number;
25
  /** Custom presenter component overrides */
26
  presenters?: PresenterMapType;
27
  /** Filter visible tabs by name */
28
  tabs?: string[];
29
}
30
```
31

32
**Usage Examples:**
33

34
```typescript
35
// Individual story configuration
36
export const ColorTokens = {
37
  name: "Color Tokens",
38
  parameters: {
39
    designToken: {
40
      showSearch: true,
41
      defaultTab: "Colors",
42
      pageSize: 20,
43
      tabs: ["Colors", "Gradients"],
44
      styleInjection: `
45
        .design-token-container {
46
          background: #f8f9fa;
47
          padding: 16px;
48
          border-radius: 8px;
49
        }
50
      `
51
    }
52
  }
53
};
54

55
// Story with custom presenters
56
export const TypographyTokens = {
57
  name: "Typography",
58
  parameters: {
59
    designToken: {
60
      defaultTab: "Typography",
61
      presenters: {
62
        "FontSize": CustomFontSizePresenter,
63
        "FontWeight": CustomFontWeightPresenter
64
      },
65
      styleInjection: `
66
        .token-preview { font-family: 'Inter', sans-serif; }
67
      `
68
    }
69
  }
70
};
71
```
72

73
### Global Configuration
74

75
Set default configuration for all stories in your Storybook using the preview.js file.
76

77
```typescript { .api }
78
interface PreviewParameters {
79
  designToken?: Config;
80
}
81
```
82

83
**Usage Examples:**
84

85
```typescript
86
// .storybook/preview.js
87
export default {
88
  parameters: {
89
    designToken: {
90
      showSearch: true,
91
      pageSize: 15,
92
      styleInjection: `
93
        :root {
94
          --token-border-color: #e1e5e9;
95
          --token-text-color: #333;
96
        }
97
        .design-token-card {
98
          border-color: var(--token-border-color);
99
          color: var(--token-text-color);
100
        }
101
      `,
102
      presenters: {
103
        "Color": GlobalCustomColorPresenter
104
      }
105
    }
106
  }
107
};
108

109
// TypeScript version (.storybook/preview.ts)
110
import type { Preview } from '@storybook/react';
111

112
const preview: Preview = {
113
  parameters: {
114
    designToken: {
115
      showSearch: true,
116
      defaultTab: "Colors",
117
      pageSize: 12,
118
      tabs: ["Colors", "Typography", "Spacing", "Shadows"]
119
    }
120
  }
121
};
122

123
export default preview;
124
```
125

126
### Component-Level Configuration
127

128
Configure individual DesignTokenDocBlock components with specific options.
129

130
```typescript { .api }
131
interface DesignTokenDocBlockProps {
132
  categoryName: string;
133
  maxHeight?: number;
134
  showValueColumn?: boolean;
135
  viewType: TokenViewType;
136
  filterNames?: string[];
137
  usageMap?: Record<string, string[]>;
138
  theme?: string;
139
  showSearch?: boolean;
140
  pageSize?: number;
141
  presenters?: PresenterMapType;
142
}
143
```
144

145
**Usage Examples:**
146

147
```typescript
148
import { DesignTokenDocBlock } from "storybook-design-token";
149

150
// Component with full configuration
151
<DesignTokenDocBlock
152
  categoryName="Spacing"
153
  maxHeight={600}
154
  showValueColumn={true}
155
  viewType="table"
156
  showSearch={false}
157
  pageSize={10}
158
  theme="dark"
159
  filterNames={["small", "medium", "large"]}
160
  usageMap={{
161
    "spacing-sm": ["margin: var(--spacing-sm)", "padding: var(--spacing-sm)"],
162
    "spacing-md": ["gap: var(--spacing-md)", "margin-bottom: var(--spacing-md)"]
163
  }}
164
  presenters={{
165
    "Spacing": CustomSpacingPresenter
166
  }}
167
/>
168
```
169

170
### Configuration Options Reference
171

172
#### Search Configuration
173

174
```typescript { .api }
175
interface SearchConfig {
176
  /** Enable search input field */
177
  showSearch?: boolean;
178
}
179
```
180

181
Configure search functionality to allow users to filter tokens by name or value.
182

183
**Examples:**
184

185
```typescript
186
// Disable search for simple token sets
187
{ showSearch: false }
188

189
// Enable search with custom styling
190
{ 
191
  showSearch: true,
192
  styleInjection: `
193
    .search-field input {
194
      border-radius: 6px;
195
      border: 2px solid #007acc;
196
    }
197
  `
198
}
199
```
200

201
#### Tab Management
202

203
```typescript { .api }
204
interface TabConfig {
205
  /** Default selected tab */
206
  defaultTab?: string;
207
  /** Filter visible tabs */
208
  tabs?: string[];
209
}
210
```
211

212
Control which token categories are visible and which tab is selected by default.
213

214
**Examples:**
215

216
```typescript
217
// Show only specific tabs
218
{
219
  tabs: ["Colors", "Typography", "Spacing"],
220
  defaultTab: "Colors"
221
}
222

223
// Show all tabs with specific default
224
{
225
  defaultTab: "Typography"
226
}
227
```
228

229
#### Pagination Configuration
230

231
```typescript { .api }
232
interface PaginationConfig {
233
  /** Items per page */
234
  pageSize?: number;
235
}
236
```
237

238
Control how many tokens are displayed per page in card view mode.
239

240
**Examples:**
241

242
```typescript
243
// Large page size for comprehensive view
244
{ pageSize: 50 }
245

246
// Small page size for focused view
247
{ pageSize: 8 }
248
```
249

250
#### Style Injection
251

252
```typescript { .api }
253
interface StyleConfig {
254
  /** Custom CSS injection */
255
  styleInjection?: string;
256
}
257
```
258

259
Inject custom CSS to override default styling or add theme-specific styles.
260

261
**Examples:**
262

263
```typescript
264
{
265
  styleInjection: `
266
    .design-token-container {
267
      --primary-color: #007acc;
268
      --border-radius: 8px;
269
      --shadow: 0 2px 8px rgba(0,0,0,0.1);
270
    }
271
    
272
    .design-token-card {
273
      border-radius: var(--border-radius);
274
      box-shadow: var(--shadow);
275
    }
276
    
277
    .token-name {
278
      color: var(--primary-color);
279
      font-weight: 600;
280
    }
281
    
282
    /* Dark theme overrides */
283
    .dark-theme .design-token-container {
284
      background: #1a1a1a;
285
      color: #ffffff;
286
    }
287
  `
288
}
289
```
290

291
#### Presenter Customization
292

293
```typescript { .api }
294
interface PresenterConfig {
295
  /** Custom presenter components */
296
  presenters?: PresenterMapType;
297
}
298

299
interface PresenterMapType {
300
  [key: string]: React.FunctionComponent<PresenterProps> | React.ComponentClass<PresenterProps>;
301
}
302
```
303

304
Override built-in presenters or add custom ones for specialized token types.
305

306
**Examples:**
307

308
```typescript
309
{
310
  presenters: {
311
    // Override built-in color presenter
312
    "Color": MyCustomColorPresenter,
313
    
314
    // Add custom presenter for new token type
315
    "Elevation": ElevationPresenter,
316
    
317
    // Override multiple presenters
318
    "FontSize": BrandedFontSizePresenter,
319
    "Spacing": MetricSpacingPresenter
320
  }
321
}
322
```
323

324
### Configuration Priority
325

326
Configuration is applied in the following order (later overrides earlier):
327

328
1. Built-in defaults
329
2. Global configuration (preview.js)
330
3. Story-level configuration (story parameters)
331
4. Component-level configuration (props)
332

333
**Example Priority Resolution:**
334

335
```typescript
336
// Built-in defaults
337
{ showSearch: true, pageSize: 10 }
338

339
// Global config (preview.js)
340
{ showSearch: false, pageSize: 20, defaultTab: "Colors" }
341

342
// Story config
343
{ pageSize: 15, tabs: ["Colors", "Typography"] }
344

345
// Component props
346
{ showSearch: true }
347

348
// Final resolved config:
349
{
350
  showSearch: true,    // from component props
351
  pageSize: 15,        // from story config
352
  defaultTab: "Colors", // from global config
353
  tabs: ["Colors", "Typography"] // from story config
354
}
355
```