Loopwind

SKILL.md

---
name: loopwind
description: Generate images and videos from React + Tailwind CSS templates using the loopwind CLI.
metadata:
  version: "0.25.11"
---

# loopwind

A CLI tool for generating images and videos from JSX templates using Tailwind CSS and Satori. Templates live in a `.loopwind/` directory alongside your codebase.

## Quick Start

Loopwind is a CLI tool for generating images and videos with React and Tailwind CSS. It's designed to be used with AI Agents and Cursor.

### Installation

```bash
curl -fsSL https://loopwind.dev/install.sh | bash
```

This installs loopwind to `~/.loopwind/` and adds the `loopwind` command to your PATH. Requires Node.js 18+.

### Initialize in Your Project

Navigate to any project folder and run:

```bash
loopwind init
```

This creates `.loopwind/loopwind.json` — a configuration file with your project's theme colors.

### Install AI Skill

Give your AI agent expertise in loopwind:

```bash
npx skills add https://loopwind.dev/skill.md
```

This installs a skill that teaches Claude Code (or other AI agents) how to create templates, use animation classes, and render images/videos.

### Use with Claude Code

With the loopwind skill installed, Claude has deep knowledge of template structure, animation classes, and Tailwind CSS patterns for Satori. Just ask:

```
Create an OG image for my blog post about TypeScript tips
```

```
Create an animated intro video for my YouTube channel
```

Claude will create optimized templates and render the final output automatically.

### Install a Template

#### 1. Official Templates

```bash
loopwind add image-template
loopwind add video-template
```

Templates are installed to: `.loopwind/<template>/`

**Benefits:**
- Templates are local to your project
- Version controlled with your project
- Easy to share within your team

### Render a Template

```bash
loopwind render template-name '{"title":"Hello World","subtitle":"Built with loopwind"}'
```
or use a local props file:

```bash
loopwind render template-name props.json
```
## Commands

### `loopwind add <source>`

Install a template from various sources:

```bash
# Official templates
loopwind add image-template
loopwind add video-template
```
These will be downloaded to `.loopwind/<template>/`

### `loopwind list`

List all installed templates:

```bash
loopwind list
```

### `loopwind render <template> <props> [options]`

Render an image or video:

```bash
# Image with inline props
loopwind render banner-hero '{"title":"Hello World"}'

# Video with inline props
loopwind render video-intro '{"title":"Welcome"}'

# Using a props file
loopwind render banner-hero props.json

# Custom output
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg
```

Options:
- `--out, -o` - Output filename (default: `<template>.<ext>` in current directory)
- `--format` - Output format: `png`, `jpeg`, `svg` (images only)
- `--quality` - JPEG quality 1-100 (default: 92)

### `loopwind validate <template>`

Validate a template:

```bash
loopwind validate banner-hero
```

Checks:
- Template file exists and is valid React
- `export const meta` exists and is valid
- Required props are defined
- Fonts exist (if specified)

### `loopwind init`

Initialize loopwind in a project:

```bash
loopwind init
```

Creates `.loopwind/loopwind.json` configuration file with your project's design tokens.

## Animation Classes (Video Only)

Use Tailwind-style animation classes - no manual calculations needed:

```tsx
// Fade in: starts at 0ms, lasts 500ms
<h1 style={tw('enter-fade-in/0/500')}>Hello</h1>

// Loop: ping effect every 500ms
<div style={tw('loop-ping/500')} />

// Combined with easing
<h1 style={tw('ease-out enter-bounce-in-up/0/600')}>Title</h1>
```

See [Animation](/animation) for the complete reference.

## Next Steps

- [Templates](/templates)
- [Embedding Images](/images)
- [Animation](/animation)
- [Helpers (QR, Template Composition)](/helpers)
- [Styling with Tailwind & shadcn/ui](/styling)
- [Custom Fonts](/fonts)
- [AI Agent Integration](/agents)



# Templates

Templates are React components that define your images and videos. They use Tailwind CSS for styling and export metadata that loopwind uses for rendering.

## Installing Templates

### Official Templates

```bash
loopwind add image-template
loopwind add video-template
```

Templates are installed to `.loopwind/<template-name>/`.

### Direct URLs

```bash
loopwind add https://example.com/templates/my-template.json
```

### Local Filesystem

```bash
loopwind add ./my-templates/banner-hero
loopwind add /Users/you/templates/social-card
```

---

## Image Templates

### Basic Structure

```tsx
// .loopwind/banner-hero/template.tsx
export const meta = {
  name: "banner-hero",
  type: "image",
  description: "Hero banner with gradient background",
  size: { width: 1600, height: 900 },
  props: { title: "string", subtitle: "string" }
};

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>
  );
}
```

### Rendering Images

```bash
# Render with inline props
loopwind render banner-hero '{"title":"Hello World","subtitle":"Welcome"}'

# Custom output name
loopwind render banner-hero '{"title":"Hello"}' --out custom-name.png

# Different format
loopwind render banner-hero '{"title":"Hello"}' --format jpeg --quality 95

# Use a props file
loopwind render banner-hero props.json
```

### Output Formats

| Format | Best For |
|--------|----------|
| **PNG** (default) | Transparency, sharp text, logos |
| **JPEG** | Photographs, gradients, smaller files |
| **SVG** | Vector graphics, scalable designs |

---

## Video Templates

### Basic Structure

```tsx
// .loopwind/video-intro/template.tsx
export const meta = {
  name: "video-intro",
  type: "video",
  description: "Animated intro with bounce-in title",
  size: { width: 1920, height: 1080 },
  video: { fps: 30, duration: 3 },
  props: { title: "string" }
};

export default function VideoIntro({ tw, title }) {
  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 ease-out enter-bounce-in-up/0/600')}>
        {title}
      </h1>
    </div>
  );
}
```

### Rendering Videos

```bash
# Render with inline props
loopwind render video-intro '{"title":"Welcome!"}' --out intro.mp4

# Faster encoding with FFmpeg
loopwind render video-intro '{"title":"Welcome!"}' --ffmpeg

# Higher quality (lower CRF = better)
loopwind render video-intro '{"title":"Welcome!"}' --crf 18
```

### FPS and Duration

```tsx
video: { fps: 30, duration: 3 }  // 90 frames total
```

| FPS | Use Case |
|-----|----------|
| **24** | Cinematic look, smaller files |
| **30** | Standard web video |
| **60** | Smooth animations |

### Video-Specific Props

Templates receive these additional props:

- **`frame`** - Current frame number (0 to totalFrames - 1)
- **`progress`** - Animation progress from 0 to 1

```tsx
export default function MyVideo({ frame, progress }) {
  // frame: 0, 1, 2, ... 89 (for 3s @ 30fps)
  // progress: 0.0 at start, 0.5 at middle, 1.0 at end
}
```

### Encoding Options

| Encoder | Command | Use Case |
|---------|---------|----------|
| **WASM** (default) | `loopwind render ...` | CI/CD, no dependencies |
| **FFmpeg** | `loopwind render ... --ffmpeg` | Faster, smaller files |

Install FFmpeg: `brew install ffmpeg` (macOS)

---

## Animation Classes

Use Tailwind-style animation classes for videos:

```tsx
// Enter animations: enter-{type}/{delay}/{duration}
<h1 style={tw('enter-fade-in/0/500')}>Fade in at start</h1>
<h1 style={tw('enter-bounce-in-up/300/400')}>Bounce in after 300ms</h1>

// Exit animations: exit-{type}/{start}/{duration}
<div style={tw('exit-fade-out/2500/500')}>Fade out at 2.5s</div>

// Loop animations: loop-{type}/{duration}
<div style={tw('loop-float/1000')}>Continuous floating</div>
<div style={tw('loop-spin/1000')}>Spinning</div>

// Easing
<h1 style={tw('ease-out enter-slide-left/0/500')}>Smooth slide</h1>
```

See the full [Animation documentation](/animation) for all classes.

---

## Common Sizes

### Social Media
- **Twitter/X Card**: 1200x675
- **Facebook/OG**: 1200x630
- **Instagram Post**: 1080x1080
- **LinkedIn Post**: 1200x627

### Web Graphics
- **Hero Banner**: 1920x1080
- **Blog Header**: 1600x900
- **Thumbnail**: 640x360

---

## Example Templates

### Open Graph Image

```tsx
export const meta = {
  name: "og-image",
  type: "image",
  size: { width: 1200, height: 630 },
  props: { title: "string", description: "string" }
};

export default function OGImage({ tw, image, title, description }) {
  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.svg')} 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>
  );
}
```

### Animated Intro

```tsx
export const meta = {
  name: "animated-intro",
  type: "video",
  size: { width: 1920, height: 1080 },
  video: { fps: 60, duration: 3 },
  props: { title: "string", subtitle: "string" }
};

export default function AnimatedIntro({ tw, title, subtitle }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-background')}>
      <h1 style={tw('text-8xl font-bold text-foreground ease-out enter-bounce-in-up/0/400')}>
        {title}
      </h1>
      <p style={tw('text-2xl text-muted-foreground mt-4 ease-out enter-fade-in-up/300/400')}>
        {subtitle}
      </p>
    </div>
  );
}
```

---

## Next Steps

