@revikornmann/muka-ui 0.2.1

package/docs/consumers/setup-instructions.md

@@ -0,0 +1,57 @@
+# Muka UI consumer setup
+
+Canonical, version-locked setup steps for a repo that consumes Muka UI. When
+Muka is installed, this file ships inside the package at
+`node_modules/@revikornmann/muka-ui/docs/consumers/setup-instructions.md`, so
+the `/setup-muka` skill reads it from there and it always matches the installed
+version.
+
+Muka UI is a **public npm package** — installing it needs no `.npmrc`, registry
+configuration, or auth token.
+
+## 1. Install
+
+```bash
+npm install @revikornmann/muka-ui@latest --save
+```
+
+Import styles and components in your app root:
+
+```ts
+import '@revikornmann/muka-ui/styles';
+import { Button } from '@revikornmann/muka-ui';
+```
+
+For a brand theme, also load the brand CSS and set the data attributes (replace
+`bouwflow` with your brand):
+
+```ts
+import '@revikornmann/muka-ui/styles/tokens-bouwflow-light.css';
+```
+
+```html
+<html data-brand="bouwflow" data-theme="light">
+```
+
+## 2. Add the auto-update workflow
+
+Copy the shipped template into your repo so it stays current with Muka releases:
+
+```bash
+mkdir -p .github/workflows
+cp node_modules/@revikornmann/muka-ui/templates/update-muka.yml \
+  .github/workflows/update-muka.yml
+```
+
+This workflow listens for the `muka-released` dispatch and installs the exact
+published version. You can also run it manually from the Actions tab
+(installs `@latest`). The package is public, so it needs no secrets to install.
+
+## 3. Register as a consumer
+
+Add `owner/repo` to Muka's [`.github/consumers.txt`](../../.github/consumers.txt)
+so the release pipeline dispatches updates here. The `/setup-muka` skill opens
+this PR automatically; merge it to enable automatic updates.
+
+The Muka `CONSUMER_DISPATCH_TOKEN` PAT must have **write** access to this repo
+for the `repository_dispatch` to succeed.

package/package.json

