CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-storybook-design-token

Storybook addon to display design token documentation generated from your stylesheets and icon files.

—

Pending
Overview
Eval results
Files

build-integration.mddocs/

Build System Integration

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.

Capabilities

Storybook Preset Integration

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

/**
 * Registers manager entry points for the addon
 * @param entry - Existing entry points array
 * @returns Updated entry points including addon manager
 */
function managerEntries(entry?: any[]): any[];

/**
 * Configures Vite build system with design token plugin
 * @param viteConfig - Existing Vite configuration
 * @param options - Addon configuration options
 * @returns Updated Vite configuration with token processing
 */
function viteFinal(
  viteConfig: Record<string, any>, 
  options: any
): Promise<Record<string, any>>;

/**
 * Configures Webpack build system with design token plugin
 * @param config - Existing Webpack configuration
 * @param options - Addon configuration options
 * @returns Updated Webpack configuration with token processing
 */
function webpackFinal(
  config: any, 
  options: AddonOptions
): Promise<any>;

interface AddonOptions {
  /** Glob pattern for design token files */
  designTokenGlob?: string;
  /** Storybook presets instance */
  presets: any;
}

Usage Examples:

// .storybook/main.js
module.exports = {
  addons: [
    {
      name: "storybook-design-token",
      options: {
        designTokenGlob: "src/tokens/**/*.{css,scss,svg,png}"
      }
    }
  ]
};

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

const config: StorybookConfig = {
  addons: [
    {
      name: "storybook-design-token",
      options: {
        designTokenGlob: "**/*.{css,scss,less,svg,png,jpeg,gif}"
      }
    }
  ]
};

export default config;

Webpack Plugin

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

/**
 * Webpack plugin class for design token processing
 */
class StorybookDesignTokenPlugin {
  constructor(designTokenGlob?: string);
  apply(compiler: any): void;
}

Usage Examples:

// webpack.config.js
const { StorybookDesignTokenPlugin } = require("storybook-design-token/plugin");

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

// Custom Storybook webpack configuration
// .storybook/main.js
module.exports = {
  webpackFinal: async (config) => {
    config.plugins.push(
      new StorybookDesignTokenPlugin("tokens/**/*.{css,scss,less}")
    );
    return config;
  }
};

Vite Plugin

Direct Vite plugin integration for Vite-based Storybook configurations.

/**
 * Vite plugin function for design token processing
 * @param options - Plugin configuration options
 * @returns Vite plugin configuration
 */
function viteStorybookDesignTokenPlugin(options?: any): any;

Usage Examples:

// vite.config.js
import { viteStorybookDesignTokenPlugin } from "storybook-design-token/plugin";

export default {
  plugins: [
    viteStorybookDesignTokenPlugin({
      designTokenGlob: "src/tokens/**/*.{css,scss,svg,png}"
    })
  ]
};

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

const config: StorybookConfig = {
  viteFinal: async (config) => {
    config.plugins = config.plugins || [];
    config.plugins.push(
      viteStorybookDesignTokenPlugin({
        designTokenGlob: "design-system/**/*.{css,scss,less,svg}"
      })
    );
    return config;
  }
};

export default config;

File Pattern Configuration

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

interface FilePatternConfig {
  /** Glob pattern for design token files */
  designTokenGlob?: string;
}

The plugin uses the following pattern resolution priority:

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

Usage Examples:

// Environment variable configuration
// .env
DESIGN_TOKEN_GLOB=src/design-system/**/*.{css,scss}

// Package.json scripts
{
  "scripts": {
    "storybook": "DESIGN_TOKEN_GLOB='tokens/**/*.css' storybook dev -p 6006"
  }
}

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

{
  designTokenGlob: "assets/icons/**/*.svg" // SVG icons only
}

{
  designTokenGlob: "{src/tokens,assets/icons}/**/*.{css,scss,svg}" // Multiple directories
}

File Processing Pipeline

The build integration automatically processes discovered files through specialized parsers.

interface ProcessingPipeline {
  /** CSS/SCSS/LESS file processing */
  cssParser: (files: File[], sourceType: TokenSourceType, injectVariables?: boolean) => Promise<{ categories: Category[]; injectionStyles: string }>;
  /** SVG icon file processing */
  svgParser: (files: File[]) => Promise<Category[]>;
  /** Image file processing */
  imageParser: (files: File[]) => Promise<Category[]>;
}

interface File {
  /** File path */
  filename: string;
  /** File content */
  content: any;
}

Token Annotation Requirements

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

CSS/SCSS/LESS Files

/* CSS tokens must include @tokens annotation */
:root {
  /* @tokens Colors */
  --primary-color: #007acc;
  --secondary-color: #6c757d;
  
  /* @tokens Typography */
  --heading-font: 'Inter', sans-serif;
  --body-font: 'Arial', sans-serif;
  
  /* @tokens Spacing */
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 24px;
}
// SCSS with @tokens annotation
$tokens: true; // Optional marker

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

/* @tokens Dimensions */
$border-radius-sm: 4px;
$border-radius-md: 8px;

SVG Files

SVG files are automatically processed without annotations:

<!-- icons/arrow-right.svg -->
<svg width="24" height="24" viewBox="0 0 24 24">
  <path d="M8.59 16.59L13.17 12 8.59 7.41 10 6l6 6-6 6-1.41-1.41z"/>
</svg>

Image Files

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

assets/
├── logos/
│   ├── brand-logo.png
│   └── brand-mark.svg
└── icons/
    ├── user-avatar.png
    └── notification.png

Build Performance Optimization

The plugin includes several optimizations for build performance:

interface OptimizationConfig {
  /** Files to ignore during processing */
  ignorePatterns: string[];
  /** Caching strategy for processed tokens */
  caching: boolean;
  /** Incremental processing support */
  incremental: boolean;
}

Built-in Optimizations:

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

Custom Optimization Examples:

// .storybook/main.js with custom ignore patterns
module.exports = {
  addons: [
    {
      name: "storybook-design-token",
      options: {
        designTokenGlob: "src/**/*.{css,scss}",
        // Custom ignore patterns can be added via glob negative patterns
        ignorePatterns: ["!**/dist/**", "!**/build/**", "!**/coverage/**"]
      }
    }
  ]
};

Environment Variables

Configure the addon behavior using environment variables:

# Token file pattern
DESIGN_TOKEN_GLOB="src/tokens/**/*.{css,scss,svg}"

# Enable debug logging
DEBUG_DESIGN_TOKENS=true

# Custom output directory
DESIGN_TOKEN_OUTPUT="./storybook-static/design-tokens"

Troubleshooting Build Integration

Common issues and solutions:

// Webpack version compatibility
if (webpackVersion >= 5) {
  config.plugins.push(new StorybookDesignTokenPlugin(designTokenGlob));
} else {
  throw new Error("Webpack 4 is not supported by storybook-design-token addon");
}

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

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

Install with Tessl CLI

npx tessl i tessl/npm-storybook-design-token

docs

build-integration.md

configuration.md

doc-blocks.md

index.md

presenters.md

tile.json