metabuilder/storybook/STYLES_INTEGRATION.md

Storybook Styles Integration

Overview

Storybook now loads and compiles V2 styles schemas from packages, demonstrating how the abstract styling system becomes real CSS.

What Was Added

1. Styles Compiler

src/styles/compiler.ts - 500+ lines

A complete V2 → CSS compiler that:

• Detects schema version (V1 array vs V2 object)
• Extracts tokens as CSS custom properties
• Builds selectors from predicates
• Compiles effects (typography, transforms, etc.)
• Compiles appearance (gradients, borders, shadows)
• Compiles transitions (state-based animations)
• Handles responsive breakpoints via media queries
• Injects CSS into the page dynamically

Key Functions

// Compile V2 schema to CSS string
compileToCSS(schema: StylesSchemaV2): string

// Load and compile from package
loadPackageStyles(packageId: string): Promise<string>

// Inject compiled CSS into DOM
injectStyles(packageId: string, css: string): void

// Load and inject in one call
loadAndInjectStyles(packageId: string): Promise<string>

2. Preview Configuration

.storybook/preview.tsx

Auto-loads styles from common packages on startup:

const PACKAGES_TO_LOAD = [
  'shared',
  'ui_home',
  'ui_header',
  'ui_footer',
]

Console output:

✓ Loaded styles for shared (2.4KB)
✓ Loaded styles for ui_home (5.1KB)
✓ Loaded styles for ui_header (1.8KB)
✓ Loaded styles for ui_footer (2.1KB)
📦 All package styles loaded

3. Styles Viewer Panel

src/styles/StylesPanel.tsx

Debug panel showing:

• Compiled CSS output
• Raw V2 schema
• Summary statistics (tokens, selectors, effects, etc.)
• V1/V2 badge
• Switch between CSS/Schema views

Navigate to: Developer → Styles Viewer

4. Example Stories

src/stories/UIHome.stories.tsx

Real components using V2 styles:

• Hero Title - Gradient text with responsive sizing
• Hero Subtitle - Muted foreground color
• Feature Cards - 6 level-specific gradients with hover effects
• Full Landing Page - Complete composition

5. Documentation

src/stories/Styles.mdx

Complete documentation covering:

• V2 schema overview
• The 10 abstraction layers
• How compilation works
• Example schemas
• GUI designer vision

How It Works

Compilation Flow

1. Load Schema
   ↓
   fetch('/packages/ui_home/seed/styles.json')

2. Detect Version
   ↓
   schema.schema_version? → V2 : V1

3. Extract Tokens
   ↓
   colors → :root { --color-primary: ...; }

4. Build Selectors
   ↓
   predicate: {targetType: "Text", classes: ["hero-title"]}
   → .text.hero-title

5. Compile Effects
   ↓
   fontSize: {type: "responsive", breakpoints: {...}}
   → font-size: 4rem; @media {...}

6. Compile Appearance
   ↓
   gradient: {type: "linear", stops: [...]}
   → background: linear-gradient(...)

7. Generate CSS
   ↓
   Combine all rules with proper cascade order

8. Inject into DOM
   ↓
   <style id="styles-ui_home">...</style>

Predicate → Selector Mapping

The compiler maps component types to CSS selectors:

const typeMap = {
  'Text': '.text',
  'Button': 'button',
  'Card': '.card',
  'Box': '.box',
}

// Predicate: { targetType: "Text", classes: ["hero-title"], states: ["hover"] }
// CSS: .text.hero-title:hover

Responsive Compilation

Breakpoints from effects get compiled to media queries:

{
  "fontSize": {
    "type": "responsive",
    "breakpoints": {
      "xs": { "value": 2.5, "unit": "rem" },
      "md": { "value": 4, "unit": "rem" }
    }
  }
}

Compiles to:

.text.hero-title {
  font-size: 4rem; /* Largest by default */
}

@media (max-width: 768px) {
  .text.hero-title {
    font-size: 2.5rem;
  }
}

Usage in Stories

Auto-Load Package Styles

export default {
  title: 'My Component',
  parameters: {
    package: 'ui_home', // Automatically loads ui_home styles
  },
}

Use Classes in Components

// Component matches predicate: targetType="Text", classes=["hero-title"]
const HeroTitle = ({ children }) => (
  <h1 className="text hero-title">{children}</h1>
)

// Styles are auto-applied from V2 schema

Hover Effects Work

The compiler generates transition CSS:

.card.feature-card {
  transition: border-color 200ms ease-in-out, transform 200ms ease-in-out;
}

.card.feature-card:hover {
  border-color: var(--color-primary);
  transform: translateY(-2px);
}

Supported V2 Features

✅ Implemented

• Tokens (colors, spacing, typography) → CSS custom properties
• Selectors (predicates) → CSS selectors
• Effects (typography, transforms) → CSS properties
• Appearance (gradients, borders, shadows) → Visual layers
• Transitions (hover states) → CSS transitions
• Rules (cascade priority) → Proper ordering
• Environments (responsive) → Media queries

🚧 Partial

• Layouts (flex, grid) → Needs constraint → CSS mapping
• Animations (keyframes) → Needs timeline compiler
• Computed values → Debug panel (not runtime)

📋 Future

• Layout constraints visual editor
• Animation timeline
• Live reload on schema changes
• CSS variables hot-swapping

Viewing Styles

Console

// See loaded styles
console.log(document.getElementById('styles-ui_home').textContent)

// See all style elements
document.querySelectorAll('style[data-package]')

Styles Viewer

1. Navigate to Developer → Styles Viewer
2. Select package from dropdown
3. Switch between CSS/Schema view
4. See statistics and structure

Browser DevTools

• Inspect element
• See applied styles from <style id="styles-{package}">
• Trace source to V2 schema definitions

Example Output

Input (V2 Schema)

{
  "selectors": [{
    "id": "button_primary",
    "predicate": {
      "targetType": "Button",
      "classes": ["primary"],
      "states": []
    }
  }],
  "effects": [{
    "id": "button_effect",
    "properties": {
      "fontSize": { "type": "length", "value": { "number": 1, "unit": "rem" } }
    }
  }],
  "rules": [{
    "selector": "button_primary",
    "effects": { "ref": "button_effect" },
    "enabled": true
  }]
}

Output (Compiled CSS)

:root {
  --color-primary: oklch(0.45 0.15 265);
}

button.primary {
  font-size: 1rem;
}

Benefits

1. Proof of Concept - Shows V2 schema actually works
2. Developer Experience - Easy to see compiled CSS
3. Visual Testing - Real components with real styles
4. Documentation - Living examples of styling system
5. Debugging - Panel shows schema → CSS mapping

What This Demonstrates

✅ V2 schema compiles to real CSS ✅ Predicates become selectors ✅ Typed values become CSS properties ✅ Cascade priority is preserved ✅ Responsive breakpoints work ✅ Hover effects work ✅ Gradients compile correctly

This proves the abstract styling system is not theoretical - it's a working compiler that generates production CSS.

Next Steps

1. Add more stories for other packages
2. Implement layout compiler (flex/grid constraints)
3. Add animation timeline compiler
4. Create live editing (modify schema, see changes)
5. Build GUI designer using Storybook as preview
6. Connect to database for runtime loading

The foundation is built. Now we can evolve toward the full visual CSS designer.