@nikkory/vibe-engine 4.0.1 → 4.0.3

package/README.md

@@ -9,1032 +9,100 @@ Zero-token UI/UX code generation with 24-factor design system support.
 
 ---
 
-## Features
+## ✨ Features
 
 - 🎨 **12 Design Systems**: Material Design, iOS HIG, Glassmorphism, Neumorphism, Brutalism, Minimalism, Cyberpunk, Flat Design, Retro Vintage, Fluent Design, Carbon Design, Ant Design
-- 🎯 **24-Factor System**: Comprehensive design configuration (Color, Size, Variant, Shape, Position, State, Animation, Elevation, A11y, Alignment, Orientation, Density, Loading, Responsive, Theme, Spacing, Typography, Border, Opacity, Overflow, Cursor, Z-Index, Transition)
+- 🎯 **24-Factor Configuration**: Comprehensive design control across color, size, variant, shape, animation, accessibility, and more
 - 📦 **169 Components**: Button, Input, Card, Modal, Tabs, and 45+ more component types
-- 🔧 **Framework-Agnostic**: Use with React, Vue, Svelte, or any framework
+- 🔧 **Framework-Agnostic**: Works with React, Vue, Svelte, or any framework
 - 🏛️ **3-Tier Quality**: Basic (30-50 LOC), Standard (50-150 LOC), Enterprise (150-300 LOC)
 - 📊 **Component Registry**: Search, filter, browse 169 pre-configured components
-- 🎭 **Style Generation**: Runtime style generation with design tokens
 - 🛡️ **Type-Safe**: Full TypeScript support with strict mode
 
 ---
 
-## Installation
+## 📦 Installation
 
 ```bash
-# npm
-npm install @nikkory/vibe-engine
-
-# pnpm
-pnpm add @nikkory/vibe-engine
+# Global CLI (Recommended)
+npm install -g @nikkory/vibe-engine
 
-# yarn
-yarn add @nikkory/vibe-engine
+# Local library
+npm install @nikkory/vibe-engine
 ```
 
 ---
 
-## Quick Start
-
-### Style Generation
-
-```typescript
-import { generateStyles, cn } from '@nikkory/vibe-engine';
-
-// Generate component styles
-const styles = generateStyles({
-  componentType: 'button',
-  variant: 'filled',
-  size: 'md',
-  color: 'primary',
-});
-
-// Merge class names
-const className = cn('base-class', 'additional-class', {
-  'conditional-class': true,
-  'hidden-class': false,
-});
-```
-
-### Component Registry
-
-```typescript
-import {
-  ALL_COMPONENTS,
-  getComponent,
-  searchComponents,
-  getStableComponents,
-} from '@nikkory/vibe-engine';
+## 🚀 Quick Start
 
-// Get all 169 components
-console.log(ALL_COMPONENTS.length); // 169
+### CLI Usage
 
-// Get a specific component
-const button = getComponent('button');
-console.log(button.name); // "Button"
+```bash
+# Generate enterprise button with Material Design
+vibe generate button material-design enterprise
 
-// Search components
-const buttons = searchComponents('button'); // 10 results
+# Generate with custom factor overrides
+vibe generate button material-design enterprise --factor-4=full
 
