storybook-addon-design-system-docs 1.0.0

package/dist/util/Logger.js

@@ -0,0 +1,172 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Logger = void 0;
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    silent: 4,
+};
+// ANSI color codes
+const COLORS = {
+    reset: "\x1b[0m",
+    dim: "\x1b[2m",
+    cyan: "\x1b[36m",
+    yellow: "\x1b[33m",
+    red: "\x1b[31m",
+    magenta: "\x1b[35m",
+};
+/**
+ * Detect if colors should be used in output.
+ * Respects NO_COLOR env var and checks for TTY.
+ */
+function supportsColor() {
+    // Respect NO_COLOR convention: https://no-color.org/
+    if (process.env.NO_COLOR !== undefined) {
+        return false;
+    }
+    // Check FORCE_COLOR for CI environments that support colors
+    if (process.env.FORCE_COLOR !== undefined) {
+        return process.env.FORCE_COLOR !== "0";
+    }
+    // Check if stdout is a TTY
+    if (typeof process !== "undefined" && process.stdout?.isTTY) {
+        return true;
+    }
+    return false;
+}
+/**
+ * Logger utility for the addon with configurable log levels and context support.
+ *
+ * Features:
+ * - Log levels (debug, info, warn, error, silent)
+ * - Context/prefix support for consistent logging
+ * - Conditional ANSI colors (respects NO_COLOR, FORCE_COLOR, TTY detection)
+ * - Structured data logging
+ */
+// biome-ignore lint/suspicious/useAdjacentOverloadSignatures: Separate static/instance grouping is preferred here
+class Logger {
+    /**
+     * Create a logger instance with a specific context prefix.
+     * @param context - Context name to prefix log messages (e.g., 'ConfigLoader', 'unplugin')
+     */
+    constructor(context) {
+        this.prefix = context
+            ? `[${Logger.defaultPrefix}:${context}]`
+            : `[${Logger.defaultPrefix}]`;
+    }
+    /**
+     * Set the global log level. Messages below this level will be suppressed.
+     */
+    static setLevel(level) {
+        Logger.level = level;
+    }
+    /**
+     * Get the current global log level.
+     */
+    static getLevel() {
+        return Logger.level;
+    }
+    /**
+     * Enable or disable color output.
+     */
+    static setColors(enabled) {
+        Logger.useColors = enabled;
+    }
+    shouldLog(level) {
+        return LOG_LEVELS[level] >= LOG_LEVELS[Logger.level];
+    }
+    colorize(color, text) {
+        if (!Logger.useColors) {
+            return text;
+        }
+        return `${COLORS[color]}${text}${COLORS.reset}`;
+    }
+    formatMessage(level, message) {
+        return `${this.prefix} ${level}: ${message}`;
+    }
+    /**
+     * Log debug messages. Only shown when log level is 'debug'.
+     */
+    debug(message, data) {
+        if (!this.shouldLog("debug"))
+            return;
+        const formatted = this.formatMessage("DEBUG", message);
+        console.debug(this.colorize("dim", formatted));
+        if (data) {
+            console.debug(this.colorize("dim", JSON.stringify(data, null, 2)));
+        }
+    }
+    /**
+     * Log informational messages.
+     */
+    info(message, data) {
+        if (!this.shouldLog("info"))
+            return;
+        const formatted = this.formatMessage("INFO", message);
+        console.info(this.colorize("cyan", formatted));
+        if (data) {
+            console.info(JSON.stringify(data, null, 2));
+        }
+    }
+    /**
+     * Log warning messages.
+     */
+    warn(message, data) {
+        if (!this.shouldLog("warn"))
+            return;
+        const formatted = this.formatMessage("WARN", message);
+        console.warn(this.colorize("yellow", formatted));
+        if (data) {
+            console.warn(JSON.stringify(data, null, 2));
+        }
+    }
+    /**
+     * Log error messages.
+     */
+    error(message, error, data) {
+        if (!this.shouldLog("error"))
+            return;
+        const formatted = this.formatMessage("ERROR", message);
+        console.error(this.colorize("red", formatted));
+        if (error instanceof Error) {
+            console.error(this.colorize("red", `  ${error.message}`));
+            if (error.stack) {
+                console.error(this.colorize("dim", error.stack));
+            }
+        }
+        else if (error !== undefined) {
+            console.error(error);
+        }
+        if (data) {
+            console.error(JSON.stringify(data, null, 2));
+        }
+    }
+    // Static convenience methods for backward compatibility and quick logging
+    /**
+     * Static warn method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static warn(message) {
+        new Logger().warn(message);
+    }
+    /**
+     * Static error method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static error(message) {
+        new Logger().error(message);
+    }
+    /**
+     * Static info method for backward compatibility.
+     * Consider using instance methods for context-aware logging.
+     */
+    static info(message) {
+        new Logger().info(message);
+    }
+}
+exports.Logger = Logger;
+Logger.defaultPrefix = "storybook-addon-design-system-docs";
+Logger.level = "info";
+Logger.useColors = supportsColor();

