@fr0mpy/component-system 2.2.0 → 3.1.0

package/README.md

@@ -1,6 +1,6 @@
 # @fr0mpy/component-system
 
-Claude Code UI styling system with design tokens, 36 component recipes, and visual preview harness.
+Claude Code UI styling system with multi-theme support, design tokens, component agents, 40 Base UI recipes, and Playwright testing.
 
 ## Installation
 
@@ -10,36 +10,92 @@ npx @fr0mpy/component-system
 
 ## What's Included
 
-- **skills/** - Styling skill for consistent UI generation
-- **component-recipes/** - 36 pre-built component templates (button, card, modal, toast, etc.)
-- **commands/** - `/setup-styling` and `/component-harness`
+| Directory | Purpose |
+|-----------|---------|
+| `skills/` | Styling + React patterns skills |
+| `agents/` | 5 component system agents |
+| `component-recipes/` | 40 Base UI component templates |
+| `playwright-templates/` | Playwright test config + component specs |
+| `commands/` | `/setup-styling`, `/component-harness`, `/save-theme`, `/retheme` |
+| `.mcp.json` | Playwright MCP server configuration |
 
-## Features
+## Multi-Theme System
 
-### Design Tokens
+Create and switch between multiple themes in real-time:
 
-Run `/setup-styling` to configure your design system interactively. Generates `styling-config.json` with:
+```
+.claude/
+├── styling-config.json     # Active theme config
+├── themes/                  # Saved themes
+│   ├── stripe-inspired.json
+│   ├── matrix.json
+│   └── vercel-dark.json
+└── component-recipes/       # Component templates
+```
+
+### Workflow
+
+1. **Create themes** via `/setup-styling`:
+   - Extract from URL (analyzes any website's design system)
+   - Manual configuration (answer questions about colors, typography)
+   - Saves to both `styling-config.json` and `themes/{name}.json`
+
+2. **Switch themes** in the component harness:
+   - ThemeSwitcher dropdown loads all `.claude/themes/*.json`
+   - Live switching via CSS variable injection
+   - No page reload required
+
+3. **Quick commands**:
+   - `/save-theme [name]` - Save current config as a named theme
+   - `/retheme` - Regenerate CSS from current config
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/setup-styling` | Configure design tokens, creates theme |
+| `/component-harness` | Launch visual preview with theme switcher |
+| `/save-theme` | Save current config as named theme |
+| `/retheme` | Regenerate harness CSS from config |
+
+## Agents (5)
+
+| Agent | Purpose |
+|-------|---------|
+| style-inspector | Reverse-engineers website design systems from URLs |
+| design-token-validator | Audits components for token compliance |
+| component-auditor | Validates recipe compliance, a11y, React patterns |
+| harness-scaffolder | Scaffolds Vite preview gallery from recipes |
+| playwright-tester | Tests components via Playwright MCP with Axe a11y |
+
+## Skills (2)
+
+| Skill | Purpose |
+|-------|---------|
+| styling | Enforces design token usage, mobile-first patterns, recipe compliance |
+| react-patterns | Enforces Rules of Hooks and correct state/effect patterns |
 
-- Colors (primary, secondary, destructive, muted, etc.)
-- Border radius
-- Shadows
-- Spacing
-- Typography
+## Component Recipes (40)
 
-### Component Recipes
+| Category | Components |
+|----------|------------|
+| **Form (10)** | button, input, textarea, select, combobox, checkbox, radio, switch, slider, label |
+| **Layout (6)** | card, separator, collapsible, accordion, tabs, table |
+| **Navigation (5)** | navigation-menu, breadcrumb, pagination, dropdown-menu, context-menu |
+| **Overlay (6)** | modal, dialog, drawer, popover, hover-card, tooltip |
+| **Feedback (5)** | alert, toast, progress, skeleton, spinner |
+| **Display (4)** | badge, avatar, carousel, toggle-group |
 
-36 component recipes organized by category:
+All recipes use [Base UI](https://base-ui.com) headless primitives for accessibility with Tailwind CSS styling.
 
-- **Form** (10): button, input, textarea, select, combobox, checkbox, radio, switch, slider, label
-- **Layout** (6): card, separator, collapsible, accordion, tabs, table
-- **Navigation** (5): navigation-menu, breadcrumb, pagination, dropdown-menu, context-menu
-- **Overlay** (6): modal, dialog, drawer, popover, hover-card, tooltip
-- **Feedback** (5): alert, toast, progress, skeleton, spinner
-- **Display** (4): badge, avatar, carousel, toggle-group
+## Component Harness
 
-### Component Harness
+Run `/component-harness` to scaffold a Vite + React preview environment:
 
-Run `/component-harness` to scaffold a Vite + React development environment for visual component preview.
+- **Theme Switcher** - Dropdown to switch between saved themes
+- **Live Preview** - All 40 components with variants
+- **Instant Updates** - CSS variable injection, no page reload
+- **Playwright Testing** - Visual + accessibility testing via MCP
 
 ## Usage
 
@@ -47,13 +103,14 @@ Run `/component-harness` to scaffold a Vite + React development environment for
 # Initialize
 npx @fr0mpy/component-system
 
-# With options
+# Options
 npx @fr0mpy/component-system --force   # Overwrite existing
 npx @fr0mpy/component-system --merge   # Add to existing .claude
 npx @fr0mpy/component-system --remove  # Remove installation
 
 # Selective updates
 npx @fr0mpy/component-system --update-skills
+npx @fr0mpy/component-system --update-agents
 npx @fr0mpy/component-system --update-recipes
 npx @fr0mpy/component-system --update-commands
 ```
@@ -61,18 +118,20 @@ npx @fr0mpy/component-system --update-commands
 ## Getting Started
 
 1. Install: `npx @fr0mpy/component-system`
-2. Configure: Use `/setup-styling` to set up your design tokens
-3. Preview: Use `/component-harness` to launch visual preview
+2. Configure: `/setup-styling` to create your first theme
+3. Preview: `/component-harness` to launch visual gallery
+4. Add themes: Run `/setup-styling` again to create more themes
+5. Switch: Use the ThemeSwitcher dropdown in the harness
 
 ## Integration with Prompt System
 
-For auto-triggering styling rules when you mention UI/styling keywords, also install:
+For additional agents and context management:
 
 ```bash
 npx @fr0mpy/prompt-system
 ```
 
-When both packages are installed, the component system injects a `styling.json` trigger into the prompt system's `triggers.d/` directory.
+Skills are automatically discovered via their `USE WHEN` descriptions in YAML frontmatter.
 
 ## License
 

package/bin/cli.js

@@ -5,6 +5,7 @@ const path = require('path');
 
 const TEMPLATES_DIR = path.join(__dirname, '..', 'templates');
 const TARGET_DIR = path.join(process.cwd(), '.claude');
+const PROJECT_ROOT = process.cwd();
 const args = process.argv.slice(2);
 
 // Parse flags
@@ -16,7 +17,8 @@ const helpMode = hasFlag('--help', '-h');
 const updateSkills = hasFlag('--update-skills');
 const updateRecipes = hasFlag('--update-recipes');
 const updateCommands = hasFlag('--update-commands');
-const updateMode = updateSkills || updateRecipes || updateCommands;
+const updateAgents = hasFlag('--update-agents');
+const updateMode = updateSkills || updateRecipes || updateCommands || updateAgents;
 
 function copyDir(src, dest) {
   fs.mkdirSync(dest, { recursive: true });
@@ -52,37 +54,20 @@ function copySubdir(subdir) {
   return true;
 }
 
-function injectTriggers() {
-  const triggersDDir = path.join(TARGET_DIR, 'hooks', 'triggers.d');
-  if (!fs.existsSync(triggersDDir)) return false;
-
-  const triggers = ['styling.json', 'react-patterns.json'];
-  let injected = false;
-
-  for (const trigger of triggers) {
-    const src = path.join(TEMPLATES_DIR, 'hooks', 'triggers.d', trigger);
-    const dest = path.join(triggersDDir, trigger);
-    if (fs.existsSync(src)) {
-      fs.copyFileSync(src, dest);
-      injected = true;
-    }
+function mergeJsonFile(src, dest) {
+  if (!fs.existsSync(src)) return false;
+  const srcData = JSON.parse(fs.readFileSync(src, 'utf8'));
+  let destData = {};
+  if (fs.existsSync(dest)) {
+    try { destData = JSON.parse(fs.readFileSync(dest, 'utf8')); } catch (e) { /* invalid JSON */ }
   }
