@lifeonlars/prime-yggdrasil 0.2.5 → 0.3.0

package/README.md

@@ -158,13 +158,29 @@ npm run build
 
 ### Scripts
 ```bash
-npm run dev                 # Start Storybook
-npm run build              # Build library
-npm run test:contrast      # Test color contrast
+npm run storybook          # Start Storybook development server
+npm run build              # Build library package
+npm run build-storybook    # Build static Storybook for deployment
+npm run test:contrast      # Test color contrast (APCA)
 npm run test:themes        # Validate theme structure
+npm run lint               # Lint TypeScript/JavaScript
 npm run lint:css           # Lint CSS files
+npm run chromatic          # Run visual regression tests
 ```
 
+### Testing
+
+**Storybook Built-in Testing:**
+- **Play functions** - Interactive tests run automatically when viewing stories
+- **Accessibility tests** - `@storybook/addon-a11y` checks components for a11y violations
+- **Visual regression** - Chromatic integration for catching visual changes
+
+**CI/CD Pipeline:**
+- GitHub Actions runs on every push/PR
+- Validates linting, builds, and accessibility
+- Chromatic visual regression testing (on push to main/master)
+- See [`.github/workflows/ci.yml`](.github/workflows/ci.yml) for details
+
 ## 📊 Project Stats
 
 - **Semantic Tokens**: 727 color replacements (96% coverage)
@@ -173,25 +189,152 @@ npm run lint:css           # Lint CSS files
 - **Contrast**: WCAG 3.0 (APCA) validated
 - **Dark Mode**: Optimized shadows with white rim strategy
 