package/dist/util/resolveTemplate.d.ts

@@ -0,0 +1,10 @@
+import type { NormalizedAddonOptions } from "@/core/primitives/types";
+/**
+ * Resolves the absolute path to the MDX template for a given section.
+ * Checks user-configured directory, project override, and built-in templates.
+ *
+ * @param sectionName - The name of the section (e.g., "Colors", "Typography", "assets").
+ * @param options - The normalized addon options.
+ * @returns The absolute path to the resolved MDX template file, or undefined if not found.
+ */
+export declare function resolveTemplate(sectionName: string, options: NormalizedAddonOptions): string;

package/dist/util/resolveTemplate.js

@@ -0,0 +1,60 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTemplate = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const node_url_1 = require("node:url");
+const Logger_1 = require("@/util/Logger");
+const __filename = (0, node_url_1.fileURLToPath)(import.meta.url);
+const __dirname = node_path_1.default.dirname(__filename);
+const logger = new Logger_1.Logger("resolveTemplate");
+/**
+ * Convert camelCase or PascalCase to kebab-case
+ * e.g., "BorderRadius" -> "border-radius", "Colors" -> "colors"
+ */
+function toKebabCase(str) {
+    return str.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
+}
+/**
+ * Resolves the absolute path to the MDX template for a given section.
+ * Checks user-configured directory, project override, and built-in templates.
+ *
+ * @param sectionName - The name of the section (e.g., "Colors", "Typography", "assets").
+ * @param options - The normalized addon options.
+ * @returns The absolute path to the resolved MDX template file, or undefined if not found.
+ */
+function resolveTemplate(sectionName, options) {
+    const kebabName = toKebabCase(sectionName);
+    const filename = `${kebabName}.mdx`;
+    // 1. User configured directory
+    if (options.templates?.directory) {
+        const userTemplate = node_path_1.default.resolve(options.templates.directory, filename);
+        if (node_fs_1.default.existsSync(userTemplate)) {
+            logger.debug(`Using user template from configured directory: ${userTemplate}`);
+            return userTemplate;
+        }
+    }
+    // 2. .storybook/design-system-docs override
+    const userOverridePath = node_path_1.default.resolve(process.cwd(), ".storybook", "design-system-docs", filename);
+    if (node_fs_1.default.existsSync(userOverridePath)) {
+        logger.debug(`Using user override template: ${userOverridePath}`);
+        return userOverridePath;
+    }
+    // 3. Built-in templates
+    // We try multiple potential locations to be robust across build/dev environments
+    const potentialPaths = [
+        node_path_1.default.resolve(__dirname, "../../templates", filename), // src structure (addon/util -> src/templates)
+        node_path_1.default.resolve(__dirname, "../templates", filename), // dist structure (dist/util -> dist/templates)
+        node_path_1.default.resolve(__dirname, "templates", filename), // fallback
+    ];
+    for (const p of potentialPaths) {
+        if (node_fs_1.default.existsSync(p)) {
+            logger.debug(`Using built-in template: ${p}`);
+            return p;
+        }
+    }
+    logger.warn(`Could not find template for section: ${sectionName} (checked ${filename})`);
+    // Fallback: return the first potential path even if it doesn't exist, to let the caller handle the error
+    return potentialPaths[0];
+}
+exports.resolveTemplate = resolveTemplate;

package/manager.js

@@ -0,0 +1 @@
+import './dist/manager';

package/package.json