- [Layouts](/layouts) - Wrap templates with reusable layouts
- [Embedding Images](/images) - Using the `image()` helper
- [Animation](/animation) - Full animation reference
- [Styling](/styling) - Tailwind & shadcn/ui integration
- [Fonts](/fonts) - Custom fonts


# Layouts

Layouts let you wrap templates with consistent headers, footers, and styling. A child template specifies a layout in its meta, and the layout receives the child content as a `children` prop.

## Basic Usage

### Layout Template

Create a layout template that receives `children`:

```tsx
// .loopwind/base-layout/template.tsx
export const meta = {
  name: 'base-layout',
  type: 'image',
  size: { width: 1200, height: 630 },
  props: {},
};

export default function BaseLayout({ tw, children }) {
  return (
    <div style={tw('flex flex-col w-full h-full bg-background')}>
      {/* Header */}
      <div style={tw('flex items-center px-8 py-4 border-b border-border')}>
        <span style={tw('text-2xl font-bold text-primary')}>loopwind</span>
      </div>

      {/* Content slot */}
      <div style={tw('flex flex-1')}>
        {children}
      </div>

      {/* Footer */}
      <div style={tw('flex items-center justify-between px-8 py-4 border-t border-border')}>
        <span style={tw('text-muted-foreground')}>loopwind.dev</span>
      </div>
    </div>
  );
}
```

### Usage in Templates

Reference the layout using a relative path:

```tsx
// .loopwind/blog-post/template.tsx
export const meta = {
  name: 'blog-post',
  type: 'image',
  layout: '../base-layout', // Layout controls size
  props: {
    title: 'string',
    excerpt: 'string',
  },
};

export default function BlogPost({ tw, title, excerpt }) {
  return (
    <div style={tw('flex flex-col justify-center p-12')}>
      <h1 style={tw('text-5xl font-bold text-foreground mb-4 text-balance')}>
        {title}
      </h1>
      <p style={tw('text-xl text-muted-foreground leading-relaxed')}>
        {excerpt}
      </p>
    </div>
  );
}
```

### Render

```bash
loopwind render blog-post '{"title":"Hello World","excerpt":"My first post"}'
```

The output uses the layout's size (1200x630) with the child content inside.

---

## Key Concepts

### Size

When using a layout, the **layout's size** controls the final output dimensions. The child template doesn't need a `size` property.

### Path Resolution

Use relative paths to reference layouts:

```tsx
layout: '../base-layout'      // Sibling directory
layout: './shared/layout'     // Subdirectory
layout: '../../layouts/main'  // Parent's sibling
```

### Props Flow

The layout receives:
- All standard helpers (`tw`, `image`, `qr`, `template`, etc.)
- `children` prop containing the rendered child content
- Animation context (`frame`, `progress`) for video layouts

```tsx
export default function Layout({ tw, children, frame, progress }) {
  // tw, image, qr, template, path, textPath all available
  return (
    <div style={tw('flex w-full h-full')}>
      {children}
    </div>
  );
}
```

---

## Video Layouts

Layouts work with video templates. Both the layout and child can use animations:

```tsx
// .loopwind/video-layout/template.tsx
export const meta = {
  name: 'video-layout',
  type: 'video',
  size: { width: 1920, height: 1080 },
  video: { fps: 60, duration: 4 },
  props: {},
};

export default function VideoLayout({ tw, children }) {
  return (
    <div style={tw('flex flex-col w-full h-full bg-background')}>
      {/* Animated header */}
      <div style={tw('flex items-center px-12 py-6 ease-out enter-slide-down/0/500')}>
        <span style={tw('text-3xl font-bold text-primary')}>loopwind</span>
      </div>

      {/* Content */}
      <div style={tw('flex flex-1')}>
        {children}
      </div>

      {/* Animated footer */}
      <div style={tw('flex px-12 py-6 ease-out enter-fade-in/500/400')}>
        <span style={tw('text-muted-foreground')}>loopwind.dev</span>
      </div>
    </div>
  );
}
```

---

## Example: Consistent OG Images

Create a layout for all your OG images:

```tsx
// .loopwind/og-layout/template.tsx
export const meta = {
  name: 'og-layout',
  type: 'image',
  size: { width: 1200, height: 630 },
  props: {},
};

export default function OGLayout({ tw, image, children }) {
  return (
    <div style={tw('flex w-full h-full bg-background')}>
      {/* Content area */}
      <div style={tw('flex flex-col flex-1 p-12')}>
        {/* Logo */}
        <div style={tw('flex items-center gap-3 mb-auto')}>
          <img src={image('logo.svg')} style={tw('h-10 w-auto')} />
          <span style={tw('text-2xl font-bold')}>MyBrand</span>
        </div>

        {/* Slot for page-specific content */}
        <div style={tw('flex flex-1 items-center')}>
          {children}
        </div>

        {/* Domain */}
        <span style={tw('text-muted-foreground mt-auto')}>mybrand.com</span>
      </div>
    </div>
  );
}
```

Then create page-specific templates:

```tsx
// .loopwind/og-blog/template.tsx
export const meta = {
  name: 'og-blog',
  type: 'image',
  layout: '../og-layout',
  props: {
    title: 'string',
    author: 'string',
  },
};

export default function OGBlog({ tw, title, author }) {
  return (
    <div style={tw('flex flex-col')}>
      <span style={tw('text-sm text-muted-foreground uppercase tracking-wider mb-2')}>
        Blog Post
      </span>
      <h1 style={tw('text-4xl font-bold text-foreground mb-4 text-balance')}>
        {title}
      </h1>
      <span style={tw('text-muted-foreground')}>By {author}</span>
    </div>
  );
}
```

---

## Next Steps

- [Templates](/templates) - Template structure and metadata
- [Animation](/animation) - Animation classes for video layouts
- [Helpers](/helpers) - Using image(), qr(), and template()


# Embedding Images

Use the `image()` helper to embed images in your templates. It supports loading from props, template directories, and URLs.

## Prop-based Images

Pass the prop name to load an image path from props:

```tsx
export const meta = {
  name: "product-card",
  type: "image",
  size: { width: 1200, height: 630 },
  props: {
    title: "string",
    background: "string?"
  }
};

export default function ProductCard({ tw, image, title, background }) {
  // Use fallback if no background prop provided
  const bgSrc = background
    ? image('background')
    : 'https://images.unsplash.com/photo-1557682250-33bd709cbe85?w=1200';

  return (
    <div style={tw('relative w-full h-full')}>
      <img
        src={bgSrc}
        style={tw('absolute inset-0 w-full h-full object-cover')}
      />
      <div style={tw('relative z-10 p-12')}>
        <h1 style={tw('text-6xl font-bold text-white')}>{title}</h1>
      </div>
    </div>
  );
}
```

The `image('background')` helper loads from the `background` prop value (file path or URL).

## Direct File Images

Load images directly from your template directory by including the file extension:

```tsx
export default function ChangelogItem({ tw, image, text }) {
  return (
    <div style={tw('flex items-center gap-4')}>
      {/* Load check.svg from template directory */}
      <img
        src={image('check.svg')}
        style={tw('w-6 h-6')}
      />
      <span style={tw('text-lg')}>{text}</span>
    </div>
  );
}
```

You can also use subdirectories:

```tsx
<img src={image('assets/icons/star.svg')} />
<img src={image('shared/logo.png')} />
```

**Template directory structure:**
```
.loopwind/my-template/
├── template.tsx
├── check.svg           ← image('check.svg')
└── assets/
    └── icons/
        └── star.svg    ← image('assets/icons/star.svg')
```

## URLs

The `image()` helper also supports loading images from URLs:

```json
{
  "background": "https://example.com/image.jpg"
}
```

## Supported Formats

- **JPEG** (`.jpg`, `.jpeg`)
- **PNG** (`.png`)
- **GIF** (`.gif`)
- **WebP** (`.webp`)
- **SVG** (`.svg`)

## Image Positioning

Use Tailwind's object-fit utilities:

```tsx
export default function ImageGrid({ tw, image, img1, img2, img3 }) {
  return (
    <div style={tw('flex gap-4 w-full h-full p-8 bg-gray-100')}>
      {/* Cover - fills entire area, may crop */}
      <img
        src={image('img1')}
        style={tw('w-full h-full object-cover rounded-lg')}
      />

      {/* Contain - fits within area, may letterbox */}
      <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>
  );
}
```

## Troubleshooting

### Images Not Loading

Check file paths are relative to the props file:

```json
{
  "background": "./images/bg.jpg"
}
```

Absolute paths won't work.

### Optimize Image Sizes

Use appropriately sized images before embedding:

```bash
convert large-image.jpg -resize 1600x900 optimized.jpg
```

---

## Next Steps

- [Templates](/templates) - Creating image and video templates
- [Animation](/animation) - Animation classes for videos
- [Styling](/styling) - Tailwind & shadcn/ui integration


# Animation

loopwind provides **Tailwind-style animation classes** that work with time to create smooth video animations without writing custom code.

> **Note:** Animation classes only work with **video templates** and **GIFs**. For static images, animations will have no effect since there's no time context.

## Quick Start