-## 🤖 AI Agent Integration
+## 🤖 AI Agent Infrastructure
+
+Yggdrasil includes **6 specialized AI agents** that prevent drift, guide composition, and enforce design system compliance.
+
+### 🚀 Quick Start: Initialize Agents
+
+```bash
+npx @lifeonlars/prime-yggdrasil init
+```
+
+This copies 4 active agents + 2 future specs to your project's `.ai/yggdrasil/` directory.
+
+### 📋 The 6 Agents
+
+#### Active Agents (Phase 1-4 Complete)
+
+1. **Block Composer** - Composition-first UI planning
+   - Prevents bespoke component creation
+   - Suggests PrimeReact components + existing Blocks
+   - Specifies all 5+ states (default, hover, focus, active, disabled)
+
+2. **PrimeFlex Guard** - Layout constraint enforcement
+   - Allows PrimeFlex for layout/spacing ONLY (not design)
+   - Critical rule: NO PrimeFlex on PrimeReact components (except `w-full` on inputs)
+   - Maintains 4px grid discipline
+
+3. **Semantic Token Intent** - State-complete token selection
+   - Ensures all states defined (default, hover, focus, active, disabled)
+   - Validates token pairings work in light/dark modes
+   - Prevents hardcoded colors and foundation tokens in app code
+
+4. **Drift Validator** - Comprehensive policy enforcement
+   - 7 core rules (no hardcoded colors, no PrimeFlex on components, etc.)
+   - ESLint plugin + CLI validation
+   - Autofix capability for safe violations
+
+#### Future Agents (Phase 6 Specs Ready)
+
+5. **Interaction Patterns** *(specification complete)*
+   - Standardizes empty/loading/error/success patterns
+   - Enforces keyboard navigation and focus management
+   - Ensures copy is clear, pragmatic, non-fluffy
+
+6. **Accessibility** *(specification complete)*
+   - WCAG 2.1 AA minimum compliance
+   - Contrast ratio validation
+   - Ensures color is not the only cue (icons, text, patterns)
+   - Validates ARIA and semantic HTML
+
+### 🛠️ Agent Tools
+
+**ESLint Plugin** (Phase 3)
+```bash
+npm install --save-dev @lifeonlars/eslint-plugin-yggdrasil
+```
+
+```js
+// eslint.config.js
+import yggdrasil from '@lifeonlars/eslint-plugin-yggdrasil';
+
+export default [
+  {
+    plugins: { '@lifeonlars/yggdrasil': yggdrasil },
+    rules: yggdrasil.configs.recommended.rules  // Warnings for adoption
+    // Or: yggdrasil.configs.strict.rules      // Errors for enforcement
+  }
+];
+```
+
+**CLI Validation** (Phase 4)
+```bash
+# Report-only validation
+npx @lifeonlars/prime-yggdrasil validate
+
+# Detailed audit with recommendations
+npx @lifeonlars/prime-yggdrasil audit
+
+# Apply automatic fixes
+npx @lifeonlars/prime-yggdrasil audit --fix
+
+# JSON output for CI/CD
+npx @lifeonlars/prime-yggdrasil validate --format json
+```
+
+### 📖 Agent Documentation
+
+**For Consumers:**
+- [`.ai/yggdrasil/README.md`](./.ai/agents/README.md) - Quick start guide (copied to your project)
+- [`docs/AESTHETICS.md`](./docs/AESTHETICS.md) - Mandatory aesthetic principles reference
+- [`docs/PRIMEFLEX-POLICY.md`](./docs/PRIMEFLEX-POLICY.md) - Complete PrimeFlex allowlist
+
+**For Agent Developers:**
+- [`.ai/agents/block-composer.md`](./.ai/agents/block-composer.md) - Composition planning
+- [`.ai/agents/primeflex-guard.md`](./.ai/agents/primeflex-guard.md) - Layout constraints
+- [`.ai/agents/semantic-token-intent.md`](./.ai/agents/semantic-token-intent.md) - Token selection
+- [`.ai/agents/drift-validator.md`](./.ai/agents/drift-validator.md) - Policy enforcement
+- [`.ai/agents/interaction-patterns.md`](./.ai/agents/interaction-patterns.md) - Behavioral patterns *(future)*
+- [`.ai/agents/accessibility.md`](./.ai/agents/accessibility.md) - WCAG compliance *(future)*
+
+### 🎯 Agent Workflow Example
+
+**Implementing a User Profile Form:**
+
+1. **Block Composer** - "Use `<Card>` + `<InputText>` + `<Button>`. Specify loading/empty/error states."
+2. **PrimeFlex Guard** - "Use `flex flex-column gap-3 p-4` for layout. NO `bg-*` or `rounded-*` utilities."
+3. **Semantic Token Intent** - "Use `var(--surface-neutral-primary)` for card, `var(--text-neutral-default)` for labels."
+4. **Drift Validator** - "✅ No violations. All rules passing."
+
+### 🔧 Dual Enforcement Strategy
+
+**Prevention (Agents guide before code is written)**
+- Block Composer prevents bespoke UI
+- PrimeFlex Guard prevents utility chaos
+- Semantic Token Intent prevents styling violations
+
+**Detection (ESLint + CLI catch violations after)**
+- ESLint: Code-time detection in IDE (fast feedback)
+- CLI: Runtime validation with deeper analysis (pre-commit, CI/CD)
+
+### 🚀 Migration Path
+
+1. **Week 1**: Install update, run `npx @lifeonlars/prime-yggdrasil init`
+2. **Week 2**: Read agent documentation in `.ai/yggdrasil/`
+3. **Week 3**: Install ESLint plugin (`recommended` config - warnings only)
+4. **Week 4**: Run `yggdrasil audit` on existing code, apply fixes incrementally
+5. **Week 5+**: Switch to ESLint `strict` config (errors) for new code
+
+### 📊 Enforcement Stats
 
-Yggdrasil is specifically designed to guide AI agents toward component-driven development:
+- **7 ESLint Rules** - Warnings (recommended) or errors (strict)
+- **5 CLI Validation Rules** - Report-only or autofix mode
+- **4 Active Agents** - Guidance during development
+- **2 Future Agents** - Specifications ready for Phase 6
 
-1. **Comprehensive Documentation** - AI agents can read [AI-AGENT-GUIDE.md](./docs/AI-AGENT-GUIDE.md)
-2. **Decision Trees** - Step-by-step component selection guidance
-3. **Token Reference** - Quick lookup for semantic tokens
-4. **Anti-Patterns** - Clear examples of what NOT to do
-5. **Validation Rules** - Optional ESLint/pre-commit hooks
+### Example AI Prompt (with Agents)
 