@@ -0,0 +1,153 @@
+{
+  "name": "storybook-addon-design-system-docs",
+  "version": "1.0.0",
+  "description": "Design System documentation that comes directly from your tailwind config.",
+  "author": "Saulo Vallory <https://saulo.engineer>",
+  "contributors": [
+    "Matan Yosef <https://github.com/matanio>"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/svallory/storybook-addon-design-system-docs"
+  },
+  "dependencies": {
+    "unplugin": "^1.12.0"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.3.11",
+    "@chromatic-com/storybook": "^4.1.3",
+    "@frontline-hq/recma-sections": "^1.0.8",
+    "@storybook/addon-a11y": "^10.1.11",
+    "@storybook/addon-docs": "^10.1.11",
+    "@storybook/addon-links": "^10.1.11",
+    "@storybook/addon-vitest": "^10.1.11",
+    "@storybook/mdx2-csf": "^1.1.0",
+    "@storybook/react-vite": "^10.1.11",
+    "@types/node": "^18.15.0",
+    "@types/react": "^18.2.65",
+    "@types/react-dom": "^18.2.21",
+    "@vitejs/plugin-react": "^4.2.1",
+    "@vitest/browser": "^2.1.9",
+    "@vitest/coverage-v8": "^2.1.9",
+    "auto": "^11.1.1",
+    "autoprefixer": "^10.4.23",
+    "boxen": "^7.1.1",
+    "dedent": "^1.5.1",
+    "nodemon": "^3.1.10",
+    "npm-run-all": "^4.1.5",
+    "playwright": "^1.57.0",
+    "postcss": "^8.5.6",
+    "prompts": "^2.4.2",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "storybook": "^10.1.11",
+    "tailwindcss": "^3.0.0 || ^4.0.0",
+    "tsup": "^8.5.0",
+    "typescript": "^5.4.2",
+    "vite": "^5.4.21",
+    "vitest": "^2.1.9",
+    "zx": "^7.2.3"
+  },
+  "peerDependencies": {
+    "tailwindcss": "^3.0.0 || ^4.0.0",
+    "react": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
+    "react-dom": "^16.8.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./preset": {
+      "types": "./dist/preset.d.ts",
+      "import": "./dist/preset.js",
+      "require": "./dist/preset.cjs"
+    },
+    "./manager": "./dist/manager.js",
+    "./components": {
+      "types": "./dist/components/primitives/index.d.ts",
+      "import": "./dist/components/primitives/index.js"
+    },
+    "./components/theme": {
+      "types": "./dist/components/primitives/index.d.ts",
+      "import": "./dist/components/primitives/index.js",
+      "require": "./dist/components/primitives/index.cjs"
+    },
+    "./components/assets": {
+      "types": "./dist/components/assets/index.d.ts",
+      "import": "./dist/components/assets/index.js",
+      "require": "./dist/components/assets/index.cjs"
+    },
+    "./assets": {
+      "types": "./dist/assets.d.ts",
+      "import": "./dist/assets.js",
+      "require": "./dist/assets.cjs"
+    },
+    "./mdx-templates/*": "./templates/*.mdx",
+    "./package.json": "./package.json"
+  },
+  "bundler": {
+    "exportEntries": [
+      "src/addon/index.ts",
+      "src/addon/assets.ts",
+      "src/addon/components/primitives/index.ts",
+      "src/addon/components/assets/index.ts"
+    ],
+    "managerEntries": [
+      "src/addon/manager.tsx"
+    ],
+    "nodeEntries": [
+      "src/addon/preset.ts"
+    ]
+  },
+  "files": [
+    "dist/**/*",
+    "templates",
+    "README.md",
+    "*.js",
+    "*.d.ts"
+  ],
+  "keywords": [
+    "tailwind",
+    "css",
+    "layout",
+    "appearance",
+    "style",
+    "design",
+    "system",
+    "auto",
+    "docs",
+    "storybook-addons"
+  ],
+  "license": "MIT",
+  "overrides": {
+    "storybook": "$storybook"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "build:watch": "bun run build -- --watch",
+    "test": "vitest",
+    "lint": "biome check src",
+    "lint:fix": "biome check src --write",
+    "format": "biome format src --write",
+    "start": "bun run build && run-p build:watch storybook:rebuild",
+    "prerelease": "zx scripts/prepublish-checks.js",
+    "release": "bun run build && auto shipit",
+    "storybook:rebuild": "nodemon --watch dist --exec \"storybook dev -p 6006 --no-open\"",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build"
+  },
+  "storybook": {
+    "displayName": "Design System Docs",
+    "supportedFrameworks": [
+      "react",
+      "vue"
+    ],
+    "icon": "https://user-images.githubusercontent.com/321738/63501763-88dbf600-c4cc-11e9-96cd-94adadc2fd72.png"
+  },
+  "type": "module"
+}

package/preset.js

@@ -0,0 +1,13 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+
+const preset = require('./dist/preset.cjs');
+
+export const managerEntries = (entry = []) => {
+    return [...entry, require.resolve('./dist/manager.js')];
+};
+
+export const experimental_indexers = preset.experimental_indexers;
+export const viteFinal = preset.viteFinal;
+export const stories = preset.stories;
+export const staticDirs = preset.staticDirs;

package/tailwind.config.js