-// Get stable components only
-const stable = getStableComponents(); // 169 components
+# Batch generate all components for Material Design
+vibe batch -o ./generated --ds material-design
 ```
 
 ### Design Systems
 
-```typescript
-import { CURRENT_DESIGN_SYSTEMS, DESIGN_SYSTEM_INFO } from '@nikkory/vibe-engine';
-
-// Available design systems (12 total)
-console.log(CURRENT_DESIGN_SYSTEMS);
-// ['material-design', 'ios-hig', 'glassmorphism', ...]
-
-// Get design system info
-const materialInfo = DESIGN_SYSTEM_INFO['material-design'];
-console.log(materialInfo.name); // "Material Design 3"
-```
+| Design System     | Description                      |
+| ----------------- | -------------------------------- |
+| material-design   | Google Material Design 3         |
+| ios-hig           | Apple Human Interface Guidelines |
+| glassmorphism     | Frosted glass effect             |
+| neumorphism       | Soft UI with shadows             |
+| brutalism         | Bold, raw aesthetic              |
+| minimalism        | Clean, simple design             |
+| cyberpunk         | Neon futuristic style            |
+| flat-design       | Microsoft Metro style            |
+| retro-vintage     | Classic nostalgic look           |
+| fluent-design     | Microsoft Fluent UI              |
+| carbon-design     | IBM Carbon Design                |
+| ant-design        | Ant Design System                |
 
 ### Quality Tiers
 
-```typescript
-import { TIERS, TIER_INFO } from '@nikkory/vibe-engine';
-
-// Available tiers
-console.log(TIERS); // ['basic', 'standard', 'enterprise']
-
-// Get tier details
-const enterprise = TIER_INFO.enterprise;
-console.log(enterprise.features);
-// ['memo', 'useCallback', 'analytics', 'ARIA', 'error boundaries']
-```
-
-### 24-Factor Configuration
-
-```typescript
-import {
-  // Basic factors (1-6)
-  COLORS,
-  SIZES,
-  VARIANTS,
-  SHAPES,
-  POSITIONS,
-  ICON_POSITIONS,
-
-  // Standard factors (7-11)
-  STATES,
-  ANIMATIONS,
-  ELEVATIONS,
-  A11Y_LEVELS,
-  ALIGNMENTS,
-
-  // Enterprise factors (12-24)
-  ORIENTATIONS,
-  DENSITIES,
-  LOADING_STATES,
-  RESPONSIVE_BREAKPOINTS,
-  THEMES,
-  SPACINGS,
-  TYPOGRAPHIES,
-  BORDERS,
-  OPACITIES,
-  OVERFLOWS,
-  CURSORS,
-  Z_INDICES,
-  TRANSITIONS,
-} from '@nikkory/vibe-engine';
-
-// Use factors in configuration
-const config = {
-  color: COLORS[0], // 'primary'
-  size: SIZES[1], // 'md'
-  variant: VARIANTS[0], // 'filled'
-  animation: ANIMATIONS[0], // 'fadeIn'
-  elevation: ELEVATIONS[1], // 'medium'
-  a11yLevel: A11Y_LEVELS[1], // 'enhanced'
-};
-```
-
----
-
-## API Reference
-
-### Style Generation
-
-#### `generateStyles(config: StyleConfig): GeneratedStyles`
-
-Generate component styles from configuration.
-
-**Parameters**:
-
-- `config.componentType`: Component type (`'button'`, `'input'`, etc.)
-- `config.variant`: Style variant (`'filled'`, `'outlined'`, etc.)
-- `config.size`: Component size (`'sm'`, `'md'`, `'lg'`)
-- `config.color`: Color scheme (`'primary'`, `'secondary'`, etc.)
-
-**Returns**: `{ className: string, styles: object }`
-
-#### `cn(...inputs: ClassValue[]): string`
-
-Merge class names with conditional support.
-
-**Parameters**:
-
-- `inputs`: Class names, objects, or arrays
-
-**Returns**: Merged class name string
-
-### Component Registry
-
-#### `ALL_COMPONENTS: RegistryComponentDefinition[]`
-
-Array of all 169 registered components.
-
-#### `getComponent(id: string): RegistryComponentDefinition | undefined`
-
-Get a component by ID.
-
-#### `searchComponents(query: string): RegistryComponentDefinition[]`
-
-Search components by name, tags, or category.
-
-#### `getStableComponents(): RegistryComponentDefinition[]`
-
-Get all components with `status: 'stable'`.
-
-#### `getPopularComponents(): RegistryComponentDefinition[]`
-
-Get all components marked as popular (15 components).
-
-#### `getNewComponents(): RegistryComponentDefinition[]`
-
-Get all components marked as new (7 components).
-
-### Constants
-
-#### `CURRENT_DESIGN_SYSTEMS: DesignSystem[]`
-
-Available design systems (12 total).
-
-#### `TIERS: Tier[]`
-
-Available quality tiers: `['basic', 'standard', 'enterprise']`.
-
-#### `CURRENT_COMPONENT_TYPES: ComponentType[]`
-
-Available component types (50 total).
-
-### Types
-
-```typescript
-import type {
-  // Core types
-  DesignSystem,
-  Tier,
-  ComponentType,
-  Factor24Config,
-  StyleConfig,
-  GeneratedStyles,
-
-  // Section Architecture types
-  SectionConfig,
-  SectionTemplate,
-  SectionFactors,
-  SectionCategory,
-  SlotConfig,
-  StoredComponentInSlot,
-  TemplateVisibility,
-  TemplateMetadata,
-
-  // Unified Granularity Architecture types
-  GranularityLevel,
-  GranularityConfig,
-  GranularityTemplate,
-  GranularitySlotConfig,
-  GranularitySlotPosition,
-  GranularityFactorDefinition,
-  GranularityFactorCategory,
-  GranularityFactorValues,
-  GranularityLayoutConfig,
-  ChildReference,
-  // Level-specific aliases
-  AtomConfig,
-  ComponentConfig,
-  PageConfig,
-  TemplateConfig,
-} from '@nikkory/vibe-engine';
-```
-
----
-
-## 24-Factor Design System
-
-### Factors 1-6 (Basic Tier)
-
-| Factor           | Values                                            | Description     |
-| ---------------- | ------------------------------------------------- | --------------- |
-| 1. Color         | primary, secondary, success, error, warning, info | Color schemes   |
-| 2. Size          | xs, sm, md, lg, xl, 2xl                           | Component sizes |
-| 3. Variant       | filled, outlined, text, ghost                     | Style variants  |
-| 4. Shape         | rectangle, rounded, pill, circle                  | Corner radius   |
-| 5. Position      | top, right, bottom, left, center                  | Positioning     |
-| 6. Icon Position | left, right, top, bottom                          | Icon placement  |
-
-### Factors 7-11 (Standard Tier)
-
-| Factor        | Values                                  | Description         |
-| ------------- | --------------------------------------- | ------------------- |
-| 7. State      | default, hover, active, focus, disabled | Interaction states  |
-| 8. Animation  | none, fadeIn, slideIn, bounce, pulse    | Entry animations    |
-| 9. Elevation  | none, low, medium, high, highest        | Shadow depth        |
-| 10. A11y      | basic, enhanced, full                   | Accessibility level |
-| 11. Alignment | left, center, right, justify            | Text alignment      |
-
-### Factors 12-16 (Standard Extended)
-
-| Factor            | Values                        | Description      |
-| ----------------- | ----------------------------- | ---------------- |
-| 12. Orientation   | horizontal, vertical          | Layout direction |
-| 13. Density       | compact, normal, comfortable  | Spacing density  |
-| 14. Loading State | idle, loading, success, error | Async state      |
-| 15. Responsive    | xs, sm, md, lg, xl            | Breakpoints      |
-| 16. Theme         | light, dark, auto             | Color theme      |
-
-### Factors 17-24 (Enterprise Tier)
-
-| Factor         | Values                        | Description       |
-| -------------- | ----------------------------- | ----------------- |
-| 17. Spacing    | none, xs, sm, md, lg, xl      | Margins/padding   |
-| 18. Typography | xs, sm, base, lg, xl, 2xl     | Font sizes        |
-| 19. Border     | none, thin, medium, thick     | Border width      |
-| 20. Opacity    | 0, 25, 50, 75, 100            | Transparency      |
-| 21. Overflow   | visible, hidden, scroll, auto | Overflow behavior |
-| 22. Cursor     | default, pointer, wait, text  | Cursor style      |
-| 23. Z-Index    | 0, 10, 20, 30, 40, 50         | Stacking order    |
-| 24. Transition | none, fast, normal, slow      | Animation speed   |
-
----
-
-## Algorithm Engine Registries
-
-**New in v4.0.0**: Registry-based architecture for the 24-Factor × 3-Tier × 12-Design-Systems generation engine.
-
-### Registry Overview
-
-| Registry                | Purpose                                       | Total Entries |
-| ----------------------- | --------------------------------------------- | ------------- |
-| Tiers Registry          | Maps tiers to factor ranges and code features | 3             |
-| Factors Registry        | 24 Factor definitions with metadata           | 24            |
-| Components Registry     | 34 Components with factor applicability       | 34            |
-| Design Systems Registry | 12 Design systems with factor values          | 12            |
-
-### Components Registry Usage
-
-```typescript
-import {
-  COMPONENT_REGISTRY,
-  getComponentEntry,
-  getAllComponentTypes,
-  getApplicableFactors,
-  getSkippedFactors,
-  getFactorApplicability,
-  componentSupportsDesignSystem,
-  searchComponents,
-} from '@nikkory/vibe-engine';
-
-// Get all 34 component types
-const types = getAllComponentTypes();
-console.log(types); // ['button', 'input', 'card', ...]
-
-// Get component entry with factor applicability
-const button = getComponentEntry('button');
-console.log(button.category); // 'basic'
-console.log(button.elementType); // 'button'
-
-// Get applicable factors for a component
-const factors = getApplicableFactors('button');
-console.log(factors); // [1, 2, 3, 4, 6, 7, 8, ...] (applicable factor IDs)
-
-// Get skipped factors (null applicability)
-const skipped = getSkippedFactors('button');
-console.log(skipped); // [5, 11, 12, ...] (Position, Alignment, Orientation)
-
-// Check factor applicability with overrides
-const applicability = getFactorApplicability('avatar', 4);
-console.log(applicability); // 'circle' (override value for Shape)
-
-// Search components
-const results = searchComponents('modal');
-```
-
-### Design Systems Registry Usage
-
-```typescript
-import {
-  DESIGN_SYSTEM_REGISTRY,
-  getDesignSystemEntry,
-  getAllDesignSystems,
-  getFactorValue,
-  getFactorTailwindClasses,
-  getDesignSystemCssVariables,
-  generateThemeCss,
-  mergeFactorValues,
-} from '@nikkory/vibe-engine';
-
-// Get all 12 design systems
-const systems = getAllDesignSystems();
-console.log(systems); // ['material-design', 'ios-hig', ...]
-
-// Get design system entry
-const md = getDesignSystemEntry('material-design');
-console.log(md.name); // 'Material Design'
-console.log(md.description); // 'Google Material Design 3...'
-
-// Get factor value for a design system
-const colorValue = getFactorValue('material-design', 1);
-console.log(colorValue?.tailwindClasses); // 'bg-blue-500 text-white hover:bg-blue-600'
-console.log(colorValue?.cssVariables); // { '--md-color-primary': '#2196f3' }
-
-// Get Tailwind classes directly
-const classes = getFactorTailwindClasses('brutalism', 4);
-console.log(classes); // 'rounded-none'
-
-// Get CSS variables for Tailwind v4 @theme
-const vars = getDesignSystemCssVariables('glassmorphism');
-console.log(vars['--glass-blur']); // '16px'
-
-// Generate @theme CSS block for Tailwind v4
-const themeCss = generateThemeCss('material-design');
-console.log(themeCss);
-// @theme {
-//   --md-color-primary: #2196f3;
-//   --md-color-secondary: #9c27b0;
-//   ...
-// }
-
-// Merge design system values with custom overrides
-const merged = mergeFactorValues('material-design', {
-  1: { factorId: 1, value: 'custom', tailwindClasses: 'bg-red-500' },
-});
-```
-
-### Factor Applicability Pattern
-
-Each component defines which of the 24 factors apply:
-
-```typescript
-type FactorApplicability = null | true | string;
-
-// null = factor not applicable (skip)
-// true = factor applicable with design system default
-// string = factor applicable with specific override value
-
-// Example: Avatar component
-{
-  factorApplicability: {
-    1: true,      // Color - use default
-    4: 'circle',  // Shape - override to circular
-    21: 'hidden', // Overflow - clip to shape
-  }
-}
-```
-
-### Tailwind v4 Integration
-
-Design systems provide CSS variables for Tailwind v4 `@theme` integration:
-
-```css
-/* Generated by generateThemeCss('material-design') */
-@theme {
-  --md-color-primary: #2196f3;
-  --md-color-secondary: #9c27b0;
-  --md-shape-corner-small: 4px;
-  --md-shape-corner-medium: 8px;
-  --md-motion-duration-short: 100ms;
-}
-```
-
----
-
-## Section Architecture
-
-**New in v4.0.0**: Complete Section Architecture for building pages from configurable sections.
-
-### SectionConfig (14 Fields)
-
-```typescript
-import type {
-  SectionConfig,
-  SectionTemplate,
-  SectionFactors,
-  SectionCategory,
-  SlotConfig,
-  StoredComponentInSlot,
-} from '@nikkory/vibe-engine';
-
-// Create a section configuration
-const heroSection: SectionConfig = {
-  // Section-Level Fields (6)
-  sectionId: 'hero-1',
-  sectionType: 'hero',
-  title: 'Welcome to Our Platform',
-  subtitle: 'Build amazing experiences',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-
-  // Layout Fields (3)
-  layout: 'flex',
-  columns: 2,
-  spacing: 'lg',
-
-  // Generation Fields (2)
-  slots: [],
-  itemCount: 1,
-
-  // Component-Specific Fields (3)
-  showCta: true,
-  showMedia: true,
-  styleOverrides: { className: 'hero-custom' },
-};
-```
-
-### Section Categories (10 Types)
-
-| Category     | Description           | Typical Layout |
-| ------------ | --------------------- | -------------- |
-| hero         | Landing page hero     | flex, 1-2 cols |
-| features     | Feature grid/list     | grid, 3-4 cols |
-| testimonials | Customer testimonials | carousel       |
-| pricing      | Pricing plans         | grid, 3 cols   |
-| cta          | Call-to-action        | flex, 1 col    |
-| faq          | Frequently asked      | accordion      |
-| team         | Team members grid     | grid, 3-4 cols |
-| contact      | Contact form          | flex, 2 cols   |
-| gallery      | Image gallery         | masonry        |
-| stats        | Statistics/metrics    | grid, 4 cols   |
-
-### SectionTemplate (22 Fields = 14 Config + 8 Metadata)
-
-```typescript
-const heroTemplate: SectionTemplate = {
-  // SectionConfig (14 fields)
-  ...heroSection,
-
-  // TemplateMetadata (8 fields)
-  templateId: 'hero-material-001',
-  templateName: 'Material Hero',
-  description: 'Material Design 3 hero section with gradient',
-  author: 'nikkory-team',
-  version: '1.0.0',
-  tags: ['hero', 'material', 'enterprise', 'landing'],
-  visibility: 'public', // 'private' | 'team' | 'public'
-  thumbnail: 'https://cdn.nikkory.com/templates/hero-material.png',
-};
-```
-
-### SectionFactors (13 Factors)
-
-Factors that propagate from Section to Components:
-
-```typescript
-const factors: SectionFactors = {
-  // Visual Factors (6)
-  colorPrimary: '#2196f3',
-  colorText: '#1a1a1a',
-  colorBackground: '#ffffff',
-  typography: 'default', // 'compact' | 'default' | 'relaxed' | 'spacious'
-  borderRadius: 'md', // 'none' | 'sm' | 'md' | 'lg' | 'xl' | 'full'
-  elevation: 'sm', // 'none' | 'sm' | 'md' | 'lg' | 'xl'
-
-  // Layout Factors (4)
-  padding: 'lg',
-  gap: 'md',
-  alignment: 'center', // 'start' | 'center' | 'end' | 'stretch' | 'between'
-  maxWidth: 'xl', // 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full'
-
-  // Behavior Factors (3)
-  animation: 'smooth', // 'none' | 'subtle' | 'smooth' | 'dynamic' | 'playful'
-  responsive: { mobile: 'stack', tablet: 'grid', desktop: 'grid' },
-  a11yLevel: 'enhanced', // 'standard' | 'enhanced' | 'maximum'
-};
-```
-
-### Slot System
-
-Place components in section slots:
-
-```typescript
-const slotConfig: SlotConfig = {
-  slotId: 'hero-cta-slot',
-  position: 'content', // 'header' | 'content' | 'footer' | 'sidebar' | 'overlay'
-  allowedComponents: ['button', 'input', 'chip'],
-  maxComponents: 3,
-  defaultComponent: 'button',
-};
-
-const componentInSlot: StoredComponentInSlot = {
-  componentRef: 'button',
-  instanceId: 'hero-cta-button-1',
-  propOverrides: {
-    variant: 'filled',
-    size: 'lg',
-    label: 'Get Started',
-  },
-  order: 0,
-  visible: true,
-};
-```
-
-### Hybrid Storage (Visibility-Based)
-
-- `private`: JSON file only (local machine)
-- `team`: JSON + Cloud sync to team workspace
-- `public`: JSON + Cloud sync + Marketplace listing
-
-```typescript
-import type { LocalStorageConfig, CloudSyncConfig } from '@nikkory/vibe-engine';
-
-const localConfig: LocalStorageConfig = {
-  basePath: './.nikkory/templates',
-  fileExtension: '.section.json',
-  prettyPrint: true,
-  createBackups: true,
-};
-
-const cloudConfig: CloudSyncConfig = {
-  apiEndpoint: 'https://api.nikkory.com/templates',
-  syncInterval: 60000, // 1 minute
-  conflictResolution: 'newest-wins',
-  enableOfflineQueue: true,
-};
-```
-
----
-
-## Unified Granularity Architecture
-
-**New in v4.0.0**: Generic type system for all 6 granularity levels with dynamic factor cascade.
-
-### GranularityConfig<G> - Generic Interface
-
-Replace duplicate Section/Page/Layout/Template patterns with ONE generic interface:
-
-```typescript
-import type {
-  GranularityLevel,
-  GranularityConfig,
-  GranularityTemplate,
-  GranularitySlotConfig,
-  GranularityFactorDefinition,
-} from '@nikkory/vibe-engine';
-
-// 6 Granularity Levels
-type GranularityLevel = 'atom' | 'component' | 'section' | 'page' | 'layout' | 'template';
-
-// Generic config for ANY granularity level
-const sectionConfig: GranularityConfig<'section'> = {
-  id: 'hero-section-1',
-  granularity: 'section',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  title: 'Hero Section',
-  layout: { type: 'flex', alignment: 'center' },
-  factors: { spacing: 'lg', colorPrimary: '#3B82F6' },
-};
-
-const pageConfig: GranularityConfig<'page'> = {
-  id: 'landing-page-1',
-  granularity: 'page',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  title: 'Landing Page',
-  children: [
-    { childGranularity: 'section', ref: 'hero-section-1', slot: 'main' },
-    { childGranularity: 'section', ref: 'features-section-1', slot: 'main' },
-  ],
-};
-```
-
-### Granularity Hierarchy
-
-Factors cascade DOWN from higher levels to lower levels:
-
-```
-template (Level 6) - Highest
-    ↓
-layout (Level 5)
-    ↓
-page (Level 4)
-    ↓
-section (Level 3)
-    ↓
-component (Level 2)
-    ↓
-atom (Level 1) - Lowest
-```
-
-```typescript
-import { GRANULARITY_HIERARCHY, getGranularityRank } from '@nikkory/vibe-engine';
-
-// Check hierarchy
-console.log(GRANULARITY_HIERARCHY);
-// ['template', 'layout', 'page', 'section', 'component', 'atom']
-
-// Compare levels
-console.log(getGranularityRank('template')); // 6
-console.log(getGranularityRank('page')); // 4
-console.log(getGranularityRank('atom')); // 1
-```
-
-### GranularityTemplate<G> - With Metadata
-
-Templates extend configs with 8 metadata fields for sharing and versioning:
-
-```typescript
-const heroTemplate: GranularityTemplate<'section'> = {
-  // Config fields
-  id: 'hero-instance-1',
-  granularity: 'section',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  title: 'Hero Section',
-
-  // 8 Metadata fields
-  templateId: 'hero-section-v1',
-  templateName: 'Hero Section Template',
-  description: 'Full-width hero with headline and CTA',
-  author: 'Nikkory Team',
-  version: '1.0.0',
-  tags: ['hero', 'landing', 'cta'],
-  visibility: 'public', // 'private' | 'team' | 'public'
-  thumbnail: 'https://nikkory.com/templates/hero.png',
-};
-```
-
-### Factor Cascade System
-
-Factors are defined with `level` and `cascadeDown` - no more hardcoded arrays:
-
-```typescript
-import type { GranularityFactorDefinition } from '@nikkory/vibe-engine';
-
-const spacingFactor: GranularityFactorDefinition = {
-  id: 'spacing',
-  name: 'Spacing',
-  category: 'layout',
-  level: 'template', // Minimum level where this factor applies
-  cascadeDown: true, // Cascade to page → section → component → atom
-  defaults: {
-    'material-design': 'md',
-    'ios-hig': 'sm',
-  },
-  options: ['xs', 'sm', 'md', 'lg', 'xl'],
-  description: 'Controls spacing between elements',
-};
-
-// Dynamic factor resolution (replaces hardcoded 8/13/24 arrays)
-// getFactorsForLevel('page') → Returns all factors for page level
-// getFactorsForLevel('section') → Returns all factors for section level
-```
-
-### Level-Specific Slot Positions
-
-Slots vary by granularity level:
-
-```typescript
-import type { GranularitySlotPosition } from '@nikkory/vibe-engine';
-
-// Page slots (6 positions)
-type PageSlots = GranularitySlotPosition<'page'>;
-// = 'header' | 'main' | 'sidebar' | 'footer' | 'overlay' | 'floating'
-
-// Section slots (5 positions)
-type SectionSlots = GranularitySlotPosition<'section'>;
-// = 'header' | 'content' | 'footer' | 'sidebar' | 'overlay'
-
-// Layout slots (4 positions)
-type LayoutSlots = GranularitySlotPosition<'layout'>;
-// = 'header' | 'main' | 'sidebar' | 'footer'
-
-// Template slots (3 positions)
-type TemplateSlots = GranularitySlotPosition<'template'>;
-// = 'pages' | 'shared' | 'assets'
-```
-
-### Level-Specific Type Aliases
-
-Convenience type aliases for each level:
-
-```typescript
-import type {
-  AtomConfig,
-  ComponentConfig,
-  SectionGranularityConfig,
-  PageConfig,
-  LayoutGranularityConfig,
-  TemplateConfig,
-  // Template types
-  AtomTemplate,
-  ComponentTemplate,
-  SectionGranularityTemplate,
-  PageTemplate,
-  LayoutTemplate,
-  TemplateGranularityTemplate,
-} from '@nikkory/vibe-engine';
-
-// These are aliases for GranularityConfig<Level>
-const atom: AtomConfig = { id: '1', granularity: 'atom', ... };
-const component: ComponentConfig = { id: '2', granularity: 'component', ... };
-const section: SectionGranularityConfig = { id: '3', granularity: 'section', ... };
-const page: PageConfig = { id: '4', granularity: 'page', ... };
-const layout: LayoutGranularityConfig = { id: '5', granularity: 'layout', ... };
-const template: TemplateConfig = { id: '6', granularity: 'template', ... };
-```
-
-### Factor Resolution Types
-
-```typescript
-import type {
-  GranularityFactorResolutionResult,
-  GranularityFactorOverride,
-  GranularityFactorQueryOptions,
-  GranularityFactorCascadeConfig,
-} from '@nikkory/vibe-engine';
-import { FACTOR_PRIORITY } from '@nikkory/vibe-engine';
-
-// Factor priority (higher wins)
-console.log(FACTOR_PRIORITY.DEFAULT); // 0
-console.log(FACTOR_PRIORITY.CASCADE); // 25
-console.log(FACTOR_PRIORITY.CONFIG); // 50
-console.log(FACTOR_PRIORITY.USER); // 100 (always wins)
-```
-
----
-
-## Composition Generator
-
-**New in v4.0.0**: Generate higher-level compositions (pages from sections, layouts from pages, templates from pages).
-
-### Usage
-
-```typescript
-import { CompositionGenerator } from '@nikkory/vibe-engine';
-import type { CompositionConfig } from '@nikkory/vibe-engine';
-
-const generator = new CompositionGenerator();
-
-// Generate a landing page from sections
-const result = generator.generateComposition({
-  parent: LANDING_PAGE_DEFINITION,
-  children: [HERO_SECTION, FEATURES_SECTION, CTA_SECTION],
-  strategy: 'slots',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  outputDir: './src/pages',
-});
-
-console.log(result.componentPath); // './src/pages/MaterialDesignLandingPageEnterprise.tsx'
-console.log(result.linesOfCode); // 150-300 for enterprise tier
-console.log(result.displayName); // 'MaterialDesignLandingPageEnterprise'
-```
-
-### Composition Strategies
-
-**1. Slot Composition** - Pages compose sections via named slots:
-
-```typescript
-strategy: 'slots';
-// Parent: Page definition
-// Children: Section definitions
-// Result: Page component with section slots
-```
-
-**2. Children Composition** - Layouts compose pages via children prop:
-
-```typescript
-strategy: 'children';
-// Parent: Layout definition
-// Children: Page definitions
-// Result: Layout component with page children
-```
-
-**3. Template Composition** - Templates compose multiple pages:
-
-```typescript
-strategy: 'template';
-// Parent: Template definition
-// Children: Page definitions
-// Result: Template with all pages
-```
-
-### Generation Result
-
-```typescript
-interface GenerationResult {
-  success: boolean;
-  componentPath: string; // Generated file path
-  linesOfCode: number; // Total LOC (varies by tier)
-  displayName: string; // Component display name
-  error?: string; // Error message if failed
-}
-```
-
-### Tier Features
-
-The generator respects tier-specific features:
-
-| Tier           | LOC     | Features                             |
-| -------------- | ------- | ------------------------------------ |
-| **Basic**      | 30-50   | Core composition, basic imports      |
-| **Standard**   | 50-150  | + forwardRef, displayName, variants  |
-| **Enterprise** | 150-300 | + memo, useCallback, analytics, ARIA |
-
----
-
-## Matrix Multiplication Code Generation
-
-**New in v4.0.0**: Dynamic code generation using matrix multiplication algorithm.
-
-### Overview
-
-The Matrix Multiplication System replaces hardcoded component generation with a dynamic algorithm that multiplies 4 matrices to produce component configurations:
-
-```
-Component = Matrix1 × Matrix2 × Matrix3 × Matrix4 + Override
-```
-
-### The 4 Matrices
-
-| Matrix       | Input                     | Output             | Source                                 |
-| ------------ | ------------------------- | ------------------ | -------------------------------------- |
-| **Matrix 1** | Component ID              | HTML Element Type  | COMPONENT_REGISTRY                     |
-| **Matrix 2** | Factor ID + Design System | Factor Values      | FACTOR_REGISTRY + user overrides       |
-| **Matrix 3** | Tier                      | React Patterns     | Tier definitions                       |
-| **Matrix 4** | Component × Factor        | Applicable Factors | COMPONENT_REGISTRY.factorApplicability |
-
-### Usage
-
-```typescript
-import { MatrixResolver, TemplateEngine } from '@nikkory/vibe-engine/matrix';
-
-// Initialize resolver
-const resolver = new MatrixResolver();
-const templateEngine = new TemplateEngine();
-
-// Resolve component configuration
-const config = resolver.resolve({
-  componentId: 'button',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  factor24Config: {
-    4: 'md', // borderRadius = md (rounded corners)
-    5: 'md', // shadowStyle = md (elevation)
-    17: 'md', // spacing = md
-  },
-});
-
-// Generate React component code
-const code = templateEngine.generate(config);
-console.log(config.classNames);
-// → ['rounded-md', 'shadow-md', 'px-4 py-2']
-```
-
-### ResolvedComponentConfig
-
-The `resolve()` method returns a complete configuration:
-
-```typescript
-interface ResolvedComponentConfig {
-  componentName: string; // 'ButtonMaterialDesignEnterprise'
-  elementType: string; // 'button' (from COMPONENT_REGISTRY)
-  tier: Tier; // 'enterprise'
-  designSystem: DesignSystem; // 'material-design'
-  classNames: readonly string[]; // ['rounded-md', 'shadow-md', ...]
-  imports: readonly string[]; // React imports for tier
-  wrappers: readonly string[]; // ['memo', 'forwardRef']
-  features: readonly string[]; // ['displayName', 'analytics']
-}
-```
-
-### Matrix 2: Factor Override System
-
-User overrides take precedence over design system defaults:
-
-```typescript
-const config = resolver.resolve({
-  componentId: 'button',
-  designSystem: 'material-design', // Default: borderRadius = 'md'
-  tier: 'enterprise',
-  factor24Config: {
-    4: 'xl', // Override: borderRadius = 'xl' (more rounded)
-  },
-});
-
-console.log(config.classNames);
-// → ['rounded-xl', 'shadow-md', 'px-4 py-2']
-//    ^^^^^^^^^^^ User override applied!
-```
-
-### Design System Differentiation
-
-Different design systems produce different code:
-
-```typescript
-// Material Design: Rounded corners + shadows
-const material = resolver.resolve({
-  componentId: 'button',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  factor24Config: { 4: 'md', 5: 'md', 17: 'md' },
-});
-console.log(material.classNames);
-// → ['rounded-md', 'shadow-md', 'px-4 py-2']
-
-// Brutalism: Sharp corners + no shadows
-const brutalism = resolver.resolve({
-  componentId: 'button',
-  designSystem: 'brutalism',
-  tier: 'enterprise',
-  factor24Config: { 4: 'none', 5: 'none', 17: 'md' },
-});
-console.log(brutalism.classNames);
-// → ['rounded-none', 'shadow-none', 'px-4 py-2']
-```
-
-### Tier Patterns (Matrix 3)
-
-Each tier generates different React patterns:
-
-| Tier           | Imports                                      | Wrappers             | Features                   | LOC     |
-| -------------- | -------------------------------------------- | -------------------- | -------------------------- | ------- |
-| **Basic**      | `React`                                      | `React.FC`           | None                       | 30-50   |
-| **Standard**   | `React`, `forwardRef`                        | `forwardRef`         | `displayName`              | 50-150  |
-| **Enterprise** | `React`, `forwardRef`, `memo`, `useCallback` | `memo`, `forwardRef` | `displayName`, `analytics` | 150-300 |
-
-### Generated Code Example
-
-**Enterprise Tier with Material Design:**
-
-```typescript
-/**
- * ButtonMaterialDesignEnterprise Component
- *
- * Generated by Nikkory Vibe Matrix Generator
- * Powered by Nikkory
- */
-
-import * as React from 'react';
-import { forwardRef, memo, useCallback } from 'react';
+| Tier       | LOC     | Features                                |
+| ---------- | ------- | --------------------------------------- |
+| Basic      | 30-50   | Core props, basic styling               |
+| Standard   | 50-150  | + forwardRef, displayName, variants     |
+| Enterprise | 150-300 | + memo, useCallback, analytics, ARIA    |
+
+### Example Output (Enterprise Tier)
+
+Generated Material Design Button with full production-ready features:
+
+```typescript
+import React, { memo, forwardRef, useCallback } from 'react';
+
+export const MaterialDesignButtonEnterprise = memo(
+  forwardRef<HTMLButtonElement, MaterialDesignButtonEnterpriseProps>(
+    ({ children, analyticsEvent, onClick, ...props }, ref) => {
+      const handleClick = useCallback(
+        (e: React.MouseEvent<HTMLButtonElement>): void => {
+          if (analyticsEvent && typeof window !== 'undefined') {
+            (window as unknown as { dataLayer?: unknown[] }).dataLayer?.push({
+              event: analyticsEvent,
+              category: 'component',
+              action: 'click',
+            });
+          }
+          onClick?.(e);
+        },
+        [analyticsEvent, onClick]
+      );
 
-export const ButtonMaterialDesignEnterprise = memo(
-  forwardRef<HTMLButtonElement, ButtonMaterialDesignEnterpriseProps>(
-    ({ children, className, ...props }, ref) => {
       return (
         <button
           ref={ref}
-          className={`rounded-md shadow-md px-4 py-2 ${className ?? ''}`}
+          onClick={handleClick}
+          className="bg-blue-500 hover:bg-blue-600 rounded-full px-6 py-3"
+          aria-label={props['aria-label']}
           {...props}
         >
           {children}
@@ -1044,179 +112,56 @@ export const ButtonMaterialDesignEnterprise = memo(
   )
 );
 
-ButtonMaterialDesignEnterprise.displayName = 'ButtonMaterialDesignEnterprise';
-```
-
-### ComponentGenerator Integration
-
-**As of v4.0.0**, the `ComponentGenerator` class internally uses the Matrix Multiplication system for all code generation:
-
-```typescript
-import { ComponentGenerator } from '@nikkory/vibe-engine';
-
-const generator = new ComponentGenerator();
-
-// ComponentGenerator now uses MatrixResolver + TemplateEngine internally
-const result = generator.generate({
-  componentType: 'button',
-  designSystem: 'material-design',
-  tier: 'enterprise',
-  factorOverrides: { 2: 'lg' }, // Size override
-});
-
-console.log(result.code.componentCode); // Clean, performant code (39-44 LOC)
-console.log(result.style.tailwindClasses); // Resolved classes
-```
-
-**Benefits**:
-
-- ✅ **Performance**: 0.05ms average generation time (100x faster than target)
-- ✅ **Memory**: 1.47MB usage (3x under target)
-- ✅ **Output Quality**: 39-44 lines (under 100-line target)
-- ✅ **Backward Compatible**: Public API unchanged
-
-### Testing
-
-Test the matrix system with the included test script:
-
-```bash
-# Run matrix tests
-npx tsx packages/engine/src/matrix/test-matrix.ts
+MaterialDesignButtonEnterprise.displayName = 'MaterialDesignButtonEnterprise';
 ```
 
