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