loopwind 0.9.1

package/website/dist/llm.txt

@@ -0,0 +1,2448 @@
+# dsgn - Complete Documentation for LLMs
+
+This is a comprehensive, single-file documentation for dsgn, optimized for LLM consumption.
+Generated: 2025-11-17T21:03:55.855Z
+
+---
+
+
+
+================================================================================
+FILE: index.mdx
+================================================================================
+
+## Image Templates
+
+```tsx
+// Social media card template
+export default function OGImage({ tw, image, title, description, logo }) {
+  return (
+    <div style={tw('flex w-full h-full bg-white')}>
+      <div style={tw('flex-1 flex flex-col justify-between p-12')}>
+        <img src={image(logo)} style={tw('h-12 w-auto')} />
+        
+        <div>
+          <h1 style={tw('text-5xl font-bold text-gray-900 mb-4')}>
+            {title}
+          </h1>
+          <p style={tw('text-xl text-gray-600')}>
+            {description}
+          </p>
+        </div>
+        
+        <p style={tw('text-gray-400')}>yoursite.com</p>
+      </div>
+      
+      <div style={tw('flex-1')}>
+        <img 
+          src={image(featuredImage)} 
+          style={tw('w-full h-full object-cover')}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+**Render it:**
+```bash
+dsgn render og-image '{"title":"Hello World","description":"My awesome blog post"}'
+```
+
+**Output:** `og-image.png` (1200×630px) in your current directory
+
+**Perfect for:** Open Graph images, Twitter cards, blog headers, product cards, and quote graphics.
+
+## Video Templates
+
+```tsx
+// Animated intro video
+export default function VideoIntro({ tw, progress, title }) {
+  // Fade in animation
+  const titleOpacity = progress < 0.3 ? progress / 0.3 : 1;
+  
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
+      <h1 
+        style={{
+          ...tw('text-8xl font-bold text-white'),
+          opacity: titleOpacity
+        }}
+      >
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+**Render it:**
+```bash
+dsgn render video-intro '{"title":"Welcome!"}' --out intro.mp4
+```
+
+**Output:** `intro.mp4` (1920×1080px, 3 seconds @ 30fps) in your current directory
+
+**Perfect for:** Social media intros, animated logos, tutorial overlays, and product showcases.
+
+## Features
+
+- 🎨 **shadcn/ui Design System**: Beautiful, semantic colors out of the box (`text-primary`, `bg-card`, etc.)
+- ✨ **Template-based**: Install design templates like you install UI components
+- 🎨 **Tailwind CSS Support**: Style templates with Tailwind utility classes + opacity modifiers (`bg-primary/50`)
+- 📱 **Built-in Helpers**: QR codes, image embedding, video backgrounds, template composition
+- ✅ **Smart Validation**: Automatic prop and template validation with helpful error messages
+- 🚀 **Framework-agnostic**: Works with Node, Bun, Deno, Laravel, Python, and more
+- 🤖 **Agent-friendly**: Machine-readable metadata for LLMs
+- 📦 **Easy installation**: `npx dsgn add template-name`
+- 🎬 **Video support**: Render animated videos with frame-by-frame control
+- ⚡ **Powered by Satori**: Generate images from React + Tailwind
+
+## Quick Start
+
+### Installation
+
+```bash
+npm install -g dsgn
+```
+
+Or use with npx:
+
+```bash
+npx dsgn --help
+```
+
+### Initialize in Your Project
+
+Navigate to any project folder and run:
+
+```bash
+dsgn init
+```
+
+This creates a `_dsgn/` folder where templates will be installed.
+
+### Install a Template
+
+Templates can be installed from multiple sources:
+
+#### 1. Official Registry (Coming Soon)
+
+```bash
+dsgn add banner-hero
+dsgn add og-image --registry https://custom-registry.com/r
+```
+
+#### 2. GitHub Repositories
+
+```bash
+# From a GitHub repo (looks for template.json in repo root)
+dsgn add github:username/repo
+
+# From a specific path in the repo
+dsgn add github:username/repo/templates/banner-hero
+
+# From an organization
+dsgn add github:myorg/design-templates/social-media/og-image
+```
+
+#### 3. Direct URLs
+
+```bash
+# Install from any publicly accessible URL
+dsgn add https://example.com/templates/my-template.json
+dsgn add https://cdn.example.com/templates/awesome-banner.json
+```
+
+**Requirements:**
+- URL must return JSON in the registry template format
+- Must be publicly accessible (no authentication)
+
+#### 4. Local Filesystem
+
+```bash
+# Relative path
+dsgn add ./my-templates/banner-hero
+dsgn add ../shared-templates/product-card
+
+# Absolute path
+dsgn add /Users/you/templates/social-card
+```
+
+**Use cases:**
+- Development and testing
+- Private templates
+- Shared team templates (monorepo)
+- Before publishing to registry
+
+Templates are installed to: `_dsgn/templates/<template>/` (customizable in `dsgn.json`)
+
+**Benefits:**
+- Templates are local to your project (like npm packages)
+- Different projects can use different template versions
+- Version controlled with your project
+- Easy to share within your team
+- Works offline once installed
+
+### Render an Image
+
+```bash
+dsgn render banner-hero '{"title":"Hello World","subtitle":"Built with dsgn"}'
+```
+
+Output: `banner-hero.png` (1600x900px)
+
+You can also use a props file:
+```bash
+dsgn render banner-hero props.json
+```
+
+## Commands
+
+### `dsgn add <source>`
+
+Install a template from various sources:
+
+```bash
+# From registry
+dsgn add banner-hero
+
+# From GitHub
+dsgn add github:username/repo/path/to/template
+
+# From URL
+dsgn add https://example.com/my-template.json
+
+# From local path
+dsgn add ./my-templates/custom-banner
+```
+
+### `dsgn list`
+
+List all installed templates:
+
+```bash
+dsgn list
+```
+
+### `dsgn render <template> <props> [options]`
+
+Render an image or video:
+
+```bash
+# Image with inline props
+dsgn render banner-hero '{"title":"Hello World"}'
+
+# Video with inline props
+dsgn render video-intro '{"title":"Welcome"}' --out intro.mp4
+
+# Using a props file
+dsgn render banner-hero props.json
+
+# Custom output
+dsgn render banner-hero '{"title":"Hello"}' --out custom-name.png
+
+# Different format
+dsgn render banner-hero '{"title":"Hello"}' --format jpeg
+```
+
+Options:
+- `--out, -o` - Output filename (default: `<template>.<ext>`)
+- `--format` - Output format: `png`, `jpeg`, `svg` (images only)
+- `--quality` - JPEG quality 1-100 (default: 92)
+
+### `dsgn validate <template>`
+
+Validate a template:
+
+```bash
+dsgn validate banner-hero
+```
+
+Checks:
+- Template file exists and is valid React
+- `meta.json` exists and is valid
+- Required props are defined
+- Fonts exist (if specified)
+
+### `dsgn init`
+
+Initialize dsgn in a project:
+
+```bash
+dsgn init
+```
+
+Creates `dsgn.json` configuration file.
+
+## Next Steps
+
+- [Learn about Templates](/templates)
+- [Image Rendering](/images)
+- [Video Rendering](/video)
+- [Helpers (QR, Template Composition)](/helpers)
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Custom Fonts](/fonts)
+
+
+
+
+
+================================================================================
+FILE: templates.mdx
+================================================================================
+
+# Installing Templates from Different Sources
+
+## Overview
+
+dsgn supports installing templates from multiple sources:
+
+1. **Official Registry** (default)
+2. **Direct URLs**
+3. **GitHub Repositories**
+4. **Local Filesystem**
+
+## 1. Official Registry (Default)
+
+Install templates from the official dsgn registry at `https://dsgncli.com/r`
+
+```bash
+dsgn add banner-hero
+dsgn add product-card
+dsgn add social-og-image
+```
+
+**How it works:**
+- Fetches from: `https://dsgncli.com/r/banner-hero`
+- Returns JSON with template files
+- Installs to: `_dsgn/templates/banner-hero/`
+
+### Custom Registry
+
+Use a different registry:
+
+```bash
+dsgn add banner-hero --registry https://my-registry.com/templates
+```
+
+## 2. Direct URLs
+
+Install a template from any publicly accessible URL:
+
+```bash
+dsgn add https://example.com/templates/my-template.json
+dsgn add https://cdn.example.com/templates/awesome-banner.json
+```
+
+**Requirements:**
+- URL must return JSON in the registry template format
+- Must be publicly accessible (no authentication)
+
+**Example template JSON:**
+
+```json
+{
+  "name": "my-template",
+  "version": "1.0.0",
+  "description": "My custom template",
+  "files": [
+    {
+      "path": "my-template.tsx",
+      "content": "import React from 'react';\n\nexport default function..."
+    },
+    {
+      "path": "meta.json",
+      "content": "{\"name\":\"my-template\"...}"
+    }
+  ]
+}
+```
+
+## 3. GitHub Repositories
+
+Install templates directly from GitHub repos:
+
+```bash
+# From a GitHub repo (looks for template.json in repo root)
+dsgn add github:username/repo
+
+# From a specific path in the repo
+dsgn add github:username/repo/templates/banner-hero
+
+# From an organization
+dsgn add github:myorg/design-templates/social-media/og-image
+```
+
+**How it works:**
+1. Detects `github:` prefix
+2. Converts to raw GitHub URL
+3. Fetches `template.json` (or `meta.json` + template file)
+4. Downloads all referenced files
+5. Installs locally
+
+**Template structure on GitHub:**
+
+Option A: Single template.json (self-contained)
+```
+username/repo/
+└── template.json  # Contains all files inline
+```
+
+Option B: Separate files
+```
+username/repo/
+├── meta.json
+├── banner-hero.tsx
+└── fonts/
+    └── Inter-Bold.woff
+```
+
+## 4. Local Filesystem
+
+Install templates from your local filesystem:
+
+```bash
+# Relative path
+dsgn add ./my-templates/banner-hero
+dsgn add ../shared-templates/product-card
+
+# Absolute path
+dsgn add /Users/you/templates/social-card
+```
+
+**Use cases:**
+- Development and testing
+- Private templates
+- Shared team templates (monorepo)
+- Before publishing to registry
+
+## Template Installation Directory
+
+Templates are installed to `_dsgn/templates/<template-name>/` by default.
+
+Customize this in `dsgn.json`:
+
+```json
+{
+  "templatesDir": "my-custom-templates"
+}
+```
+
+## Benefits of Local Installation
+
+- **Version Control**: Templates are part of your project
+- **Offline**: Works without internet once installed
+- **Team Sharing**: Everyone on the team has the same templates
+- **Customization**: Fork and modify templates per project
+- **Consistency**: Different projects can use different template versions
+
+## Next Steps
+
+- [Learn about Helpers](/helpers)
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Custom Fonts](/fonts)
+- [Image Rendering](/images)
+- [Video Rendering](/video)
+
+
+
+
+
+================================================================================
+FILE: images.mdx
+================================================================================
+
+# Image Rendering
+
+Generate beautiful images from React components using dsgn's powerful image rendering engine powered by Satori.
+
+## Quick Start
+
+```bash
+# Render an image template with inline props
+dsgn render banner-hero '{"title":"Hello World","subtitle":"Welcome"}'
+
+# Custom output name
+dsgn render banner-hero '{"title":"Hello"}' --out custom-name.png
+
+# Different format
+dsgn render banner-hero '{"title":"Hello"}' --format jpeg --quality 95
+
+# Or use a props file
+dsgn render banner-hero props.json
+```
+
+## Image Template Structure
+
+### Basic Template
+
+```tsx
+// banner-hero.tsx
+export default function BannerHero({ title, subtitle, tw }) {
+  return (
+    <div style={tw('flex flex-col justify-center items-center w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}>
+      <h1 style={tw('text-7xl font-bold text-white mb-4')}>
+        {title}
+      </h1>
+      <p style={tw('text-2xl text-white/80')}>
+        {subtitle}
+      </p>
+    </div>
+  );
+}
+```
+
+### Metadata (meta.json)
+
+```json
+{
+  "name": "banner-hero",
+  "type": "image",
+  "description": "Hero banner with gradient background",
+  "size": {
+    "width": 1600,
+    "height": 900
+  },
+  "props": {
+    "title": "string",
+    "subtitle": "string"
+  }
+}
+```
+
+### Props File
+
+```json
+{
+  "title": "Welcome to dsgn",
+  "subtitle": "Generate beautiful images from React"
+}
+```
+
+## Output Formats
+
+### PNG (Default)
+
+```bash
+dsgn render my-template '{"title":"Hello"}'
+# Output: my-template.png
+```
+
+**Best for:**
+- Designs with transparency
+- High-quality graphics
+- Sharp text and logos
+- Web graphics
+
+### JPEG
+
+```bash
+dsgn render my-template '{"title":"Hello"}' --format jpeg --quality 92
+```
+
+**Options:**
+- `--quality` - 1-100 (default: 92)
+
+**Best for:**
+- Photographs
+- Gradients
+- Smaller file sizes
+- Social media images
+
+### SVG
+
+```bash
+dsgn render my-template '{"title":"Hello"}' --format svg
+```
+
+**Best for:**
+- Vector graphics
+- Scalable designs
+- Print-ready artwork
+- Logos and icons
+
+## Embedding Images
+
+Use the `image()` helper to embed external images in your templates.
+
+### Basic Usage
+
+```tsx
+export default function ProductCard({ tw, image, title, background }) {
+  return (
+    <div style={tw('relative w-full h-full')}>
+      {/* Background image */}
+      <img 
+        src={image(background)} 
+        style={tw('absolute inset-0 w-full h-full object-cover')}
+      />
+      
+      {/* Content overlay */}
+      <div style={tw('relative z-10 p-12')}>
+        <h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
+      </div>
+    </div>
+  );
+}
+```
+
+**Props:**
+```json
+{
+  "title": "New Product",
+  "background": "./images/background.jpg"
+}
+```
+
+### Supported Image Formats
+
+- ✅ **JPEG** (`.jpg`, `.jpeg`)
+- ✅ **PNG** (`.png`)
+- ✅ **GIF** (`.gif`)
+- ✅ **WebP** (`.webp`)
+- ✅ **SVG** (`.svg`)
+
+### Image Positioning
+
+```tsx
+export default function ImageGrid({ tw, image, img1, img2, img3 }) {
+  return (
+    <div style={tw('grid grid-cols-3 gap-4 w-full h-full p-8 bg-gray-100')}>
+      {/* Cover - fills entire area */}
+      <img 
+        src={image(img1)} 
+        style={tw('w-full h-full object-cover rounded-lg')}
+      />
+      
+      {/* Contain - fits within area */}
+      <img 
+        src={image(img2)} 
+        style={tw('w-full h-full object-contain')}
+      />
+      
+      {/* Fill - stretches to fill */}
+      <img 
+        src={image(img3)} 
+        style={tw('w-full h-full object-fill')}
+      />
+    </div>
+  );
+}
+```
+
+## Common Image Templates
+
+### Open Graph / Social Cards
+
+```tsx
+// og-image.tsx
+export default function OGImage({ tw, title, description, image, logo }) {
+  return (
+    <div style={tw('flex w-full h-full bg-white')}>
+      {/* Left side - Content */}
+      <div style={tw('flex-1 flex flex-col justify-between p-12')}>
+        <img src={image(logo)} style={tw('h-12 w-auto')} />
+        
+        <div>
+          <h1 style={tw('text-5xl font-bold text-gray-900 mb-4')}>
+            {title}
+          </h1>
+          <p style={tw('text-xl text-gray-600')}>
+            {description}
+          </p>
+        </div>
+        
+        <p style={tw('text-gray-400')}>yoursite.com</p>
+      </div>
+      
+      {/* Right side - Image */}
+      <div style={tw('flex-1')}>
+        <img 
+          src={image(featuredImage)} 
+          style={tw('w-full h-full object-cover')}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+**Size:** 1200x630 (standard OG image size)
+
+### Product Cards
+
+```tsx
+export default function ProductCard({ tw, image, product, price, badge }) {
+  return (
+    <div style={tw('flex flex-col w-full h-full bg-white rounded-2xl overflow-hidden')}>
+      {/* Product image */}
+      <div style={tw('relative h-2/3')}>
+        <img 
+          src={image(product)} 
+          style={tw('w-full h-full object-cover')}
+        />
+        {badge && (
+          <div style={tw('absolute top-4 right-4 bg-red-500 text-white px-4 py-2 rounded-full text-sm font-bold')}>
+            {badge}
+          </div>
+        )}
+      </div>
+      
+      {/* Product info */}
+      <div style={tw('flex-1 p-6 flex flex-col justify-between')}>
+        <h2 style={tw('text-2xl font-bold text-gray-900')}>
+          {title}
+        </h2>
+        <div style={tw('flex justify-between items-center')}>
+          <span style={tw('text-3xl font-bold text-gray-900')}>
+            ${price}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+### Quote Cards
+
+```tsx
+export default function QuoteCard({ tw, image, quote, author, avatar }) {
+  return (
+    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-gradient-to-br from-indigo-500 to-purple-600 p-16')}>
+      {avatar && (
+        <img 
+          src={image(avatar)} 
+          style={tw('w-24 h-24 rounded-full border-4 border-white mb-8')}
+        />
+      )}
+      
+      <blockquote style={tw('text-3xl text-white text-center font-light mb-8 max-w-3xl')}>
+        "{quote}"
+      </blockquote>
+      
+      <p style={tw('text-xl text-white/80')}>
+        — {author}
+      </p>
+    </div>
+  );
+}
+```
+
+## Performance Tips
+
+### 1. Optimize Image Sizes
+
+Use appropriately sized images before embedding:
+
+```bash
+# Resize large images before using them
+convert large-image.jpg -resize 1600x900 optimized.jpg
+```
+
+### 2. Use Web-Optimized Formats
+
+- **WebP** for modern browsers (smaller file sizes)
+- **JPEG** for photos with controlled quality
+- **PNG** only when transparency is needed
+
+### 3. Batch Rendering
+
+Render multiple images at once:
+
+```bash
+# Using a script with inline props
+dsgn render my-template '{"title":"Image 1"}'
+dsgn render my-template '{"title":"Image 2"}'
+dsgn render my-template '{"title":"Image 3"}'
+
+# Or loop through props files
+for props in props/*.json; do
+  dsgn render my-template "$props"
+done
+```
+
+### 4. Cache Templates
+
+Templates are cached after first load for faster subsequent renders.
+
+## Common Sizes
+
+### Social Media
+
+- **Twitter/X Card**: 1200x675
+- **Facebook Post**: 1200x630
+- **Instagram Post**: 1080x1080
+- **LinkedIn Post**: 1200x627
+- **Pinterest Pin**: 1000x1500
+
+### Web Graphics
+
+- **Hero Banner**: 1920x1080
+- **Blog Header**: 1600x900
+- **Thumbnail**: 640x360
+- **Avatar**: 400x400
+
+### Print
+
+- **Flyer (A4)**: 2480x3508 (300 DPI)
+- **Business Card**: 1050x600 (300 DPI)
+- **Poster (A3)**: 3508x4961 (300 DPI)
+
+## Troubleshooting
+
+### Fonts Not Rendering
+
+Make sure fonts are properly loaded in `meta.json`:
+
+```json
+{
+  "fonts": [
+    {
+      "name": "Inter",
+      "path": "fonts/Inter-Bold.woff",
+      "weight": 700
+    }
+  ]
+}
+```
+
+### Images Not Loading
+
+Check file paths are relative to the props file:
+
+```json
+{
+  "background": "./images/bg.jpg"  // ✅ Relative path
+  "background": "/images/bg.jpg"   // ❌ Absolute path won't work
+}
+```
+
+### Blurry Text
+
+Ensure you're using appropriate dimensions. Satori renders at exact pixel dimensions.
+
+## Next Steps
+
+- [Learn about Video Rendering](/video)
+- [QR Codes and Template Composition](/helpers)
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Using Custom Fonts](/fonts)
+
+
+
+
+
+================================================================================
+FILE: video.mdx
+================================================================================
+
+# Video Rendering
+
+Create animated videos programmatically using React components. Perfect for automated video generation, social media content, and dynamic animations.
+
+## Quick Start
+
+```bash
+# Render a video template with inline props
+dsgn render video-intro '{"title":"Welcome!"}' --out intro.mp4
+
+# With custom encoding
+dsgn render video-intro '{"title":"Welcome!"}' --preset ultrafast
+
+# Or use a props file
+dsgn render video-intro props.json --out intro.mp4
+```
+
+## Video Template Structure
+
+### Basic Template
+
+```tsx
+// video-intro.tsx
+export default function VideoIntro({ tw, title, frame, progress }) {
+  // Animate opacity based on progress
+  const titleOpacity = progress < 0.3 ? progress / 0.3 : 1;
+  
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
+      <h1 
+        style={{
+          ...tw('text-8xl font-bold text-white'),
+          opacity: titleOpacity
+        }}
+      >
+        {title}
+      </h1>
+      
+      {/* Show frame counter */}
+      <div style={tw('absolute bottom-10 right-10 text-white text-sm')}>
+        Frame: {frame}
+      </div>
+    </div>
+  );
+}
+```
+
+### Metadata (meta.json)
+
+```json
+{
+  "name": "video-intro",
+  "type": "video",
+  "description": "Animated intro with fade-in title",
+  "size": {
+    "width": 1920,
+    "height": 1080
+  },
+  "video": {
+    "fps": 30,
+    "duration": 3
+  },
+  "props": {
+    "title": "string"
+  }
+}
+```
+
+### Props File
+
+```json
+{
+  "title": "Welcome!"
+}
+```
+
+## Video-Specific Props
+
+Every video template receives these additional props:
+
+### `frame`
+Current frame number (0 to totalFrames - 1)
+
+```tsx
+export default function MyVideo({ frame }) {
+  // Frame 0, 1, 2, 3, ... 89 (for 3s @ 30fps)
+  return <div>Frame: {frame}</div>;
+}
+```
+
+### `progress`
+Animation progress from 0 to 1
+
+```tsx
+export default function MyVideo({ progress }) {
+  // 0.0 at start, 0.5 at middle, 1.0 at end
+  const x = progress * 100; // Move from 0 to 100
+  
+  return (
+    <div style={{ transform: `translateX(${x}px)` }}>
+      Moving element
+    </div>
+  );
+}
+```
+
+## Animation Patterns
+
+### Fade In/Out
+
+```tsx
+export default function FadeVideo({ progress, title, tw }) {
+  // Fade in first 20%, stay visible, fade out last 20%
+  let opacity = 1;
+  if (progress < 0.2) {
+    opacity = progress / 0.2;
+  } else if (progress > 0.8) {
+    opacity = (1 - progress) / 0.2;
+  }
+  
+  return (
+    <h1 style={{ ...tw('text-6xl font-bold'), opacity }}>
+      {title}
+    </h1>
+  );
+}
+```
+
+### Slide In
+
+```tsx
+export default function SlideVideo({ progress, tw }) {
+  // Slide in from left
+  const x = -100 + (progress * 100); // -100 to 0
+  
+  return (
+    <div style={{ 
+      ...tw('text-4xl font-bold'),
+      transform: `translateX(${x}%)`
+    }}>
+      Sliding Text
+    </div>
+  );
+}
+```
+
+### Scale Animation
+
+```tsx
+export default function ScaleVideo({ progress, tw }) {
+  // Scale from 0 to 1
+  const scale = progress;
+  
+  return (
+    <div style={{ 
+      ...tw('text-6xl font-bold'),
+      transform: `scale(${scale})`
+    }}>
+      Growing Text
+    </div>
+  );
+}
+```
+
+### Rotation
+
+```tsx
+export default function RotateVideo({ progress, tw }) {
+  // Rotate 360 degrees
+  const rotation = progress * 360;
+  
+  return (
+    <div style={{ 
+      ...tw('w-32 h-32 bg-blue-500 rounded-lg'),
+      transform: `rotate(${rotation}deg)`
+    }}>
+    </div>
+  );
+}
+```
+
+### Easing Functions
+
+Create smooth animations with easing:
+
+```tsx
+function easeOutCubic(t) {
+  return 1 - Math.pow(1 - t, 3);
+}
+
+export default function EasedVideo({ progress, tw }) {
+  const easedProgress = easeOutCubic(progress);
+  const x = easedProgress * 100;
+  
+  return (
+    <div style={{ transform: `translateX(${x}px)` }}>
+      Smooth animation
+    </div>
+  );
+}
+```
+
+## Embedding Videos
+
+Use the `video()` helper to embed video backgrounds that auto-sync with your animation.
+
+### Basic Usage
+
+```tsx
+export default function VideoOverlay({ tw, video, title, background }) {
+  return (
+    <div style={tw('relative w-full h-full')}>
+      {/* Background video - automatically synced to current frame */}
+      <img 
+        src={video(background)} 
+        style={tw('absolute inset-0 w-full h-full object-cover')}
+      />
+      
+      {/* Text overlay */}
+      <div style={tw('relative z-10 flex items-center justify-center w-full h-full')}>
+        <h1 style={tw('text-7xl font-bold text-white drop-shadow-lg')}>
+          {title}
+        </h1>
+      </div>
+    </div>
+  );
+}
+```
+
+**Props:**
+```json
+{
+  "title": "Amazing Video",
+  "background": "./footage/background.mp4"
+}
+```
+
+### How Video Sync Works
+
+1. **First pass**: Template calls `video()` to register needed videos
+2. **Pre-processing**: dsgn extracts all frames at template's FPS
+3. **Rendering**: Each frame uses the corresponding video frame
+4. **Caching**: Frames are cached in memory for fast access
+
+### Animated Overlay Example
+
+```tsx
+export default function VideoWithText({ tw, video, frame, progress, title, clip }) {
+  // Fade in title
+  const titleOpacity = progress < 0.2 ? progress / 0.2 : 1;
+  
+  return (
+    <div style={tw('relative w-full h-full')}>
+      {/* Synced video background */}
+      <img 
+        src={video(clip)} 
+        style={tw('absolute inset-0 w-full h-full object-cover')}
+      />
+      
+      {/* Dark overlay */}
+      <div style={tw('absolute inset-0 bg-black/40')} />
+      
+      {/* Animated title */}
+      <div style={tw('relative z-10 flex items-center justify-center w-full h-full')}>
+        <h1 
+          style={{
+            ...tw('text-8xl font-bold text-white text-center'),
+            opacity: titleOpacity
+          }}
+        >
+          {title}
+        </h1>
+      </div>
+      
+      {/* Frame counter */}
+      <div style={tw('absolute bottom-4 right-4 text-white text-sm bg-black/50 px-3 py-1 rounded')}>
+        {frame} / {Math.floor(3 * 30)}
+      </div>
+    </div>
+  );
+}
+```
+
+## Combining Videos and Images
+
+Use both `video()` and `image()` helpers together to create rich, branded video content.
+
+### Video Background with Logo
+
+```tsx
+export default function BrandedVideo({ tw, video, image, progress, background, logo, title }) {
+  // Logo slides in from top
+  const logoY = progress < 0.3 ? -100 + (progress / 0.3) * 100 : 0;
+  // Title fades in after logo
+  const titleOpacity = progress > 0.3 ? Math.min((progress - 0.3) / 0.3, 1) : 0;
+  
+  return (
+    <div style={tw('relative w-full h-full')}>
+      {/* Video background */}
+      <img 
+        src={video(background)} 
+        style={tw('absolute inset-0 w-full h-full object-cover')}
+      />
+      
+      {/* Gradient overlay */}
+      <div style={tw('absolute inset-0 bg-gradient-to-t from-black/80 to-transparent')} />
+      
+      {/* Animated logo */}
+      <div 
+        style={{
+          ...tw('absolute top-12 left-12'),
+          transform: `translateY(${logoY}px)`
+        }}
+      >
+        <img 
+          src={image(logo)} 
+          style={tw('h-16 w-auto')}
+        />
+      </div>
+      
+      {/* Animated title */}
+      <div style={tw('absolute bottom-20 left-12 right-12')}>
+        <h1 
+          style={{
+            ...tw('text-7xl font-bold text-white'),
+            opacity: titleOpacity
+          }}
+        >
+          {title}
+        </h1>
+      </div>
+    </div>
+  );
+}
+```
+
+**Props:**
+```json
+{
+  "title": "Introducing Our New Product",
+  "background": "./footage/product-demo.mp4",
+  "logo": "./images/company-logo.png"
+}
+```
+
+### Multi-Element Video Composition
+
+```tsx
+export default function ProductShowcase({ 
+  tw, 
+  video, 
+  image, 
+  progress, 
+  backgroundVideo,
+  productImage,
+  badge,
+  title,
+  price 
+}) {
+  // Product image zooms in
+  const scale = 0.8 + (Math.min(progress / 0.5, 1) * 0.2); // 0.8 to 1.0
+  
+  // Badge rotates in
+  const badgeRotation = progress < 0.4 ? (progress / 0.4) * 360 : 360;
+  const badgeOpacity = Math.min(progress / 0.4, 1);
+  
+  // Price slides up
+  const priceY = progress > 0.6 ? (1 - Math.min((progress - 0.6) / 0.4, 1)) * 50 : 50;
+  
+  return (
+    <div style={tw('relative w-full h-full bg-white')}>
+      {/* Video background (blurred) */}
+      <div style={tw('absolute inset-0 overflow-hidden')}>
+        <img 
+          src={video(backgroundVideo)} 
+          style={{
+            ...tw('w-full h-full object-cover'),
+            filter: 'blur(20px)',
+            transform: 'scale(1.1)' // Prevent blur edge artifacts
+          }}
+        />
+        <div style={tw('absolute inset-0 bg-white/50')} />
+      </div>
+      
+      {/* Main product image */}
+      <div style={tw('relative z-10 flex items-center justify-center w-full h-full p-20')}>
+        <div style={{ transform: `scale(${scale})` }}>
+          <img 
+            src={image(productImage)} 
+            style={tw('w-96 h-96 object-contain drop-shadow-2xl')}
+          />
+        </div>
+      </div>
+      
+      {/* Animated badge */}
+      <div 
+        style={{
+          ...tw('absolute top-20 right-20'),
+          opacity: badgeOpacity,
+          transform: `rotate(${badgeRotation}deg)`
+        }}
+      >
+        <img 
+          src={image(badge)} 
+          style={tw('w-32 h-32')}
+        />
+      </div>
+      
+      {/* Title */}
+      <div style={tw('absolute top-20 left-20')}>
+        <h2 style={tw('text-5xl font-bold text-gray-900')}>
+          {title}
+        </h2>
+      </div>
+      
+      {/* Animated price */}
+      <div 
+        style={{
+          ...tw('absolute bottom-20 left-20'),
+          transform: `translateY(${priceY}px)`
+        }}
+      >
+        <div style={tw('text-6xl font-black text-blue-600')}>
+          ${price}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+**Props:**
+```json
+{
+  "title": "Premium Headphones",
+  "price": "299",
+  "backgroundVideo": "./footage/studio-background.mp4",
+  "productImage": "./images/headphones.png",
+  "badge": "./images/new-badge.png"
+}
+```
+
+### Video with Multiple Image Overlays
+
+```tsx
+export default function TutorialVideo({ 
+  tw, 
+  video, 
+  image, 
+  progress, 
+  frame,
+  screencast,
+  avatar,
+  logo,
+  instructor,
+  lesson
+}) {
+  // Avatar pulses
+  const avatarScale = 1 + Math.sin(frame * 0.2) * 0.05;
+  
+  // Logo stays visible
+  const logoOpacity = 1;
+  
+  return (
+    <div style={tw('relative w-full h-full bg-gray-900')}>
+      {/* Main screencast video */}
+      <img 
+        src={video(screencast)} 
+        style={tw('absolute inset-0 w-full h-full object-contain')}
+      />
+      
+      {/* Company logo (top left) */}
+      <div style={{
+        ...tw('absolute top-8 left-8'),
+        opacity: logoOpacity
+      }}>
+        <img 
+          src={image(logo)} 
+          style={tw('h-12 w-auto')}
+        />
+      </div>
+      
+      {/* Instructor avatar (bottom right) */}
+      <div style={tw('absolute bottom-8 right-8')}>
+        <div 
+          style={{
+            ...tw('relative'),
+            transform: `scale(${avatarScale})`
+          }}
+        >
+          <img 
+            src={image(avatar)} 
+            style={tw('w-24 h-24 rounded-full border-4 border-blue-500')}
+          />
+          {/* Red recording dot */}
+          <div style={tw('absolute -top-1 -right-1 w-6 h-6 bg-red-500 rounded-full animate-pulse')} />
+        </div>
+      </div>
+      
+      {/* Lesson info overlay */}
+      <div style={tw('absolute bottom-8 left-8 bg-black/80 backdrop-blur px-6 py-4 rounded-lg')}>
+        <p style={tw('text-sm text-gray-400')}>Instructor</p>
+        <p style={tw('text-xl font-bold text-white mb-2')}>{instructor}</p>
+        <p style={tw('text-sm text-blue-400')}>{lesson}</p>
+      </div>
+    </div>
+  );
+}
+```
+
+**Props:**
+```json
+{
+  "instructor": "Sarah Johnson",
+  "lesson": "Lesson 3: Advanced Techniques",
+  "screencast": "./footage/screen-recording.mp4",
+  "avatar": "./images/instructor.jpg",
+  "logo": "./images/course-logo.png"
+}
+```
+
+### Supported Formats
+
+**Video formats** (via `video()` helper):
+- ✅ MP4 (`.mp4`)
+- ✅ MOV (`.mov`)
+- ✅ WebM (`.webm`)
+- ✅ AVI (`.avi`)
+
+**Image formats** (via `image()` helper):
+- ✅ JPEG (`.jpg`, `.jpeg`)
+- ✅ PNG (`.png`) - with transparency
+- ✅ GIF (`.gif`)
+- ✅ WebP (`.webp`)
+- ✅ SVG (`.svg`)
+
+### Best Practices
+
+1. **Pre-optimize assets**: Resize images and videos to match your output resolution
+2. **Use PNG for logos**: Transparency works perfectly with video backgrounds
+3. **Match frame rates**: If possible, use videos with the same FPS as your template
+4. **Consider file sizes**: Large videos take longer to process
+5. **Test opacity**: Ensure overlays are visible against video backgrounds
+
+## FPS and Duration
+
+### Common Frame Rates
+
+```json
+{
+  "video": {
+    "fps": 24,      // Film standard
+    "duration": 5
+  }
+}
+```
+
+```json
+{
+  "video": {
+    "fps": 30,      // YouTube/web standard
+    "duration": 3
+  }
+}
+```
+
+```json
+{
+  "video": {
+    "fps": 60,      // Smooth animations
+    "duration": 2
+  }
+}
+```
+
+**Total frames = fps × duration**
+- 24fps × 5s = 120 frames
+- 30fps × 3s = 90 frames
+- 60fps × 2s = 120 frames
+
+### Choosing FPS
+
+- **24fps**: Cinematic look, smaller files
+- **30fps**: Standard web video, good balance
+- **60fps**: Smooth animations, larger files
+
+## Encoding Options
+
+### Default (Balanced)
+
+```bash
+dsgn render video-intro '{"title":"Welcome"}'
+```
+
+Uses H.264 codec with good quality/size balance.
+
+### Fast Encoding
+
+```bash
+dsgn render video-intro '{"title":"Welcome"}' --preset ultrafast
+```
+
+Faster encoding, slightly larger files. Good for previews.
+
+### High Quality
+
+```bash
+dsgn render video-intro '{"title":"Welcome"}' --preset slow
+```
+
+Better compression, slower encoding. Good for final output.
+
+## Performance
+
+### Rendering Speed
+
+On an M1 Mac:
+- **30fps, 3s video** (90 frames): ~15-20 seconds
+- **60fps, 3s video** (180 frames): ~30-40 seconds
+
+Speed depends on:
+- Template complexity
+- Image/video embedding
+- CPU performance
+- Frame count
+
+### Optimization Tips
+
+1. **Lower FPS for previews**: Test at 15fps, render final at 30fps
+2. **Shorter duration**: Preview with 1s, expand for final
+3. **Simplify templates**: Complex layouts take longer
+4. **Pre-optimize media**: Resize images/videos before embedding
+
+### Memory Usage
+
+Video frames are cached in memory during rendering:
+- **1920x1080 @ 30fps for 3s**: ~500MB RAM
+- **1920x1080 @ 60fps for 5s**: ~1.7GB RAM
+
+For long videos, consider rendering in segments.
+
+## Common Video Templates
+
+### Social Media Intro
+
+```tsx
+export default function SocialIntro({ tw, progress, brand, tagline }) {
+  const logoScale = progress < 0.4 ? progress / 0.4 : 1;
+  const taglineOpacity = progress > 0.5 ? (progress - 0.5) / 0.5 : 0;
+  
+  return (
+    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-gradient-to-br from-pink-500 to-purple-600')}>
+      <h1 
+        style={{
+          ...tw('text-9xl font-black text-white mb-8'),
+          transform: `scale(${logoScale})`
+        }}
+      >
+        {brand}
+      </h1>
+      
+      <p 
+        style={{
+          ...tw('text-3xl text-white'),
+          opacity: taglineOpacity
+        }}
+      >
+        {tagline}
+      </p>
+    </div>
+  );
+}
+```
+
+### Progress Bar Animation
+
+```tsx
+export default function ProgressVideo({ tw, progress, title, subtitle }) {
+  return (
+    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-gray-900 p-12')}>
+      <h2 style={tw('text-5xl font-bold text-white mb-12')}>
+        {title}
+      </h2>
+      
+      {/* Progress bar */}
+      <div style={tw('w-full max-w-2xl h-4 bg-gray-700 rounded-full overflow-hidden')}>
+        <div 
+          style={{
+            ...tw('h-full bg-gradient-to-r from-blue-500 to-green-500'),
+            width: `${progress * 100}%`
+          }}
+        />
+      </div>
+      
+      <p style={tw('text-2xl text-gray-400 mt-8')}>
+        {subtitle}
+      </p>
+    </div>
+  );
+}
+```
+
+### Countdown Timer
+
+```tsx
+export default function CountdownVideo({ tw, frame, message }) {
+  const fps = 30;
+  const secondsRemaining = Math.ceil((90 - frame) / fps); // 3s countdown
+  
+  return (
+    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-black')}>
+      <div style={tw('text-[200px] font-black text-white')}>
+        {secondsRemaining}
+      </div>
+      <p style={tw('text-3xl text-gray-400 mt-8')}>
+        {message}
+      </p>
+    </div>
+  );
+}
+```
+
+## Output Format
+
+Videos are always rendered as MP4 (H.264 codec) for maximum compatibility.
+
+## Next Steps
+
+- [Learn about Image Rendering](/images)
+- [QR Codes and Template Composition](/helpers)
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Custom Fonts in Videos](/fonts)
+
+
+
+
+
+================================================================================
+FILE: helpers.mdx
+================================================================================
+
+# Template Helpers
+
+Additional helpers for creating powerful, composable templates.
+
+## Overview
+
+Beyond the basics, dsgn provides:
+- `template()` - Compose templates together
+- `qr()` - Generate QR codes on the fly
+- `config` - Access user configuration
+
+For image and video embedding, see the [Images](/images) and [Video](/video) pages.
+
+## Template Composition
+
+Compose multiple templates together to create complex designs.
+
+### Usage
+
+```tsx
+export default function CompositeCard({ tw, template, title, author, avatar }) {
+  return (
+    <div style={tw('w-full h-full bg-gradient-to-br from-purple-600 to-blue-500 p-12')}>
+      <div style={tw('bg-white rounded-2xl p-8 shadow-xl')}>
+        <h1 style={tw('text-4xl font-bold text-gray-900 mb-6')}>{title}</h1>
+        
+        {/* Embed another template */}
+        <div style={tw('mb-6')}>
+          {template('user-badge', {
+            name: author,
+            avatar: avatar
+          })}
+        </div>
+        
+        <p style={tw('text-gray-600')}>Published by {author}</p>
+      </div>
+    </div>
+  );
+}
+```
+
+**How it works:**
+1. `template(name, props)` renders another installed template
+2. The embedded template is rendered at its specified size
+3. You can embed multiple templates in one design
+4. Templates can be nested (template within a template)
+
+### Use Cases
+
+**1. Reusable components:**
+```tsx
+// Create a logo template once, use it everywhere
+<div>{template('company-logo', { variant: 'dark' })}</div>
+```
+
+**2. Complex layouts:**
+```tsx
+// Combine multiple templates into one design
+<div style={tw('grid grid-cols-2 gap-4')}>
+  {template('product-card', { product: product1 })}
+  {template('product-card', { product: product2 })}
+</div>
+```
+
+**3. Dynamic content:**
+```tsx
+// Render templates based on data
+{users.map(user => 
+  template('user-avatar', { name: user.name, image: user.avatar })
+)}
+```
+
+### Best Practices
+
+1. **Keep templates focused** - Each template should do one thing well
+2. **Pass minimal props** - Only pass what the embedded template needs
+3. **Document dependencies** - Note which templates are required in your README
+4. **Avoid deep nesting** - Too many nested templates can be hard to debug
+
+## QR Codes
+
+Generate QR codes dynamically in your templates.
+
+### Usage
+
+```tsx
+export default function QRCard({ tw, qr, title, url }) {
+  return (
+    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-white p-10')}>
+      <h1 style={tw('text-4xl font-bold text-black mb-8')}>{title}</h1>
+      
+      {/* Generate QR code for the URL */}
+      <img src={qr(url)} style={tw('w-64 h-64')} />
+      
+      <p style={tw('text-gray-600 mt-4')}>{url}</p>
+    </div>
+  );
+}
+```
+
+**Props format:**
+```json
+{
+  "title": "Scan Me",
+  "url": "https://example.com"
+}
+```
+
+### QR Options
+
+You can customize QR code appearance:
+
+```tsx
+// Basic QR code
+<img src={qr('https://example.com')} />
+
+// With error correction level
+<img src={qr('https://example.com', { errorCorrectionLevel: 'H' })} />
+
+// With custom size
+<img src={qr('https://example.com', { width: 512 })} />
+```
+
+**Error correction levels:**
+- `L` - Low (~7% correction)
+- `M` - Medium (~15% correction) - default
+- `Q` - Quartile (~25% correction)
+- `H` - High (~30% correction)
+
+## User Configuration
+
+Access user settings from `dsgn.json` using the `config` prop:
+
+```tsx
+export default function BrandedTemplate({ tw, config, title }) {
+  // Access custom colors from dsgn.json
+  const primaryColor = config?.colors?.brand || '#6366f1';
+  
+  return (
+    <div style={tw('w-full h-full p-12')}>
+      <h1 style={{ 
+        ...tw('text-6xl font-bold'),
+        color: primaryColor 
+      }}>
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+**User's dsgn.json:**
+```json
+{
+  "colors": {
+    "brand": "#ff6b6b"
+  },
+  "fonts": {
+    "sans": ["Inter", "system-ui", "sans-serif"]
+  }
+}
+```
+
+This allows templates to adapt to user preferences and brand guidelines.
+
+## All Props Reference
+
+Every template receives these props:
+
+```tsx
+export default function MyTemplate({ 
+  // Core helpers
+  tw,        // Tailwind class converter
+  qr,        // QR code generator (this page)
+  template,  // Template composer (this page)
+  config,    // User config from dsgn.json (this page)
+  
+  // Media helpers (see dedicated pages)
+  image,     // Image embedder → see /images
+  video,     // Video frame getter → see /video
+  
+  // Video-specific (only in video templates)
+  frame,     // Current frame number → see /video
+  progress,  // Animation progress 0-1 → see /video
+  
+  // Your custom props
+  ...props   // Any props from your props.json
+}) {
+  // Your template code
+}
+```
+
+## Next Steps
+
+- [Image Rendering and Embedding](/images)
+- [Video Rendering and Animation](/video)
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Custom Fonts](/fonts)
+
+
+
+
+
+================================================================================
+FILE: styling.mdx
+================================================================================
+
+# Styling Templates
+
+Style your templates with Tailwind utility classes and shadcn/ui's beautiful design system.
+
+## Quick Start
+
+```tsx
+export default function MyTemplate({ title, tw }) {
+  return (
+    <div style={tw('flex items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
+      <h1 style={tw('text-7xl font-bold text-white')}>
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+## The `tw()` Function
+
+Every template receives a `tw()` function that converts Tailwind classes to inline styles compatible with Satori:
+
+```tsx
+// Tailwind classes
+tw('flex items-center justify-center p-8 bg-blue-500')
+
+// Converts to inline styles:
+{
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  padding: '2rem',
+  backgroundColor: '#3b82f6'
+}
+```
+
+### Basic Usage
+
+```tsx
+export default function Banner({ title, subtitle, tw }) {
+  return (
+    <div style={tw('w-full h-full p-12 bg-gray-50')}>
+      <h1 style={tw('text-6xl font-bold text-gray-900 mb-4')}>
+        {title}
+      </h1>
+      <p style={tw('text-2xl text-gray-600')}>
+        {subtitle}
+      </p>
+    </div>
+  );
+}
+```
+
+### Combining with Custom Styles
+
+Mix Tailwind classes with custom styles using the spread operator:
+
+```tsx
+export default function CustomGradient({ title, tw }) {
+  return (
+    <div
+      style={{
+        ...tw('flex flex-col items-center justify-center w-full h-full p-20'),
+        background: 'linear-gradient(135deg, #667eea 0%, #764ba2 100%)',
+      }}
+    >
+      <h1 style={tw('text-8xl font-bold text-white')}>{title}</h1>
+    </div>
+  );
+}
+```
+
+## shadcn/ui Design System
+
+dsgn uses **shadcn/ui's design system** by default, providing semantic color tokens for beautiful, consistent designs.
+
+### Default Color Palette
+
+All templates automatically have access to these semantic colors:
+
+```typescript
+colors: {
+  // Primary colors
+  primary: '#18181b',           // Main brand color
+  'primary-foreground': '#fafafa',
+
+  // Secondary colors
+  secondary: '#f4f4f5',         // Subtle accents
+  'secondary-foreground': '#18181b',
+
+  // Background
+  background: '#ffffff',        // Page background
+  foreground: '#09090b',        // Main text color
+
+  // Muted
+  muted: '#f4f4f5',            // Subtle backgrounds
+  'muted-foreground': '#71717a', // Muted text
+
+  // Accent
+  accent: '#f4f4f5',           // Highlight color
+  'accent-foreground': '#18181b',
+
+  // Destructive
+  destructive: '#ef4444',       // Error/danger states
+  'destructive-foreground': '#fafafa',
+
+  // UI Elements
+  border: '#e4e4e7',           // Border color
+  input: '#e4e4e7',            // Input borders
+  ring: '#18181b',             // Focus rings
+  card: '#ffffff',             // Card background
+  'card-foreground': '#09090b',
+}
+```
+
+### Using Semantic Colors
+
+```tsx
+export default function SemanticCard({ title, description, price, tw }) {
+  return (
+    <div style={tw('bg-card border border-border rounded-lg p-6')}>
+      <h2 style={tw('text-card-foreground text-2xl font-bold mb-2')}>
+        {title}
+      </h2>
+      <p style={tw('text-muted-foreground mb-4')}>
+        {description}
+      </p>
+      <div style={tw('text-primary text-3xl font-bold')}>
+        ${price}
+      </div>
+    </div>
+  );
+}
+```
+
+### Opacity Modifiers
+
+Use Tailwind's slash syntax for opacity with any color:
+
+```tsx
+export default function OpacityExample({ tw }) {
+  return (
+    <div style={tw('bg-primary/50')}>          {/* 50% opacity */}
+      <p style={tw('text-muted-foreground/75')}> {/* 75% opacity */}
+        Subtle text
+      </p>
+      <div style={tw('border border-border/30')}> {/* 30% opacity */}
+        Faint border
+      </div>
+    </div>
+  );
+}
+```
+
+**Supported syntax:**
+- `bg-{color}/{opacity}` - Background with opacity
+- `text-{color}/{opacity}` - Text with opacity  
+- `border-{color}/{opacity}` - Border with opacity
+
+### Text Hierarchy
+
+```tsx
+// Primary text
+tw('text-foreground')
+
+// Secondary/muted text
+tw('text-muted-foreground')
+
+// Accent/brand text
+tw('text-primary')
+
+// Destructive/error text
+tw('text-destructive')
+```
+
+### Backgrounds
+
+```tsx
+// Page background
+tw('bg-background')
+
+// Card/elevated surfaces
+tw('bg-card')
+
+// Subtle backgrounds
+tw('bg-muted')
+
+// Accent backgrounds
+tw('bg-accent')
+```
+
+## Supported Tailwind Classes
+
+### Layout
+
+- **Display**: `flex`, `inline-flex`, `block`, `inline-block`, `hidden`
+- **Flex Direction**: `flex-row`, `flex-col`, `flex-row-reverse`, `flex-col-reverse`
+- **Justify**: `justify-start`, `justify-end`, `justify-center`, `justify-between`, `justify-around`
+- **Align**: `items-start`, `items-end`, `items-center`, `items-baseline`, `items-stretch`
+
+### Spacing
+
+- **Padding**: `p-{n}`, `px-{n}`, `py-{n}`, `pt-{n}`, `pb-{n}`, `pl-{n}`, `pr-{n}`
+- **Margin**: `m-{n}`, `mx-{n}`, `my-{n}`, `mt-{n}`, `mb-{n}`, `ml-{n}`, `mr-{n}`
+- **Gap**: `gap-{n}`, `gap-x-{n}`, `gap-y-{n}`
+- **Sizes**: 0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24, 32, 40, 48, 56, 64
+
+Examples:
+```tsx
+tw('p-4')      // padding: 1rem
+tw('px-8')     // paddingLeft: 2rem, paddingRight: 2rem
+tw('m-6')      // margin: 1.5rem
+tw('gap-4')    // gap: 1rem
+```
+
+### Sizing
+
+- **Width**: `w-{n}`, `w-full`, `w-screen`, `w-1/2`, `w-1/3`, `w-2/3`
+- **Height**: `h-{n}`, `h-full`, `h-screen`
+
+Examples:
+```tsx
+tw('w-full')   // width: 100%
+tw('h-64')     // height: 16rem
+tw('w-1/2')    // width: 50%
+```
+
+### Typography
+
+- **Font Size**: `text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`, `text-7xl`, `text-8xl`, `text-9xl`
+- **Font Weight**: `font-thin`, `font-light`, `font-normal`, `font-medium`, `font-semibold`, `font-bold`, `font-extrabold`, `font-black`
+- **Text Align**: `text-left`, `text-center`, `text-right`
+- **Line Height**: `leading-none`, `leading-tight`, `leading-normal`, `leading-relaxed`, `leading-loose`
+
+### Colors
+
+All standard Tailwind colors plus shadcn semantic colors:
+
+**Standard colors:**
+- `text-{color}-{shade}`, `bg-{color}-{shade}`, `border-{color}-{shade}`
+- Colors: `red`, `blue`, `green`, `yellow`, `purple`, `pink`, `gray`, `indigo`, `teal`, `orange`
+- Shades: `50`, `100`, `200`, `300`, `400`, `500`, `600`, `700`, `800`, `900`
+
+**shadcn semantic colors:**
+- `text-foreground`, `text-primary`, `text-muted-foreground`, `text-destructive`
+- `bg-background`, `bg-card`, `bg-muted`, `bg-accent`, `bg-primary`
+- `border-border`, `border-input`
+
+```tsx
+tw('text-blue-500')        // Standard Tailwind color
+tw('bg-purple-600')        // Standard Tailwind color
+tw('text-primary')         // shadcn semantic color
+tw('bg-card')              // shadcn semantic color
+```
+
+### Position & Layout
+
+- **Position**: `relative`, `absolute`, `fixed`, `sticky`
+- **Inset**: `inset-0`, `top-0`, `bottom-0`, `left-0`, `right-0`
+- **Z-Index**: `z-0`, `z-10`, `z-20`, `z-30`, `z-40`, `z-50`
+
+### Borders
+
+- **Border Width**: `border`, `border-{n}`, `border-t`, `border-b`, `border-l`, `border-r`
+- **Border Radius**: `rounded`, `rounded-sm`, `rounded-md`, `rounded-lg`, `rounded-xl`, `rounded-2xl`, `rounded-3xl`, `rounded-full`
+- **Border Color**: `border-{color}-{shade}`, `border-border`, `border-input`
+
+### Effects
+
+- **Shadow**: `shadow-sm`, `shadow`, `shadow-md`, `shadow-lg`, `shadow-xl`, `shadow-2xl`
+- **Opacity**: `opacity-0`, `opacity-25`, `opacity-50`, `opacity-75`, `opacity-100`
+
+### Filters
+
+- **Blur**: `blur-none`, `blur-sm`, `blur`, `blur-md`, `blur-lg`, `blur-xl`
+- **Brightness**: `brightness-0`, `brightness-50`, `brightness-100`, `brightness-150`, `brightness-200`
+- **Contrast**: `contrast-0`, `contrast-50`, `contrast-100`, `contrast-150`, `contrast-200`
+
+## Gradients
+
+### Linear Gradients
+
+```tsx
+// Gradient direction
+tw('bg-gradient-to-r')      // left to right
+tw('bg-gradient-to-br')     // top-left to bottom-right
+tw('bg-gradient-to-t')      // bottom to top
+
+// Gradient colors
+tw('from-blue-500')         // Start color
+tw('via-purple-500')        // Middle color
+tw('to-pink-500')           // End color
+
+// Complete gradient
+tw('bg-gradient-to-r from-blue-500 via-purple-500 to-pink-500')
+```
+
+### Gradient Examples
+
+```tsx
+export default function GradientCard({ title, tw }) {
+  return (
+    <div style={tw('w-full h-full bg-gradient-to-br from-cyan-500 to-blue-600 p-12')}>
+      <h1 style={tw('text-white text-6xl font-bold')}>
+        {title}
+      </h1>
+    </div>
+  );
+}
+```
+
+## Custom Theme Colors
+
+Override default colors in your `dsgn.json`:
+
+```json
+{
+  "theme": {
+    "colors": {
+      "primary": "#3b82f6",
+      "primary-foreground": "#ffffff",
+      "accent": "#10b981",
+      "brand": "#ff6b6b"
+    }
+  }
+}
+```
+
+Then use in templates:
+
+```tsx
+tw('text-brand')    // Uses your custom brand color
+tw('bg-primary')    // Uses your custom primary color
+```
+
+## Auto-Detection from tailwind.config.js
+
+dsgn automatically detects and loads your project's Tailwind configuration:
+
+```
+your-project/
+├── tailwind.config.js  ← Automatically detected
+├── dsgn.json
+└── _dsgn/templates/
+```
+
+This includes:
+- Custom colors
+- Custom spacing values
+- Custom fonts
+- Theme extensions
+- Custom utilities
+
+## Complete Example
+
+```tsx
+export default function ModernCard({ 
+  tw, 
+  image,
+  title, 
+  description, 
+  category,
+  author,
+  avatar 
+}) {
+  return (
+    <div style={tw('w-full h-full bg-card')}>
+      {/* Hero image */}
+      <div style={tw('relative h-2/3')}>
+        <img 
+          src={image(hero)} 
+          style={tw('w-full h-full object-cover')}
+        />
+        {/* Category badge */}
+        <div style={tw('absolute top-4 left-4 bg-primary/90 backdrop-blur px-4 py-2 rounded-full')}>
+          <span style={tw('text-sm font-semibold text-primary-foreground')}>
+            {category}
+          </span>
+        </div>
+      </div>
+      
+      {/* Content */}
+      <div style={tw('h-1/3 p-8 flex flex-col justify-between')}>
+        <div>
+          <h2 style={tw('text-3xl font-bold text-foreground mb-2')}>
+            {title}
+          </h2>
+          <p style={tw('text-muted-foreground line-clamp-2')}>
+            {description}
+          </p>
+        </div>
+        
+        {/* Author */}
+        <div style={tw('flex items-center gap-3')}>
+          <img 
+            src={image(avatar)} 
+            style={tw('w-10 h-10 rounded-full border-2 border-border')}
+          />
+          <span style={tw('text-sm text-muted-foreground')}>
+            {author}
+          </span>
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+## Why This Approach?
+
+- **Semantic naming**: `text-primary` instead of `text-blue-600`
+- **Consistency**: All templates use the same design language
+- **Flexibility**: Easy to customize entire theme
+- **Accessibility**: Pre-tested color contrasts
+- **Modern**: Same system as shadcn/ui components
+- **Familiar**: Standard Tailwind syntax
+
+## Next Steps
+
+- [Custom Fonts](/fonts)
+- [Built-in Helpers](/helpers)
+- [Image Rendering](/images)
+- [Video Rendering](/video)
+
+
+
+
+
+================================================================================
+FILE: fonts.mdx
+================================================================================
+
+# Font Handling in dsgn
+
+The recommended way to use fonts is through `dsgn.json` - configure fonts once, use everywhere.
+
+## Using Fonts from dsgn.json (Recommended)
+
+Configure fonts in your `dsgn.json` and use Tailwind classes in templates.
+
+### Simple Setup (CSS Only)
+
+Define font families without loading custom fonts (uses system fonts):
+
+```json
+{
+  "fonts": {
+    "sans": ["Inter", "system-ui", "-apple-system", "sans-serif"],
+    "serif": ["Georgia", "serif"],
+    "mono": ["Courier New", "monospace"]
+  }
+}
+```
+
+**Template usage:**
+```tsx
+export default function({ title, tw }) {
+  return (
+    <div style={tw('w-full h-full')}>
+      {/* Uses fonts.sans from dsgn.json */}
+      <h1 style={tw('font-sans text-6xl font-bold')}>
+        {title}
+      </h1>
+
+      {/* Uses fonts.mono from dsgn.json */}
+      <code style={tw('font-mono text-sm')}>
+        {code}
+      </code>
+    </div>
+  );
+}
+```
+
+**Result:** Uses system fonts, falls back to Noto Sans for rendering.
+
+### Complete Setup (With Font Files)
+
+Load custom font files for brand-specific typography:
+
+```json
+{
+  "fonts": {
+    "sans": {
+      "family": ["Inter", "system-ui", "sans-serif"],
+      "files": [
+        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
+        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
+      ]
+    },
+    "mono": {
+      "family": ["JetBrains Mono", "monospace"],
+      "files": [
+        { "path": "./fonts/JetBrainsMono-Regular.woff", "weight": 400 }
+      ]
+    }
+  }
+}
+```
+
+**Project structure:**
+```
+your-project/
+├── dsgn.json
+├── fonts/
+│   ├── Inter-Regular.woff
+│   ├── Inter-Bold.woff
+│   └── JetBrainsMono-Regular.woff
+└── _dsgn/
+    └── templates/
+```
+
+**Template usage (same as before):**
+```tsx
+<h1 style={tw('font-sans font-bold')}>
+  {/* Uses Inter Bold from dsgn.json */}
+  {title}
+</h1>
+```
+
+**Available classes:**
+- `font-sans` - Uses `fonts.sans` from dsgn.json
+- `font-serif` - Uses `fonts.serif` from dsgn.json
+- `font-mono` - Uses `fonts.mono` from dsgn.json
+
+**Supported formats:**
+- ✅ **WOFF** (`.woff`) - Recommended
+- ✅ **WOFF2** (`.woff2`) - Best compression
+- ✅ **TTF** (`.ttf`) - Also supported
+- ✅ **OTF** (`.otf`) - Also supported
+
+## Template-Specific Fonts (Advanced)
+
+For templates that need unique fonts not shared across the project:
+
+**Template structure:**
+```
+_dsgn/templates/my-template/
+├── my-template.tsx
+├── meta.json
+└── fonts/
+    └── SpecialFont.woff
+```
+
+**meta.json:**
+```json
+{
+  "name": "my-template",
+  "type": "image",
+  "size": { "width": 1200, "height": 630 },
+  "fonts": [
+    {
+      "name": "Special Font",
+      "path": "fonts/SpecialFont.woff",
+      "weight": 400,
+      "style": "normal"
+    }
+  ]
+}
+```
+
+**Template usage:**
+```tsx
+<h1 style={{ fontFamily: 'Special Font', fontWeight: 400 }}>
+  {title}
+</h1>
+```
+
+## Font Loading Priority
+
+dsgn loads fonts in this order:
+
+1. **dsgn.json fonts** (if configured with `files`)
+2. **Template meta.json fonts** (if specified)
+3. **Default Noto Sans** (from CDN)
+
+This means dsgn.json fonts override template fonts, ensuring consistency.
+
+## Default Fonts
+
+If no fonts are configured, dsgn automatically fetches **Noto Sans** from jsDelivr CDN.
+
+## Best Practices
+
+1. ✅ **Use dsgn.json for project-wide fonts** - Configure once, use everywhere
+2. ✅ **Use font classes** - `tw('font-sans')` instead of `fontFamily: 'Inter'`
+3. ✅ **Include fallbacks** - Always add system fonts: `["Inter", "system-ui", "sans-serif"]`
+4. ✅ **Match names** - First font in `family` array is used as the loaded font name
+5. ✅ **Relative paths** - Font paths are relative to `dsgn.json` location
+6. ⚠️ **Template fonts for special cases** - Only use meta.json fonts for template-specific typography
+
+## Examples
+
+### Minimal Setup (System Fonts)
+```json
+{
+  "fonts": {
+    "sans": ["Inter", "-apple-system", "sans-serif"]
+  }
+}
+```
+Uses system Inter if available, falls back to Noto Sans for rendering.
+
+### Brand Fonts Setup
+```json
+{
+  "fonts": {
+    "sans": {
+      "family": ["Montserrat", "sans-serif"],
+      "files": [
+        { "path": "./fonts/Montserrat-Regular.woff", "weight": 400 },
+        { "path": "./fonts/Montserrat-Bold.woff", "weight": 700 }
+      ]
+    }
+  }
+}
+```
+Loads and uses Montserrat for all templates.
+
+### Multi-Font Setup
+```json
+{
+  "fonts": {
+    "sans": {
+      "family": ["Inter", "sans-serif"],
+      "files": [
+        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
+        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
+      ]
+    },
+    "serif": {
+      "family": ["Playfair Display", "serif"],
+      "files": [
+        { "path": "./fonts/Playfair-Regular.woff", "weight": 400 }
+      ]
+    },
+    "mono": {
+      "family": ["Fira Code", "monospace"],
+      "files": [
+        { "path": "./fonts/FiraCode-Regular.woff", "weight": 400 }
+      ]
+    }
+  }
+}
+```
+Loads different fonts for each style class.
+
+## Performance
+
+- ✅ **Font caching** - Fonts load once and are cached for all renders
+- ✅ **Video optimization** - 90-frame video loads fonts once, not 90 times
+- ✅ **No CDN delays** - Local fonts load instantly
+
+## Next Steps
+
+- [Styling with Tailwind & shadcn/ui](/styling)
+- [Built-in Helpers](/helpers)
+- [Image Rendering](/images)
+- [Video Rendering](/video)
+
+