-**Test Output:**
-
-```
-✅ Material Design Button Test Complete
-  Component Name: ButtonMaterialDesignEnterprise
-  Class Names: rounded-md, px-4 py-2
-
-✅ Brutalism Button Test Complete
-  Component Name: ButtonBrutalismEnterprise
-  Class Names: rounded-none, px-4 py-2
-
-🎯 Result: ✅ DIFFERENT (PASS)
-✅ Design systems generate DIFFERENT code (Target State met!)
-```
+**Generated in <0.1s** with full TypeScript types and tests included.
 
 ---
 
-## Advanced Usage
+## 🎯 24-Factor System
 
-### Validators
+The engine supports 24 configurable design factors:
 
-```typescript
-import {
-  isValidColorScheme,
-  isValidSize,
-  isValidAnimation,
-  validateFactor24Completeness,
-} from '@nikkory/vibe-engine';
+**Basic Factors (1-6)**
+- Color, Size, Variant, Shape, Position, Icon Position
 
-// Validate individual factors
-if (isValidColorScheme('primary')) {
-  console.log('Valid color');
-}
-
-// Validate complete configuration
-const result = validateFactor24Completeness(config);
-if (!result.isComplete) {
-  console.log('Missing factors:', result.missing);
-}
-```
-
-### Result/Option Types
-
-```typescript
-import { Result, Option } from '@nikkory/vibe-engine';
+**Standard Factors (7-11)**
+- State, Animation, Elevation, Accessibility, Alignment
 
-// Result type for error handling
-function generateCode(): Result<string, Error> {
-  try {
-    const code = '...';
-    return Result.ok(code);
-  } catch (error) {
-    return Result.fail(new Error('Generation failed'));
-  }
-}
+**Standard Extended (12-16)**
+- Orientation, Density, Loading State, Responsive, Theme
 
-const result = generateCode();
-if (result.isSuccess()) {
-  console.log(result.getValue());
-} else {
-  console.error(result.getError());
-}
-
-// Option type for nullable values
-const maybeComponent = Option.fromNullable(getComponent('button'));
-if (maybeComponent.isSome()) {
-  console.log(maybeComponent.unwrap().name);
-}
-```
-
----
-
-## Package Structure
-
-```
-@nikkory/vibe-engine/
-├── dist/
-│   ├── index.js         # CommonJS
-│   ├── index.mjs        # ES Module
-│   ├── index.d.ts       # TypeScript types
-│   ├── browser.js       # Browser build
-│   └── browser.mjs
-├── src/
-│   ├── generator/       # Style generation
-│   ├── presets/         # Component registry
-│   ├── constants/       # Design systems, tiers
-│   ├── types/           # TypeScript definitions
-│   └── utils/           # Utility functions
-└── package.json
-```
+**Enterprise Factors (17-24)**
+- Spacing, Typography, Border, Opacity, Overflow, Cursor, Z-Index, Transition
 
 ---
 