```tsx
export default function MyVideo({ tw, title, subtitle }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-black')}>
      {/* Bounce in from below: starts at 0, lasts 400ms */}
      <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/400')}>
        {title}
      </h1>

      {/* Fade in with upward motion: starts at 300ms, lasts 400ms */}
      <p style={tw('text-2xl text-white/80 mt-4 ease-out enter-fade-in-up/300/400')}>
        {subtitle}
      </p>

      {/* Continuous floating animation: repeats every 1s (1000ms) */}
      <div style={tw('mt-8 text-4xl loop-float/1000')}>
        ⬇️
      </div>
    </div>
  );
}
```

## Animation Format

loopwind uses three types of animations with **millisecond timing**:

| Type | Format | Description |
|------|--------|-------------|
| Enter | `enter-{type}/{start}/{duration}` | Animations that play when entering |
| Exit | `exit-{type}/{start}/{duration}` | Animations that play when exiting |
| Loop | `loop-{type}/{duration}` | Continuous looping animations |

All timing values are in **milliseconds** (1000ms = 1 second).

## Utility-Based Animations

In addition to predefined animations, loopwind supports **Tailwind utility-based animations** that let you animate any transform or opacity property directly:

```tsx
// Slide in 20px from the left
<div style={tw('enter-translate-x-5/0/1000')}>Content</div>

// Rotate 90 degrees on entrance
<div style={tw('enter-rotate-90/0/500')}>Spinning</div>

// Fade to 50% opacity in a loop
<div style={tw('loop-opacity-50/1000')}>Pulsing</div>

// Scale down with negative value
<div style={tw('enter--scale-50/0/800')}>Shrinking</div>
```

### Supported Utilities

| Utility | Format | Description | Example |
|---------|--------|-------------|---------|
| **translate-x** | `enter-translate-x-{value}` | Translate horizontally | `enter-translate-x-5` = 20px<br/>`enter-translate-x-full` = 100%<br/>`enter-translate-x-[20px]` = 20px |
| **translate-y** | `enter-translate-y-{value}` | Translate vertically | `loop-translate-y-10` = 40px<br/>`enter-translate-y-1/2` = 50%<br/>`enter-translate-y-[5rem]` = 80px |
| **opacity** | `enter-opacity-{n}` | Set opacity (0-100) | `enter-opacity-50` = 50% |
| **scale** | `enter-scale-{n}` | Scale element (0-200) | `enter-scale-100` = 1.0x |
| **rotate** | `enter-rotate-{n}` | Rotate in degrees | `enter-rotate-45` = 45° |
| **skew-x** | `enter-skew-x-{n}` | Skew on X axis in degrees | `enter-skew-x-12` = 12° |
| **skew-y** | `enter-skew-y-{n}` | Skew on Y axis in degrees | `exit-skew-y-6` = 6° |

**Translate value formats:**
- **Numeric**: `5` = 20px (Tailwind spacing scale: 1 unit = 4px)
- **Keywords**: `full` = 100%
- **Fractions**: `1/2` = 50%, `1/3` = 33.333%, `2/3` = 66.666%, etc.
- **Arbitrary values**: `[20px]`, `[5rem]`, `[10%]` (rem converts to px: 1rem = 16px)

All utilities work with:
- **All prefixes**: `enter-`, `exit-`, `loop-`, `animate-`
- **Negative values**: Prefix with `-` (e.g., `-translate-x-5`, `-rotate-45`)
- **Timing syntax**: Add `/start/duration` (e.g., `enter-translate-x-5/0/800`)

### Translate Animations

```tsx
// Numeric (Tailwind spacing): 20px (5 * 4px)
<div style={tw('enter-translate-x-5/0/500')}>Content</div>

// Keyword: Full width (100%)
<div style={tw('enter-translate-y-full/0/800')}>Dropping full height</div>

// Fraction: Half width (50%)
<div style={tw('enter-translate-x-1/2/0/600')}>Slide in halfway</div>

// Arbitrary values: Exact px or rem
<div style={tw('enter-translate-y-[20px]/0/500')}>Slide 20px</div>
<div style={tw('enter-translate-x-[5rem]/0/800')}>Slide 5rem (80px)</div>

// Loop with fractions
<div style={tw('loop-translate-y-1/4/1000')}>Oscillate 25%</div>

// Negative values
<div style={tw('exit--translate-y-8/2000/500')}>Rising</div>
```

### Opacity Animations

```tsx
// Fade to 100% opacity
<div style={tw('enter-opacity-100/0/500')}>Fading In</div>

// Fade to 50% opacity
<div style={tw('enter-opacity-50/0/800')}>Half Opacity</div>

// Pulse between 50% and 100%
<div style={tw('loop-opacity-50/1000')}>Pulsing</div>

// Fade out to 0%
<div style={tw('exit-opacity-0/2500/500')}>Vanishing</div>
```

### Scale Animations

```tsx
// Scale from 0 to 100% (1.0x)
<div style={tw('enter-scale-100/0/500')}>Growing</div>

// Scale to 150% (1.5x)
<div style={tw('enter-scale-150/0/800')}>Enlarging</div>

// Pulse scale in a loop
<div style={tw('loop-scale-110/1000')}>Breathing</div>

// Scale down to 50%
<div style={tw('exit-scale-50/2000/500')}>Shrinking</div>
```

### Rotate Animations

```tsx
// Rotate 90 degrees
<div style={tw('enter-rotate-90/0/500')}>Quarter Turn</div>

// Rotate 180 degrees
<div style={tw('enter-rotate-180/0/1000')}>Half Turn</div>

// Continuous rotation in loop (360 degrees per cycle)
<div style={tw('loop-rotate-360/2000')}>Spinning</div>

// Rotate backwards with negative value
<div style={tw('enter--rotate-45/0/500')}>Counter Rotation</div>
```

### Skew Animations

```tsx
// Skew on X axis
<div style={tw('enter-skew-x-12/0/500')}>Slanted</div>

// Skew on Y axis
<div style={tw('enter-skew-y-6/0/800')}>Tilted</div>

// Oscillating skew in loop
<div style={tw('loop-skew-x-6/1000')}>Wobbling</div>

// Negative skew
<div style={tw('exit--skew-x-12/2000/500')}>Reverse Slant</div>
```

### Combining Utilities

You can combine multiple utility animations on the same element:

```tsx
// Translate and rotate together
<div style={tw('enter-translate-y-10/0/500 enter-rotate-45/0/500')}>
  Flying In
</div>

// Fade and scale
<div style={tw('enter-opacity-100/0/800 enter-scale-100/0/800')}>
  Appearing
</div>

// Enter with translate, exit with rotation
<div style={tw('enter-translate-x-5/0/500 exit-rotate-180/2500/500')}>
  Slide and Spin
</div>
```

### Bracket Notation

For more CSS-like syntax, you can use brackets with units:

```tsx
// Using bracket notation with seconds
<h1 style={tw('enter-slide-up/[0.6s]/[1.5s]')}>Hello</h1>

// Using bracket notation with milliseconds
<h1 style={tw('enter-fade-in/[300ms]/[800ms]')}>World</h1>

// Mix and match - plain numbers are milliseconds
<h1 style={tw('enter-bounce-in/0/[1.2s]')}>Mixed</h1>
```

## Enter Animations

Format: `enter-{type}/{startMs}/{durationMs}`

- `startMs` - when the animation begins (milliseconds from start)
- `durationMs` - how long the animation lasts

When values are omitted (`enter-fade-in`), it uses the full video duration.

### Fade Animations

Simple opacity transitions with optional direction.

```tsx
// Fade in from 0ms to 500ms
<h1 style={tw('enter-fade-in/0/500')}>Hello</h1>

// Fade in with upward motion
<h1 style={tw('enter-fade-in-up/0/600')}>Hello</h1>
```

| Class | Description |
|-------|-------------|
| `enter-fade-in/0/500` | Fade in (opacity 0 → 1) |
| `enter-fade-in-up/0/500` | Fade in + slide up (30px) |
| `enter-fade-in-down/0/500` | Fade in + slide down (30px) |
| `enter-fade-in-left/0/500` | Fade in + slide from left (30px) |
| `enter-fade-in-right/0/500` | Fade in + slide from right (30px) |

### Slide Animations

Larger movement (100px) with fade.

```tsx
// Slide in from left: starts at 0, lasts 500ms
<div style={tw('enter-slide-left/0/500')}>Content</div>

// Slide up from bottom: starts at 200ms, lasts 600ms
<div style={tw('enter-slide-up/200/600')}>Content</div>
```

| Class | Description |
|-------|-------------|
| `enter-slide-left/0/500` | Slide in from left (100px) |
| `enter-slide-right/0/500` | Slide in from right (100px) |
| `enter-slide-up/0/500` | Slide in from bottom (100px) |
| `enter-slide-down/0/500` | Slide in from top (100px) |

### Bounce Animations

Playful entrance with overshoot effect.

```tsx
// Bounce in with scale overshoot
<h1 style={tw('enter-bounce-in/0/500')}>Bouncy!</h1>

// Bounce in from below
<div style={tw('enter-bounce-in-up/0/600')}>Pop!</div>
```

| Class | Description |
|-------|-------------|
| `enter-bounce-in/0/500` | Bounce in with scale overshoot |
| `enter-bounce-in-up/0/500` | Bounce in from below |
| `enter-bounce-in-down/0/500` | Bounce in from above |
| `enter-bounce-in-left/0/500` | Bounce in from left |
| `enter-bounce-in-right/0/500` | Bounce in from right |

### Scale & Zoom Animations

Size-based transitions.

