0
# Build System Integration
1

2
Webpack and Vite plugins for automatic design token file discovery and processing during the build process. The addon integrates seamlessly with both build systems to parse design token files and make them available at runtime.
3

4
## Capabilities
5

6
### Storybook Preset Integration
7

8
The addon provides preset functions that automatically configure the build system when added to your Storybook configuration.
9

10
```typescript { .api }
11
/**
12
 * Registers manager entry points for the addon
13
 * @param entry - Existing entry points array
14
 * @returns Updated entry points including addon manager
15
 */
16
function managerEntries(entry?: any[]): any[];
17

18
/**
19
 * Configures Vite build system with design token plugin
20
 * @param viteConfig - Existing Vite configuration
21
 * @param options - Addon configuration options
22
 * @returns Updated Vite configuration with token processing
23
 */
24
function viteFinal(
25
  viteConfig: Record<string, any>, 
26
  options: any
27
): Promise<Record<string, any>>;
28

29
/**
30
 * Configures Webpack build system with design token plugin
31
 * @param config - Existing Webpack configuration
32
 * @param options - Addon configuration options
33
 * @returns Updated Webpack configuration with token processing
34
 */
35
function webpackFinal(
36
  config: any, 
37
  options: AddonOptions
38
): Promise<any>;
39

40
interface AddonOptions {
41
  /** Glob pattern for design token files */
42
  designTokenGlob?: string;
43
  /** Storybook presets instance */
44
  presets: any;
45
}
46
```
47

48
**Usage Examples:**
49

50
```typescript
51
// .storybook/main.js
52
module.exports = {
53
  addons: [
54
    {
55
      name: "storybook-design-token",
56
      options: {
57
        designTokenGlob: "src/tokens/**/*.{css,scss,svg,png}"
58
      }
59
    }
60
  ]
61
};
62

63
// .storybook/main.ts (TypeScript)
64
import type { StorybookConfig } from '@storybook/react-vite';
65

66
const config: StorybookConfig = {
67
  addons: [
68
    {
69
      name: "storybook-design-token",
70
      options: {
71
        designTokenGlob: "**/*.{css,scss,less,svg,png,jpeg,gif}"
72
      }
73
    }
74
  ]
75
};
76

77
export default config;
78
```
79

80
### Webpack Plugin
81

82
Direct Webpack plugin integration for advanced build configurations and custom setups.
83

84
```typescript { .api }
85
/**
86
 * Webpack plugin class for design token processing
87
 */
88
class StorybookDesignTokenPlugin {
89
  constructor(designTokenGlob?: string);
90
  apply(compiler: any): void;
91
}
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
// webpack.config.js
98
const { StorybookDesignTokenPlugin } = require("storybook-design-token/plugin");
99

100
module.exports = {
101
  plugins: [
102
    new StorybookDesignTokenPlugin("src/design-system/**/*.{css,scss,svg}")
103
  ]
104
};
105

106
// Custom Storybook webpack configuration
107
// .storybook/main.js
108
module.exports = {
109
  webpackFinal: async (config) => {
110
    config.plugins.push(
111
      new StorybookDesignTokenPlugin("tokens/**/*.{css,scss,less}")
112
    );
113
    return config;
114
  }
115
};
116
```
117

118
### Vite Plugin
119

120
Direct Vite plugin integration for Vite-based Storybook configurations.
121

122
```typescript { .api }
123
/**
124
 * Vite plugin function for design token processing
125
 * @param options - Plugin configuration options
126
 * @returns Vite plugin configuration
127
 */
128
function viteStorybookDesignTokenPlugin(options?: any): any;
129
```
130

131
**Usage Examples:**
132

133
```typescript
134
// vite.config.js
135
import { viteStorybookDesignTokenPlugin } from "storybook-design-token/plugin";
136

137
export default {
138
  plugins: [
139
    viteStorybookDesignTokenPlugin({
140
      designTokenGlob: "src/tokens/**/*.{css,scss,svg,png}"
141
    })
142
  ]
143
};
144

145
// Custom Storybook Vite configuration
146
// .storybook/main.ts
147
import type { StorybookConfig } from '@storybook/react-vite';
148

149
const config: StorybookConfig = {
150
  viteFinal: async (config) => {
151
    config.plugins = config.plugins || [];
152
    config.plugins.push(
153
      viteStorybookDesignTokenPlugin({
154
        designTokenGlob: "design-system/**/*.{css,scss,less,svg}"
155
      })
156
    );
157
    return config;
158
  }
159
};
160

161
export default config;
162
```
163

164
### File Pattern Configuration
165

166
Configure which files are processed for design tokens using glob patterns and environment variables.
167

168
```typescript { .api }
169
interface FilePatternConfig {
170
  /** Glob pattern for design token files */
171
  designTokenGlob?: string;
172
}
173
```
174

175
The plugin uses the following pattern resolution priority:
176

177
1. `designTokenGlob` option passed to plugin
178
2. `DESIGN_TOKEN_GLOB` environment variable
179
3. Default pattern: `"**/*.{css,scss,less,svg,png,jpeg,gif}"`
180

181
**Usage Examples:**
182