@@ -0,0 +1,147 @@
+{
+  "name": "@revikornmann/muka-ui",
+  "version": "0.2.1",
+  "description": "Muka Design System - Multi-brand design tokens and React components",
+  "main": "dist/cjs/components/index.js",
+  "module": "dist/esm/components/index.js",
+  "types": "dist/types/components/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/components/index.d.ts",
+      "import": "./dist/esm/components/index.js",
+      "require": "./dist/cjs/components/index.js"
+    },
+    "./styles": "./dist/styles/index.css",
+    "./styles/*": "./dist/styles/*",
+    "./build": "./scripts/build-tokens.js",
+    "./tokens/*": "./tokens/*",
+    "./manifest": "./build/manifest.json",
+    "./package.json": "./package.json"
+  },
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "bin": {
+    "muka-ui": "./cli/bin/muka-ui.js"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "skills",
+    "scripts/build-tokens.js",
+    "scripts/postinstall-nudge.js",
+    "tokens",
+    "build/manifest.json",
+    "docs/consumers",
+    "templates"
+  ],
+  "scripts": {
+    "build": "npm run build:tokens && npm run build:components && npm run build:styles",
+    "build:tokens": "node scripts/build-tokens.js",
+    "build:components": "npm run build:esm && npm run build:cjs && npm run build:types",
+    "build:styles": "node scripts/build-styles.js",
+    "build:esm": "tsc --project tsconfig.esm.json",
+    "build:cjs": "tsc --project tsconfig.cjs.json",
+    "build:types": "tsc --project tsconfig.types.json",
+    "dev": "npm run storybook",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build",
+    "test": "vitest",
+    "test:unit": "vitest run --config vitest.config.ts",
+    "test:visual": "vitest run --config vitest.browser.config.ts",
+    "test:visual:update": "vitest run --config vitest.browser.config.ts -u",
+    "test:stories": "vitest run --config vitest.stories.config.ts",
+    "test:stories:watch": "vitest --config vitest.stories.config.ts",
+    "test:stories:ui": "vitest --config vitest.stories.config.ts --ui",
+    "test:all": "npm run test:unit && npm run test:visual && npm run test:stories",
+    "test:ui": "vitest --ui",
+    "figma:connect": "figma-code-connect",
+    "figma:connect:dev": "figma-code-connect --dev",
+    "figma:connect:publish": "figma-code-connect --publish",
+    "lint": "eslint .",
+    "validate:tokens": "node scripts/validate-tokens.js",
+    "setup:automation": "node scripts/setup-automation.js",
+    "disable:automation": "node scripts/disable-automation.js",
+    "enable:automation": "node scripts/enable-automation.js",
+    "check:automation": "node scripts/check-automation-status.js",
+    "sync:skills": "node scripts/sync-shipped-skills.js",
+    "prepack": "node scripts/sync-shipped-skills.js",
+    "postinstall": "node scripts/postinstall-nudge.js",
+    "prepare": "husky || true"
+  },
+  "keywords": [
+    "design-system",
+    "design-tokens",
+    "react",
+    "multi-brand",
+    "ai-design-system"
+  ],
+  "author": "Revi Körnmann",
+  "license": "MIT",
+  "dependencies": {
+    "@radix-ui/react-accordion": "^1.2.12",
+    "@radix-ui/react-context-menu": "^2.2.16",
+    "@radix-ui/react-dropdown-menu": "^2.1.16",
+    "@radix-ui/react-popover": "^1.1.15",
+    "@radix-ui/react-tooltip": "^1.2.8",
+    "@remixicon/react": "^4.9.0",
+    "glob": "^11.0.3",
+    "pdfjs-dist": "^5.4.624",
+    "react-pdf": "^10.4.1",
+    "vaul": "^1.1.2"
+  },
+  "peerDependencies": {
+    "react": ">=16.8.0",
+    "react-dom": ">=16.8.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.39.4",
+    "@figma/code-connect": "^1.3.8",
+    "@playwright/test": "^1.56.1",
+    "@storybook/addon-a11y": "^10.3.4",
+    "@storybook/addon-designs": "^11.1.3",
+    "@storybook/addon-docs": "^10.3.4",
+    "@storybook/addon-mcp": "^0.5.0",
+    "@storybook/addon-onboarding": "^10.3.4",
+    "@storybook/addon-vitest": "^10.3.4",
+    "@storybook/react-vite": "^10.3.4",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.0",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^18.0.0",
+    "@types/react-dom": "^18.0.0",
+    "@vitejs/plugin-react": "^4.7.0",
+    "@vitest/browser": "^4.1.9",
+    "@vitest/browser-playwright": "^4.1.9",
+    "@vitest/coverage-v8": "^4.1.9",
+    "@vitest/ui": "^4.1.9",
+    "eslint": "^9.39.4",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^5.2.0",
+    "globals": "^17.6.0",
+    "husky": "^9.1.7",
+    "playwright": "^1.56.1",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "storybook": "^10.3.4",
+    "typescript": "^5.0.0",
+    "typescript-eslint": "^8.59.2",
+    "vitest": "^4.1.9"
+  },
+  "overrides": {
+    "esbuild": ">=0.28.1"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/revikornmann/muka.git"
+  },
+  "bugs": {
+    "url": "https://github.com/revikornmann/muka/issues"
+  },
+  "homepage": "https://muka.kornmann.com",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/scripts/build-tokens.js