```tsx
// Scale in from 50%
<div style={tw('enter-scale-in/0/500')}>Growing</div>

// Zoom in from 0%
<div style={tw('enter-zoom-in/0/1000')}>Zooming</div>
```

| Class | Description |
|-------|-------------|
| `enter-scale-in/0/500` | Scale up from 50% to 100% |
| `enter-zoom-in/0/500` | Zoom in from 0% to 100% |

### Rotate & Flip Animations

Rotation-based transitions.

```tsx
// Rotate in 180 degrees
<div style={tw('enter-rotate-in/0/500')}>Spinning</div>

// 3D flip on X axis
<div style={tw('enter-flip-in-x/0/500')}>Flipping</div>
```

| Class | Description |
|-------|-------------|
| `enter-rotate-in/0/500` | Rotate in from -180° |
| `enter-flip-in-x/0/500` | 3D flip on horizontal axis |
| `enter-flip-in-y/0/500` | 3D flip on vertical axis |

## Exit Animations

Format: `exit-{type}/{startMs}/{durationMs}`

- `startMs` - when the exit animation begins
- `durationMs` - how long the exit animation lasts

Exit animations use the same timing system but animate elements out.

```tsx
// Fade out starting at 2500ms, lasting 500ms (ends at 3000ms)
<h1 style={tw('exit-fade-out/2500/500')}>Goodbye</h1>

// Combined enter and exit on same element
<h1 style={tw('enter-fade-in/0/500 exit-fade-out/2500/500')}>
  Hello and Goodbye
</h1>
```

| Class | Description |
|-------|-------------|
| `exit-fade-out/2500/500` | Fade out (opacity 1 → 0) |
| `exit-fade-out-up/2500/500` | Fade out + slide up |
| `exit-fade-out-down/2500/500` | Fade out + slide down |
| `exit-fade-out-left/2500/500` | Fade out + slide left |
| `exit-fade-out-right/2500/500` | Fade out + slide right |
| `exit-slide-up/2500/500` | Slide out upward (100px) |
| `exit-slide-down/2500/500` | Slide out downward (100px) |
| `exit-slide-left/2500/500` | Slide out to left (100px) |
| `exit-slide-right/2500/500` | Slide out to right (100px) |
| `exit-scale-out/2500/500` | Scale out to 150% |
| `exit-zoom-out/2500/500` | Zoom out to 200% |
| `exit-rotate-out/2500/500` | Rotate out to 180° |
| `exit-bounce-out/2500/500` | Bounce out with scale |
| `exit-bounce-out-up/2500/500` | Bounce out upward |
| `exit-bounce-out-down/2500/500` | Bounce out downward |
| `exit-bounce-out-left/2500/500` | Bounce out to left |
| `exit-bounce-out-right/2500/500` | Bounce out to right |

## Loop Animations

Format: `loop-{type}/{durationMs}`

Loop animations repeat every `{durationMs}` milliseconds:
- `/1000` = 1 second loop
- `/500` = 0.5 second loop
- `/2000` = 2 second loop

When duration is omitted (`loop-bounce`), it defaults to 1000ms (1 second).

```tsx
// Pulse opacity every 500ms
<div style={tw('loop-fade/500')}>Pulsing</div>

// Bounce every 800ms
<div style={tw('loop-bounce/800')}>Bouncing</div>

// Full rotation every 2000ms
<div style={tw('loop-spin/2000')}>Spinning</div>
```

| Class | Description |
|-------|-------------|
| `loop-fade/{ms}` | Opacity pulse (0.5 → 1 → 0.5) |
| `loop-bounce/{ms}` | Bounce up and down |
| `loop-spin/{ms}` | Full 360° rotation |
| `loop-ping/{ms}` | Scale up + fade out (radar effect) |
| `loop-wiggle/{ms}` | Side to side wiggle |
| `loop-float/{ms}` | Gentle up and down floating |
| `loop-pulse/{ms}` | Scale pulse (1.0 → 1.05 → 1.0) |
| `loop-shake/{ms}` | Shake side to side |

## Easing Functions

Add an easing class **before** the animation class to control the timing curve.

```tsx
// Ease in (accelerate)
<h1 style={tw('ease-in enter-fade-in/0/1000')}>Accelerating</h1>

// Ease out (decelerate) - default
<h1 style={tw('ease-out enter-fade-in/0/1000')}>Decelerating</h1>

// Ease in-out (smooth)
<h1 style={tw('ease-in-out enter-fade-in/0/1000')}>Smooth</h1>

// Strong cubic easing
<h1 style={tw('ease-out-cubic enter-bounce-in/0/500')}>Dramatic</h1>
```

| Class | Description | Best For |
|-------|-------------|----------|
| `linear` | Constant speed | Mechanical motion |
| `ease-in` | Slow start, fast end | Exit animations |
| `ease-out` | Fast start, slow end (default) | Enter animations |
| `ease-in-out` | Slow start and end | Subtle transitions |
| `ease-in-cubic` | Strong slow start | Dramatic exits |
| `ease-out-cubic` | Strong fast start | Impactful entrances |
| `ease-in-out-cubic` | Strong both ends | Emphasis animations |
| `ease-in-quart` | Very strong slow start | Powerful exits |
| `ease-out-quart` | Very strong fast start | Punchy entrances |
| `ease-in-out-quart` | Very strong both ends | Maximum drama |

### Per-Animation-Type Easing

You can apply **different easing functions** to enter, exit, and loop animations on the same element using `enter-ease-*`, `exit-ease-*`, and `loop-ease-*` classes.

```tsx
// Different easing for enter and exit
<h1 style={tw('enter-ease-out-cubic enter-fade-in/0/500 exit-ease-in exit-fade-out/2500/500')}>
  Smooth entrance, sharp exit
</h1>

// Loop with linear easing, enter with bounce
<div style={tw('enter-ease-out enter-bounce-in/0/400 loop-ease-linear loop-fade/1000')}>
  Bouncy entrance, linear loop
</div>

// Default easing still works (applies to all animations)
<div style={tw('ease-in-out enter-fade-in/0/500 exit-fade-out/2500/500')}>
  Same easing for both
</div>

// Mix default with specific overrides
<div style={tw('ease-out enter-fade-in/0/500 exit-ease-in-cubic exit-fade-out/2500/500')}>
  Default ease-out for enter, cubic-in for exit
</div>
```

**How it works:**

1. **Default easing** (`ease-*`) applies to ALL animations if no specific override is set
2. **Specific easing** (`enter-ease-*`, `exit-ease-*`, `loop-ease-*`) overrides the default for that animation type
3. If both are present, specific easing takes priority for its animation type

**Available easing classes:**

| Default (all animations) | Enter only | Exit only | Loop only |
|--------------------------|------------|-----------|-----------|
| `ease-in` | `enter-ease-in` | `exit-ease-in` | `loop-ease-in` |
| `ease-out` | `enter-ease-out` | `exit-ease-out` | `loop-ease-out` |
| `ease-in-out` | `enter-ease-in-out` | `exit-ease-in-out` | `loop-ease-in-out` |
| `ease-in-cubic` | `enter-ease-in-cubic` | `exit-ease-in-cubic` | `loop-ease-in-cubic` |
| `ease-out-cubic` | `enter-ease-out-cubic` | `exit-ease-out-cubic` | `loop-ease-out-cubic` |
| `ease-in-out-cubic` | `enter-ease-in-out-cubic` | `exit-ease-in-out-cubic` | `loop-ease-in-out-cubic` |
| `ease-in-quart` | `enter-ease-in-quart` | `exit-ease-in-quart` | `loop-ease-in-quart` |
| `ease-out-quart` | `enter-ease-out-quart` | `exit-ease-out-quart` | `loop-ease-out-quart` |
| `ease-in-out-quart` | `enter-ease-in-out-quart` | `exit-ease-in-out-quart` | `loop-ease-in-out-quart` |
| `linear` | `enter-ease-linear` | `exit-ease-linear` | `loop-ease-linear` |
| `ease-spring` | `enter-ease-spring` | `exit-ease-spring` | `loop-ease-spring` |

### Spring Easing

Spring easing creates natural, physics-based bouncy animations. Use the built-in `ease-spring` easing or create custom springs with configurable parameters.

```tsx
// Default spring easing
<h1 style={tw('ease-spring enter-bounce-in/0/500')}>Bouncy spring!</h1>

// Per-animation-type spring
<div style={tw('enter-ease-spring enter-fade-in/0/500 exit-ease-out exit-fade-out/2500/500')}>
  Spring entrance, smooth exit
</div>

// Custom spring with parameters: ease-spring/mass/stiffness/damping
<h1 style={tw('ease-spring/1/100/10 enter-scale-in/0/800')}>
  Custom spring (mass=1, stiffness=100, damping=10)
</h1>

// More bouncy spring (lower damping)
<div style={tw('ease-spring/1/170/8 enter-bounce-in-up/0/600')}>
  Extra bouncy!
</div>

// Stiffer spring (higher stiffness, faster)
<div style={tw('ease-spring/1/200/12 enter-fade-in-up/0/400')}>
  Snappy spring
</div>

// Per-animation-type custom springs
<div style={tw('enter-ease-spring/1/150/10 enter-fade-in/0/500 exit-ease-spring/1/100/15 exit-fade-out/2500/500')}>
  Different springs for enter and exit
</div>
```

