@damarkuncoro/meta-architecture-style-engine 0.1.1 → 0.1.3

package/README.md

@@ -1,831 +1,364 @@
-# Meta Architecture Style Engine (MASE)
-
-<div align="center">
-
-**Official Style Governance & Runtime for Meta Architecture**
-
-[![NPM Version](https://img.shields.io/npm/v/@damarkuncoro/meta-architecture-style-engine)](https://www.npmjs.com/package/@damarkuncoro/meta-architecture-style-engine)
-[![NPM Downloads](https://img.shields.io/npm/dw/@damarkuncoro/meta-architecture-style-engine)](https://www.npmjs.com/package/@damarkuncoro/meta-architecture-style-engine)
-[![License](https://img.shields.io/npm/l/@damarkuncoro/meta-architecture-style-engine)](LICENSE)
-[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue)](https://www.typescriptlang.org/)
-[![Build Status](https://img.shields.io/badge/Build-Passing-green)]()
-[![Code Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen)]()
-[![Type Safety](https://img.shields.io/badge/Type%20Safety-100%25-brightgreen)]()
-[![Platform Agnostic](https://img.shields.io/badge/Platform%20Agnostic-100%25-brightgreen)]()
-[![Bundle Size](https://img.shields.io/badge/Bundle%20Size-12KB-brightgreen)]()
-[![Performance](https://img.shields.io/badge/Performance-%3C5ms-brightgreen)]()
-[![PRs Welcome](https://img.shields.io/badge/PRs-Welcome-brightgreen)](https://github.com/damarkuncoro/meta-architecture-style-engine/pulls)
-[![Code of Conduct](https://img.shields.io/badge/Code%20of%20Conduct-Enabled-blue)](https://github.com/damarkuncoro/meta-architecture-style-engine/blob/main/CODE_OF_CONDUCT.md)
-
-*A Constitutional Styling System - Where Style is Law, Not Just Visuals*
-
-</div>
-
----
-
-## 📖 Table of Contents
-
-- [Overview](#-overview)
-- [Philosophy](#-philosophy)
-- [Key Features](#-key-features)
-- [Architecture](#-architecture)
-- [Installation](#-installation)
-- [Quick Start](#-quick-start)
-- [Usage](#-usage)
-  - [Runtime Usage](#runtime-usage)
-  - [CLI Usage](#cli-usage)
-  - [DSL Syntax](#dsl-syntax)
-- [API Reference](#-api-reference)
-- [Examples](#-examples)
-- [Development](#-development)
-- [Contributing](#-contributing)
-- [License](#-license)
-
----
-
-## 🎯 Overview
-
-**MASE (Meta Architecture Style Engine)** is a powerful style governance and runtime engine designed for Meta Architecture. Unlike traditional styling frameworks, MASE treats styling as a constitutional system where every style decision is validated against a set of rules and constraints.
-
-MASE enforces design system rules, manages tokens, and compiles style contracts into various output formats (CSS, React Native, PDF) through a sophisticated governance system inspired by the Trias Politica principle.
-
-### What Makes MASE Different?
-
-| Traditional Approach | MASE Approach |
-| :--- | :--- |
-| **Utility Classes** | **Style Contracts** (Legal Articles) |
-| **Config Files** | **Constitutions** (Laws) |
-| **Prefix Variants** (`hover:`) | **Contextual Laws** |
-| **Compilers** | **Style Resolution Engine** (Judiciary) |
-| **CSS Output** | **Canonical Style Graph** + **Materializer** |
-| **Best Practices** | **Enforced Governance** |
-
----
-
-## 💡 Philosophy
-
-MASE is not just another "Tailwind Killer" or styling framework. It's a **Constitutional Styling System** — a governance system for styling where:
-
-> **"Style is not just visual, but a legal decision that must be validated."**
-
-### Core Principles
-
-1. **Separation of Concerns**: Complete separation between specification, validation, and materialization
-2. **Type Safety**: Every style decision is validated at compile-time and runtime
-3. **Platform Agnostic**: The core engine doesn't know about CSS, React Native, or any specific platform
-4. **Immutable Truth**: Style contracts and token registries are immutable sources of truth
-5. **Audit Trail**: Every style resolution can be traced back to its constitutional origin
-
----
-
-## ✨ Key Features
-
-### 🏛️ Style Governance
-- **Constitution-based Rules**: Define what's legal in your design system
-- **Domain Taxonomy**: Organize rules by semantic domains (Layout, Typography, Interaction)
-- **Token Registry**: Centralized management of design tokens
-- **Violation Detection**: Automatic detection of style violations with educational error messages
-
-### ⚖️ Runtime Style Resolution
-- **StyleProvider**: React context provider for theme and device context
-- **StyleContract**: Type-safe style contracts with validation
-- **Dynamic Resolution**: Context-aware style resolution based on theme, device, and platform
-- **Performance Optimized**: Sub-5ms resolution per component
-
-### 🎨 Multi-Platform Support
-- **CSS Materializer**: Generate optimized CSS for web applications
-- **React Native Materializer**: Generate StyleSheet for native applications
-- **PDF Materializer**: Generate render instructions for PDF generation
-- **Extensible**: Easy to add custom materializers for any platform
-
-### 📝 Contract DSL
-- **Declarative Syntax**: Define style contracts using a specialized DSL
-- **Type-Safe**: Compile-time validation of contract definitions
-- **Context-Aware**: Define responsive and state-based styling rules
-- **Theme Support**: Built-in support for light/dark themes
-
-### 🔧 Developer Experience
-- **CLI Tools**: Command-line interface for validation, compilation, and generation
-- **TypeScript Support**: Full TypeScript support with type definitions
-- **Dual Build**: Supports both ESM and CJS modules
-- **Zero-Dependency Testing**: Uses Node.js native test runner for lightweight and fast testing
-- **Hot Reload**: Watch mode for development
-
----
-
-## 🏗️ Architecture
-
-MASE implements the **Trias Politica** principle, separating styling into three independent bodies:
-
-### 1. The Constitution (Spec Layer)
-The **Written Law** that defines what's legal in the design system universe.
-
-- **Semantic Namespace**: Universal language (e.g., `background.intent.primary`)
-- **Domain Taxonomy**: Legal area groupings (Layout, Typography, Interaction)
-- **Token Registry**: The "currency" of the nation (atomic values)
-
-```typescript
-// Example Constitution
-const buttonConstitution = {
-  domain: 'interaction',
-  rules: {
-    intent: {
-      allows: ['color.primary', 'color.secondary'],
-      default: 'color.primary'
-    },
-    padding: {
-      allows: ['space.sm', 'space.md', 'space.lg'],
-      default: 'space.md'
-    }
-  }
-};
-```
-
-### 2. The Judiciary (Style Resolution Engine - SRE)
-The **Judicial Body (Judge)** that validates style contracts.
-
-- **Responsibility**: Accepts `StyleContract` and `Context`, decides if valid or violates constitution
-- **Characteristics**:
-  - ❌ Doesn't know CSS
-  - ❌ Doesn't know Platform (Web/Native)
-  - ✅ Only knows **Legal vs Illegal**
-- **Output**: `StyleResolutionResult` (Resolved Node or Violation Verdict)
-
-```typescript
-// Example Resolution
-const result = engine.resolve(contract, constitution, context);
-// Returns: { valid: true, className: 'bg-primary p-md' }
-// Or: { valid: false, violations: [...] }
-```
-
-### 3. The Executive (Style Materialization Engine - SME)
-The **Executive Body (Executor)** that executes judicial decisions into physical reality.
-
-- **Responsibility**: Execute judicial decisions into actual styles
-- **Plugin System**:
-  - **CSS Materializer**: Converts decisions to CSS (Web)
-  - **Native Materializer**: Converts decisions to StyleSheet (React Native)
-  - **PDF/Canvas**: Converts decisions to render instructions
-
-```typescript
-// Example Materialization
-const cssMaterializer = new CSSMaterializer();
-const css = cssMaterializer.materialize(resolvedStyle, context);
-// Returns: ".button { background: #007bff; padding: 1rem; }"
-```
-
-### Architecture Diagram
-
-```
-┌─────────────────────────────────────────────────────────────┐
-│                    MASE Architecture                         │
-├─────────────────────────────────────────────────────────────┤
-│                                                               │
-│  ┌──────────────────┐      ┌──────────────────┐            │
-│  │   Constitution   │─────▶│   Judiciary      │            │
-│  │   (Spec Layer)   │      │   (SRE)          │            │
-│  │                  │      │                  │            │
-│  │  • Semantic NS   │      │  • Validation    │            │
-│  │  • Domain Tax    │      │  • Resolution    │            │
-│  │  • Token Reg     │      │  • Violation     │            │
-│  └──────────────────┘      └────────┬─────────┘            │
-│                                    │                       │
-│                                    ▼                       │
-│                          ┌──────────────────┐              │
-│                          │   Executive      │              │
-│                          │   (SME)          │              │
-│                          │                  │              │
-│                          │  • CSS Mat       │              │
-│                          │  • RN Mat        │              │
-│                          │  • PDF Mat       │              │
-│                          └──────────────────┘              │
-│                                                               │
-└─────────────────────────────────────────────────────────────┘
-```
-
----
+# MASE - Meta Architecture Style Engine
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.0-blue.svg)](https://www.typescriptlang.org/)
+[![Build Status](https://img.shields.io/badge/build-passing-brightgreen.svg)]()
+[![Version](https://img.shields.io/badge/version-0.1.4-blue.svg)](https://github.com/damarkuncoro/meta-architecture-style-engine)
+
+A comprehensive, theme-aware styling engine for modern web applications. MASE provides atomic CSS utilities, design token management, and multi-platform materialization with full TypeScript support.
+
+## 🚀 Features
+
+### Core Capabilities
+- **700+ Atomic CSS Utilities** - Complete coverage of all modern CSS properties
+- **Design Token System** - Centralized token management with theme support
+- **Multi-Platform Materialization** - Generate styles for Web, React Native, PDF, and more
+- **Constitutional Styling** - Enforce design system rules and governance
+- **Dark Mode Support** - Automatic theme switching with CSS variables
+- **Full TypeScript Support** - Type-safe development with comprehensive type definitions
+- **Style Governance** - Built-in validation and compliance checking
+- **Performance Optimization** - Caching and efficient style resolution
+
+### Integration Options
+- **PostCSS Plugin** - Automatic CSS variable generation
+- **Atomic CSS Generator** - Utility-first approach similar to Tailwind
+- **Tailwind Preset** - Seamless integration with existing Tailwind projects
+- **CSS-in-JS** - Support for styled-components, emotion, and more
+- **React Integration** - React Provider and hooks for runtime styling
+
+### Specialized Handlers
+- **Layout** - Display, position, visibility, z-index, overflow, object-fit
+- **Flexbox** - Complete flexbox utilities with justify/align support
+- **Grid** - Full CSS Grid support with template columns/rows
+- **Typography** - Font size, weight, line-height, text alignment
+- **Color** - Background, text, and border colors
+- **Effects** - Shadows, border radius, opacity
+- **Background** - Background image, position, repeat, size, gradients
+- **Border** - Border radius, width, color, style, outline
+- **Transform** - Scale, rotate, translate, skew, perspective
+- **Transition** - Transition properties, timing functions, animations
+- **Interactivity** - Cursor, pointer events, resize, scroll behavior
+- **Tables** - Border collapse, spacing, layout, caption side
+- **SVG** - Fill, stroke, stroke width
+- **Accessibility** - Forced color adjust, screen reader utilities, focus states
+- **Filters** - Blur, brightness, contrast, drop-shadow, grayscale, hue-rotate, invert, saturate, sepia, backdrop-filter
 
 ## 📦 Installation
 
-### Install the Package
-
 ```bash
 npm install @damarkuncoro/meta-architecture-style-engine
 ```
 
-### Install CLI Globally (Optional)
+### Peer Dependencies
 
 ```bash
-npm install -g @damarkuncoro/meta-architecture-style-engine
+npm install @damarkuncoro/meta-architecture@^2.0.4 react@>=18.0.0 postcss@^8.0.0
 ```
 
-### Peer Dependencies
+## 🎯 Quick Start
 
-MASE requires the following peer dependencies:
+### Option 1: PostCSS Plugin (Recommended)
 
-```json
-{
-  "peerDependencies": {
-    "@damarkuncoro/meta-architecture": "^2.0.4",
-    "react": ">=18.0.0"
-  }
+**postcss.config.js**
+```javascript
+export default {
+  plugins: [
+    require('@damarkuncoro/meta-architecture-style-engine/postcss')({
+      prefix: '--',
+      rootSelector: ':root',
+      generateDarkMode: true,
+      darkModeAttribute: 'data-theme="dark"'
+    })
+  ]
 }
 ```
 
----
-
-## 🚀 Quick Start
-
-Get started with MASE in 5 minutes.
-
-### Step 1: Create a Contract File
-
-Create a file named `Button.contract.dsl`:
+**styles.css**
+```css
+/* MASE CSS variables are automatically injected */
 
-```dsl
-contract Button {
-  domain: interaction
-  
-  intent {
-    allows: [color.primary, color.secondary]
-    default: color.primary
-  }
-  
-  padding {
-    allows: [space.sm, space.md, space.lg]
-    default: space.md
-  }
+body {
+  font-family: system-ui, sans-serif;
+  color: var(--color-text-primary);
+  background-color: var(--color-background);
 }
-```
-
-### Step 2: Validate Your Contract
 
-```bash
-mase validate Button.contract.dsl
+.button {
+  background-color: var(--color-primary);
+  color: var(--color-white);
+  padding: var(--space-md);
+  border-radius: var(--radius-md);
+}
 ```
 
-Output:
-```
-✅ Contract is valid!
-```
+### Option 2: Atomic CSS Generator
 
-### Step 3: Compile to TypeScript
+```typescript
+import { AtomicCSSGenerator } from '@damarkuncoro/meta-architecture-style-engine';
+import { TOKENS } from '@damarkuncoro/meta-architecture-style-engine';
+
+const generator = new AtomicCSSGenerator();
+const css = generator.generate(TOKENS, {
+  prefix: 'mase-',
+  selector: ':root',
+  includeReset: true
+});
 
-```bash
-mase compile Button.contract.dsl -o Button.ts
+console.log(css);
 ```
 
-This generates a TypeScript file with your contract.
+### Option 3: Tailwind Preset
 
-### Step 4: Generate CSS
+**tailwind.config.js**
+```javascript
+import { createMasePreset } from '@damarkuncoro/meta-architecture-style-engine/tailwind';
 
-```bash
-mase generate-css Button.contract.dsl -o button.css
+export default {
+  presets: [
+    createMasePreset({
+      useCssVariables: true,
+      variablePrefix: '--'
+    })
+  ]
+}
 ```
 
-This generates CSS classes based on your contract.
-
-### Step 5: Use in Your Application
+### Option 4: React Integration
 
-```tsx
-import { StyleProvider, useStyleContext } from '@damarkuncoro/meta-architecture-style-engine';
-import { ButtonContract } from './Button';
+```typescript
+import { StyleProvider, useStyleContract } from '@damarkuncoro/meta-architecture-style-engine';
 
 function App() {
   return (
-    <StyleProvider initialTheme="light">
-      <MyComponent />
+    <StyleProvider>
+      <YourComponent />
     </StyleProvider>
   );
 }
 
-function MyComponent() {
-  const { theme, device } = useStyleContext();
-  
-  const buttonStyles = ButtonContract.resolve({
-    device,
-    theme,
-    platform: 'web'
+function YourComponent() {
+  const { resolveStyles } = useStyleContract();
+  const styles = resolveStyles({
+    backgroundColor: 'primary',
+    padding: 'md',
+    borderRadius: 'md'
   });
   
-  return (
-    <button className={buttonStyles.className}>
-      Click me
-    </button>
-  );
+  return <div style={styles}>Hello MASE!</div>;
 }
 ```
 
----
-
-## 📚 Usage
-
-### Runtime Usage
-
-#### StyleProvider
-
-Wrap your application with the `StyleProvider` to enable style resolution.
-
-**Web Usage (Default):**
+## 📚 Documentation
 
-```tsx
-import { StyleProvider } from '@damarkuncoro/meta-architecture-style-engine';
+### Core Documentation
+- [Quick Start Guide](docs/quick-start.md) - Get started with MASE in minutes
+- [Architecture Diagram](docs/architecture-diagram.md) - System architecture overview
+- [DSL Reference](docs/dsl-reference.md) - Domain-specific language guide
+- [Migration Guide](docs/migration-guide.md) - Migrate from other systems
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
 
-function App() {
-  return (
-    <StyleProvider initialTheme="light">
-      <YourApp />
-    </StyleProvider>
-  );
-}
-```
-
-**Native Usage (with Adapter):**
+### Integration Guides
+- [CSS Import Guide](docs/integrations/css-import-guide.md) - Using MASE with CSS imports
+- [Atomic CSS Complete Guide](docs/integrations/atomic-css-complete-guide.md) - Complete utility reference
+- [Next.js Integration](docs/integrations/nextjs.md) - Next.js specific setup
+- [React Native Integration](docs/integrations/react-native.md) - React Native setup
+- [Storybook Integration](docs/integrations/storybook.md) - Storybook integration
 
-MASE is platform-agnostic. For non-web platforms, inject the appropriate adapter.
+### Development Documentation
+- [Development Guide](docs/development/guide.md) - Contributing to MASE
+- [Integration Layer Review](docs/development/integration-layer-comprehensive-review.md) - Integration layer analysis
+- [Recommendations Implementation](docs/development/recommendations-implementation.md) - Implemented improvements
+- [Atomic CSS Implementation](docs/development/final-atomic-css-implementation.md) - Complete implementation report
+- [Comprehensive Atomic CSS Implementation](docs/development/comprehensive-atomic-css-implementation.md) - Detailed implementation guide
 
-```tsx
-import { StyleProvider, NativePlatformAdapter } from '@damarkuncoro/meta-architecture-style-engine';
+### Examples
+- [Basic Examples](examples/basic/) - Simple component examples
+- [Advanced Examples](examples/advanced/) - Complex use cases
+- [Integration Examples](examples/integration/) - Integration patterns
 
-const nativeAdapter = new NativePlatformAdapter();
+## 🎨 Utility Classes Reference
 
-function App() {
-  return (
-    <StyleProvider 
-      initialTheme="light" 
-      adapter={nativeAdapter}
-    >
-      <YourApp />
-    </StyleProvider>
-  );
-}
+### Layout
+```css
+.block { display: block; }
+.flex { display: flex; }
+.grid { display: grid; }
+.relative { position: relative; }
+.z-10 { z-index: 10; }
 ```
 
-#### useStyleContext
-
-Access theme and device context in your components:
-
-```tsx
-import { useStyleContext } from '@damarkuncoro/meta-architecture-style-engine';
-
-function MyComponent() {
-  const { theme, device, platform } = useStyleContext();
-  
-  return (
-    <div>
-      Current theme: {theme}
-      Current device: {device}
-    </div>
-  );
-}
+### Flexbox
+```css
+.flex-row { flex-direction: row; }
+.items-center { align-items: center; }
+.justify-between { justify-content: space-between; }
+.gap-4 { gap: 1rem; }
 ```
 
-#### StyleContract
-
-Create type-safe style contracts:
-
-```typescript
-import { StyleContract } from '@damarkuncoro/meta-architecture-style-engine';
-
-const buttonContract = new StyleContract({
-  intent: 'color.primary',
-  padding: 'space.md',
-  borderRadius: 'radius.md'
-});
-
-const resolved = buttonContract.resolve({
-  theme: 'light',
-  device: 'desktop',
-  platform: 'web'
-});
+### Grid
+```css
+.grid-cols-3 { grid-template-columns: repeat(3, minmax(0, 1fr)); }
+.col-span-2 { grid-column: span 2 / span 2; }
 ```
 
-#### StyleResolutionEngine
-
-Use the core engine for advanced scenarios:
-
-```typescript
-import { 
-  StyleResolutionEngine, 
-  TokenRegistry, 
-  ThemeResolver 
-} from '@damarkuncoro/meta-architecture-style-engine';
-
-// Create engine
-const tokenRegistry = new TokenRegistry();
-const themeResolver = new ThemeResolver();
-const engine = new StyleResolutionEngine(tokenRegistry, themeResolver);
-
-// Define contract
-const contract = {
-  intent: 'color.primary',
-  padding: 'space.md'
-};
-
-// Define constitution
-const constitution = {
-  componentName: 'Button',
-  rules: [
-    {
-      property: 'intent',
-      domain: 'interaction',
-      allowedTokens: ['color.primary', 'color.secondary']
-    },
-    {
-      property: 'padding',
-      domain: 'layout',
-      allowedTokens: ['space.sm', 'space.md', 'space.lg']
-    }
-  ]
-};
-
-// Resolve
-const result = engine.resolve(contract, constitution);
-
-console.log(result.className); // "bg-primary p-md"
-console.log(result.valid); // true
+### Spacing
+```css
+.p-4 { padding: 1rem; }
+.m-4 { margin: 1rem; }
+.gap-4 { gap: 1rem; }
 ```
 
-### CLI Usage
-
-#### Initialize a New Project
-
-```bash
-mase init my-app
+### Typography
+```css
+.text-lg { font-size: 1.125rem; }
+.font-bold { font-weight: 700; }
+.leading-relaxed { line-height: 1.625; }
 ```
 
-#### Compile Contract
-
-```bash
-mase compile Button.contract.dsl -o Button.ts
+### Color
+```css
+.bg-primary { background-color: var(--color-primary); }
+.text-white { color: var(--color-white); }
+.border-gray-200 { border-color: var(--color-gray-200); }
 ```
 
-Options:
-- `-o, --output <file>` - Output file
-- `--format <format>` - Output format (ts, json, ast)
-- `--watch` - Watch for changes
-
-#### Validate Contract
-
-```bash
-mase validate Button.contract.dsl
+### Effects
+```css
+.rounded-md { border-radius: 0.375rem; }
+.shadow-lg { box-shadow: var(--shadow-lg); }
+.opacity-50 { opacity: 0.5; }
 ```
 
-Options:
-- `--strict` - Enable strict validation
-- `--fix` - Auto-fix issues
-- `--watch` - Watch for changes
-
-#### Generate CSS
-
-```bash
-mase generate-css Button.contract.dsl -o button.css
+### Filters
+```css
+.blur-md { filter: blur(8px); }
+.brightness-125 { filter: brightness(1.25); }
+.backdrop-blur-md { backdrop-filter: blur(8px); }
 ```
 
-Options:
-- `-o, --output <file>` - Output file
-- `--format <format>` - Output format (class, variable, inline)
-- `--theme <theme>` - Theme (light, dark)
-- `--device <device>` - Device (mobile, tablet, desktop)
-
-#### Watch for Changes
-
-```bash
-mase watch Button.contract.dsl
+### Interactivity
+```css
+.cursor-pointer { cursor: pointer; }
+.pointer-events-none { pointer-events: none; }
+.select-none { user-select: none; }
 ```
 
-Options:
-- `--command <command>` - Command to run on change
-- `--debounce <ms>` - Debounce time in ms
+## 🌙 Dark Mode
 
-### DSL Syntax
+MASE provides automatic dark mode support:
 
-The MASE DSL provides a declarative way to define style contracts.
-
-#### Basic Contract
-
-```dsl
-contract Button {
-  domain: interaction
-  
-  intent {
-    allows: [color.primary, color.secondary]
-    default: color.primary
-  }
-  
-  padding {
-    allows: [space.sm, space.md, space.lg]
-    default: space.md
-  }
+```css
+/* Light mode */
+.button {
+  background-color: var(--color-primary);
+  color: var(--color-white);
 }
-```
-
-#### Responsive Styling
 
-```dsl
-contract Container {
-  domain: layout
-  
-  padding {
-    allows: [space.sm, space.md, space.lg]
-    default: space.md
-    
-    constraints {
-      mobile: [space.sm, space.md]
-      desktop: [space.md, space.lg]
-    }
-  }
+/* Dark mode */
+[data-theme="dark"] .button {
+  background-color: var(--color-primary-dark);
+  color: var(--color-white-dark);
 }
 ```
 
-#### State-Based Styling
+### Theme Switching
 
-```dsl
-contract Button {
-  domain: interaction
-  
-  intent {
-    allows: [color.primary, color.secondary]
-    default: color.primary
-    
-    constraints {
-      hover: [color.primary.hover, color.secondary.hover]
-      active: [color.primary.active, color.secondary.active]
-    }
-  }
-}
-```
-
-#### Theme Support
-
-```dsl
-contract Card {
-  domain: layout
-  
-  background {
-    allows: [surface.card, surface.ground]
-    default: surface.card
-    
-    constraints {
-      dark: [surface.card.dark, surface.ground.dark]
-    }
-  }
+```javascript
+function setTheme(theme) {
+  document.documentElement.setAttribute('data-theme', theme);
+  localStorage.setItem('theme', theme);
 }
-```
-
----
-
-## 🔧 API Reference
-
-### Core Exports
-
-#### Domain Layer
-
-```typescript
-// Types
-export * from './domain/types';
-
-// Core Engine
-export { StyleResolutionEngine } from './domain/StyleResolutionEngine';
-export { CanonicalStyleGraph } from './domain/CanonicalStyleGraph';
-export { ContextBinder } from './domain/ContextBinder';
-export { ViolationEngine } from './domain/ViolationEngine';
-
-// Registries
-export { TokenRegistry } from './domain/TokenRegistry';
-export { ThemeResolver } from './domain/ThemeResolver';
-export { ContextFactory } from './domain/ContextFactory';
-```
-
-#### Runtime Layer
-
-```typescript
-export { StyleContract } from './runtime/StyleContract';
-export { StyleProvider } from './runtime/StyleProvider';
-```
-
-#### Adapter Layer
-
-```typescript
-export { MasePlugin } from './adapter/MasePlugin';
-export { createPipeline } from './adapter/pipeline-factory';
-export * from './adapter/rules';
-```
-
-#### Data Layer
-
-```typescript
-export * from './data/tokens';
-export * from './data/constitutions';
-```
-
-#### DSL Layer
-
-```typescript
-export { 
-  ContractDSLTokenizer, 
-  ContractDSLParser, 
-  ContractDSLValidator, 
-  ContractDSLCompiler 
-} from './dsl';
-```
 
-#### Materializer Layer
-
-```typescript
-export type { 
-  Materializer, 
-  MaterializationContext, 
-  MaterializationResult 
-} from './materializer';
-
-export { 
-  MaterializationError, 
-  CSSMaterializer, 
-  RNMaterializer, 
-  PDFMaterializer 
-} from './materializer';
+// Initialize theme
+const savedTheme = localStorage.getItem('theme');
+const systemTheme = window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light';
+setTheme(savedTheme || systemTheme);
 ```
 
-### Key Interfaces
+## 🔧 CLI Commands
 
-#### StyleContract
+```bash
+# Initialize MASE in your project
+npx @damarkuncoro/meta-architecture-style-engine init
 
-```typescript
-interface StyleContract {
-  resolve(context: ResolutionContext): StyleResolutionResult;
-  validate(): ValidationResult;
-}
-```
+# Compile style contracts
+npx @damarkuncoro/meta-architecture-style-engine compile <contract-file>
 
-#### StyleResolutionResult
+# Generate CSS
+npx @damarkuncoro/meta-architecture-style-engine generate-css
 
-```typescript
-interface StyleResolutionResult {
-  valid: boolean;
-  className?: string;
-  styles?: Record<string, any>;
-  violations?: Violation[];
-}
-```
+# Validate contracts
+npx @damarkuncoro/meta-architecture-style-engine validate <contract-file>
 
-#### ResolutionContext
-
-```typescript
-interface ResolutionContext {
-  theme: 'light' | 'dark';
-  device: 'mobile' | 'tablet' | 'desktop';
-  platform: 'web' | 'native' | 'pdf';
-  state?: Record<string, any>;
-}
+# Watch for changes
+npx @damarkuncoro/meta-architecture-style-engine watch <contract-file>
 ```
 
----
-
-## 📖 Examples
-
-### Phase 2 Examples
-
-Explore advanced Phase 2 features:
-
-- **[Interactive DSL Playground](./examples/advanced/dsl-playground/README.md)** - Live DSL editor with real-time validation
-- **[Advanced ContractEntity](./examples/advanced/contract-entity/README.md)** - Lifecycle hooks, middleware, composition
+## 📊 Performance
 
-### Complete Button Component
+MASE is optimized for performance:
 
-```tsx
-import React from 'react';
-import { StyleProvider, useStyleContext, StyleContract } from '@damarkuncoro/meta-architecture-style-engine';
+- **Caching** - 50-90% improvement for repeated style resolutions
+- **Efficient Generation** - Minimal CSS output with no duplicates
+- **Type Safety** - Compile-time type checking reduces runtime errors
+- **Lazy Evaluation** - Only generate what's needed
 
-// Define button contract
-const buttonContract = new StyleContract({
-  intent: 'color.primary',
-  padding: 'space.md',
-  borderRadius: 'radius.md',
-  fontSize: 'text.base',
-  fontWeight: 'font.semibold'
-});
+### Benchmarks
 
-function Button({ children, variant = 'primary' }: ButtonProps) {
-  const { theme, device } = useStyleContext();
-  
-  const styles = buttonContract.resolve({
-    theme,
-    device,
-    platform: 'web',
-    state: { variant }
-  });
-  
-  return (
-    <button className={styles.className}>
-      {children}
-    </button>
-  );
-}
+Run performance benchmarks:
 
-function App() {
-  return (
-    <StyleProvider initialTheme="light">
-      <Button>Click me</Button>
-    </StyleProvider>
-  );
-}
-```
-
-### Card Component with Responsive Design
-
-```tsx
-import React from 'react';
-import { StyleProvider, useStyleContext, StyleContract } from '@damarkuncoro/meta-architecture-style-engine';
-
-const cardContract = new StyleContract({
-  background: 'surface.card',
-  padding: 'space.lg',
-  borderRadius: 'radius.lg',
-  shadow: 'shadow.md'
-});
-
-function Card({ children }: CardProps) {
-  const { theme, device } = useStyleContext();
-  
-  const styles = cardContract.resolve({
-    theme,
-    device,
-    platform: 'web'
-  });
-  
-  return (
-    <div className={styles.className}>
-      {children}
-    </div>
-  );
-}
+```bash
+npm run benchmark
 ```
 
-### TypeScript-Only Usage
+Expected results:
+- Style Resolution (No Cache): ~0.5-2ms per operation
+- Style Resolution (With Cache): ~0.01-0.1ms per operation (90-95% faster)
+- Cache Hit Rate: 100% for repeated operations
 
-```typescript
-import { 
-  StyleResolutionEngine, 
-  TokenRegistry, 
-  ThemeResolver,
-  CSSMaterializer 
-} from '@damarkuncoro/meta-architecture-style-engine';
-
-// Setup
-const tokenRegistry = new TokenRegistry();
-const themeResolver = new ThemeResolver();
-const engine = new StyleResolutionEngine(tokenRegistry, themeResolver);
-const cssMaterializer = new CSSMaterializer();
-
-// Define contract
-const contract = {
-  background: 'surface.card',
-  padding: 'space.lg',
-  borderRadius: 'radius.lg'
-};
-
-// Define constitution
-const constitution = {
-  componentName: 'Card',
-  domain: 'layout',
-  rules: [
-    {
-      property: 'background',
-      allowedTokens: ['surface.card', 'surface.ground']
-    },
-    {
-      property: 'padding',
-      allowedTokens: ['space.sm', 'space.md', 'space.lg']
-    },
-    {
-      property: 'borderRadius',
-      allowedTokens: ['radius.sm', 'radius.md', 'radius.lg']
-    }
-  ]
-};
-
-// Resolve
-const context = {
-  theme: 'light',
-  device: 'desktop',
-  platform: 'web'
-};
-
-const result = engine.resolve(contract, constitution, context);
+## 🏗️ Architecture
 
-// Materialize
-if (result.valid) {
-  const css = cssMaterializer.materialize(result, context);
-  console.log(css);
-}
+MASE follows a layered architecture:
+
+```
+┌─────────────────────────────────────────┐
+│         Integration Layer              │
+│  ┌──────────┬──────────┬─────────┐│
+│  │ PostCSS   │  Atomic   │ Tailwind ││
+│  │  Plugin    │   CSS     │ Preset  ││
+│  └──────────┴──────────┴─────────┘│
+└─────────────────────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│         Domain Layer                │
+│  ┌──────────┬──────────┬─────────┐│
+│  │ Tokens    │Governance│Resolution││
+│  │ Registry   │  Engine  │  Engine  ││
+│  └──────────┴──────────┴─────────┘│
+└─────────────────────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│      Materialization Layer           │
+│  ┌──────────┬──────────┬─────────┐│
+│  │   CSS     │   RN     │   PDF   ││
+│  │Materializer│Materializer│Materializer││
+│  └──────────┴──────────┴─────────┘│
+└─────────────────────────────────────────┘
+               ↓
+┌─────────────────────────────────────────┐
+│        Runtime Layer                │
+│  ┌──────────┬──────────┬─────────┐│
+│  │   Web     │   RN     │Adapter  ││
+│  │  Adapter  │  Adapter  │Factory  ││
+│  └──────────┴──────────┴─────────┘│
+└─────────────────────────────────────────┘
 ```
 
----
+## 🤝 Contributing
 
-## 🛠️ Development
+We welcome contributions! Please see our [Development Guide](docs/development/guide.md) for details.
 
-### Setup
+### Development Setup
 
 ```bash
 # Clone the repository
@@ -835,182 +368,43 @@ cd meta-architecture-style-engine
 # Install dependencies
 npm install
 
-# Build the project
-npm run build
-
 # Run tests
 npm test
-```
 
-### Project Structure
-
-```
-meta-architecture-style-engine/
-├── src/
-│   ├── adapter/          # Plugin system and pipeline factory
-│   ├── cli/              # Command-line interface
-│   ├── data/             # Tokens and constitutions
-│   ├── domain/           # Core engine (SRE)
-│   ├── dsl/              # Contract DSL compiler
-│   ├── materializer/     # Platform materializers (SME)
-│   └── runtime/          # React runtime components
-├── docs/                 # Documentation
-├── __tests__/            # Test files
-├── package.json
-├── tsconfig.json
-└── tsup.config.ts        # Build configuration
-```
-
-### Scripts
-
-```bash
-# Build
+# Build the project
 npm run build
 
-# Test
-npm test
-
-# Clean build artifacts
-npm run clean
-
 # Run CLI
 npm run cli
 ```
 
-### Testing
-
-MASE uses Vitest for testing. Tests are organized by component and follow the test matrix specification:
-
-- **Valid Contract**: Happy path scenarios
-- **Invalid Token**: Token not in registry
-- **Invalid Semantic**: Wrong semantic key
-- **Domain Violation**: Cross-domain properties
-- **Context Fallback**: Graceful degradation
-- **Hard Rejection**: Fatal violations
-- **Performance**: < 5ms resolution per component
-
-### Quality Metrics
-
-| Metric | Target | Description |
-| :--- | :--- | :--- |
-| **Type Safety** | 100% | No `any`, fully typed contracts |
-| **Platform Agnostic** | 100% | SRE code has no CSS/Web terminology |
-| **Immutability** | Enforced | CSG and Token Registry are `readonly` |
-| **Audit Trail** | 100% | Every resolution decision is traceable |
-
----
-
-## 🤝 Contributing
-
-We welcome contributions! Please follow these guidelines:
-
-### Contribution Guidelines
-
-1. **Strict Separation**: Don't mix CSS logic in the SRE
-2. **Spec-First**: Discuss constitution changes before coding
-3. **Violation as Feature**: Errors are governance features, not bugs
-4. **Type Safety**: Maintain 100% type safety
-5. **Testing**: Ensure all tests pass before submitting PR
-
-### Development Workflow
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-### Code of Conduct
-
-- Be respectful and inclusive
-- Provide constructive feedback
-- Focus on what is best for the community
-- Show empathy towards other community members
-
----
-
 ## 📄 License
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
----
+MIT License - see [LICENSE](LICENSE) file for details
 
 ## 🙏 Acknowledgments
 
-- Inspired by the principles of constitutional governance
+- Inspired by Tailwind CSS's utility-first approach
 - Built with TypeScript for type safety
-- Powered by the Meta Architecture ecosystem
+- Designed for modern web development
+- Part of the Meta Architecture ecosystem
 
----
+## 📞 Support
 
-## 📞 Support & Community
+- 📖 [Documentation](docs/)
+- 🐛 [Issue Tracker](https://github.com/damarkuncoro/meta-architecture-style-engine/issues)
+- 💬 [Discussions](https://github.com/damarkuncoro/meta-architecture-style-engine/discussions)
+- 📧 [Email](mailto:support@damarkuncoro.com)
 
-### Documentation
+## 🔗 Related Projects
 
-- **[Full Documentation](./docs/README.md)** - Complete documentation
-- **[Quick Start Guide](./docs/quick-start.md)** - Get started in 5 minutes
-- **[Development Guide](./docs/development.md)** - Comprehensive development guide
-- **[Phase 2: Integration Design & DSL](./docs/phase2-integration-design.md)** - Context-awareness, ContractEntity, and DSL features
-- **[Architecture Diagrams](./docs/architecture-diagram.md)** - Visual architecture documentation
-- **[Performance Benchmarks](./docs/benchmarks.md)** - Performance metrics and comparisons
-- **[Migration Guide](./docs/migration-guide.md)** - Migrate from Tailwind/CSS-in-JS
-- **[DSL Reference](./docs/dsl-reference.md)** - Quick reference card for DSL syntax
-- **[Interactive Demo](./docs/interactive-demo.md)** - Interactive examples and live demos
-- **[Troubleshooting](./docs/troubleshooting.md)** - Common issues and solutions
-
-### Framework Integrations
-
-- **[Next.js Integration](./docs/integrations/nextjs.md)** - Integrate MASE with Next.js
-- **[React Native Integration](./docs/integrations/react-native.md)** - Integrate MASE with React Native
-- **[Storybook Integration](./docs/integrations/storybook.md)** - Integrate MASE with Storybook
-
-### Examples
-
-- **[Examples Directory](./examples/README.md)** - Comprehensive examples collection
-- **[Basic Examples](./examples/basic/)** - Button, Card, Input components
-- **[Advanced Examples](./examples/advanced/)** - Responsive, theming, animations
-- **[Real-World Apps](./examples/real-world/)** - E-commerce, Dashboard, Social apps
-
-### Community
-
-- **[GitHub Issues](https://github.com/damarkuncoro/meta-architecture-style-engine/issues)** - Report bugs
-- **[GitHub Discussions](https://github.com/damarkuncoro/meta-architecture-style-engine/discussions)** - Ask questions
-- **[Pull Requests](https://github.com/damarkuncoro/meta-architecture-style-engine/pulls)** - Contribute code
-
----
-
-## 🗺️ Roadmap
-
-### ✅ Phase 0: Prototype (v0.1)
-- Basic `TokenRegistry` & `StyleRule`
-- Simple `StyleValidator` (Runtime)
-- `StrictButton` component demo
-
-### ✅ Phase 1: Review & Ratify (Materialization)
-- Card Governance implementation
-- Testing strategy with Vitest
-- Domain expansion (Shadow, Surface)
-
-### 🔄 Phase 2: Integration Design & DSL
-- Context-Awareness for responsive design
-- ContractEntity abstract class
-- DSL Design for declarative contracts
-
-### 🔜 Phase 3: SRE Implementation
-- Style resolution algorithms
-- Context Binder for variants/conditions
-
-### 🔜 Phase 4: SME (Materializers)
-- Semantic node to CSS Properties mapping
-- Atomic CSS generation optimization
+- [@damarkuncoro/meta-architecture](https://github.com/damarkuncoro/meta-architecture) - The core Meta Architecture framework
 
 ---
 
-<div align="center">
-
-**Built with ❤️ by Damar Kuncoro**
+**MASE** - Meta Architecture Style Engine
 
-[![GitHub](https://img.shields.io/badge/GitHub-damarkuncoro-blue)](https://github.com/damarkuncoro)
-[![Twitter](https://img.shields.io/badge/Twitter-@damarkuncoro-blue)](https://twitter.com/damarkuncoro)
+*Build beautiful, consistent, and theme-aware user interfaces with ease.*
 
-</div>
+**Author:** Damar Kuncoro  
+**Version:** 0.1.4