@@ -0,0 +1,469 @@
+const fs = require('fs');
+const path = require('path');
+const glob = require('glob');
+
+/**
+ * Token builder that uses the manifest.json to build themes correctly.
+ *
+ * @param {Object} [options]
+ * @param {string} [options.rootDir] - Project root for resolving token paths.
+ *   Defaults to the muka-ui package root (one level above this script).
+ *   Consumer repos pass their own project root so that manifest patterns
+ *   like "node_modules/muka-ui/tokens/..." resolve correctly.
+ */
+class TokenBuilder {
+  constructor(options = {}) {
+    this.rootDir = options.rootDir || path.join(__dirname, '..');
+    this.manifest = null;
+    this.tokens = {};
+  }
+
+  // Load manifest configuration.
+  // Accepts an optional manifest object directly (for external consumers).
+  loadManifest(manifestObj) {
+    if (manifestObj) {
+      this.manifest = manifestObj;
+    } else {
+      const manifestPath = path.join(this.rootDir, 'build/manifest.json');
+      this.manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    }
+    console.log('📋 Loaded manifest configuration');
+  }
+
+  // Load and merge tokens from file patterns
+  loadTokensFromPattern(pattern) {
+    const tokensDir = path.join(this.rootDir, 'tokens');
+    const fullPattern = path.join(this.rootDir, pattern);
+    
+    const files = glob.sync(fullPattern);
+    let mergedTokens = {};
+    
+    files.forEach(file => {
+      try {
+        const tokenData = JSON.parse(fs.readFileSync(file, 'utf8'));
+        this.deepMerge(mergedTokens, tokenData);
+        console.log(`   ✅ Loaded ${path.relative(tokensDir, file)}`);
+      } catch (error) {
+        console.log(`   ⚠️  Error loading ${path.relative(tokensDir, file)}: ${error.message}`);
+      }
+    });
+    return mergedTokens;
+  }
+
+  // Deep merge utility
+  deepMerge(target, source) {
+    for (const key in source) {
+      if (key.startsWith('$')) continue; // Skip metadata
+      
+      if (source[key] && typeof source[key] === 'object' && !source[key].$value) {
+        if (!target[key]) target[key] = {};
+        this.deepMerge(target[key], source[key]);
+      } else {
+        target[key] = source[key];
+      }
+    }
+  }
+
+  // Resolve token references like {color.gray.9}
+  resolveTokenValue(value, tokens, visited = new Set()) {
+    if (typeof value !== 'string' || !value.includes('{')) {
+      return value;
+    }
+
+    const tokenRef = value.match(/\{([^}]+)\}/);
+    if (!tokenRef) return value;
+
+    const tokenPath = tokenRef[1];
+    
+    // Prevent circular references
+    if (visited.has(tokenPath)) {
+      console.warn(`⚠️  Circular reference detected: ${tokenPath}`);
+      return value;
+    }
+    
+    visited.add(tokenPath);
+    
+    const resolvedValue = this.getTokenValue(tokenPath, tokens);
+    if (resolvedValue !== null) {
+      // If the resolved value is non-string (array/object), return it directly
+      // when the reference is the entire value (not embedded in a larger string)
+      if (typeof resolvedValue !== 'string' && value === tokenRef[0]) {
+        return resolvedValue;
+      }
+      const newValue = value.replace(tokenRef[0], resolvedValue);
+      return this.resolveTokenValue(newValue, tokens, visited);
+    }
+    
+    return value;
+  }
+
+  /**
+   * Fix invalid rgba( #hex, alpha) → rgba(r, g, b, alpha).
+   * CSS rgba() does not accept hex; it requires numeric RGB values.
+   */
+  fixRgbaHexValues(value) {
+    if (typeof value !== 'string') return value;
+    return value.replace(
+      /rgba\(\s*#([0-9a-fA-F]{3}|[0-9a-fA-F]{6}),\s*([\d.]+)\s*\)/g,
+      (_, hex, alpha) => {
+        let r, g, b;
+        if (hex.length === 3) {
+          r = parseInt(hex[0] + hex[0], 16);
+          g = parseInt(hex[1] + hex[1], 16);
+          b = parseInt(hex[2] + hex[2], 16);
+        } else {
+          r = parseInt(hex.slice(0, 2), 16);
+          g = parseInt(hex.slice(2, 4), 16);
+          b = parseInt(hex.slice(4, 6), 16);
+        }
+        return `rgba(${r}, ${g}, ${b}, ${alpha})`;
+      }
+    );
+  }
+
+  // Get token value by path (e.g., "color.gray.9")
+  getTokenValue(tokenPath, tokens) {
+    const pathParts = tokenPath.split('.');
+    let current = tokens;
+    
+    for (const part of pathParts) {
+      if (current && current[part]) {
+        current = current[part];
+      } else {
+        return null;
+      }
+    }
+    
+    return current && current.$value ? current.$value : null;
+  }
+
+  // Resolve all token references in a token object
+  resolveAllReferences(tokens) {
+    const processObject = (obj) => {
+      if (typeof obj !== 'object' || obj === null) return obj;
+      
+      if (obj.$value) {
+        if (typeof obj.$value === 'string') {
+          obj.$value = this.resolveTokenValue(obj.$value, tokens);
+        } else if (typeof obj.$value === 'object' && !Array.isArray(obj.$value)) {
+          // Resolve references inside composite token values (border, etc.)
+          for (const key in obj.$value) {
+            if (typeof obj.$value[key] === 'string') {
+              obj.$value[key] = this.resolveTokenValue(obj.$value[key], tokens);
+            }
+          }
+        } else if (Array.isArray(obj.$value)) {
+          // Resolve references inside array values (boxShadow layers, etc.)
+          obj.$value = obj.$value.map(item => {
+            if (typeof item === 'object' && item !== null) {
+              // Process each property in array items
+              const resolvedItem = {};
+              for (const key in item) {
+                if (typeof item[key] === 'string') {
+                  resolvedItem[key] = this.resolveTokenValue(item[key], tokens);
+                } else {
+                  resolvedItem[key] = item[key];
+                }
+              }
+              return resolvedItem;
+            }
+            return item;
+          });
+        }
+        return obj;
+      }
+      
+      for (const key in obj) {
+        if (Object.hasOwn(obj, key)) {
+          obj[key] = processObject(obj[key]);
+        }
+      }
+      
+      return obj;
+    };
+    
+    return processObject(tokens);
+  }
+
+  // Resolve override token references using the base (fully resolved) tokens as context
+  resolveOverrideTokens(overrideTokens, contextTokens) {
+    const resolved = JSON.parse(JSON.stringify(overrideTokens));
+
+    const processObject = (obj) => {
+      if (typeof obj !== 'object' || obj === null) return obj;
+      if (obj.$value) {
+        if (typeof obj.$value === 'string') {
+          obj.$value = this.resolveTokenValue(obj.$value, contextTokens);
+        }
+        return obj;
+      }
+      for (const key in obj) {
+        if (key.startsWith('$')) continue;
+        if (Object.hasOwn(obj, key)) {
+          obj[key] = processObject(obj[key]);
+        }
+      }
+      return obj;
+    };
+
+    return processObject(resolved);
+  }
+
+  // Convert tokens to CSS custom properties
+  generateCSS(tokens, brand = null, theme = null) {
+    let css = '';
+    const selector = brand && theme
+      ? `[data-brand="${brand}"][data-theme="${theme}"]`
+      : ':root';
+    
+    if (brand && theme) {
+      css += `/* Muka Design System - ${brand} ${theme} theme */\n`;
+      css += `/* Generated automatically from design tokens */\n\n`;
+    } else {
+      css += `/* Muka Design System Tokens */\n`;
+      css += `/* Generated automatically from design tokens */\n\n`;
+    }
+
+    css += `${selector} {\n`;
+    
+    this.processTokensForCSS(tokens, '', (name, value) => {
+      let resolvedValue = this.resolveTokenValue(value, tokens);
+      resolvedValue = this.fixRgbaHexValues(resolvedValue);
+      css += `  --${name}: ${resolvedValue};\n`;
+    });
+    
+    css += '}\n';
+
+    // Responsive @media overrides from breakpoint override files
+    css += this.generateBreakpointCSS(tokens, selector);
+
+    // Layout mode forcing (for Storybook / design tools)
+    css += this.generateLayoutModeCSS(tokens);
+    
+    // Add root fallback for default theme
+    if (brand === 'muka' && theme === 'light') {
+      css += '\n/* Default theme fallback */\n:root {\n';
+      this.processTokensForCSS(tokens, '', (name, value) => {
+        let resolvedValue = this.resolveTokenValue(value, tokens);
+        resolvedValue = this.fixRgbaHexValues(resolvedValue);
+        css += `  --${name}: ${resolvedValue};\n`;
+      });
+      css += '}\n';
+
+      // Responsive overrides for :root fallback
+      css += this.generateBreakpointCSS(tokens, ':root');
+
+      // Layout mode forcing for :root fallback
+      css += this.generateLayoutModeCSS(tokens);
+    }
+    
+    return css;
+  }
+
+  // Recursively process tokens for CSS generation
+  processTokensForCSS(obj, prefix, callback) {
+    for (const [key, value] of Object.entries(obj)) {
+      if (key.startsWith('$')) continue; // Skip metadata
+      
+      const cssName = prefix ? `${prefix}-${key}` : key;
+      
+      if (value && typeof value === 'object' && value.$value !== undefined) {
+        // This is a token with a value
+        if (value.$type === 'typography' && typeof value.$value === 'object') {
+          // Handle typography tokens specially - flatten the object
+          for (const [prop, propValue] of Object.entries(value.$value)) {
+            const resolvedPropValue = this.resolveTokenValue(propValue, obj);
+            callback(`${cssName}-${prop}`, resolvedPropValue);
+          }
+        } else if (value.$type === 'border' && typeof value.$value === 'object') {
+          // Handle border composite tokens: { color, width, style } → "width style color"
+          const color = this.resolveTokenValue(value.$value.color, obj);
+          const width = this.resolveTokenValue(value.$value.width, obj);
+          const style = value.$value.style || 'solid';
+          callback(cssName, `${width} ${style} ${color}`);
+        } else if (value.$type === 'boxShadow' && Array.isArray(value.$value)) {
+          // Handle boxShadow composite tokens: array of layers → CSS box-shadow
+          const shadowStr = value.$value.map(layer => {
+            const inset = layer.type === 'innerShadow' ? 'inset ' : '';
+            const color = this.resolveTokenValue(layer.color, obj);
+            return `${inset}${layer.x} ${layer.y} ${layer.blur} ${layer.spread} ${color}`;
+          }).join(', ');
+          callback(cssName, shadowStr);
+        } else {
+          // Regular token with simple value
+          const resolvedValue = this.resolveTokenValue(value.$value, obj);
+          callback(cssName, resolvedValue);
+        }
+      } else if (value && typeof value === 'object' && !value.$value) {
+        // This is a nested object, recurse
+        this.processTokensForCSS(value, cssName, callback);
+      }
+    }
+  }
+
+  // Load and resolve a breakpoint override file against the base tokens
+  loadBreakpointOverride(filePath, baseTokens) {
+    const fullPath = path.join(this.rootDir, filePath);
+    if (!fs.existsSync(fullPath)) {
+      console.warn(`   ⚠️  Breakpoint file not found: ${filePath}`);
+      return null;
+    }
+
+    try {
+      const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
+      return this.resolveOverrideTokens(raw, baseTokens);
+    } catch (error) {
+      console.warn(`   ⚠️  Error loading breakpoint file ${filePath}: ${error.message}`);
+      return null;
+    }
+  }
+
+  // Get breakpoint definitions sorted ascending by min-width
+  getSortedBreakpoints(tokens) {
+    const bpConfig = this.manifest.breakpoints || {};
+    const bpTokens = tokens.breakpoint;
+    if (!bpTokens || Object.keys(bpConfig).length === 0) return [];
+
+    const breakpoints = [];
+    for (const [bpName, filePath] of Object.entries(bpConfig)) {
+      const token = bpTokens[bpName];
+      if (!token || !token.$value) {
+        console.warn(`   ⚠️  No breakpoint primitive found for "${bpName}"`);
+        continue;
+      }
+      breakpoints.push({ name: bpName, value: token.$value, filePath });
+    }
+
+    breakpoints.sort((a, b) => parseFloat(a.value) - parseFloat(b.value));
+    return breakpoints;
+  }
+
+  // Generate @media blocks from breakpoint override files (for production)
+  generateBreakpointCSS(tokens, selector) {
+    let css = '';
+    const breakpoints = this.getSortedBreakpoints(tokens);
+
+    for (const bp of breakpoints) {
+      const overrideTokens = this.loadBreakpointOverride(bp.filePath, tokens);
+      if (!overrideTokens) continue;
+
+      css += `\n/* Responsive overrides: ${bp.name} (min-width: ${bp.value}) */\n`;
+      css += `@media (min-width: ${bp.value}) {\n`;
+      css += `  ${selector} {\n`;
+      this.processTokensForCSS(overrideTokens, '', (name, value) => {
+        let resolvedValue = this.fixRgbaHexValues(value);
+        css += `    --${name}: ${resolvedValue};\n`;
+      });
+      css += `  }\n`;
+      css += `}\n`;
+    }
+
+    return css;
+  }
+
+  // Generate [data-layout] blocks for Storybook / design tool forcing
+  generateLayoutModeCSS(tokens) {
+    let css = '';
+    const breakpoints = this.getSortedBreakpoints(tokens);
+
+    // Map breakpoint names to human-friendly layout mode names
+    const layoutModeNames = { sm: 'mobile', md: 'tablet', lg: 'desktop', xl: 'widescreen' };
+
+    for (const bp of breakpoints) {
+      const modeName = layoutModeNames[bp.name] || bp.name;
+      const overrideTokens = this.loadBreakpointOverride(bp.filePath, tokens);
+      if (!overrideTokens) continue;
+
+      css += `\n/* Layout mode: ${modeName} (forced via data-layout attribute) */\n`;
+      css += `[data-layout="${modeName}"] {\n`;
+      this.processTokensForCSS(overrideTokens, '', (name, value) => {
+        let resolvedValue = this.fixRgbaHexValues(value);
+        css += `  --${name}: ${resolvedValue};\n`;
+      });
+      css += `}\n`;
+    }
+
+    return css;
+  }
+
+  // Build tokens for Storybook
+  async build() {
+    console.log('🚀 Building design tokens for Storybook...\n');
+    
+    try {
+      // Load manifest (skip if already loaded via loadManifest(obj))
+      if (!this.manifest) {
+        this.loadManifest();
+      }
+      
+      // Ensure output directory exists
+      const outputDir = path.join(this.rootDir, 'styles');
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true });
+      }
+      
+      // Build all themes
+      this.buildAllThemes();
+      
+    } catch (error) {
+      console.error('❌ Error building tokens:', error);
+      process.exit(1);
+    }
+  }
+
+  // Build all brand/theme combinations
+  buildAllThemes() {
+    console.log('\n🎨 Building brand/theme combinations...\n');
+    
+    const themes = Object.keys(this.manifest.themes);
+    
+    themes.forEach(themeName => {
+      console.log(`📦 Building ${themeName}...`);
+      
+      try {
+        // Load tokens for this theme
+        const tokens = this.loadTokensForTheme(themeName);
+        
+        // Resolve all token references
+        const resolvedTokens = this.resolveAllReferences(tokens);
+        
+        // Generate CSS
+        const css = this.generateCSS(resolvedTokens);
+        
+        // Write CSS file
+        const outputDir = path.join(this.rootDir, 'styles');
+        const outputPath = path.join(outputDir, `tokens-${themeName}.css`);
+        fs.writeFileSync(outputPath, css);
+        
+        console.log(`   ✅ Generated: tokens-${themeName}.css`);
+      } catch (error) {
+        console.error(`   ❌ Error building ${themeName}:`, error.message);
+      }
+    });
+    
+    console.log('\n🎉 All theme combinations built successfully!');
+  }
+
+  // Load tokens for a specific theme
+  loadTokensForTheme(themeName) {
+    const themeFiles = this.manifest.themes[themeName];
+    let mergedTokens = {};
+    
+    console.log(`🏗️  Loading design tokens for ${themeName}...`);
+    
+    themeFiles.forEach(filePattern => {
+      const tokens = this.loadTokensFromPattern(filePattern);
+      this.deepMerge(mergedTokens, tokens);
+    });
+    
+    return mergedTokens;
+  }
+}
+
+// Run the build if this file is executed directly
+if (require.main === module) {
+  const builder = new TokenBuilder();
+  builder.build();
+}
+
+module.exports = TokenBuilder;

package/scripts/postinstall-nudge.js

@@ -0,0 +1,26 @@
+/**
+ * postinstall nudge
+ *
+ * Printed when a consumer installs @revikornmann/muka-ui. It only PRINTS — it
+ * never writes into the consumer's repo — because silently touching a project's
+ * `.claude/` from a dependency is intrusive, and postinstall is skipped under
+ * `--ignore-scripts` / many CI setups anyway.
+ *
+ * Guard: when muka installs its OWN dev dependencies this file runs from the
+ * repo root (not under node_modules), so we skip the nudge there.
+ */
+
+// If we're not inside a node_modules tree, this is muka's own install — skip.
+if (!__dirname.includes(`${require('path').sep}node_modules${require('path').sep}`)) {
+  process.exit(0);
+}
+
+console.log(`
+🎨 Muka UI installed.
+
+Finish setup in Claude Code:
+  1. npx muka-ui install-skill   # makes /setup-muka available
+  2. /setup-muka [brand]         # installs styles + auto-update workflow
+
+Docs: node_modules/@revikornmann/muka-ui/docs/consumers/setup-instructions.md
+`);