**Spring parameters:**

| Parameter | Description | Effect when increased | Default |
|-----------|-------------|----------------------|---------|
| **mass** | Mass of the spring | Slower, more inertia | 1 |
| **stiffness** | Spring stiffness | Faster, snappier | 100 |
| **damping** | Damping coefficient | Less bounce, smoother | 10 |

**Common spring presets:**

```tsx
// Gentle bounce (default)
ease-spring/1/100/10

// Extra bouncy
ease-spring/1/170/8

// Snappy (no bounce)
ease-spring/1/200/15

// Slow and bouncy
ease-spring/2/100/8

// Fast and tight
ease-spring/0.5/300/20
```

**How spring works:**

1. **Default `ease-spring`** - Uses a pre-calculated spring curve optimized for most use cases
2. **Custom `ease-spring/mass/stiffness/damping`** - Generates a physics-based spring curve using the [damped harmonic oscillator](https://www.kvin.me/css-springs) formula
3. The spring automatically calculates its ideal duration to reach the final state
4. Works with all animation types: `ease-spring`, `enter-ease-spring`, `exit-ease-spring`, `loop-ease-spring`

## Combining Enter and Exit

You can use both enter and exit animations on the same element:

```tsx
export default function EnterExit({ tw, title }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      {/* Fade in during first 500ms, fade out during last 500ms (assuming 3s video) */}
      <h1 style={tw('text-8xl font-bold text-white enter-fade-in/0/500 exit-fade-out/2500/500')}>
        {title}
      </h1>
    </div>
  );
}
```

The opacities from multiple animations are **multiplied together**, so you get smooth transitions that combine properly.

## Staggered Animations

Create sequenced animations by offsetting start times:

```tsx
export default function StaggeredList({ tw, items }) {
  return (
    <div style={tw('flex flex-col gap-4')}>
      {/* First item: starts at 0ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/0/300')}>
        {items[0]}
      </div>

      {/* Second item: starts at 100ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/100/300')}>
        {items[1]}
      </div>

      {/* Third item: starts at 200ms, lasts 300ms */}
      <div style={tw('ease-out enter-fade-in-left/200/300')}>
        {items[2]}
      </div>
    </div>
  );
}
```

### Dynamic Staggering

For dynamic lists, calculate the timing programmatically:

```tsx
export default function DynamicStagger({ tw, items }) {
  return (
    <div style={tw('flex flex-col gap-4')}>
      {items.map((item, i) => {
        const start = i * 100;      // Each item starts 100ms later
        const duration = 300;       // Each animation lasts 300ms

        return (
          <div
            key={i}
            style={tw(`ease-out enter-fade-in-up/${start}/${duration}`)}
          >
            {item}
          </div>
        );
      })}
    </div>
  );
}
```

## Common Patterns

### Intro Sequence

```tsx
export default function IntroVideo({ tw, title, subtitle, logo }) {
  return (
    <div style={tw('flex flex-col items-center justify-center w-full h-full bg-gradient-to-br from-blue-600 to-purple-700')}>
      {/* Logo appears first */}
      <img
        src={logo}
        style={tw('h-20 mb-8 ease-out enter-scale-in/0/300')}
      />

      {/* Title bounces in */}
      <h1 style={tw('text-7xl font-bold text-white ease-out enter-bounce-in-up/200/500')}>
        {title}
      </h1>

      {/* Subtitle fades in last */}
      <p style={tw('text-2xl text-white/80 mt-4 ease-out enter-fade-in-up/400/700')}>
        {subtitle}
      </p>
    </div>
  );
}
```

### Text Reveal

```tsx
export default function TextReveal({ tw, words }) {
  return (
    <div style={tw('flex flex-wrap gap-2 justify-center')}>
      {words.split(' ').map((word, i) => (
        <span
          key={i}
          style={tw(`text-4xl font-bold ease-out enter-fade-in-up/${i * 100}/200`)}
        >
          {word}
        </span>
      ))}
    </div>
  );
}
```

### Looping Background Element

```tsx
export default function AnimatedBackground({ tw, children }) {
  return (
    <div style={tw('relative w-full h-full')}>
      {/* Floating background circles */}
      <div style={tw('absolute top-10 left-10 w-20 h-20 rounded-full bg-white/10 loop-float/2000')} />
      <div style={tw('absolute bottom-20 right-20 w-32 h-32 rounded-full bg-white/10 loop-fade/1500')} />

      {/* Main content */}
      <div style={tw('relative z-10')}>
        {children}
      </div>
    </div>
  );
}
```

### Full Enter/Exit Animation

```tsx
export default function FullAnimation({ tw, title }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      {/* Enter: starts at 0, lasts 400ms. Exit: starts at 2600ms, lasts 400ms */}
      <h1 style={tw('text-8xl font-bold text-white ease-out enter-bounce-in-up/0/400 exit-fade-out-up/2600/400')}>
        {title}
      </h1>
    </div>
  );
}
```

## Programmatic Animations

For complete control beyond animation classes, use `progress` and `frame` directly.

### Available Props

| Prop | Type | Description |
|------|------|-------------|
| `progress` | `number` | 0 to 1 through the video (0% to 100%) |
| `frame` | `number` | Current frame number (0, 1, 2, ... totalFrames-1) |

These are **only available in video templates**. Use them when animation classes aren't flexible enough.

### Using `frame`

```tsx
export default function FrameAnimation({ tw, frame, title }) {
  // Color cycling using frame number
  const hue = (frame * 5) % 360; // Cycle through colors

  // Pulsing based on frame
  const fps = 30;
  const pulse = Math.sin(frame / fps * Math.PI * 2) * 0.2 + 0.8; // 0.6 to 1.0

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-black')}>
      <h1 style={{
        ...tw('text-8xl font-bold'),
        color: `hsl(${hue}, 70%, 60%)`,
        transform: `scale(${pulse})`
      }}>
        {title}
      </h1>
    </div>
  );
}
```

### Using `progress`

```tsx
export default function ProgressAnimation({ tw, progress, title }) {
  // Custom fade based on progress
  const opacity = progress < 0.3 ? progress / 0.3 : 1;

  // Custom scale based on progress
  const scale = 0.8 + progress * 0.2; // 0.8 to 1.0

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <h1 style={{
        ...tw('text-8xl font-bold text-white'),
        opacity,
        transform: `scale(${scale})`
      }}>
        {title}
      </h1>
    </div>
  );
}
```

### Custom Easing

```tsx
export default function CustomEasing({ tw, progress, title }) {
  // Smoothstep easing
  const eased = progress * progress * (3 - 2 * progress);

  // Elastic easing
  const elastic = Math.pow(2, -10 * progress) * Math.sin((progress - 0.075) * (2 * Math.PI) / 0.3) + 1;

  return (
    <div style={tw('flex items-center justify-center w-full h-full')}>
      <h1 style={{
        ...tw('text-8xl font-bold'),
        opacity: eased,
        transform: `translateY(${(1 - elastic) * 100}px)`
      }}>
        {title}
      </h1>
    </div>
  );
}
```

### When to Use Programmatic Animations

Use `progress`/`frame` instead of animation classes when you need:
- **Custom easing functions** (elastic, bounce with specific curves beyond built-in ease-spring)
- **Color cycling or gradients** based on time
- **Mathematical animations** (sine waves, spirals, etc.)
- **Complex multi-property animations** that need precise coordination
- **Conditional logic** based on specific frame numbers

For everything else, prefer animation classes - they're simpler and more maintainable.

### Animating Along Paths

Animate elements along SVG paths with proper rotation using built-in **path helpers**:

```tsx
export default function PathFollowing({ tw, progress, path }) {
  // Follow a quadratic Bezier curve - one line!
  const rocket = path.followQuadratic(
    { x: 200, y: 400 },   // Start point
    { x: 960, y: 150 },   // Control point
    { x: 1720, y: 400 },  // End point
    progress
  );

  return (
    <div style={{ display: 'flex', ...tw('relative w-full h-full bg-gray-900') }}>
      {/* Draw the path (optional) */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 200 400 Q 960 150 1720 400"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
        />
      </svg>

      {/* Element following the path */}
      <div
        style={{
          position: "absolute",
          left: rocket.x,
          top: rocket.y,
          transform: `translate(-50%, -50%) rotate(${rocket.angle}deg)`,
          fontSize: '48px'
        }}
      >
        🚀
      </div>
    </div>
  );
}
```

### Text Path Animations

Combine `textPath` helpers with animation classes to create animated text along curves:

**Rotating text around a circle:**
```tsx
export default function RotatingCircleText({ tw, textPath, progress }) {
  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {/* Text rotates around circle using progress */}
      {textPath.onCircle(
        "SPINNING TEXT • AROUND • ",
        960,      // center x
        540,      // center y
        400,      // radius
        progress, // rotation offset (0-1 animates full rotation)
        {
          fontSize: "3xl",
          fontWeight: "bold",
          color: "yellow-300"
        }
      )}
    </div>
  );
}
```

**Animated text reveal along a path:**
```tsx
export default function PathTextReveal({ tw, textPath, progress }) {
  // Create custom path follower that animates position
  const pathFollower = (t) => {
    // Only show characters up to current progress
    const visibleProgress = progress * 1.5; // Extend range for smooth reveal
    const opacity = t < visibleProgress ? 1 : 0;

    // Follow quadratic curve
    const pos = {
      x: (1 - t) * (1 - t) * 200 + 2 * (1 - t) * t * 960 + t * t * 1720,
      y: (1 - t) * (1 - t) * 400 + 2 * (1 - t) * t * 150 + t * t * 400,
      angle: 0
    };

    return { ...pos, opacity };
  };

  return (
    <div style={tw('relative w-full h-full bg-gray-900')}>
      {textPath.onPath(
        "REVEALING TEXT",
        pathFollower,
        {
          fontSize: "4xl",
          fontWeight: "bold",
          color: "blue-300"
        }
      ).map((char, i) => (
        <div key={i} style={{ ...char.props.style, opacity: char.props.style.opacity || 1 }}>
          {char}
        </div>
      ))}
    </div>
  );
}
```

**Staggered character entrance:**
```tsx
export default function StaggeredCircleText({ tw, textPath }) {
  const text = "HELLO WORLD";

  return (
    <div style={tw('relative w-full h-full bg-slate-900')}>
      {textPath.onCircle(
        text,
        960, 540, 400, 0,
        { fontSize: "4xl", fontWeight: "bold", color: "white" }
      ).map((char, i) => {
        // Stagger fade-in: each character starts 50ms later
        const staggerDelay = i * 50;
        return (
          <div
            key={i}
            style={{
              ...char.props.style,
              ...tw(`enter-fade-in/${staggerDelay}/300 enter-scale-100/${staggerDelay}/300`)
            }}
          >
            {char.props.children}
          </div>
        );
      })}
    </div>
  );
}
```

**Text with bounce entrance along arc:**
```tsx
export default function BouncyArcText({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gradient-to-br from-purple-600 to-blue-500')}>
      {/* Draw the arc path */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 300 900 A 600 600 0 0 1 1620 900"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
          strokeDasharray="5 5"
        />
      </svg>

      {/* Text follows arc with staggered bounce */}
      {textPath.onArc(
        "BOUNCING ON ARC",
        960,  // cx
        300,  // cy
        600,  // radius
        180,  // start angle
        360,  // end angle
        { fontSize: "3xl", fontWeight: "bold", color: "white" }
      ).map((char, i) => (
        <div
          key={i}
          style={{
            ...char.props.style,
            ...tw(`ease-out enter-bounce-in-up/${i * 80}/500`)
          }}
        >
          {char.props.children}
        </div>
      ))}
    </div>
  );
}
```

**Loop animation with text on curve:**
```tsx
export default function LoopingCurveText({ tw, textPath, frame }) {
  // Calculate wave effect using frame
  const waveOffset = Math.sin(frame / 30 * Math.PI * 2) * 0.1;

  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {textPath.onQuadratic(
        "WAVY TEXT",
        { x: 200, y: 400 },
        { x: 960, y: 150 },
        { x: 1720, y: 400 },
        { fontSize: "4xl", fontWeight: "bold", color: "pink-300" }
      ).map((char, i) => (
        <div
          key={i}
          style={{
            ...char.props.style,
            transform: `${char.props.style.transform} translateY(${Math.sin((i + frame) / 5) * 10}px)`
          }}
        >
          {char.props.children}
        </div>
      ))}
    </div>
  );
}
```

**Tips for animating text paths:**
1. **Use `progress` for smooth rotation** on circles and arcs
2. **Map over returned characters** to apply individual animations
3. **Combine with animation classes** like `enter-fade-in`, `enter-bounce-in`, etc.
4. **Stagger character animations** by calculating delays: `i * delayMs`
5. **Use `frame` for continuous effects** like waves or pulsing
6. **Preserve the original transform** when adding animations: `transform: '${char.props.style.transform} ...'`

**Common path types:**

**Quadratic Bezier** (Q command):
```tsx
// Position: (1-t)²·P0 + 2(1-t)t·P1 + t²·P2
function pointOnQuadraticBezier(p0, p1, p2, t) {
  const x = (1 - t) * (1 - t) * p0.x + 2 * (1 - t) * t * p1.x + t * t * p2.x;
  const y = (1 - t) * (1 - t) * p0.y + 2 * (1 - t) * t * p1.y + t * t * p2.y;
  return { x, y };
}

// Tangent angle
function angleOnQuadraticBezier(p0, p1, p2, t) {
  const dx = 2 * (1 - t) * (p1.x - p0.x) + 2 * t * (p2.x - p1.x);
  const dy = 2 * (1 - t) * (p1.y - p0.y) + 2 * t * (p2.y - p1.y);
  return Math.atan2(dy, dx) * (180 / Math.PI);
}
```

**Cubic Bezier** (C command):
```tsx
// Position: (1-t)³·P0 + 3(1-t)²t·P1 + 3(1-t)t²·P2 + t³·P3
function pointOnCubicBezier(p0, p1, p2, p3, t) {
  const mt = 1 - t;
  const mt2 = mt * mt;
  const mt3 = mt2 * mt;
  const t2 = t * t;
  const t3 = t2 * t;
  const x = mt3 * p0.x + 3 * mt2 * t * p1.x + 3 * mt * t2 * p2.x + t3 * p3.x;
  const y = mt3 * p0.y + 3 * mt2 * t * p1.y + 3 * mt * t2 * p2.y + t3 * p3.y;
  return { x, y };
}

// Tangent angle
function angleOnCubicBezier(p0, p1, p2, p3, t) {
  const mt = 1 - t;
  const mt2 = mt * mt;
  const t2 = t * t;
  const dx = -3 * mt2 * p0.x + 3 * mt2 * p1.x - 6 * mt * t * p1.x - 3 * t2 * p2.x + 6 * mt * t * p2.x + 3 * t2 * p3.x;
  const dy = -3 * mt2 * p0.y + 3 * mt2 * p1.y - 6 * mt * t * p1.y - 3 * t2 * p2.y + 6 * mt * t * p2.y + 3 * t2 * p3.y;
  return Math.atan2(dy, dx) * (180 / Math.PI);
}
```

**Circle**:
```tsx
function pointOnCircle(cx, cy, radius, angleRadians) {
  return {
    x: cx + radius * Math.cos(angleRadians),
    y: cy + radius * Math.sin(angleRadians)
  };
}

// Usage
const angleRadians = progress * Math.PI * 2;
const pos = pointOnCircle(300, 300, 100, angleRadians);
const tangentAngle = (angleRadians * 180 / Math.PI) + 90; // Tangent is perpendicular
```

**Tips:**
- Use `progress` (0-1) for smooth animation
- The `translate(-50%, -50%)` centers the element on the path
- Combine rotation with the translate: `translate(-50%, -50%) rotate(${angle}deg)`
- For text following a path, you can animate individual characters at different progress values

## SVG Stroke Animations

Animate SVG path strokes with the **stroke-dash** classes, perfect for drawing or erasing line art, icons, and illustrations.

### How It Works

SVG stroke animations use `strokeDasharray` and `strokeDashoffset` CSS properties to create drawing effects:

1. **Enter animations** - Draw the stroke from start to finish
2. **Exit animations** - Erase the stroke from finish to start
3. **Loop animations** - Continuously draw and erase

### Format

All stroke-dash animations require the **path length** in brackets:

```tsx
enter-stroke-dash-[length]/start/duration
exit-stroke-dash-[length]/start/duration
loop-stroke-dash-[length]/duration
```

### Basic Examples

```tsx
export default function SVGAnimation({ tw }) {
  return (
    <svg width="400" height="200" viewBox="0 0 400 200">
      {/* Draw a curve over 1 second */}
      <path
        d="M10 150 Q 95 10 180 150"
        stroke="black"
        strokeWidth={4}
        fill="none"
        style={tw('enter-stroke-dash-[300]/0/1000')}
      />
    </svg>
  );
}
```

### Enter Animations (Drawing)

Draw strokes from 0% to 100%:

```tsx
// Draw a 300px path over 1 second
<path style={tw('enter-stroke-dash-[300]/0/1000')} />

// Draw with spring easing
<path style={tw('ease-spring enter-stroke-dash-[500]/0/1500')} />

// Stagger multiple paths
<path style={tw('enter-stroke-dash-[200]/0/600')} />
<path style={tw('enter-stroke-dash-[200]/200/600')} />
<path style={tw('enter-stroke-dash-[200]/400/600')} />
```

### Exit Animations (Erasing)

Erase strokes from 100% to 0%:

```tsx
// Erase starting at 2000ms, lasting 500ms
<path style={tw('exit-stroke-dash-[300]/2000/500')} />

// Draw then erase the same path
<path style={tw('enter-stroke-dash-[400]/0/800 exit-stroke-dash-[400]/2200/800')} />
```

### Loop Animations

Continuously draw and erase:

```tsx
// Loop every 2 seconds (draws in first half, erases in second half)
<path style={tw('loop-stroke-dash-[300]/2000')} />

// Faster loop
<path style={tw('loop-stroke-dash-[200]/1000')} />
```

### Getting Path Length

To find the path length for your SVG:

```tsx
// In browser console or component:
const path = document.querySelector('path');
const length = path.getTotalLength();
console.log(length); // e.g., 347.89
```

Then use that value:

```tsx
<path style={tw('enter-stroke-dash-[347.89]/0/1000')} />
```

### Complete Example

```tsx
export default function DrawingEffect({ tw }) {
  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <svg width="600" height="400" viewBox="0 0 600 400">
        {/* Checkmark icon drawn in sequence */}
        <path
          d="M100 200 L 200 300 L 400 100"
          stroke="#10b981"
          strokeWidth={8}
          fill="none"
          strokeLinecap="round"
          strokeLinejoin="round"
          style={tw('ease-out enter-stroke-dash-[600]/0/1200')}
        />

        {/* Circle drawn after checkmark */}
        <circle
          cx="250"
          cy="200"
          r="150"
          stroke="#10b981"
          strokeWidth={6}
          fill="none"
          style={tw('ease-out enter-stroke-dash-[942]/1000/1000')}
        />
      </svg>
    </div>
  );
}
```

### Combining with Other Animations

Stroke animations work alongside other animation classes:

```tsx
// Fade in while drawing
<path style={tw('enter-stroke-dash-[300]/0/1000 enter-fade-in/0/1000')} />

// Draw with pulsing color
<svg>
  <path
    stroke="url(#gradient)"
    style={tw('enter-stroke-dash-[500]/0/1500')}
  />
  <defs>
    <linearGradient id="gradient">
      <stop offset="0%" stopColor="#8b5cf6" />
      <stop offset="100%" stopColor="#ec4899" />
    </linearGradient>
  </defs>
</svg>
```

### Animated Dashed Strokes (Marching Ants)

For **marching ants** or **animated dashed patterns**, use `frame` or `progress` directly instead of animation classes:

```tsx
export default function MarchingAnts({ tw, frame }) {
  // Calculate animated offset (loops every 30 frames)
  const dashOffset = -(frame % 30) * 2;

  return (
    <div style={tw('flex items-center justify-center w-full h-full bg-gray-900')}>
      <svg width="600" height="400" viewBox="0 0 600 400">
        {/* Marching ants border */}
        <rect
          x="50"
          y="50"
          width="500"
          height="300"
          fill="none"
          stroke="#3b82f6"
          strokeWidth={3}
          strokeDasharray="10 5"
          strokeDashoffset={dashOffset}
        />

        {/* Animated circle with different speed */}
        <circle
          cx="300"
          cy="200"
          r="80"
          fill="none"
          stroke="#10b981"
          strokeWidth={4}
          strokeDasharray="15 8"
          strokeDashoffset={dashOffset * 1.5}
        />
      </svg>
    </div>
  );
}
```

**Tips:**
- `strokeDasharray="10 5"` - 10px dash, 5px gap
- `strokeDashoffset={dashOffset}` - animates the pattern position
- Negative offset moves forward, positive moves backward
- Different speeds: multiply by different values (e.g., `dashOffset * 2`)

This technique is different from `stroke-dash` classes:
- **`stroke-dash` classes** - Draw/erase the stroke (reveal animation)
- **Marching ants** - Move a dashed pattern along the stroke

## Performance Tips

1. **Use Tailwind classes** when possible - they're optimized for the renderer
2. **Avoid too many nested animations** - each adds computation per frame
3. **Use loop animations sparingly** - they're computed every frame
4. **Prefer opacity and transform** - they're the most performant properties

## Next Steps

- [Templates](/templates) - Creating image and video templates
- [Helpers](/helpers) - QR codes, images, and more


# Template Helpers

Additional helpers for creating powerful, composable templates.

## Overview

Beyond the basics, loopwind provides:
- `template()` - Compose templates together
- `qr()` - Generate QR codes on the fly
- `config` - Access user configuration

For image embedding, see the [Images](/images) page.

## 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 `.loopwind/loopwind.json` using the `config` prop:

```tsx
export default function BrandedTemplate({ tw, config, title }) {
  // Access custom colors from loopwind.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 `.loopwind/loopwind.json`:**
```json title=".loopwind/loopwind.json"
{
  "colors": {
    "brand": "#ff6b6b"
  },
  "fonts": {
    "sans": ["Inter", "system-ui", "sans-serif"]
  }
}
```

This allows templates to adapt to user preferences and brand guidelines.

## Text on Path

Render text along curves, circles, and custom paths with automatic character positioning and rotation.

### Usage

```tsx
export default function CircleText({ tw, textPath, message }) {
  return (
    <div style={tw('relative w-full h-full bg-slate-900')}>
      {textPath.onCircle(
        message,
        960,  // center x
        540,  // center y
        400,  // radius
        0,    // rotation offset (0-1)
        {
          fontSize: "4xl",
          fontWeight: "bold",
          color: "white",
          letterSpacing: 0.05
        }
      )}
    </div>
  );
}
```

### Available Functions

All `textPath` functions return an array of positioned character elements:

**`textPath.onCircle(text, cx, cy, radius, offset, options?)`**
```tsx
// Text around a circle
textPath.onCircle("HELLO WORLD", 960, 540, 400, 0, {
  fontSize: "4xl",
  color: "white"
})
```

**`textPath.onPath(text, pathFollower, options?)`**
```tsx
// Text along any custom path
textPath.onPath("CUSTOM PATH", (t) => ({
  x: 100 + t * 800,
  y: 200 + Math.sin(t * Math.PI) * 100,
  angle: Math.cos(t * Math.PI) * 20
}), {
  fontSize: "2xl",
  fontWeight: "semibold"
})
```

**`textPath.onQuadratic(text, p0, p1, p2, options?)`**
```tsx
// Text along a quadratic Bezier curve
textPath.onQuadratic(
  "CURVED TEXT",
  { x: 200, y: 400 },   // start
  { x: 960, y: 100 },   // control point
  { x: 1720, y: 400 },  // end
  { fontSize: "3xl", color: "blue-300" }
)
```

**`textPath.onCubic(text, p0, p1, p2, p3, options?)`**
```tsx
// Text along a cubic Bezier curve
textPath.onCubic(
  "S-CURVE",
  { x: 200, y: 600 },   // start
  { x: 600, y: 400 },   // control 1
  { x: 1320, y: 800 },  // control 2
  { x: 1720, y: 600 },  // end
  { fontSize: "3xl", color: "purple-300" }
)
```

**`textPath.onArc(text, cx, cy, radius, startAngle, endAngle, options?)`**
```tsx
// Text along a circular arc
textPath.onArc(
  "ARC TEXT",
  960,   // center x
  540,   // center y
  400,   // radius
  0,     // start angle (degrees)
  180,   // end angle (degrees)
  { fontSize: "2xl", color: "pink-300" }
)
```

### Options

All `textPath` functions accept an optional `options` object:

```typescript
{
  fontSize?: string;      // Tailwind size: "xl", "2xl", "4xl", etc.
  fontWeight?: string;    // Tailwind weight: "bold", "semibold", etc.
  color?: string;         // Tailwind color: "white", "blue-500", etc.
  letterSpacing?: number; // Space between characters (0-1, default: 0)
  style?: any;           // Additional inline styles
}
```

### Examples

**Animated rotating text:**
```tsx
export default function RotatingText({ tw, textPath, progress }) {
  return (
    <div style={tw('relative w-full h-full bg-black')}>
      {textPath.onCircle(
        "SPINNING • TEXT • ",
        960, 540, 400,
        progress,  // Rotate based on video progress
        { fontSize: "3xl", color: "yellow-300" }
      )}
    </div>
  );
}
```

**Multiple text paths:**
```tsx
export default function MultiPath({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gradient-to-br from-slate-900 to-slate-700')}>
      {/* Text on outer circle */}
      {textPath.onCircle(
        "OUTER RING",
        960, 540, 500, 0,
        { fontSize: "5xl", fontWeight: "bold", color: "white" }
      )}

      {/* Text on inner circle */}
      {textPath.onCircle(
        "inner ring",
        960, 540, 300, 0.5,  // offset by 50% for rotation
        { fontSize: "2xl", color: "white/60" }
      )}
    </div>
  );
}
```

**Text following a drawn path:**
```tsx
export default function PathText({ tw, textPath }) {
  return (
    <div style={tw('relative w-full h-full bg-gray-900')}>
      {/* Draw the path */}
      <svg width="1920" height="1080" style={{ position: 'absolute' }}>
        <path
          d="M 200 400 Q 960 150 1720 400"
          stroke="rgba(255,255,255,0.2)"
          strokeWidth={2}
          fill="none"
        />
      </svg>

      {/* Text following the path */}
      {textPath.onQuadratic(
        "FOLLOWING THE CURVE",
        { x: 200, y: 400 },
        { x: 960, y: 150 },
        { x: 1720, y: 400 },
        { fontSize: "3xl", fontWeight: "bold", color: "blue-300" }
      )}
    </div>
  );
}
```

For animated text paths, see [Text Path Animations](/animation#text-path-animations).

## Reserved Prop Names

The following prop names are **reserved** and cannot be used in your template's `meta.props`:

- `tw`, `qr`, `image`, `template` - Core helpers
- `path`, `textPath` - Path and text helpers
- `config`, `frame`, `progress` - System props

**Why?** These names are used for loopwind's built-in helpers. Using them as prop names would cause conflicts.

**Example:**
```tsx
// ❌ BAD - 'image' is reserved
export const meta = {
  props: {
    title: "string",
    image: "string"  // Error!
  }
};

// ✅ GOOD - Use descriptive alternatives
export const meta = {
  props: {
    title: "string",
    imageUrl: "string",    // or imageSrc, photoUrl, etc.
    logoUrl: "string"
  }
};
```

If you try to use a reserved name, you'll get a helpful error:
```
Template uses reserved prop names: image

Try renaming: "image" → "imageUrl" or "imageSrc"

Reserved names: tw, qr, image, template, path, textPath, config, frame, progress
```

## All Props Reference

Every template receives these props:

```tsx
export default function MyTemplate({
  // Core helpers (RESERVED - cannot be used as prop names)
  tw,        // Tailwind class converter
  qr,        // QR code generator (this page)
  template,  // Template composer (this page)
  config,    // User config from loopwind.json (this page)
  textPath,  // Text on path helpers (this page)

  // Media helpers (RESERVED)
  image,     // Image embedder → see /images
  path,      // Path following → see /animation

  // Video-specific (RESERVED - only in video templates)
  frame,     // Current frame number → see /templates
  progress,  // Animation progress 0-1 → see /templates

  // Your custom props (use any names EXCEPT the reserved ones above)
  ...props   // Any props from your meta.props
}) {
  // Your template code
}
```

## Next Steps

- [Embedding Images](/images)
- [Templates](/templates)
- [Styling with Tailwind & shadcn/ui](/styling)
- [Custom Fonts](/fonts)



# 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

loopwind 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 defined in `.loopwind/loopwind.json`:

```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

You can override the default shadcn colors or add your own custom colors in `.loopwind/loopwind.json`:

```json title=".loopwind/loopwind.json"
{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "primary-foreground": "#ffffff",
      "accent": "#10b981",
      "brand": "#ff6b6b"
    }
  }
}
```

Then use these custom colors in your templates:

```tsx
tw('text-brand')    // Uses your custom brand color
tw('bg-primary')    // Uses your custom primary color
tw('bg-accent')     // Uses your custom accent color
```

## Auto-Detection from tailwind.config.js

loopwind automatically detects and loads your project's Tailwind configuration:

```
your-project/
├── tailwind.config.js  ← Automatically detected
└── .loopwind/
    ├── loopwind.json
    └── 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)
- [Templates](/templates)
- [Embedding Images](/images)



# Font Handling in loopwind

The recommended way to use fonts is through `loopwind.json` - configure fonts once, use everywhere.

## Using Fonts from loopwind.json (Recommended)

Configure fonts in your `.loopwind/loopwind.json` and use Tailwind classes in templates.

### Simple Setup

Define font families in `.loopwind/loopwind.json` without loading custom fonts (uses system fonts):

```json title=".loopwind/loopwind.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 loopwind.json */}
      <h1 style={tw('font-sans text-6xl font-bold')}>
        {title}
      </h1>

      {/* Uses fonts.mono from loopwind.json */}
      <code style={tw('font-mono text-sm')}>
        {code}
      </code>
    </div>
  );
}
```

**Result:** Uses system fonts, falls back to Inter for rendering.

### Complete Setup (With Font Files)

Load custom font files for brand-specific typography in `.loopwind/loopwind.json`:

```json title=".loopwind/loopwind.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/
├── .loopwind/
│   ├── loopwind.json
│   └── templates/
└── fonts/
    ├── Inter-Regular.woff
    ├── Inter-Bold.woff
    └── JetBrainsMono-Regular.woff
