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

configuration.mddocs/

Configuration System

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.

Capabilities

Story-Level Configuration

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

interface StoryParameters {
  /** Design token addon configuration */
  designToken?: Config;
}

interface Config {
  /** Enable/disable search functionality (default: true) */
  showSearch?: boolean;
  /** Default selected tab name */
  defaultTab?: string;
  /** Custom CSS injection for styling */
  styleInjection?: string;
  /** Number of items displayed per page */
  pageSize?: number;
  /** Custom presenter component overrides */
  presenters?: PresenterMapType;
  /** Filter visible tabs by name */
  tabs?: string[];
}

Usage Examples:

// Individual story configuration
export const ColorTokens = {
  name: "Color Tokens",
  parameters: {
    designToken: {
      showSearch: true,
      defaultTab: "Colors",
      pageSize: 20,
      tabs: ["Colors", "Gradients"],
      styleInjection: `
        .design-token-container {
          background: #f8f9fa;
          padding: 16px;
          border-radius: 8px;
        }
      `
    }
  }
};

// Story with custom presenters
export const TypographyTokens = {
  name: "Typography",
  parameters: {
    designToken: {
      defaultTab: "Typography",
      presenters: {
        "FontSize": CustomFontSizePresenter,
        "FontWeight": CustomFontWeightPresenter
      },
      styleInjection: `
        .token-preview { font-family: 'Inter', sans-serif; }
      `
    }
  }
};

Global Configuration

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

interface PreviewParameters {
  designToken?: Config;
}

Usage Examples:

// .storybook/preview.js
export default {
  parameters: {
    designToken: {
      showSearch: true,
      pageSize: 15,
      styleInjection: `
        :root {
          --token-border-color: #e1e5e9;
          --token-text-color: #333;
        }
        .design-token-card {
          border-color: var(--token-border-color);
          color: var(--token-text-color);
        }
      `,
      presenters: {
        "Color": GlobalCustomColorPresenter
      }
    }
  }
};

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

const preview: Preview = {
  parameters: {
    designToken: {
      showSearch: true,
      defaultTab: "Colors",
      pageSize: 12,
      tabs: ["Colors", "Typography", "Spacing", "Shadows"]
    }
  }
};

export default preview;

Component-Level Configuration

Configure individual DesignTokenDocBlock components with specific options.

interface DesignTokenDocBlockProps {
  categoryName: string;
  maxHeight?: number;
  showValueColumn?: boolean;
  viewType: TokenViewType;
  filterNames?: string[];
  usageMap?: Record<string, string[]>;
  theme?: string;
  showSearch?: boolean;
  pageSize?: number;
  presenters?: PresenterMapType;
}

Usage Examples:

import { DesignTokenDocBlock } from "storybook-design-token";

// Component with full configuration
<DesignTokenDocBlock
  categoryName="Spacing"
  maxHeight={600}
  showValueColumn={true}
  viewType="table"
  showSearch={false}
  pageSize={10}
  theme="dark"
  filterNames={["small", "medium", "large"]}
  usageMap={{
    "spacing-sm": ["margin: var(--spacing-sm)", "padding: var(--spacing-sm)"],
    "spacing-md": ["gap: var(--spacing-md)", "margin-bottom: var(--spacing-md)"]
  }}
  presenters={{
    "Spacing": CustomSpacingPresenter
  }}
/>

Configuration Options Reference

Search Configuration

interface SearchConfig {
  /** Enable search input field */
  showSearch?: boolean;
}

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

Examples:

// Disable search for simple token sets
{ showSearch: false }

// Enable search with custom styling
{ 
  showSearch: true,
  styleInjection: `
    .search-field input {
      border-radius: 6px;
      border: 2px solid #007acc;
    }
  `
}

Tab Management

interface TabConfig {
  /** Default selected tab */
  defaultTab?: string;
  /** Filter visible tabs */
  tabs?: string[];
}

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

Examples:

// Show only specific tabs
{
  tabs: ["Colors", "Typography", "Spacing"],
  defaultTab: "Colors"
}

// Show all tabs with specific default
{
  defaultTab: "Typography"
}

Pagination Configuration

interface PaginationConfig {
  /** Items per page */
  pageSize?: number;
}

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

Examples:

// Large page size for comprehensive view
{ pageSize: 50 }

// Small page size for focused view
{ pageSize: 8 }

Style Injection

interface StyleConfig {
  /** Custom CSS injection */
  styleInjection?: string;
}

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

Examples:

{
  styleInjection: `
    .design-token-container {
      --primary-color: #007acc;
      --border-radius: 8px;
      --shadow: 0 2px 8px rgba(0,0,0,0.1);
    }
    
    .design-token-card {
      border-radius: var(--border-radius);
      box-shadow: var(--shadow);
    }
    
    .token-name {
      color: var(--primary-color);
      font-weight: 600;
    }
    
    /* Dark theme overrides */
    .dark-theme .design-token-container {
      background: #1a1a1a;
      color: #ffffff;
    }
  `
}

Presenter Customization

interface PresenterConfig {
  /** Custom presenter components */
  presenters?: PresenterMapType;
}

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

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

Examples:

{
  presenters: {
    // Override built-in color presenter
    "Color": MyCustomColorPresenter,
    
    // Add custom presenter for new token type
    "Elevation": ElevationPresenter,
    
    // Override multiple presenters
    "FontSize": BrandedFontSizePresenter,
    "Spacing": MetricSpacingPresenter
  }
}

Configuration Priority

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

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

Example Priority Resolution:

// Built-in defaults
{ showSearch: true, pageSize: 10 }

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

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

// Component props
{ showSearch: true }

// Final resolved config:
{
  showSearch: true,    // from component props
  pageSize: 15,        // from story config
  defaultTab: "Colors", // from global config
  tabs: ["Colors", "Typography"] // from story config
}

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