-## TypeScript Support
-
-Full TypeScript support with strict mode enabled:
-
-```typescript
-import type {
-  // Core types
-  DesignSystem,
-  Tier,
-  ComponentType,
-  Framework,
-
-  // Configuration types
-  Factor24Config,
-  StyleConfig,
-  GenerationConfig,
+## 📖 Documentation
 
-  // Registry types
-  RegistryComponentDefinition,
-  ComponentCategory,
-  ComponentStatus,
+For detailed API documentation, examples, and guides:
 
-  // Utility types
-  Result,
-  Option,
-} from '@nikkory/vibe-engine';
-```
+- **Website**: https://nikkory.com
+- **Full Documentation**: https://docs.nikkory.com
+- **GitHub**: https://github.com/kemonra/nikkory-vibe
 
 ---
 
-## Browser Support
+## 📊 Component Registry
 
-- Chrome/Edge: Latest 2 versions
-- Firefox: Latest 2 versions
-- Safari: Latest 2 versions
-- Node.js: ≥18.0.0
+169 pre-configured components across 12 categories:
+
+- **Basic**: Button, Input, Textarea, Checkbox, Radio, Switch, Select, Slider
+- **Feedback**: Alert, Badge, Chip, Progress, Spinner, Skeleton, Tooltip
+- **Navigation**: Tabs, Menu, Breadcrumb, Pagination, Stepper
+- **Data Display**: Card, Table, List, Accordion, Avatar
+- **Overlay**: Modal, Drawer, Popover
+- **Date/Time**: Date Picker, Calendar
+- **Media**: Audio, Video, Image, File
 
 ---
 