```

**Template usage (same as before):**
```tsx
<h1 style={tw('font-sans font-bold')}>
  {/* Uses Inter Bold from loopwind.json */}
  {title}
</h1>
```

**Available classes:**
- `font-sans` - Uses `fonts.sans` from loopwind.json
- `font-serif` - Uses `fonts.serif` from loopwind.json
- `font-mono` - Uses `fonts.mono` from loopwind.json

**Supported formats:**
- ✅ **WOFF** (`.woff`) - Recommended for best compatibility
- ✅ **TTF** (`.ttf`) - Also supported
- ✅ **OTF** (`.otf`) - Also supported
- ❌ **WOFF2** (`.woff2`) - Not supported by renderer

## Font Loading Priority

loopwind loads fonts in this order:

1. **loopwind.json fonts** (if configured with `files`)
2. **Bundled Inter fonts** (included with CLI)

This ensures fonts work out of the box with no configuration.

## Default Fonts

If no fonts are configured, loopwind uses **Inter** (Regular 400, Bold 700) which is bundled with the CLI. This means fonts work offline with no configuration required.

## Best Practices

1. ✅ **Use loopwind.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 `loopwind.json` location

## Examples

### Minimal Setup (System Fonts)
```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": ["Inter", "-apple-system", "sans-serif"]
  }
}
```
Uses system Inter if available, falls back to Noto Sans for rendering.

### Brand Fonts Setup
```json title=".loopwind/loopwind.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 title=".loopwind/loopwind.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.