183
```typescript
184
// Environment variable configuration
185
// .env
186
DESIGN_TOKEN_GLOB=src/design-system/**/*.{css,scss}
187

188
// Package.json scripts
189
{
190
  "scripts": {
191
    "storybook": "DESIGN_TOKEN_GLOB='tokens/**/*.css' storybook dev -p 6006"
192
  }
193
}
194

195
// Multiple pattern examples
196
{
197
  designTokenGlob: "src/tokens/**/*.{css,scss,less}" // CSS variants only
198
}
199

200
{
201
  designTokenGlob: "assets/icons/**/*.svg" // SVG icons only
202
}
203

204
{
205
  designTokenGlob: "{src/tokens,assets/icons}/**/*.{css,scss,svg}" // Multiple directories
206
}
207
```
208

209
### File Processing Pipeline
210

211
The build integration automatically processes discovered files through specialized parsers.
212

213
```typescript { .api }
214
interface ProcessingPipeline {
215
  /** CSS/SCSS/LESS file processing */
216
  cssParser: (files: File[], sourceType: TokenSourceType, injectVariables?: boolean) => Promise<{ categories: Category[]; injectionStyles: string }>;
217
  /** SVG icon file processing */
218
  svgParser: (files: File[]) => Promise<Category[]>;
219
  /** Image file processing */
220
  imageParser: (files: File[]) => Promise<Category[]>;
221
}
222

223
interface File {
224
  /** File path */
225
  filename: string;
226
  /** File content */
227
  content: any;
228
}
229
```
230

231
### Token Annotation Requirements
232

233
Design token files must include specific annotations for the parser to recognize them:
234

235
#### CSS/SCSS/LESS Files
236

237
```css
238
/* CSS tokens must include @tokens annotation */
239
:root {
240
  /* @tokens Colors */
241
  --primary-color: #007acc;
242
  --secondary-color: #6c757d;
243
  
244
  /* @tokens Typography */
245
  --heading-font: 'Inter', sans-serif;
246
  --body-font: 'Arial', sans-serif;
247
  
248
  /* @tokens Spacing */
249
  --spacing-sm: 8px;
250
  --spacing-md: 16px;
251
  --spacing-lg: 24px;
252
}
253
```
254

255
```scss
256
// SCSS with @tokens annotation
257
$tokens: true; // Optional marker
258

259
/* @tokens Colors */
260
$primary-blue: #0066cc;
261
$success-green: #28a745;
262

263
/* @tokens Dimensions */
264
$border-radius-sm: 4px;
265
$border-radius-md: 8px;
266
```
267

268
#### SVG Files
269

270
SVG files are automatically processed without annotations:
271

272
```xml
273
<!-- icons/arrow-right.svg -->
274
<svg width="24" height="24" viewBox="0 0 24 24">
275
  <path d="M8.59 16.59L13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.41z"/>
276
</svg>
277
```
278

279
#### Image Files
280

281
Image files (PNG, JPEG, GIF) are automatically processed:
282

283
```
284
assets/
285
├── logos/
286
│   ├── brand-logo.png
287
│   └── brand-mark.svg
288
└── icons/
289
    ├── user-avatar.png
290
    └── notification.png
291
```
292

293
### Build Performance Optimization
294

295
The plugin includes several optimizations for build performance:
296

297
```typescript { .api }
298
interface OptimizationConfig {
299
  /** Files to ignore during processing */
300
  ignorePatterns: string[];
301
  /** Caching strategy for processed tokens */
302
  caching: boolean;
303
  /** Incremental processing support */
304
  incremental: boolean;
305
}
306
```
307

308
**Built-in Optimizations:**
309

310
- Automatic exclusion of `node_modules/**` and `storybook-static/**`
311
- Chunk file filtering (`**/*.chunk.*`)
312
- File content caching to avoid reprocessing unchanged files
313
- Incremental builds with dependency tracking
314

315
**Custom Optimization Examples:**
316

317
```typescript
318
// .storybook/main.js with custom ignore patterns
319
module.exports = {
320
  addons: [
321
    {
322
      name: "storybook-design-token",
323
      options: {
324
        designTokenGlob: "src/**/*.{css,scss}",
325
        // Custom ignore patterns can be added via glob negative patterns
326
        ignorePatterns: ["!**/dist/**", "!**/build/**", "!**/coverage/**"]
327
      }
328
    }
329
  ]
330
};
331
```
332

333
### Environment Variables
334

335
Configure the addon behavior using environment variables:
336

337
```bash
338
# Token file pattern
339
DESIGN_TOKEN_GLOB="src/tokens/**/*.{css,scss,svg}"
340

341
# Enable debug logging
342
DEBUG_DESIGN_TOKENS=true
343

344
# Custom output directory
345
DESIGN_TOKEN_OUTPUT="./storybook-static/design-tokens"
346
```
347

348
### Troubleshooting Build Integration
349

350
Common issues and solutions:
351

352
```typescript
353
// Webpack version compatibility
354
if (webpackVersion >= 5) {
355
  config.plugins.push(new StorybookDesignTokenPlugin(designTokenGlob));
356
} else {
357
  throw new Error("Webpack 4 is not supported by storybook-design-token addon");
358
}
359

360
// File watching for development
361
// The plugin automatically sets up file watching for token files
362
// No additional configuration needed
363

364
// Build output verification
365
// Check browser dev tools for:
366
console.log("Design tokens loaded:", window.__DESIGN_TOKENS__);
367
```