-  return injected;
-}
-
-function removeTriggers() {
-  const triggersDDir = path.join(TARGET_DIR, 'hooks', 'triggers.d');
-  const triggers = ['styling.json', 'react-patterns.json'];
-  let removed = false;
-
-  for (const trigger of triggers) {
-    const triggerPath = path.join(triggersDDir, trigger);
-    if (fs.existsSync(triggerPath)) {
-      fs.unlinkSync(triggerPath);
-      removed = true;
-    }
+  const merged = { ...destData, ...srcData };
+  // Deep merge mcpServers if both exist
+  if (destData.mcpServers && srcData.mcpServers) {
+    merged.mcpServers = { ...destData.mcpServers, ...srcData.mcpServers };
   }
-  return removed;
+  fs.writeFileSync(dest, JSON.stringify(merged, null, 2) + '\n');
+  return true;
 }
 
 async function init() {
@@ -95,7 +80,7 @@ async function init() {
   if (componentSystemExists && !forceMode && !mergeMode) {
     console.log('⚠️  Component system already exists in .claude/');
     console.log('   Use --force to overwrite, --merge to update, or use selective updates:');
-    console.log('   --update-skills, --update-recipes, --update-commands\n');
+    console.log('   --update-skills, --update-recipes, --update-commands, --update-agents\n');
     process.exit(1);
   }
 
@@ -108,14 +93,39 @@ async function init() {
   fs.mkdirSync(TARGET_DIR, { recursive: true });
 
   if (forceMode && componentSystemExists) {
-    // Only remove component-system specific dirs
-    const componentDirs = ['skills', 'component-recipes'];
-    for (const dir of componentDirs) {
-      const dirPath = path.join(TARGET_DIR, dir);
-      if (fs.existsSync(dirPath)) {
-        fs.rmSync(dirPath, { recursive: true });
+    // Remove component-system specific skill files (preserve prompt-system skills)
+    const componentSkills = ['styling.md', 'react-patterns.md', 'style-inspector.md'];
+    const skillsDir = path.join(TARGET_DIR, 'skills');
+    if (fs.existsSync(skillsDir)) {
+      for (const skill of componentSkills) {
+        const skillPath = path.join(skillsDir, skill);
+        if (fs.existsSync(skillPath)) {
+          fs.unlinkSync(skillPath);
+        }
+      }
+    }
+
+    // Remove component-system specific agent files
+    const componentAgents = [
+      'style-inspector.md', 'design-token-validator.md',
+      'component-auditor.md', 'harness-scaffolder.md', 'playwright-tester.md'
+    ];
+    const agentsDir = path.join(TARGET_DIR, 'agents');
+    if (fs.existsSync(agentsDir)) {
+      for (const agent of componentAgents) {
+        const agentPath = path.join(agentsDir, agent);
+        if (fs.existsSync(agentPath)) {
+          fs.unlinkSync(agentPath);
+        }
       }
     }
+
+    // Remove component-recipes entirely (owned by component-system)
+    const recipesDir = path.join(TARGET_DIR, 'component-recipes');
+    if (fs.existsSync(recipesDir)) {
+      fs.rmSync(recipesDir, { recursive: true });
+    }
+
     console.log('🗑️  Removed existing component system files.\n');
   }
 
@@ -123,6 +133,20 @@ async function init() {
   copyDir(path.join(TEMPLATES_DIR, 'skills'), path.join(TARGET_DIR, 'skills'));
   copyDir(path.join(TEMPLATES_DIR, 'component-recipes'), path.join(TARGET_DIR, 'component-recipes'));
 
+  // Copy agents (merge into existing agents dir if prompt-system is installed)
+  const agentsDir = path.join(TARGET_DIR, 'agents');
+  fs.mkdirSync(agentsDir, { recursive: true });
+  copyDir(path.join(TEMPLATES_DIR, 'agents'), agentsDir);
+
+  // Migrate: remove style-inspector from skills if it exists (now an agent)
+  const oldStyleInspector = path.join(TARGET_DIR, 'skills', 'style-inspector.md');
+  if (fs.existsSync(oldStyleInspector)) {
+    fs.unlinkSync(oldStyleInspector);
+  }
+
+  // Copy Playwright templates (staged for harness scaffolding)
+  copyDir(path.join(TEMPLATES_DIR, 'playwright'), path.join(TARGET_DIR, 'playwright-templates'));
+
   // Copy styling commands
   const commandsDir = path.join(TARGET_DIR, 'commands');
   fs.mkdirSync(commandsDir, { recursive: true });
@@ -135,21 +159,24 @@ async function init() {
     path.join(commandsDir, 'component-harness.md')
   );
 
+  // Merge MCP configuration into project .mcp.json
+  const mcpSrc = path.join(TEMPLATES_DIR, 'mcp', 'mcp.json');
+  const mcpDest = path.join(PROJECT_ROOT, '.mcp.json');
+  if (mergeJsonFile(mcpSrc, mcpDest)) {
+    console.log('✅ Configured Playwright MCP server in .mcp.json');
+  }
+
   console.log('✅ Created component system files:');
-  console.log('   📁 skills/            - Styling skill for UI generation');
-  console.log('   📁 component-recipes/ - 36 component templates');
+  console.log('   📁 skills/              - Styling + React patterns skills');
+  console.log('   📁 agents/              - 5 component system agents');
+  console.log('   📁 component-recipes/   - 38 component templates');
+  console.log('   📁 playwright-templates/ - Playwright test config + specs');
   console.log('   📄 commands/setup-styling.md');
   console.log('   📄 commands/component-harness.md\n');
 
-  // Inject triggers if prompt-system is installed
-  if (promptSystemExists) {
-    if (injectTriggers()) {
-      console.log('✅ Injected triggers into prompt system.');
-      console.log('   Styling and React patterns will auto-trigger on relevant prompts.\n');
-    }
-  } else {
-    console.log('ℹ️  Prompt system not detected.');
-    console.log('   For auto-triggering styling rules, also install:');
+  // Suggest prompt-system if not installed
+  if (!promptSystemExists) {
+    console.log('💡 For agents and prompt management, also install:');
     console.log('   npx @fr0mpy/prompt-system\n');
   }
 
@@ -166,8 +193,21 @@ async function update() {
 
   const updates = [];
 
-  if (updateSkills && copySubdir('skills')) updates.push('skills');
+  if (updateSkills && copySubdir('skills')) {
+    // Migrate: remove style-inspector from skills if it exists
+    const oldStyleInspector = path.join(TARGET_DIR, 'skills', 'style-inspector.md');
+    if (fs.existsSync(oldStyleInspector)) {
+      fs.unlinkSync(oldStyleInspector);
+    }
+    updates.push('skills');
+  }
   if (updateRecipes && copySubdir('component-recipes')) updates.push('component-recipes');
+  if (updateAgents) {
+    const agentsDir = path.join(TARGET_DIR, 'agents');
+    fs.mkdirSync(agentsDir, { recursive: true });
+    copyDir(path.join(TEMPLATES_DIR, 'agents'), agentsDir);
+    updates.push('agents');
+  }
   if (updateCommands) {
     const commandsDir = path.join(TARGET_DIR, 'commands');
     fs.mkdirSync(commandsDir, { recursive: true });
@@ -198,16 +238,47 @@ function remove() {
   // Check if prompt-system exists - if so, only remove component-system files
   const hasHooks = fs.existsSync(path.join(TARGET_DIR, 'hooks'));
 
-  const componentDirs = ['skills', 'component-recipes'];
+  const componentSkills = ['styling.md', 'react-patterns.md', 'style-inspector.md'];
+  const componentAgents = [
+    'style-inspector.md', 'design-token-validator.md',
+    'component-auditor.md', 'harness-scaffolder.md', 'playwright-tester.md'
+  ];
   const componentCommands = ['setup-styling.md', 'component-harness.md'];
 
-  for (const dir of componentDirs) {
-    const dirPath = path.join(TARGET_DIR, dir);
-    if (fs.existsSync(dirPath)) {
-      fs.rmSync(dirPath, { recursive: true });
+  // Remove component-system specific skill files (preserve prompt-system skills)
+  const skillsDir = path.join(TARGET_DIR, 'skills');
+  if (fs.existsSync(skillsDir)) {
+    for (const skill of componentSkills) {
+      const skillPath = path.join(skillsDir, skill);
+      if (fs.existsSync(skillPath)) {
+        fs.unlinkSync(skillPath);
+      }
     }
   }
 
+  // Remove component-system specific agent files (preserve prompt-system agents)
+  const agentsDir = path.join(TARGET_DIR, 'agents');
+  if (fs.existsSync(agentsDir)) {
+    for (const agent of componentAgents) {
+      const agentPath = path.join(agentsDir, agent);
+      if (fs.existsSync(agentPath)) {
+        fs.unlinkSync(agentPath);
+      }
+    }
+  }
+
+  // Remove component-recipes entirely (owned by component-system)
+  const recipesDir = path.join(TARGET_DIR, 'component-recipes');
+  if (fs.existsSync(recipesDir)) {
+    fs.rmSync(recipesDir, { recursive: true });
+  }
+
+  // Remove playwright-templates (owned by component-system)
+  const playwrightDir = path.join(TARGET_DIR, 'playwright-templates');
+  if (fs.existsSync(playwrightDir)) {
+    fs.rmSync(playwrightDir, { recursive: true });
+  }
+
   // Remove styling commands
   const commandsDir = path.join(TARGET_DIR, 'commands');
   if (fs.existsSync(commandsDir)) {
@@ -219,15 +290,31 @@ function remove() {
     }
   }
 
-  // Remove triggers
-  removeTriggers();
-
   // Remove styling-config.json if it exists
   const stylingConfig = path.join(TARGET_DIR, 'styling-config.json');
   if (fs.existsSync(stylingConfig)) {
     fs.unlinkSync(stylingConfig);
   }
 
+  // Clean up Playwright MCP config from .mcp.json
+  const mcpPath = path.join(PROJECT_ROOT, '.mcp.json');
+  if (fs.existsSync(mcpPath)) {
+    try {
+      const mcpConfig = JSON.parse(fs.readFileSync(mcpPath, 'utf8'));
+      if (mcpConfig.mcpServers?.playwright) {
+        delete mcpConfig.mcpServers.playwright;
+        if (Object.keys(mcpConfig.mcpServers).length === 0) {
+          delete mcpConfig.mcpServers;
+        }
+        if (Object.keys(mcpConfig).length === 0) {
+          fs.unlinkSync(mcpPath);
+        } else {
+          fs.writeFileSync(mcpPath, JSON.stringify(mcpConfig, null, 2) + '\n');
+        }
+      }
+    } catch (e) { /* .mcp.json may not be valid JSON */ }
+  }
+
   if (hasHooks) {
     console.log('✅ Removed component system files. Prompt system preserved.\n');
   } else {
@@ -256,6 +343,7 @@ Selective updates:
   --update-skills    Update only skills/
   --update-recipes   Update only component-recipes/
   --update-commands  Update only styling commands
+  --update-agents    Update only agents/
 
 Options:
   -h, --help     Show this help message
@@ -264,16 +352,21 @@ Options:
   -r, --remove   Remove component system (alias: --uninstall)
 
 What's included:
-  • skills/            Styling skill for consistent UI generation
-  • component-recipes/ 36 pre-built component templates
-  • commands/          /setup-styling, /component-harness
+  • skills/              Styling + React patterns skills
+  • agents/              5 component system agents (style-inspector,
+                         design-token-validator, component-auditor,
+                         harness-scaffolder, playwright-tester)
+  • component-recipes/   38 pre-built component templates
+  • playwright-templates/ Playwright test config + component specs
+  • commands/            /setup-styling, /component-harness
+  • .mcp.json            Playwright MCP server configuration
 
 Getting started:
   1. Run: npx @fr0mpy/component-system
   2. Use: /setup-styling to configure your design system
-  3. Use: /component-harness to preview components
+  3. Use: /component-harness to preview and test components
 
-For prompt injection and agents:
+For prompt injection and additional agents:
   npx @fr0mpy/prompt-system
 
 Learn more: https://github.com/fr0mpy/claude-base-setup