-### Example AI Prompt
 ```
 I'm building a React app with Yggdrasil design system.
 
 Before implementing UI:
-1. Read: node_modules/@lifeonlars/prime-yggdrasil/docs/AI-AGENT-GUIDE.md
-2. Check: Is there a PrimeReact component for this?
-3. Use: Semantic tokens only (no hardcoded colors)
-4. Follow: 4px grid for all spacing
+1. Read: .ai/yggdrasil/block-composer.md
+2. Read: docs/AESTHETICS.md (mandatory reference)
+3. Check: Is there a PrimeReact component for this?
+4. Use: Semantic tokens only (no hardcoded colors)
+5. Follow: 4px grid for all spacing
+6. Validate: Run `yggdrasil audit` before committing
 
 Create a user profile form with name, email, and submit button.
 ```

package/cli/bin/yggdrasil.js

@@ -0,0 +1,134 @@
+#!/usr/bin/env node
+
+/**
+ * Yggdrasil CLI - Design System Agent Infrastructure
+ *
+ * Commands:
+ *   init      - Initialize Yggdrasil agents in your project
+ *   validate  - Validate code against design system rules (Phase 4)
+ *   audit     - Detailed audit with autofix suggestions (Phase 4)
+ */
+
+import { fileURLToPath } from 'url';
+import { dirname, join } from 'path';
+import { existsSync } from 'fs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+
+const args = process.argv.slice(2);
+const command = args[0];
+
+// Parse command-line arguments
+function parseArgs(args) {
+  const options = {};
+  for (let i = 1; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === '--fix') {
+      options.fix = true;
+    } else if (arg === '--format') {
+      options.format = args[++i];
+    } else if (arg === '--rules') {
+      options.rules = args[++i];
+    } else if (arg.startsWith('--')) {
+      // Skip unknown options
+      console.warn(`⚠️  Unknown option: ${arg}`);
+    }
+  }
+  return options;
+}
+
+async function main() {
+  const options = parseArgs(args);
+
+  switch (command) {
+    case 'init':
+      const { initCommand } = await import('../commands/init.js');
+      await initCommand();
+      break;
+
+    case 'validate':
+      const { validateCommand } = await import('../commands/validate.js');
+      await validateCommand(options);
+      break;
+
+    case 'audit':
+      const { auditCommand } = await import('../commands/audit.js');
+      await auditCommand(options);
+      break;
+
+    case '--version':
+    case '-v':
+      const packageJsonPath = join(__dirname, '../../package.json');
+      if (existsSync(packageJsonPath)) {
+        const pkg = await import(packageJsonPath, { assert: { type: 'json' } });
+        console.log(pkg.default.version);
+      }
+      break;
+
+    case '--help':
+    case '-h':
+    case undefined:
+      printHelp();
+      break;
+
+    default:
+      console.error(`❌ Unknown command: ${command}`);
+      console.log('');
+      printHelp();
+      process.exit(1);
+  }
+}
+
+function printHelp() {
+  console.log(`
+🌳 Yggdrasil CLI - AI-Agent-Friendly Design System
+
+Usage:
+  npx @lifeonlars/prime-yggdrasil <command> [options]
+
+Commands:
+  init              Initialize Yggdrasil agents in your project
+  validate          Validate code against design system rules
+  audit             Detailed audit with autofix suggestions
+
+Options:
+  -h, --help        Show this help message
+  -v, --version     Show version number
+
+Validate/Audit Options:
+  --format <type>   Output format: cli (default), json, markdown
+  --rules <list>    Comma-separated list of rules to check
+  --fix             Apply automatic fixes (audit only)
+
+Examples:
+  # Initialize agents in your project
+  npx @lifeonlars/prime-yggdrasil init
+
+  # Validate code (report-only)
+  npx @lifeonlars/prime-yggdrasil validate
+
+  # Detailed audit with recommendations
+  npx @lifeonlars/prime-yggdrasil audit
+
+  # Audit with automatic fixes
+  npx @lifeonlars/prime-yggdrasil audit --fix
+
+  # Validate specific rules only
+  npx @lifeonlars/prime-yggdrasil validate --rules no-tailwind,no-hardcoded-colors
+
+  # Output as JSON for CI/CD integration
+  npx @lifeonlars/prime-yggdrasil validate --format json
+
+  # Generate markdown report
+  npx @lifeonlars/prime-yggdrasil audit --format markdown > audit-report.md
+
+Documentation:
+  https://github.com/lifeonlars/prime-yggdrasil#readme
+`);
+}
+
+main().catch((error) => {
+  console.error('❌ Error:', error.message);
+  process.exit(1);
+});