-## Related Packages
+## 🔧 Related Packages
 
 - **[@nikkory/vibe-react](https://npmjs.com/package/@nikkory/vibe-react)** - React component library
 - **[@nikkory/vibe-patterns](https://npmjs.com/package/@nikkory/vibe-patterns)** - 634 pre-built patterns
@@ -1224,42 +169,32 @@ import type {
 
 ---
 
-## Migration from v3.x
-
-See [Migration Guide](../../docs/MIGRATION-v3-to-v4.md) for detailed instructions.
+## 🌐 Browser Support
 
-**Quick migration**:
-
-```bash
-# Replace old package
-npm uninstall @nikkory/vibe-core @nikkory/vibe-shared
-npm install @nikkory/vibe-engine
-
-# Update imports
-# Old: import { ... } from '@nikkory/vibe-core'
-# New: import { ... } from '@nikkory/vibe-engine'
-```
+- Chrome/Edge: Latest 2 versions
+- Firefox: Latest 2 versions
+- Safari: Latest 2 versions
+- Node.js: ≥18.0.0
 
 ---
 
-## Contributing
+## 📄 License
 
-We welcome contributions! See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+MIT © Nikkory
 
----
+**Copyright © 2024-2026 Nikkory. All rights reserved.**
 
-## License
+This software and its source code are proprietary to Nikkory and protected by copyright law. Unauthorized copying, distribution, modification, or use of this software, via any medium, is strictly prohibited without express written permission from Nikkory.
 
-MIT © Nikkory
+For licensing inquiries, please contact: dev@nikkory.com
 
 ---
 
-## Support
+## 💬 Support
 
-- **Documentation**: https://docs.nikkory.com
 - **GitHub Issues**: https://github.com/kemonra/nikkory-vibe/issues
-- **Discord**: https://discord.gg/nikkory
 - **Email**: dev@nikkory.com
+- **Website**: https://nikkory.com
 
 ---