storybook-addon-design-system-docs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 Storybook contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,108 @@
+# Storybook Addon Design System Docs
+
+Automate your Design System documentation using your Tailwind CSS configuration and asset folders.
+
+![License](https://img.shields.io/npm/l/storybook-addon-design-system-docs)
+![Version](https://img.shields.io/npm/v/storybook-addon-design-system-docs)
+
+## 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
+
+```bash
+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:
+
+```ts
+// .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/'` | Sidebar group name for generated docs      |
+| `assets`         | `AssetGroup[]` | No       | `[]`               | List of asset groups to generate           |
+| `showOnlyCustom` | `boolean`      | No       | `false`            | If true, only shows custom Tailwind values |
+
+### Asset Configuration
+
+```ts
+assets: [
+    {
+        name: 'Icons', // Display name
+        source: './src/icons', // Source directory (relative to project root)
+        staticPath: '/icons', // URL path (must match where you serve static files or let addon handle it)
+        variants: {
+            // Optional variants
+            enabled: true,
+            suffixes: ['.light', '.dark'],
+        },
+        display: {
+            // Optional display settings
+            layout: 'grid',
+            showFilename: true,
+        },
+    },
+];
+```
+
+## Contributing
+
+We welcome contributions! Please see [CONTRIBUTING.md](CONTRIBUTING.md) for details.
+
+## Credits
+
+This project is a fork of [storybook-addon-tailwind-autodocs](https://github.com/matanio/storybook-addon-tailwind-autodocs) by [Matan Yosef](https://github.com/matanio).
+
+> Thank you Matan for the initial implementation!
+
+## License
+
+MIT © [Saulo Vallory](https://saulo.engineer) and [Matan Yosef](https://github.com/matanio)

package/dist/core/assets/config.d.ts

@@ -0,0 +1,15 @@
+import type { AssetGroupConfig, NormalizedAssetGroup } from "@/types";
+/**
+ * Validates that the provided configurations meet minimum requirements.
+ * Throws an error if any configuration is invalid.
+ */
+export declare function validateAssetConfig(configs: AssetGroupConfig[]): void;
+/**
+ * Converts a single raw `AssetGroupConfig` into a `NormalizedAssetGroup`.
+ * Applies defaults for all optional fields and resolves paths.
+ */
+export declare function normalizeAssetGroup(config: AssetGroupConfig, sidebarGroup?: string, configDir?: string): NormalizedAssetGroup;
+/**
+ * Batch normalizes a list of asset configurations.
+ */
+export declare function normalizeAssetConfigs(assetConfigs?: AssetGroupConfig[], sidebarGroup?: string, configDir?: string): NormalizedAssetGroup[];

package/dist/core/assets/config.js

@@ -0,0 +1,100 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeAssetConfigs = exports.normalizeAssetGroup = exports.validateAssetConfig = void 0;
+const path_1 = require("path");
+const DEFAULT_VARIANT_CONFIG = {
+    enabled: true,
+    suffixes: ["-light", "-dark"],
+    defaultVariant: "light",
+};
+const DEFAULT_DISPLAY_CONFIG = {
+    layout: "grid",
+    columns: 4,
+    showFilename: true,
+    showPath: false,
+    previewSize: 128,
+    background: "checkerboard",
+};
+const DEFAULT_FILTER_CONFIG = {
+    include: ["**/*.svg"],
+    exclude: [],
+};
+/**
+ * Validates that the provided configurations meet minimum requirements.
+ * Throws an error if any configuration is invalid.
+ */
+function validateAssetConfig(configs) {
+    if (!Array.isArray(configs)) {
+        throw new Error("assets must be an array");
+    }
+    for (const config of configs) {
+        if (!config.name || typeof config.name !== "string") {
+            throw new Error("Each asset group must have a name");
+        }
+        if (!config.source || typeof config.source !== "string") {
+            throw new Error(`Asset group "${config.name}" must have a source directory`);
+        }
+    }
+}
+exports.validateAssetConfig = validateAssetConfig;
+/**
+ * Converts a single raw `AssetGroupConfig` into a `NormalizedAssetGroup`.
+ * Applies defaults for all optional fields and resolves paths.
+ */
+function normalizeAssetGroup(config, sidebarGroup = "Assets/", configDir) {
+    // Normalize path
+    let storyPath = config.path ?? sidebarGroup;
+    if (storyPath.endsWith("/")) {
+        storyPath = `${storyPath}${config.name}`;
+    }
+    // Resolve source path relative to configDir
+    const source = path_1.default.isAbsolute(config.source)
+        ? config.source
+        : configDir
+            ? path_1.default.resolve(configDir, config.source)
+            : config.source;
+    // Normalize variants config
+    const variants = {
+        ...DEFAULT_VARIANT_CONFIG,
+        ...config.variants,
+    };
+    if (config.variants?.suffixes) {
+        variants.suffixes = config.variants.suffixes;
+    }
+    // Normalize display config
+    const display = {
+        ...DEFAULT_DISPLAY_CONFIG,
+        ...config.display,
+    };
+    // Normalize filter config
+    const filter = {
+        include: config.filter?.include ?? DEFAULT_FILTER_CONFIG.include,
+        exclude: config.filter?.exclude ?? DEFAULT_FILTER_CONFIG.exclude,
+    };
+    // Normalize copy config
+    const copy = config.copy ?? {};
+    // Determine static path: user-provided or fallback to addon-assets
+    const staticPath = config.staticPath ?? `/addon-assets/${config.name}`;
+    return {
+        name: config.name,
+        path: storyPath,
+        source,
+        staticPath,
+        title: config.title ?? config.name,
+        description: config.description,
+        variants,
+        display,
+        copy,
+        filter,
+        groupByFolder: config.groupByFolder ?? false,
+    };
+}
+exports.normalizeAssetGroup = normalizeAssetGroup;
+/**
+ * Batch normalizes a list of asset configurations.
+ */
+function normalizeAssetConfigs(assetConfigs = [], sidebarGroup = "Assets/", configDir) {
+    validateAssetConfig(assetConfigs);
+    return assetConfigs.map((config) => normalizeAssetGroup(config, sidebarGroup, configDir));
+}
+exports.normalizeAssetConfigs = normalizeAssetConfigs;

package/dist/core/assets/generator.d.ts

@@ -0,0 +1,11 @@
+import type { NormalizedAddonOptions } from "@/core/primitives/types";
+export interface GenerateAssetsOptions {
+    configDir: string;
+    assets: any[];
+    addonOptions: NormalizedAddonOptions;
+}
+/**
+ * Generates physical MDX files for each configured asset group.
+ * These files are written to .storybook/design-system/assets/ and added to stories.
+ */
+export declare function generateAssetStories(options: GenerateAssetsOptions): string[];

package/dist/core/assets/generator.js

@@ -0,0 +1,77 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateAssetStories = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const Logger_1 = require("@/util/Logger");
+const resolveTemplate_1 = require("@/util/resolveTemplate");
+const logger = new Logger_1.Logger("AssetGenerator");
+/**
+ * Generates physical MDX files for each configured asset group.
+ * These files are written to .storybook/design-system/assets/ and added to stories.
+ */
+function generateAssetStories(options) {
+    const { configDir, assets, addonOptions } = options;
+    const generatedStories = [];
+    if (!assets || !Array.isArray(assets) || assets.length === 0) {
+        return [];
+    }
+    const assetsDir = path_1.default.resolve(configDir, "design-system/assets");
+    // Ensure directory exists
+    if (!fs_1.default.existsSync(assetsDir)) {
+        fs_1.default.mkdirSync(assetsDir, { recursive: true });
+    }
+    // Load template
+    let templateContent = "";
+    const templatePath = (0, resolveTemplate_1.resolveTemplate)("assets", addonOptions);
+    if (fs_1.default.existsSync(templatePath)) {
+        try {
+            templateContent = fs_1.default.readFileSync(templatePath, "utf-8");
+        }
+        catch (e) {
+            logger.error(`Failed to read assets template at ${templatePath}`, e);
+        }
+    }
+    if (!templateContent) {
+        logger.warn("Could not find assets.mdx template");
+        return [];
+    }
+    // Generate files for each group
+    const validFiles = new Set();
+    assets.forEach((group) => {
+        const groupName = group.name;
+        const groupTitle = group.title || groupName;
+        // Sanitize filename
+        const cleanName = groupName.replace(/[^a-zA-Z0-9]/g, "");
+        const filename = `${cleanName}.mdx`;
+        const filePath = path_1.default.join(assetsDir, filename);
+        // Interpolate template
+        const fileContent = templateContent
+            .replace(/\{\{group\.name\}\}/g, groupName)
+            .replace(/\{\{group\.title\}\}/g, groupTitle);
+        try {
+            fs_1.default.writeFileSync(filePath, fileContent);
+            validFiles.add(filename);
+            generatedStories.push(filePath);
+        }
+        catch (e) {
+            logger.error(`Failed to write asset MDX for group ${groupName}`, e);
+        }
+    });
+    // Cleanup orphaned files
+    if (fs_1.default.existsSync(assetsDir)) {
+        try {
+            const files = fs_1.default.readdirSync(assetsDir);
+            files.forEach((file) => {
+                if (file.endsWith(".mdx") && !validFiles.has(file)) {
+                    fs_1.default.unlinkSync(path_1.default.join(assetsDir, file));
+                }
+            });
+        }
+        catch (e) {
+            logger.warn("Failed to cleanup orphaned asset files", e);
+        }
+    }
+    return generatedStories;
+}
+exports.generateAssetStories = generateAssetStories;

package/dist/core/primitives/index.d.ts

@@ -0,0 +1,7 @@
+export * from "@/core/primitives/config";
+export * from "@/core/primitives/data";
+export * from "@/core/primitives/load";
+export * from "@/core/primitives/loaders/tw-config";
+export * from "@/core/primitives/loaders/tw-css";
+export * from "@/core/primitives/parsers/theme-css";
+export * from "@/core/primitives/types";

package/dist/core/primitives/index.js

@@ -0,0 +1,23 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("@/core/primitives/config"), exports);
+__exportStar(require("@/core/primitives/data"), exports);
+__exportStar(require("@/core/primitives/load"), exports);
+__exportStar(require("@/core/primitives/loaders/tw-config"), exports);
+__exportStar(require("@/core/primitives/loaders/tw-css"), exports);
+__exportStar(require("@/core/primitives/parsers/theme-css"), exports);
+__exportStar(require("@/core/primitives/types"), exports);

package/dist/core/primitives/types.d.ts

@@ -0,0 +1,130 @@
+import type { NormalizedSection, TemplateConfig } from "@/types";
+/**
+ * Normalized configuration for the Design System Addon.
+ * This is the internal representation of the options after validation and defaults.
+ */
+export interface NormalizedAddonOptions {
+    /** The validated Tailwind config path */
+    tailwindConfig: string;
+    /** The base sidebar group name (e.g., "Design System/") */
+    sidebarGroup: string;
+    /** The list of enabled and normalized primitive sections */
+    sections: NormalizedSection[];
+    /** Optional configuration for forcing all primitives into a single document */
+    forceSingleDoc?: NormalizedSection;
+    /** Whether to hide default Tailwind values */
+    showOnlyCustom: boolean;
+    /** Typography configuration */
+    typography?: {
+        example?: string;
+    };
+    /** Template engine configuration */
+    templates?: TemplateConfig;
+}
+/**
+ * Represents a single color definition in the theme.
+ */
+export interface ColorData {
+    /** The base name of the color (e.g., 'blue') */
+    baseName: string;
+    /** A record of shades where key is the shade level (e.g., '500') and value is the hex code */
+    shades: Record<string, string>;
+    /** A descriptive subtitle for the color group */
+    subtitle: string;
+    /** Whether this color is a custom definition (not in base Tailwind) */
+    isCustom: boolean;
+    /** Whether this color extends an existing Tailwind color */
+    isExtended: boolean;
+    /** Whether this is a default Tailwind color */
+    isDefault: boolean;
+}
+/**
+ * Context data for rendering the colors section.
+ */
+export interface ColorsContext {
+    /** All color definitions */
+    colors: ColorData[];
+    /** Colors marked as custom/extended */
+    customColors: ColorData[];
+    /** Colors from Tailwind defaults */
+    builtInColors: ColorData[];
+    /** Whether there are any colors to display */
+    hasColors: boolean;
+}
+/**
+ * Context data for rendering the typography section.
+ */
+export interface TypographyContext {
+    /** Font family definitions as pairs of [label, fontFamily] */
+    fontFamilies: [string, string][];
+    /** Custom font families defined in the theme */
+    customFamilies: [string, string][];
+    /** Standard Tailwind built-in font families (sans, serif, mono) */
+    builtInFamilies: [string, string][];
+    /** Font weight definitions as pairs of [label, value] */
+    fontWeights: [string, string][];
+    /** Font size definitions as pairs of [label, value] */
+    fontSizes: [string, string][];
+    /** Whether there are any font families to display */
+    hasFontFamily: boolean;
+    /** All weight keys available for filter state initialization */
+    allWeightKeys: string[];
+    /** All size keys available for filter state initialization */
+    allSizeKeys: string[];
+}
+/**
+ * Context data for rendering the spacing section.
+ */
+export interface SpacingContext {
+    /** Spacing value entries as pairs of [label, value] */
+    entries: [string, string][];
+    /** Whether there are any spacing values to display */
+    hasSpacing: boolean;
+    /** The maximum numeric value in the entries, used for bar chart scaling */
+    maxValue: number;
+}
+/**
+ * Context data for rendering the shadows section.
+ */
+export interface ShadowsContext {
+    /** Shadow value entries as pairs of [label, value] */
+    entries: [string, string][];
+    /** Whether there are any shadow values to display */
+    hasShadows: boolean;
+}
+/**
+ * Context data for rendering the border radius section.
+ */
+export interface RadiusContext {
+    /** Border radius entries as pairs of [label, value] */
+    entries: [string, string][];
+    /** Whether there are any border radius values to display */
+    hasRadius: boolean;
+}
+/**
+ * Main context for theme template rendering, combining all section contexts and global settings.
+ */
+export interface DesignSystemData {
+    /** List of section names that are currently enabled */
+    enabledSections: string[];
+    /** Whether to show only custom values, hiding default Tailwind tokens */
+    showOnlyCustom: boolean;
+    /** Default text to use for typography samples */
+    defaultSampleText: string;
+    /** Whether to use optimized React components for rendering */
+    useReactComponents: boolean;
+    /** Whether to force generation of a single documentation story instead of individual ones */
+    forceSingleDoc: boolean;
+    /** The sanitized export name when in single-story mode */
+    exportName?: string;
+    /** Context for the colors documentation section */
+    colors: ColorsContext;
+    /** Context for the typography documentation section */
+    typography: TypographyContext;
+    /** Optional context for the spacing documentation section */
+    spacing?: SpacingContext;
+    /** Optional context for the shadows documentation section */
+    shadows?: ShadowsContext;
+    /** Optional context for the border radius documentation section */
+    borderRadius?: RadiusContext;
+}

package/dist/core/primitives/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/manager.js

@@ -0,0 +1,2 @@
+// Minimal manager entry point
+console.log('[MANAGER] Manager loaded');