### External Font URLs
Load fonts directly from CDNs without downloading files:

```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-400-normal.woff",
          "weight": 400
        },
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-700-normal.woff",
          "weight": 700
        }
      ]
    }
  }
}
```

You can also mix local and external fonts:

```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-700-normal.woff",
          "weight": 700
        }
      ]
    }
  }
}
```

**Note:** Use WOFF format (`.woff`) for best compatibility. WOFF2 is not supported by the underlying renderer.

## 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)
- [Templates](/templates)
- [Embedding Images](/images)


# loopwind.json

Configure colors and fonts for all your templates in `.loopwind/loopwind.json`.

## File Location

```
your-project/
├── .loopwind/
│   ├── loopwind.json     ← Configuration file
│   └── templates/
```

## Minimal Example

```json title=".loopwind/loopwind.json"
{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "background": "#ffffff"
    }
  }
}
```

## Theme Colors

### Default shadcn/ui Palette

```json title=".loopwind/loopwind.json"
{
  "theme": {
    "colors": {
      "primary": "#18181b",
      "primary-foreground": "#fafafa",
      
      "secondary": "#f4f4f5",
      "secondary-foreground": "#18181b",
      
      "background": "#ffffff",
      "foreground": "#09090b",
      
      "muted": "#f4f4f5",
      "muted-foreground": "#71717a",
      
      "accent": "#f4f4f5",
      "accent-foreground": "#18181b",
      
      "destructive": "#ef4444",
      "destructive-foreground": "#fafafa",
      
      "border": "#e4e4e7",
      "input": "#e4e4e7",
      "ring": "#18181b",
      
      "card": "#ffffff",
      "card-foreground": "#09090b"
    }
  }
}
```