@@ -0,0 +1,233 @@
+/** @type {import('tailwindcss').Config} */
+export default {
+    content: ['./index.html', './src/**/*.{js,ts,jsx,tsx}'],
+    theme: {
+        // A comprehensive design system example
+        extend: {
+            colors: {
+                // Primary brand colors
+                primary: {
+                    50: '#eff6ff',
+                    100: '#dbeafe',
+                    200: '#bfdbfe',
+                    300: '#93c5fd',
+                    400: '#60a5fa',
+                    500: '#3b82f6',
+                    600: '#2563eb',
+                    700: '#1d4ed8',
+                    800: '#1e40af',
+                    900: '#1e3a8a',
+                    950: '#172554',
+                },
+                // Secondary brand colors
+                secondary: {
+                    50: '#f8fafc',
+                    100: '#f1f5f9',
+                    200: '#e2e8f0',
+                    300: '#cbd5e1',
+                    400: '#94a3b8',
+                    500: '#64748b',
+                    600: '#475569',
+                    700: '#334155',
+                    800: '#1e293b',
+                    900: '#0f172a',
+                    950: '#020617',
+                },
+                // Accent colors
+                accent: {
+                    50: '#fefce8',
+                    100: '#fef9c3',
+                    200: '#fef08a',
+                    300: '#fde047',
+                    400: '#facc15',
+                    500: '#eab308',
+                    600: '#ca8a04',
+                    700: '#a16207',
+                    800: '#854d0e',
+                    900: '#713f12',
+                    950: '#422006',
+                },
+                // Semantic colors
+                success: {
+                    50: '#f0fdf4',
+                    100: '#dcfce7',
+                    200: '#bbf7d0',
+                    300: '#86efac',
+                    400: '#4ade80',
+                    500: '#22c55e',
+                    600: '#16a34a',
+                    700: '#15803d',
+                    800: '#166534',
+                    900: '#14532d',
+                    950: '#052e16',
+                },
+                warning: {
+                    50: '#fffbeb',
+                    100: '#fef3c7',
+                    200: '#fde68a',
+                    300: '#fcd34d',
+                    400: '#fbbf24',
+                    500: '#f59e0b',
+                    600: '#d97706',
+                    700: '#b45309',
+                    800: '#92400e',
+                    900: '#78350f',
+                    950: '#451a03',
+                },
+                error: {
+                    50: '#fef2f2',
+                    100: '#fee2e2',
+                    200: '#fecaca',
+                    300: '#fca5a5',
+                    400: '#f87171',
+                    500: '#ef4444',
+                    600: '#dc2626',
+                    700: '#b91c1c',
+                    800: '#991b1b',
+                    900: '#7f1d1d',
+                    950: '#450a0a',
+                },
+                // Custom red-ish colors (kept from original)
+                'red-ish': {
+                    100: '#ff0040',
+                    200: '#f12000',
+                    300: '#ff3202',
+                    400: '#ff0220',
+                    500: '#ff0120',
+                    600: '#e0011a',
+                    700: '#c00114',
+                    800: '#a0000e',
+                    900: '#800008',
+                },
+            },
+            fontSize: {
+                // Extra small sizes
+                xxs: '0.625rem',    // 10px
+                xs: '0.75rem',      // 12px
+                sm: '0.875rem',     // 14px
+                base: '1rem',       // 16px
+                lg: '1.125rem',     // 18px
+                xl: '1.25rem',      // 20px
+                // Large sizes
+                '2xl': '1.5rem',    // 24px
+                '3xl': '1.875rem',  // 30px
+                '4xl': '2.25rem',   // 36px
+                '5xl': '3rem',      // 48px
+                '6xl': '3.75rem',   // 60px
+                '7xl': '4.5rem',    // 72px
+                '8xl': '6rem',      // 96px
+                '9xl': '8rem',      // 128px
+            },
+            fontFamily: {
+                // Primary font families
+                sans: ['Inter', 'ui-sans-serif', 'system-ui', 'sans-serif'],
+                serif: ['ui-serif', 'Georgia', 'Cambria', 'Times New Roman', 'Times', 'serif'],
+                mono: ['ui-monospace', 'SFMono-Regular', 'Menlo', 'Monaco', 'Consolas', 'Liberation Mono', 'Courier New', 'monospace'],
+
+                // Custom font families
+                display: ['Inter', 'system-ui', 'sans-serif'],
+                code: ['SFMono-Regular', 'Menlo', 'monospace'],
+            },
+            fontWeight: {
+                thin: '100',
+                extralight: '200',
+                light: '300',
+                normal: '400',
+                medium: '500',
+                semibold: '600',
+                bold: '700',
+                extrabold: '800',
+                black: '900',
+            },
+            spacing: {
+                // 0.5 = 2px
+                0.5: '0.125rem',
+                // 1.5 = 6px
+                1.5: '0.375rem',
+                // 2.5 = 10px
+                2.5: '0.625rem',
+                // 3.5 = 14px
+                3.5: '0.875rem',
+                // 4.5 = 18px
+                4.5: '1.125rem',
+                // 5.5 = 22px
+                5.5: '1.375rem',
+                // 7 = 28px
+                7: '1.75rem',
+                // 9 = 36px
+                9: '2.25rem',
+                // 11 = 44px
+                11: '2.75rem',
+                // 12 = 48px
+                12: '3rem',
+                // 14 = 56px
+                14: '3.5rem',
+                // 16 = 64px
+                16: '4rem',
+                // 20 = 80px
+                20: '5rem',
+                // 24 = 96px
+                24: '6rem',
+                // 28 = 112px
+                28: '7rem',
+                // 32 = 128px
+                32: '8rem',
+                // 36 = 144px
+                36: '9rem',
+                // 40 = 160px
+                40: '10rem',
+                // 44 = 176px
+                44: '11rem',
+                // 48 = 192px
+                48: '12rem',
+                // 52 = 208px
+                52: '13rem',
+                // 56 = 224px
+                56: '14rem',
+                // 60 = 240px
+                60: '15rem',
+                // 64 = 256px
+                64: '16rem',
+                // 72 = 288px
+                72: '18rem',
+                // 80 = 320px
+                80: '20rem',
+                // 96 = 384px
+                96: '24rem',
+            },
+            boxShadow: {
+                // Custom shadows
+                'xs': '0 1px 2px 0 rgba(0, 0, 0, 0.05)',
+                'sm': '0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)',
+                'md': '0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)',
+                'lg': '0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)',
+                'xl': '0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)',
+                '2xl': '0 25px 50px -12px rgba(0, 0, 0, 0.25)',
+                '3xl': '0 35px 60px -15px rgba(0, 0, 0, 0.3)',
+                'inner': 'inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)',
+                'none': 'none',
+                // Colored shadows
+                'primary': '0 4px 6px -1px rgba(59, 130, 246, 0.3), 0 2px 4px -1px rgba(59, 130, 246, 0.2)',
+                'accent': '0 4px 6px -1px rgba(234, 179, 8, 0.3), 0 2px 4px -1px rgba(234, 179, 8, 0.2)',
+                'success': '0 4px 6px -1px rgba(34, 197, 94, 0.3), 0 2px 4px -1px rgba(34, 197, 94, 0.2)',
+                'error': '0 4px 6px -1px rgba(239, 68, 68, 0.3), 0 2px 4px -1px rgba(239, 68, 68, 0.2)',
+            },
+            borderRadius: {
+                'none': '0px',
+                'sm': '0.125rem',      // 2px
+                DEFAULT: '0.25rem',    // 4px
+                'md': '0.375rem',      // 6px
+                'lg': '0.5rem',        // 8px
+                'xl': '0.75rem',       // 12px
+                '2xl': '1rem',         // 16px
+                '3xl': '1.5rem',       // 24px
+                'full': '9999px',
+                // Custom sizes
+                '4xl': '2rem',         // 32px
+                '5xl': '2.5rem',       // 40px
+                '6xl': '3rem',         // 48px
+            },
+        },
+    },
+    plugins: [],
+};

package/templates/assets.mdx

@@ -0,0 +1,29 @@
+{/**
+ * Asset Documentation Template
+ *
+ * This template is used to render asset documentation pages (Icons, Illustrations, etc.).
+ * The `assetGroup` import is automatically resolved to the specific asset group's data
+ * based on which virtual MDX file is being processed.
+ *
+ * Users can override this template by creating:
+ * .storybook/design-system-docs/assets.mdx
+ *
+ * The <Meta title="..." /> tag is injected automatically by the unplugin.
+ */}
+
+import { Meta } from "@storybook/addon-docs/blocks";
+import { AssetSection } from 'storybook-addon-design-system-docs/components/assets';
+import assetGroup from 'design-system-docs:assets/{{group.name}}';
+
+<Meta title="Assets/{{group.name}}" />
+
+<AssetSection
+    title="{{group.title}}"
+    description={assetGroup.config.description}
+    assets={assetGroup.assets}
+    groupByFolder={assetGroup.config.groupByFolder}
+    variants={assetGroup.config.variants}
+    copy={assetGroup.config.copy}
+    display={assetGroup.config.display}
+    storageKeyPrefix={`assets-{{group.name}}`}
+/>