Storybook Addon Design System Docs

Automate your Design System documentation using your Tailwind CSS configuration and asset folders.

Features

• 🎨 Tailwind CSS Integration: Automatically generates "Colors", "Typography", "Spacing", "Shadows", and more documentation pages directly from your tailwind.config.js.
• 🖼️ Asset Gallery: Auto-generates asset documentation (Icons, Illustrations) from your file system.
• ⚡ Zero Config: Works out of the box with sensible defaults.
• 🔧 Customizable: Override templates, customize the sidebar, and filter assets.
• 🖌️ Theming: Supports Light/Dark mode variants for assets.

Installation

npm install -D storybook-addon-design-system-docs
# or
yarn add -D storybook-addon-design-system-docs
# or
pnpm add -D storybook-addon-design-system-docs
# or
bun add -D storybook-addon-design-system-docs

Setup

Add the addon to your .storybook/main.ts configuration:

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

const config: StorybookConfig = {
    addons: [
        {
            name: 'storybook-addon-design-system-docs',
            options: {
                // REQUIRED: Path to your tailwind config
                tailwindConfig: '../tailwind.config.js',

                // Optional: Customize sidebar group name
                sidebarGroup: 'Design System',

                // Optional: Configure asset galleries
                assets: [
                    {
                        name: 'Icons',
                        source: './src/assets/icons',
                        staticPath: '/assets/icons', // URL path to serve assets from
                    },
                ],
            },
        },
        // ... other addons
    ],
};
export default config;

Configuration

Options

| Option | Type | Required | Default | Description | | ---------------- | --------------- | -------- | ------------------ | ------------------------------------------------ | | tailwindConfig | string | Yes | - | Path to tailwind.config.js | | sidebarGroup | string | No | 'Design System/' | Global sidebar group prefix for all docs | | sections | Section[] | No | Default sections | Customize which theme sections to display | | assets | AssetGroup[] | No | [] | Asset groups to generate galleries for | | showOnlyCustom | boolean | No | false | If true, only shows custom Tailwind values | | templates | TemplateConfig| No | Built-in templates | Override default MDX templates |

Sidebar Organization

The addon provides flexible control over where documentation pages appear in Storybook's sidebar through the sidebarGroup option and individual path properties.

Understanding sidebarGroup and path

• sidebarGroup: A global prefix applied to all generated documentation (both sections and assets)
• path: An optional per-section or per-asset path that controls placement relative to the sidebarGroup

Path Resolution Rules

The final sidebar location is determined by combining sidebarGroup and path:

1. Absolute path (starts with /): Ignores sidebarGroup entirely

   sidebarGroup: 'Design System/'
   sections: [{ name: 'Colors', path: '/' }]
   // Result: "Colors" (at root level)

2. Relative path: Appends to sidebarGroup

   sidebarGroup: 'Design System/'
   sections: [{ name: 'Colors', path: 'Theme/' }]
   // Result: "Design System/Theme/Colors"

3. No path specified: Uses sidebarGroup directly

   sidebarGroup: 'Design System/'
   sections: [{ name: 'Colors' }]
   // Result: "Design System/Colors"

4. Empty sidebarGroup: Uses only the path (or just the name if no path)

   sidebarGroup: ''
   sections: [{ name: 'Colors', path: 'Theme/' }]
   // Result: "Theme/Colors"

Examples

{
    name: 'storybook-addon-design-system-docs',
    options: {
        tailwindConfig: '../tailwind.config.js',
        sidebarGroup: 'Design System/',

        // Customize section placement
        sections: [
            { name: 'Colors', path: '/' },           // → "Colors" (root level)
            { name: 'Typography', path: '/' },       // → "Typography" (root level)
            { name: 'Spacing', path: 'Layout/' },    // → "Design System/Layout/Spacing"
            { name: 'Shadows', path: 'Layout/' },    // → "Design System/Layout/Shadows"
        ],

        // Asset paths work the same way
        assets: [
            {
                name: 'Icons',
                source: './src/icons',
                path: '/Resources/',  // → "Resources/Icons" (absolute path, ignores sidebarGroup)
            },
            {
                name: 'Illustrations',
                source: './src/illustrations',
                path: 'Assets/',      // → "Design System/Assets/Illustrations" (relative to sidebarGroup)
            },
        ],
    }
}

Section Configuration

Customize which Tailwind theme sections to display and where they appear:

sections: [
    'Colors',  // Simple string uses defaults
    {
        name: 'Typography',
        path: 'Theme/',  // Custom sidebar location
    },
    {
        name: 'Spacing',
        path: '/',       // Place at root level
    },
]

Available sections: Colors, Typography, Spacing, Shadows, BorderRadius (or Radius)

Asset Configuration

Generate asset galleries from your file system:

assets: [
    {
        name: 'Icons',                    // Display name
        source: './src/icons',            // Source directory (relative to project root)
        path: 'Assets/',                  // Optional: sidebar location (relative to sidebarGroup)
        staticPath: '/icons',             // Optional: URL path to serve assets from
        variants: {
            enabled: true,                // Enable variant detection
            suffixes: ['.light', '.dark'], // Filename suffixes for variants
        },
        display: {
            layout: 'grid',               // 'grid' or 'list'
            showFilename: true,           // Show filenames below assets
        },
    },
];

Asset Path Resolution: Works exactly like section paths - supports both absolute (/) and relative paths, combined with sidebarGroup.

Template Customization

Override the default MDX templates for any section:

{
    templates: {
        directory: './.storybook/design-system-docs',  // Custom template directory
    }
}

Place custom MDX files in the specified directory with names matching sections (e.g., colors.mdx, typography.mdx).

Tailwind v4 Support

The addon automatically detects and supports both Tailwind CSS v3 (config file) and v4 (CSS @theme directive):

Tailwind v3:

{ tailwindConfig: './tailwind.config.js' }

Tailwind v4:

{ tailwindConfig: './src/app.css' }  // CSS file with @theme directive

Contributing

We welcome contributions! Please see CONTRIBUTING.md for details.

Credits

This project is a fork of storybook-addon-tailwind-autodocs by Matan Yosef.

Thank you Matan for the initial implementation!

License

MIT © Saulo Vallory and Matan Yosef