### Custom Colors

```json title=".loopwind/loopwind.json"
{
  "theme": {
    "colors": {
      "primary": "#3b82f6",
      "brand": "#ff6b6b",
      "success": "#22c55e",
      "warning": "#f59e0b"
    }
  }
}
```

**Use in templates:**

```tsx
tw('text-brand')      // #ff6b6b
tw('bg-success')      // #22c55e
tw('border-warning')  // #f59e0b
```

## Fonts

### Simple (System Fonts)

```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": ["Inter", "system-ui", "sans-serif"],
    "serif": ["Georgia", "serif"],
    "mono": ["Courier New", "monospace"]
  }
}
```

### With Font Files

```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": {
      "family": ["Inter", "system-ui", "sans-serif"],
      "files": [
        { "path": "./fonts/Inter-Regular.woff", "weight": 400 },
        { "path": "./fonts/Inter-Bold.woff", "weight": 700 }
      ]
    }
  }
}
```

Paths are relative to `loopwind.json`.

**Supported formats:**
- ✅ WOFF (`.woff`)
- ✅ TTF (`.ttf`)
- ✅ OTF (`.otf`)
- ❌ WOFF2 (`.woff2`)

### External URLs

```json title=".loopwind/loopwind.json"
{
  "fonts": {
    "sans": {
      "family": ["Inter", "sans-serif"],
      "files": [
        {
          "path": "https://unpkg.com/@fontsource/inter@5.0.18/files/inter-latin-400-normal.woff",
          "weight": 400
        }
      ]
    }
  }
}
```

## Complete Example

```json title=".loopwind/loopwind.json"
{
  "theme": {
    "colors": {
      "primary": "#6366f1",
      "primary-foreground": "#ffffff",
      "background": "#ffffff",
      "foreground": "#0f172a",
      "muted": "#f1f5f9",
      "muted-foreground": "#64748b",
      "border": "#e2e8f0",
      "card": "#ffffff",
      "brand": "#8b5cf6"
    }
  },
  "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 }
      ]
    }
  }
}
```

## Schema

```typescript
{
  "theme"?: {
    "colors"?: {
      [name: string]: string;  // Hex color
    }
  },
  "fonts"?: {
    [class: string]: string[] | {
      family: string[];
      files: Array<{
        path: string;    // Local or URL
        weight: number;  // 100-900
      }>;
    }
  }
}
```

## Auto-Detection

If no `loopwind.json` exists, loopwind auto-detects `tailwind.config.js`:

```
your-project/
├── tailwind.config.js  ← Auto-detected
└── .loopwind/
    └── templates/
```

**Priority:**
1. `.loopwind/loopwind.json`
2. `tailwind.config.js`
3. Built-in defaults

## Next Steps

- [Styling](/styling) - Use colors in templates
- [Fonts](/fonts) - Font configuration details
- [Getting Started](/getting-started) - Setup guide