Initial commit

.claude-plugin/plugin.json

@@ -0,0 +1,14 @@
+{
+  "name": "tailwind-4",
+  "description": "Tailwind CSS v4 patterns: CSS-first config, oklch colors, container queries, @utility directive",
+  "version": "1.0.0",
+  "author": {
+    "name": "Design Session with Claude Code"
+  },
+  "skills": [
+    "./skills"
+  ],
+  "hooks": [
+    "./hooks"
+  ]
+}

README.md

@@ -0,0 +1,3 @@
+# tailwind-4
+
+Tailwind CSS v4 patterns: CSS-first config, oklch colors, container queries, @utility directive

hooks/hooks.json

@@ -0,0 +1,53 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/init-session.sh",
+            "timeout": 1000,
+            "description": "Initialize session state for skill recommendations"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "Read|Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/recommend-skills.sh",
+            "timeout": 1000,
+            "description": "Recommend relevant Tailwind v4 skills based on file patterns"
+          }
+        ]
+      },
+      {
+        "matcher": "Write",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-config.sh",
+            "timeout": 1000,
+            "description": "Block deprecated tailwind.config.js files in Tailwind v4"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "Write|Edit",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "${CLAUDE_PLUGIN_ROOT}/scripts/validate-tailwind-v4.sh",
+            "timeout": 5000,
+            "description": "Validate Tailwind v4 patterns and suggest fixes"
+          }
+        ]
+      }
+    ]
+  }
+}

plugin.lock.json

@@ -0,0 +1,105 @@
+{
+  "$schema": "internal://schemas/plugin.lock.v1.json",
+  "pluginId": "gh:djankies/claude-configs:tailwind-4",
+  "normalized": {
+    "repo": null,
+    "ref": "refs/tags/v20251128.0",
+    "commit": "a18d0811809f9a00e5fae6a690f1553fa0797c12",
+    "treeHash": "419af0c5882d739b7013b72a661c8eaa04711332393cec717af929d0415fa41e",
+    "generatedAt": "2025-11-28T10:16:30.280280Z",
+    "toolVersion": "publish_plugins.py@0.2.0"
+  },
+  "origin": {
+    "remote": "git@github.com:zhongweili/42plugin-data.git",
+    "branch": "master",
+    "commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
+    "repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
+  },
+  "manifest": {
+    "name": "tailwind-4",
+    "description": "Tailwind CSS v4 patterns: CSS-first config, oklch colors, container queries, @utility directive",
+    "version": "1.0.0"
+  },
+  "content": {
+    "files": [
+      {
+        "path": "README.md",
+        "sha256": "42897bffbfaaa4c3744b9f69c419a63cc9104cbe8fb51f60b722d54693a7cab8"
+      },
+      {
+        "path": "hooks/hooks.json",
+        "sha256": "4c256357ff8ec095214f0d311e54557a5af20e572cf5e2c7395070bf213d08ee"
+      },
+      {
+        "path": ".claude-plugin/plugin.json",
+        "sha256": "84d2c0695cd1940d7686789c2e894a370968d3981f51f5cd6f458cb056137b1c"
+      },
+      {
+        "path": "skills/creating-custom-utilities/SKILL.md",
+        "sha256": "db188b2620c91f8cd8a92a580c42120b96b0e0cbc33146e59d2ab82aee17035a"
+      },
+      {
+        "path": "skills/configuring-tailwind-v4/SKILL.md",
+        "sha256": "c069b146429ebe7e68e76b535a8effcdc10ed3a357550049abf0fd71f9fc29ee"
+      },
+      {
+        "path": "skills/configuring-tailwind-v4/references/nextjs-setup.md",
+        "sha256": "59755429d76eee68d51c560c640d7a623ed30f9099ba2bc666c94c44764272fd"
+      },
+      {
+        "path": "skills/configuring-tailwind-v4/references/vite-setup.md",
+        "sha256": "b31177502b1a96edb7aed256da05fc5bf11b265a314c9cf4d19d739ad51ecbde"
+      },
+      {
+        "path": "skills/configuring-tailwind-v4/references/postcss-setup.md",
+        "sha256": "3f847c3161b86d3032b2ee47ad4a5ec498efe4340f6d1ad99b5a363e0cc7a36a"
+      },
+      {
+        "path": "skills/using-theme-variables/SKILL.md",
+        "sha256": "7327b3f4d6058aa6d87bad4477d2c5e765311acb61523ab72342f3c84c99b6d7"
+      },
+      {
+        "path": "skills/using-theme-variables/references/namespace-reference.md",
+        "sha256": "aa3492dbeccaebc4538cef607f66c7d771b17506220fc65b6a4e31d6d7416022"
+      },
+      {
+        "path": "skills/using-theme-variables/references/color-conversion.md",
+        "sha256": "96531fadf4315046a15c72f8b6fa8070c106f8337eef86faeaac636208489729"
+      },
+      {
+        "path": "skills/reviewing-tailwind-patterns/SKILL.md",
+        "sha256": "d0c41d56b526381efa56a70a7e705376293ef9d58f7c93340a4d6bb2335329d9"
+      },
+      {
+        "path": "skills/handling-animations/SKILL.md",
+        "sha256": "ad5cd945e64c2d56d44d138a5cc03c15a12166d4a9f1fd603c74bdd4ab4520e0"
+      },
+      {
+        "path": "skills/handling-animations/references/animation-library.md",
+        "sha256": "905656e759fdfaa31f68476fd9ef0c3ce04385f8fcb22072fd71361013b63614"
+      },
+      {
+        "path": "skills/migrating-from-v3/SKILL.md",
+        "sha256": "2bf2744e271aa40308d3da5a674ece7678bb9f73bd0f29890dbeb01b4261b13b"
+      },
+      {
+        "path": "skills/migrating-from-v3/references/breaking-changes.md",
+        "sha256": "f454d4a08774a9297cb7761813ba3c8461e8f2a90bae5d7c1d78262c94f555ed"
+      },
+      {
+        "path": "skills/migrating-from-v3/references/migration-checklist.md",
+        "sha256": "723ff5da73470dc53739d73fe285139e13592e7e157366900941b9e14774990a"
+      },
+      {
+        "path": "skills/using-container-queries/SKILL.md",
+        "sha256": "3bd3d9092809a8c503f80da51f64489e60215c4f63fa6da3d81f271d5e24d58c"
+      }
+    ],
+    "dirSha256": "419af0c5882d739b7013b72a661c8eaa04711332393cec717af929d0415fa41e"
+  },
+  "security": {
+    "scannedAt": null,
+    "scannerVersion": null,
+    "flags": []
+  }
+}

skills/configuring-tailwind-v4/SKILL.md

@@ -0,0 +1,172 @@
+---
+name: configuring-tailwind-v4
+description: Configure Tailwind CSS v4 using Vite plugin, PostCSS, or CLI with CSS-first configuration via @import and @theme directives. Use when setting up new projects or migrating build tools.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Configuring Tailwind v4
+
+## Purpose
+
+Configure Tailwind CSS v4 using modern CSS-first configuration. Tailwind v4 eliminates JavaScript configuration files in favor of CSS-based setup using `@import` and `@theme` directives.
+
+## Installation Methods
+
+### Vite Projects (Recommended)
+
+**Step 1: Install Dependencies**
+
+```bash
+npm install tailwindcss @tailwindcss/vite
+```
+
+**Step 2: Configure Vite Plugin**
+
+Add the Tailwind plugin to `vite.config.js`:
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+**Step 3: Import Tailwind in CSS**
+
+Create or update your main CSS file (e.g., `src/index.css`):
+
+```css
+@import 'tailwindcss';
+```
+
+### PostCSS Projects
+
+**Step 1: Install Dependencies**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**Step 2: Configure PostCSS**
+
+Create `postcss.config.js`:
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**Step 3: Import Tailwind in CSS**
+
+```css
+@import 'tailwindcss';
+```
+
+### CLI Usage
+
+**Step 1: Install CLI**
+
+```bash
+npm install tailwindcss @tailwindcss/cli
+```
+
+**Step 2: Create Input CSS**
+
+```css
+@import 'tailwindcss';
+```
+
+**Step 3: Run Build Command**
+
+```bash
+npx @tailwindcss/cli -i input.css -o output.css --watch
+```
+
+## CSS-First Configuration
+
+Tailwind v4 uses the `@theme` directive for all customization:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-display: 'Satoshi', 'sans-serif';
+  --font-body: 'Inter', 'sans-serif';
+
+  --color-brand-primary: oklch(0.65 0.25 270);
+  --color-brand-accent: oklch(0.75 0.22 320);
+
+  --breakpoint-3xl: 120rem;
+  --breakpoint-4xl: 160rem;
+
+  --spacing-18: 4.5rem;
+  --spacing-72: 18rem;
+
+  --radius-4xl: 2rem;
+
+  --shadow-brutal: 8px 8px 0 0 rgb(0 0 0);
+}
+```
+
+## Automatic Content Detection
+
+Template files are discovered automatically using built-in heuristics. No content array configuration required. Files in `.gitignore` are automatically excluded.
+
+**Manual Source Control (when needed):**
+
+```css
+@import 'tailwindcss';
+
+@source "../node_modules/@my-company/ui-lib";
+@source "./legacy-components";
+```
+
+**Exclude paths:**
+
+```css
+@source not "./legacy";
+@source not "./docs";
+```
+
+**Disable automatic detection:**
+
+```css
+@import 'tailwindcss' source(none);
+@source "./src";
+```
+
+## Key Differences from v3
+
+| v3 | v4 |
+|---|---|
+| `tailwind.config.js` | CSS `@theme` directive |
+| `@tailwind base;` | `@import 'tailwindcss';` |
+| `content: []` array | Automatic detection |
+| `postcss-tailwindcss` | `@tailwindcss/postcss` |
+
+## Performance
+
+- Full builds: **3.78x faster** than v3
+- Incremental rebuilds with new CSS: **8.8x faster**
+- Incremental rebuilds without new CSS: **182x faster**
+
+## Browser Requirements
+
+Tailwind v4 requires:
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+
+Projects requiring older browser support must stay on v3.4.
+
+## See Also
+
+- references/vite-setup.md - Complete Vite configuration examples
+- references/postcss-setup.md - PostCSS configuration patterns
+- references/nextjs-setup.md - Next.js specific setup

skills/configuring-tailwind-v4/references/nextjs-setup.md

@@ -0,0 +1,373 @@
+# Next.js Setup Guide
+
+## Next.js 15+ with App Router
+
+**Install dependencies:**
+
+```bash
+npx create-next-app@latest my-app
+cd my-app
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**app/globals.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+}
+```
+
+**app/layout.tsx:**
+
+```typescript
+import type { Metadata } from 'next';
+import { Geist, Geist_Mono } from 'next/font/google';
+import './globals.css';
+
+const geistSans = Geist({
+  variable: '--font-geist-sans',
+  subsets: ['latin'],
+});
+
+const geistMono = Geist_Mono({
+  variable: '--font-geist-mono',
+  subsets: ['latin'],
+});
+
+export const metadata: Metadata = {
+  title: 'My App',
+  description: 'Built with Next.js and Tailwind CSS v4',
+};
+
+export default function RootLayout({
+  children,
+}: Readonly<{
+  children: React.ReactNode;
+}>) {
+  return (
+    <html lang="en">
+      <body className={`${geistSans.variable} ${geistMono.variable} antialiased`}>
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+**app/page.tsx:**
+
+```typescript
+export default function Home() {
+  return (
+    <main className="flex min-h-screen flex-col items-center justify-center p-24">
+      <h1 className="text-4xl font-bold text-primary">
+        Next.js + Tailwind v4
+      </h1>
+      <p className="mt-4 text-lg text-gray-600 dark:text-gray-300">
+        CSS-first configuration with @theme directive
+      </p>
+    </main>
+  );
+}
+```
+
+## Pages Router Setup
+
+**pages/_app.tsx:**
+
+```typescript
+import type { AppProps } from 'next/app';
+import '@/styles/globals.css';
+
+export default function App({ Component, pageProps }: AppProps) {
+  return <Component {...pageProps} />;
+}
+```
+
+**styles/globals.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+**pages/index.tsx:**
+
+```typescript
+export default function Home() {
+  return (
+    <div className="flex min-h-screen items-center justify-center">
+      <h1 className="text-4xl font-bold text-primary">
+        Next.js Pages Router + Tailwind v4
+      </h1>
+    </div>
+  );
+}
+```
+
+## Dark Mode Setup
+
+**app/layout.tsx:**
+
+```typescript
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" className="dark">
+      <body className="bg-white dark:bg-gray-900 text-gray-900 dark:text-white">
+        {children}
+      </body>
+    </html>
+  );
+}
+```
+
+**Dynamic dark mode with next-themes:**
+
+```bash
+npm install next-themes
+```
+
+**app/providers.tsx:**
+
+```typescript
+'use client';
+
+import { ThemeProvider } from 'next-themes';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return (
+    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+      {children}
+    </ThemeProvider>
+  );
+}
+```
+
+**app/layout.tsx:**
+
+```typescript
+import { Providers } from './providers';
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+## Component Library Integration
+
+**Shared theme across apps:**
+
+**packages/ui/theme.css:**
+
+```css
+@theme {
+  --*: initial;
+
+  --font-sans: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+  --color-success: oklch(0.72 0.15 142);
+  --color-warning: oklch(0.78 0.18 60);
+  --color-error: oklch(0.65 0.22 25);
+}
+```
+
+**apps/web/app/globals.css:**
+
+```css
+@import 'tailwindcss';
+@import '@my-company/ui/theme.css';
+```
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+## TypeScript Component Example
+
+**components/Button.tsx:**
+
+```typescript
+import { ButtonHTMLAttributes, forwardRef } from 'react';
+
+interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: 'primary' | 'secondary' | 'outline';
+  size?: 'sm' | 'md' | 'lg';
+}
+
+const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ variant = 'primary', size = 'md', className = '', children, ...props }, ref) => {
+    const baseStyles = 'rounded-lg font-medium transition-colors';
+
+    const variantStyles = {
+      primary: 'bg-primary text-white hover:opacity-90',
+      secondary: 'bg-secondary text-white hover:opacity-90',
+      outline: 'border-2 border-primary text-primary hover:bg-primary hover:text-white',
+    };
+
+    const sizeStyles = {
+      sm: 'px-3 py-1.5 text-sm',
+      md: 'px-4 py-2 text-base',
+      lg: 'px-6 py-3 text-lg',
+    };
+
+    return (
+      <button
+        ref={ref}
+        className={`${baseStyles} ${variantStyles[variant]} ${sizeStyles[size]} ${className}`}
+        {...props}
+      >
+        {children}
+      </button>
+    );
+  }
+);
+
+Button.displayName = 'Button';
+
+export default Button;
+```
+
+## Server Components with Tailwind
+
+**app/components/Card.tsx:**
+
+```typescript
+interface CardProps {
+  title: string;
+  description: string;
+  children?: React.ReactNode;
+}
+
+export default function Card({ title, description, children }: CardProps) {
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-6 shadow-md dark:border-gray-700 dark:bg-gray-800">
+      <h2 className="text-2xl font-bold text-gray-900 dark:text-white">
+        {title}
+      </h2>
+      <p className="mt-2 text-gray-600 dark:text-gray-300">
+        {description}
+      </p>
+      {children && <div className="mt-4">{children}</div>}
+    </div>
+  );
+}
+```
+
+## Environment-Specific Styling
+
+**app/globals.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+
+@layer base {
+  body {
+    @apply antialiased;
+  }
+}
+```
+
+## Performance Optimization
+
+**next.config.js:**
+
+```javascript
+const nextConfig = {
+  experimental: {
+    optimizeCss: true,
+  },
+};
+
+export default nextConfig;
+```
+
+**Production build:**
+
+```bash
+NODE_ENV=production npm run build
+```
+
+## Deployment
+
+**Vercel:**
+
+No additional configuration needed. Vercel automatically detects PostCSS config.
+
+**Self-hosted:**
+
+```bash
+npm run build
+npm start
+```
+
+**Docker:**
+
+```dockerfile
+FROM node:20-alpine AS builder
+
+WORKDIR /app
+COPY package*.json ./
+RUN npm ci
+COPY . .
+RUN npm run build
+
+FROM node:20-alpine AS runner
+WORKDIR /app
+COPY --from=builder /app/.next ./.next
+COPY --from=builder /app/public ./public
+COPY --from=builder /app/package*.json ./
+RUN npm ci --production
+
+EXPOSE 3000
+CMD ["npm", "start"]
+```

skills/configuring-tailwind-v4/references/postcss-setup.md

@@ -0,0 +1,307 @@
+# PostCSS Setup Examples
+
+## Basic PostCSS Configuration
+
+**Install dependencies:**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**input.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+## CommonJS Format
+
+**postcss.config.cjs:**
+
+```javascript
+module.exports = {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+## Next.js Integration
+
+**Install dependencies:**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**app/globals.css or styles/globals.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: var(--font-geist-sans);
+  --font-mono: var(--font-geist-mono);
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+**app/layout.tsx:**
+
+```typescript
+import './globals.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>{children}</body>
+    </html>
+  );
+}
+```
+
+## Webpack Integration
+
+**webpack.config.js:**
+
+```javascript
+module.exports = {
+  module: {
+    rules: [
+      {
+        test: /\.css$/,
+        use: [
+          'style-loader',
+          'css-loader',
+          {
+            loader: 'postcss-loader',
+            options: {
+              postcssOptions: {
+                plugins: {
+                  '@tailwindcss/postcss': {},
+                },
+              },
+            },
+          },
+        ],
+      },
+    ],
+  },
+};
+```
+
+## Custom PostCSS Plugins
+
+**Note:** Tailwind v4 replaces the need for `postcss-import` and `autoprefixer`.
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+## Build Scripts
+
+**package.json:**
+
+```json
+{
+  "scripts": {
+    "dev": "postcss src/input.css -o dist/output.css --watch",
+    "build": "NODE_ENV=production postcss src/input.css -o dist/output.css"
+  }
+}
+```
+
+## Angular Integration
+
+**Install dependencies:**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**Create postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**angular.json:**
+
+```json
+{
+  "projects": {
+    "my-app": {
+      "architect": {
+        "build": {
+          "options": {
+            "postcssConfig": "postcss.config.js",
+            "styles": ["src/styles.css"]
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+**src/styles.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+## Nuxt 3 Integration
+
+**Install dependencies:**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss
+```
+
+**nuxt.config.ts:**
+
+```typescript
+export default defineNuxtConfig({
+  postcss: {
+    plugins: {
+      '@tailwindcss/postcss': {},
+    },
+  },
+});
+```
+
+**assets/css/main.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+**app.vue:**
+
+```vue
+<template>
+  <NuxtPage />
+</template>
+
+<style>
+@import '@/assets/css/main.css';
+</style>
+```
+
+## Gatsby Integration
+
+**Install dependencies:**
+
+```bash
+npm install tailwindcss @tailwindcss/postcss gatsby-plugin-postcss
+```
+
+**gatsby-config.js:**
+
+```javascript
+module.exports = {
+  plugins: ['gatsby-plugin-postcss'],
+};
+```
+
+**postcss.config.js:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**src/styles/global.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+}
+```
+
+**gatsby-browser.js:**
+
+```javascript
+import './src/styles/global.css';
+```
+
+## Common Issues
+
+**Module parse failed: Unexpected character '@'**
+
+Ensure PostCSS is configured correctly and using `@tailwindcss/postcss`:
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+**Styles not applying**
+
+Check that:
+1. CSS import is present: `@import "tailwindcss";`
+2. PostCSS config uses correct plugin
+3. Template files aren't in `.gitignore`
+4. Class names are complete strings
+
+**Production builds missing styles**
+
+Set `NODE_ENV=production`:
+
+```bash
+NODE_ENV=production npm run build
+```

skills/configuring-tailwind-v4/references/vite-setup.md

@@ -0,0 +1,212 @@
+# Vite Setup Examples
+
+## Basic React + Vite Setup
+
+**Install dependencies:**
+
+```bash
+npm create vite@latest my-app -- --template react
+cd my-app
+npm install tailwindcss @tailwindcss/vite
+```
+
+**vite.config.js:**
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+**src/index.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+  --font-sans: 'Inter', sans-serif;
+}
+```
+
+**src/main.jsx:**
+
+```javascript
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+import './index.css';
+
+ReactDOM.createRoot(document.getElementById('root')).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## Vue + Vite Setup
+
+**Install dependencies:**
+
+```bash
+npm create vite@latest my-app -- --template vue
+cd my-app
+npm install tailwindcss @tailwindcss/vite
+```
+
+**vite.config.js:**
+
+```javascript
+import { defineConfig } from 'vite';
+import vue from '@vitejs/plugin-vue';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [vue(), tailwindcss()],
+});
+```
+
+**src/style.css:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --color-primary: oklch(0.65 0.25 142);
+  --font-sans: 'Roboto', sans-serif;
+}
+```
+
+## Svelte + Vite Setup
+
+**Install dependencies:**
+
+```bash
+npm create vite@latest my-app -- --template svelte
+cd my-app
+npm install tailwindcss @tailwindcss/vite
+```
+
+**vite.config.js:**
+
+```javascript
+import { defineConfig } from 'vite';
+import { svelte } from '@sveltejs/vite-plugin-svelte';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [svelte(), tailwindcss()],
+});
+```
+
+**src/app.css:**
+
+```css
+@import 'tailwindcss';
+```
+
+## Multi-Environment Configuration
+
+**Development with watch mode:**
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig(({ mode }) => ({
+  plugins: [
+    react(),
+    tailwindcss({
+      watch: mode === 'development',
+    }),
+  ],
+}));
+```
+
+## Monorepo Setup
+
+**Root vite.config.js:**
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  resolve: {
+    alias: {
+      '@ui': '/packages/ui/src',
+      '@shared': '/packages/shared/src',
+    },
+  },
+});
+```
+
+**Root CSS with package sources:**
+
+```css
+@import 'tailwindcss';
+
+@source "../packages/ui";
+@source "../packages/shared";
+
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+## Custom Build Output
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+  build: {
+    outDir: 'dist',
+    cssCodeSplit: true,
+    rollupOptions: {
+      output: {
+        assetFileNames: 'assets/[name].[hash][extname]',
+      },
+    },
+  },
+});
+```
+
+## Performance Optimization
+
+**Exclude unnecessary directories:**
+
+```css
+@import 'tailwindcss';
+
+@source not "./docs";
+@source not "./legacy";
+@source not "./scripts";
+```
+
+**Production build:**
+
+```bash
+NODE_ENV=production npm run build
+```
+
+**Build time monitoring:**
+
+```bash
+time npm run build
+```
+
+Expected performance:
+- Full builds: ~100ms
+- Incremental rebuilds: ~5ms
+- No-change rebuilds: ~192µs

skills/creating-custom-utilities/SKILL.md

@@ -0,0 +1,423 @@
+---
+name: creating-custom-utilities
+description: Create custom utilities with @utility directive supporting static utilities, functional utilities with values, theme-based utilities, and multi-value utilities. Use when extending Tailwind with custom CSS properties or patterns.
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Creating Custom Utilities
+
+## Purpose
+
+The `@utility` directive creates custom utility classes with full variant support (hover, focus, responsive, etc.). This is the proper way to extend Tailwind v4 with custom utilities.
+
+## Static Utilities
+
+Define utilities with fixed values:
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+
+@utility content-hidden {
+  content-visibility: hidden;
+}
+
+@utility text-balance {
+  text-wrap: balance;
+}
+
+@utility text-pretty {
+  text-wrap: pretty;
+}
+
+@utility bg-glass {
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+}
+```
+
+**Usage:**
+
+```html
+<div class="content-auto hover:content-hidden"></div>
+<p class="text-balance lg:text-pretty"></p>
+<div class="bg-glass"></div>
+```
+
+Static utilities work with all variants automatically.
+
+## Functional Utilities with Integer Values
+
+Create utilities that accept numeric values:
+
+```css
+@utility mt-* {
+  margin-top: calc(0.25rem * --value(integer));
+}
+
+@utility truncate-* {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: --value(integer);
+  overflow: hidden;
+}
+
+@utility text-stroke-* {
+  -webkit-text-stroke-width: --value(integer) px;
+}
+```
+
+**Usage:**
+
+```html
+<div class="mt-5"></div>
+<p class="truncate-3"></p>
+<h1 class="text-stroke-2"></h1>
+```
+
+The `--value(integer)` function extracts the numeric value from the class name.
+
+## Theme-Based Utilities
+
+Reference theme variables using `--value(--namespace- *)`:
+
+```css
+@theme {
+  --tab-size-2: 2;
+  --tab-size-4: 4;
+  --tab-size-8: 8;
+  --tab-size-github: 8;
+}
+
+@utility tab-* {
+  tab-size: --value(--tab-size- *);
+}
+```
+
+**Usage:**
+
+```html
+<pre class="tab-2"><code>...</code></pre>
+<pre class="tab-github"><code>...</code></pre>
+```
+
+**Another example:**
+
+```css
+@theme {
+  --aspect-square: 1 / 1;
+  --aspect-video: 16 / 9;
+  --aspect-portrait: 3 / 4;
+}
+
+@utility aspect-* {
+  aspect-ratio: --value(--aspect- *);
+}
+```
+
+**Usage:**
+
+```html
+<img class="aspect-square" />
+<video class="aspect-video" />
+<div class="aspect-portrait"></div>
+```
+
+## Multi-Value Utilities
+
+Create utilities that accept multiple value types:
+
+```css
+@utility text-stroke-* {
+  -webkit-text-stroke-width: --value(integer) px;
+  -webkit-text-stroke-color: --value(--color- *);
+}
+```
+
+**Usage:**
+
+```html
+<h1 class="text-stroke-2-blue-500">Stroked text</h1>
+<h1 class="text-stroke-1-primary">Stroked with theme color</h1>
+```
+
+**Another example:**
+
+```css
+@theme {
+  --blur-sm: 4px;
+  --blur-md: 8px;
+  --blur-lg: 16px;
+}
+
+@utility backdrop-blur-* {
+  backdrop-filter: blur(--value(--blur- *));
+  backdrop-filter: blur(--value(integer) px);
+}
+```
+
+**Usage:**
+
+```html
+<div class="backdrop-blur-sm"></div>
+<div class="backdrop-blur-12"></div>
+```
+
+## Arbitrary Values Support
+
+Support both theme values and arbitrary values:
+
+```css
+@utility tab-* {
+  tab-size: --value(integer);
+  tab-size: --value([integer]);
+}
+```
+
+**Usage:**
+
+```html
+<pre class="tab-4">Theme value</pre>
+<pre class="tab-[12]">Arbitrary value</pre>
+```
+
+The `--value([integer])` function enables arbitrary value syntax with square brackets.
+
+## Complex Utility Examples
+
+### Gradient Text
+
+```css
+@utility text-gradient-* {
+  background: linear-gradient(to right, --value(--color- *), --value(--color- *, 2));
+  -webkit-background-clip: text;
+  -webkit-text-fill-color: transparent;
+  background-clip: text;
+}
+```
+
+**Usage:**
+
+```html
+<h1 class="text-gradient-blue-500-purple-600">Gradient text</h1>
+```
+
+### Grid Template Columns
+
+```css
+@utility grid-cols-* {
+  grid-template-columns: repeat(--value(integer), minmax(0, 1fr));
+}
+```
+
+**Usage:**
+
+```html
+<div class="grid grid-cols-3"></div>
+<div class="grid grid-cols-5"></div>
+```
+
+### Custom Line Clamp
+
+```css
+@utility line-clamp-* {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: --value(integer);
+  overflow: hidden;
+}
+
+@utility line-clamp-none {
+  display: block;
+  -webkit-box-orient: horizontal;
+  -webkit-line-clamp: none;
+  overflow: visible;
+}
+```
+
+**Usage:**
+
+```html
+<p class="line-clamp-2 lg:line-clamp-3 xl:line-clamp-none"></p>
+```
+
+### Custom Spacing Scale
+
+```css
+@theme {
+  --spacing-base: 0.25rem;
+}
+
+@utility gap-* {
+  gap: calc(var(--spacing-base) * --value(integer));
+}
+
+@utility space-x-* > * + * {
+  margin-left: calc(var(--spacing-base) * --value(integer));
+}
+```
+
+**Usage:**
+
+```html
+<div class="flex gap-6"></div>
+<div class="flex space-x-4"></div>
+```
+
+### Glassmorphism Utilities
+
+```css
+@utility glass-* {
+  background: rgba(255, 255, 255, --value(integer) / 100);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+}
+
+@utility glass-dark-* {
+  background: rgba(0, 0, 0, --value(integer) / 100);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.1);
+}
+```
+
+**Usage:**
+
+```html
+<div class="glass-10"></div>
+<div class="glass-dark-20"></div>
+```
+
+## Utilities with Pseudo-Elements
+
+```css
+@utility before-content-* {
+  &::before {
+    content: --value([string]);
+    display: block;
+  }
+}
+
+@utility after-content-* {
+  &::after {
+    content: --value([string]);
+    display: block;
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="before:content-['★']">Star before</div>
+<div class="after:content-['→']">Arrow after</div>
+```
+
+## Complete Custom Utilities Library
+
+```css
+@import 'tailwindcss';
+
+@utility content-auto {
+  content-visibility: auto;
+}
+
+@utility content-hidden {
+  content-visibility: hidden;
+}
+
+@utility text-balance {
+  text-wrap: balance;
+}
+
+@utility text-pretty {
+  text-wrap: pretty;
+}
+
+@utility truncate-* {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: --value(integer);
+  overflow: hidden;
+}
+
+@utility bg-glass {
+  background: rgba(255, 255, 255, 0.1);
+  backdrop-filter: blur(10px);
+  border: 1px solid rgba(255, 255, 255, 0.2);
+}
+
+@utility text-stroke-* {
+  -webkit-text-stroke-width: --value(integer) px;
+  -webkit-text-stroke-color: --value(--color- *);
+}
+
+@theme {
+  --aspect-square: 1 / 1;
+  --aspect-video: 16 / 9;
+  --aspect-portrait: 3 / 4;
+  --aspect-ultrawide: 21 / 9;
+}
+
+@utility aspect-* {
+  aspect-ratio: --value(--aspect- *);
+  aspect-ratio: --value([number]);
+}
+
+@theme {
+  --tab-size-2: 2;
+  --tab-size-4: 4;
+  --tab-size-8: 8;
+}
+
+@utility tab-* {
+  tab-size: --value(--tab-size- *);
+  tab-size: --value(integer);
+  tab-size: --value([integer]);
+}
+```
+
+## Why Use @utility Instead of @layer utilities
+
+**Don't do this:**
+
+```css
+@layer utilities {
+  .my-button {
+    padding: 1rem;
+  }
+}
+```
+
+Won't work with variants like `hover:my-button`.
+
+**Do this:**
+
+```css
+@utility my-button {
+  padding: 1rem;
+}
+```
+
+Works with all variants: `hover:my-button`, `focus:my-button`, `lg:my-button`.
+
+## Best Practices
+
+1. **Use @utility for variant support** - Always use `@utility` instead of `@layer utilities`
+2. **Support arbitrary values** - Include `--value([type])` for flexibility
+3. **Use theme variables** - Reference theme with `--value(--namespace- *)`
+4. **Name utilities semantically** - Use clear, descriptive names
+5. **Group related utilities** - Keep similar utilities together
+
+## Common Use Cases
+
+- Custom CSS properties not in Tailwind
+- Browser-specific prefixed properties
+- Complex multi-property patterns
+- Domain-specific utilities (e.g., print styles)
+- Experimental CSS features
+
+## See Also
+
+- RESEARCH.md section: "Advanced Patterns" → "Custom Utilities with @utility"

skills/handling-animations/SKILL.md

@@ -0,0 +1,262 @@
+---
+name: handling-animations
+description: Define animations with @keyframes within @theme directive, use animate-{name} utilities, and implement entry animations with starting: variant. Use when creating custom animations or entry effects.
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Handling Animations
+
+## Purpose
+
+Define custom animations using `@keyframes` within the `@theme` directive and use Tailwind's animation utilities with full variant support.
+
+## Basic Animation Pattern
+
+Define animations within `@theme`:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  @keyframes fade-in {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-fade-in">Fades in on load</div>
+```
+
+## Animation Variable Naming
+
+**Pattern:** `--animate-{name}: {animation-shorthand};`
+
+The variable name determines the utility class:
+
+```css
+@theme {
+  --animate-spin: spin 1s linear infinite;
+  --animate-bounce: bounce 1s infinite;
+  --animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+}
+```
+
+Generates utilities:
+- `animate-spin`
+- `animate-bounce`
+- `animate-pulse`
+
+## Common Animation Types
+
+### Fade Animations
+
+**Fade In:**
+
+```css
+@theme {
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  @keyframes fade-in {
+    0% { opacity: 0; }
+    100% { opacity: 1; }
+  }
+}
+```
+
+**Fade In with Scale:**
+
+```css
+@theme {
+  --animate-fade-in-scale: fade-in-scale 0.3s ease-out;
+
+  @keyframes fade-in-scale {
+    0% {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+    100% {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+}
+```
+
+### Slide Animations
+
+**Slide Up:**
+
+```css
+@theme {
+  --animate-slide-up: slide-up 0.4s ease-out;
+
+  @keyframes slide-up {
+    0% {
+      opacity: 0;
+      transform: translateY(20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}
+```
+
+For complete directional slide examples (left, right, top, bottom), see [Animation Library](references/animation-library.md#slide-in-from-directions).
+
+### Motion Animations
+
+**Spin:**
+
+```css
+@theme {
+  --animate-spin: spin 1s linear infinite;
+
+  @keyframes spin {
+    to { transform: rotate(360deg); }
+  }
+}
+```
+
+**Bounce:**
+
+```css
+@theme {
+  --animate-bounce: bounce 1s infinite;
+
+  @keyframes bounce {
+    0%, 100% {
+      transform: translateY(-25%);
+      animation-timing-function: cubic-bezier(0.8, 0, 1, 1);
+    }
+    50% {
+      transform: translateY(0);
+      animation-timing-function: cubic-bezier(0, 0, 0.2, 1);
+    }
+  }
+}
+```
+
+For additional motion animations (pulse, ping, shake, wiggle), see [Animation Library](references/animation-library.md#complete-animation-examples).
+
+## Entry Animations with starting:
+
+The `starting:` variant applies styles before animations begin:
+
+```html
+<div class="opacity-100 transition-opacity duration-300 starting:opacity-0">
+  Fades in smoothly
+</div>
+
+<div class="
+  translate-y-0 opacity-100
+  transition-all duration-300
+  starting:translate-y-4 starting:opacity-0
+">
+  Slides up while fading in
+</div>
+```
+
+**How it works:**
+
+1. Element starts with `starting:` styles
+2. Browser renders first frame
+3. Transition/animation begins to final state
+
+## Animation with Variants
+
+Animations work with all Tailwind variants:
+
+```html
+<div class="hover:animate-spin">Spins on hover</div>
+<div class="focus:animate-pulse">Pulses on focus</div>
+<div class="group-hover:animate-bounce">Bounces when parent hovered</div>
+<div class="lg:animate-fade-in">Animates on large screens</div>
+<div class="dark:animate-pulse">Pulses in dark mode</div>
+```
+
+## Advanced Animation Techniques
+
+### Staggered Animations
+
+```html
+<div class="space-y-4">
+  <div class="animate-slide-up [animation-delay:0s]">Item 1</div>
+  <div class="animate-slide-up [animation-delay:0.1s]">Item 2</div>
+  <div class="animate-slide-up [animation-delay:0.2s]">Item 3</div>
+  <div class="animate-slide-up [animation-delay:0.3s]">Item 4</div>
+</div>
+```
+
+### Animation Control
+
+**Delayed Animation:**
+
+```html
+<div class="
+  animate-fade-in
+  [animation-delay:0.1s]
+  [animation-fill-mode:both]
+">
+  Delayed fade in
+</div>
+```
+
+**Pause on Hover:**
+
+```html
+<div class="animate-spin hover:[animation-play-state:paused]">
+  Pauses on hover
+</div>
+```
+
+## Best Practices
+
+1. **Define within @theme** - Keep all animations in one place
+2. **Use semantic names** - `fade-in` not `anim-1`
+3. **Include timing in variable** - Full animation shorthand
+4. **Test performance** - Avoid animating expensive properties (width, height)
+5. **Use transform and opacity** - Hardware accelerated
+6. **Add will-change sparingly** - Only for known animations
+7. **Respect prefers-reduced-motion** - Disable animations for accessibility
+
+## Accessibility
+
+Respect user motion preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+## References
+
+For comprehensive animation examples and patterns, see:
+
+- [Animation Library](references/animation-library.md) - Complete collection of animation examples
+  - Fade animations (in, out, scale)
+  - Slide animations (all directions)
+  - Motion animations (spin, pulse, ping, bounce)
+  - Complex patterns (shake, wiggle, loading dots)
+  - Complete animation library code
+  - Advanced techniques and performance considerations
+
+## See Also
+
+- RESEARCH.md sections: "Entry Animations with starting:" and "Animation Keyframes"

skills/handling-animations/references/animation-library.md

@@ -0,0 +1,545 @@
+# Animation Library Reference
+
+This document contains detailed animation examples and complete implementation code for Tailwind CSS v4 animations.
+
+## Complete Animation Examples
+
+### Fade In
+
+```css
+@theme {
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  @keyframes fade-in {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-fade-in">Fades in</div>
+```
+
+### Fade In Scale
+
+```css
+@theme {
+  --animate-fade-in-scale: fade-in-scale 0.3s ease-out;
+
+  @keyframes fade-in-scale {
+    0% {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+    100% {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-fade-in-scale">Fades and scales in</div>
+```
+
+### Slide In from Bottom
+
+```css
+@theme {
+  --animate-slide-up: slide-up 0.4s ease-out;
+
+  @keyframes slide-up {
+    0% {
+      opacity: 0;
+      transform: translateY(20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-slide-up">Slides up while fading in</div>
+```
+
+### Spin
+
+```css
+@theme {
+  --animate-spin: spin 1s linear infinite;
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-spin">
+  <svg>...</svg>
+</div>
+```
+
+### Pulse
+
+```css
+@theme {
+  --animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+
+  @keyframes pulse {
+    0%, 100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.5;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-pulse">Pulsing element</div>
+```
+
+### Bounce
+
+```css
+@theme {
+  --animate-bounce: bounce 1s infinite;
+
+  @keyframes bounce {
+    0%, 100% {
+      transform: translateY(-25%);
+      animation-timing-function: cubic-bezier(0.8, 0, 1, 1);
+    }
+    50% {
+      transform: translateY(0);
+      animation-timing-function: cubic-bezier(0, 0, 0.2, 1);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-bounce">Bouncing element</div>
+```
+
+### Ping (Ripple Effect)
+
+```css
+@theme {
+  --animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite;
+
+  @keyframes ping {
+    0% {
+      transform: scale(1);
+      opacity: 1;
+    }
+    75%, 100% {
+      transform: scale(2);
+      opacity: 0;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="relative">
+  <div class="absolute inset-0 animate-ping bg-blue-500 rounded-full"></div>
+  <div class="relative bg-blue-600 rounded-full w-4 h-4"></div>
+</div>
+```
+
+## Complex Animation Patterns
+
+### Shake Animation
+
+```css
+@theme {
+  --animate-shake: shake 0.5s ease-in-out;
+
+  @keyframes shake {
+    0%, 100% {
+      transform: translateX(0);
+    }
+    10%, 30%, 50%, 70%, 90% {
+      transform: translateX(-10px);
+    }
+    20%, 40%, 60%, 80% {
+      transform: translateX(10px);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="hover:animate-shake">Shake on hover</div>
+```
+
+### Wiggle
+
+```css
+@theme {
+  --animate-wiggle: wiggle 1s ease-in-out infinite;
+
+  @keyframes wiggle {
+    0%, 100% {
+      transform: rotate(-3deg);
+    }
+    50% {
+      transform: rotate(3deg);
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-wiggle">Wiggling element</div>
+```
+
+### Slide In from Directions
+
+```css
+@theme {
+  --animate-slide-in-left: slide-in-left 0.4s ease-out;
+  --animate-slide-in-right: slide-in-right 0.4s ease-out;
+  --animate-slide-in-top: slide-in-top 0.4s ease-out;
+  --animate-slide-in-bottom: slide-in-bottom 0.4s ease-out;
+
+  @keyframes slide-in-left {
+    0% {
+      transform: translateX(-100%);
+      opacity: 0;
+    }
+    100% {
+      transform: translateX(0);
+      opacity: 1;
+    }
+  }
+
+  @keyframes slide-in-right {
+    0% {
+      transform: translateX(100%);
+      opacity: 0;
+    }
+    100% {
+      transform: translateX(0);
+      opacity: 1;
+    }
+  }
+
+  @keyframes slide-in-top {
+    0% {
+      transform: translateY(-100%);
+      opacity: 0;
+    }
+    100% {
+      transform: translateY(0);
+      opacity: 1;
+    }
+  }
+
+  @keyframes slide-in-bottom {
+    0% {
+      transform: translateY(100%);
+      opacity: 0;
+    }
+    100% {
+      transform: translateY(0);
+      opacity: 1;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-slide-in-left">Slides from left</div>
+<div class="animate-slide-in-right">Slides from right</div>
+<div class="animate-slide-in-top">Slides from top</div>
+<div class="animate-slide-in-bottom">Slides from bottom</div>
+```
+
+### Loading Dots
+
+```css
+@theme {
+  --animate-dot-pulse: dot-pulse 1.4s infinite ease-in-out;
+
+  @keyframes dot-pulse {
+    0%, 80%, 100% {
+      opacity: 0;
+    }
+    40% {
+      opacity: 1;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="flex gap-1">
+  <div class="w-2 h-2 bg-blue-500 rounded-full animate-dot-pulse"></div>
+  <div class="w-2 h-2 bg-blue-500 rounded-full animate-dot-pulse [animation-delay:0.2s]"></div>
+  <div class="w-2 h-2 bg-blue-500 rounded-full animate-dot-pulse [animation-delay:0.4s]"></div>
+</div>
+```
+
+## Complete Animation Library
+
+Full implementation of all animations:
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --animate-spin: spin 1s linear infinite;
+  --animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite;
+  --animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  --animate-bounce: bounce 1s infinite;
+
+  --animate-fade-in: fade-in 0.3s ease-out;
+  --animate-fade-out: fade-out 0.3s ease-in;
+  --animate-fade-in-scale: fade-in-scale 0.3s ease-out;
+
+  --animate-slide-up: slide-up 0.4s ease-out;
+  --animate-slide-down: slide-down 0.4s ease-out;
+  --animate-slide-left: slide-left 0.4s ease-out;
+  --animate-slide-right: slide-right 0.4s ease-out;
+
+  --animate-shake: shake 0.5s ease-in-out;
+  --animate-wiggle: wiggle 1s ease-in-out infinite;
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  @keyframes ping {
+    0% {
+      transform: scale(1);
+      opacity: 1;
+    }
+    75%, 100% {
+      transform: scale(2);
+      opacity: 0;
+    }
+  }
+
+  @keyframes pulse {
+    0%, 100% {
+      opacity: 1;
+    }
+    50% {
+      opacity: 0.5;
+    }
+  }
+
+  @keyframes bounce {
+    0%, 100% {
+      transform: translateY(-25%);
+      animation-timing-function: cubic-bezier(0.8, 0, 1, 1);
+    }
+    50% {
+      transform: translateY(0);
+      animation-timing-function: cubic-bezier(0, 0, 0.2, 1);
+    }
+  }
+
+  @keyframes fade-in {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+
+  @keyframes fade-out {
+    0% {
+      opacity: 1;
+    }
+    100% {
+      opacity: 0;
+    }
+  }
+
+  @keyframes fade-in-scale {
+    0% {
+      opacity: 0;
+      transform: scale(0.95);
+    }
+    100% {
+      opacity: 1;
+      transform: scale(1);
+    }
+  }
+
+  @keyframes slide-up {
+    0% {
+      opacity: 0;
+      transform: translateY(20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes slide-down {
+    0% {
+      opacity: 0;
+      transform: translateY(-20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateY(0);
+    }
+  }
+
+  @keyframes slide-left {
+    0% {
+      opacity: 0;
+      transform: translateX(20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateX(0);
+    }
+  }
+
+  @keyframes slide-right {
+    0% {
+      opacity: 0;
+      transform: translateX(-20px);
+    }
+    100% {
+      opacity: 1;
+      transform: translateX(0);
+    }
+  }
+
+  @keyframes shake {
+    0%, 100% {
+      transform: translateX(0);
+    }
+    10%, 30%, 50%, 70%, 90% {
+      transform: translateX(-10px);
+    }
+    20%, 40%, 60%, 80% {
+      transform: translateX(10px);
+    }
+  }
+
+  @keyframes wiggle {
+    0%, 100% {
+      transform: rotate(-3deg);
+    }
+    50% {
+      transform: rotate(3deg);
+    }
+  }
+}
+```
+
+## Advanced Techniques
+
+### Animation with Variants
+
+Animations work with all Tailwind variants:
+
+```html
+<div class="hover:animate-spin">Spins on hover</div>
+<div class="focus:animate-pulse">Pulses on focus</div>
+<div class="group-hover:animate-bounce">Bounces when parent hovered</div>
+<div class="lg:animate-fade-in">Animates on large screens</div>
+<div class="dark:animate-pulse">Pulses in dark mode</div>
+```
+
+### Combining Multiple Animations
+
+Use arbitrary properties for complex animations:
+
+```html
+<div class="
+  animate-fade-in
+  [animation-delay:0.1s]
+  [animation-fill-mode:both]
+">
+  Delayed fade in
+</div>
+```
+
+### Staggered Animations
+
+```html
+<div class="space-y-4">
+  <div class="animate-slide-up [animation-delay:0s]">Item 1</div>
+  <div class="animate-slide-up [animation-delay:0.1s]">Item 2</div>
+  <div class="animate-slide-up [animation-delay:0.2s]">Item 3</div>
+  <div class="animate-slide-up [animation-delay:0.3s]">Item 4</div>
+</div>
+```
+
+### Pausing Animations
+
+```html
+<div class="animate-spin hover:[animation-play-state:paused]">
+  Pauses on hover
+</div>
+```
+
+## Performance Considerations
+
+1. **Use transform and opacity** - Hardware accelerated properties
+2. **Avoid animating expensive properties** - Don't animate width, height, or layout properties
+3. **Add will-change sparingly** - Only for known animations that need performance boost
+4. **Test on low-end devices** - Ensure smooth performance across all devices
+5. **Use CSS animations over JavaScript** - Better performance and smoother animations
+
+## Accessibility
+
+Respect user motion preferences:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```

skills/migrating-from-v3/SKILL.md

@@ -0,0 +1,495 @@
+---
+name: migrating-from-v3
+description: Migrate from Tailwind CSS v3 to v4 including configuration migration (JS to CSS), utility renames, opacity changes, and color system updates. Use when upgrading existing projects to v4.
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash
+---
+
+# Migrating from v3 to v4
+
+## Purpose
+
+Migrate existing Tailwind CSS v3 projects to v4's CSS-first configuration, updated utilities, and modern color system.
+
+## Automated Migration Tool
+
+Tailwind provides an automated upgrade tool:
+
+```bash
+npx @tailwindcss/upgrade@next
+```
+
+**Requirements:**
+- Node.js 20 or higher
+- Run in a new git branch
+- Review all changes manually
+- Test thoroughly
+
+**What it handles:**
+- Updates dependencies
+- Migrates configuration to CSS
+- Updates template files
+- Converts utility class names
+
+**What it doesn't handle:**
+- Custom plugins (manual migration needed)
+- Complex configuration logic
+- Dynamic class generation
+
+## Configuration Migration
+
+### JavaScript Config → CSS Theme
+
+**v3 (tailwind.config.js):**
+
+```javascript
+module.exports = {
+  content: ['./src/**/*.{html,js}'],
+  theme: {
+    extend: {
+      colors: {
+        brand: '#3b82f6',
+        accent: '#a855f7',
+      },
+      fontFamily: {
+        sans: ['Inter', 'sans-serif'],
+        display: ['Satoshi', 'sans-serif'],
+      },
+      spacing: {
+        18: '4.5rem',
+        72: '18rem',
+      },
+      borderRadius: {
+        '4xl': '2rem',
+      },
+    },
+  },
+  plugins: [],
+};
+```
+
+**v4 (CSS @theme):**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', sans-serif;
+  --font-display: 'Satoshi', sans-serif;
+
+  --color-brand: oklch(0.65 0.25 270);
+  --color-accent: oklch(0.65 0.25 320);
+
+  --spacing-18: 4.5rem;
+  --spacing-72: 18rem;
+
+  --radius-4xl: 2rem;
+}
+```
+
+### Content Detection
+
+**v3:**
+
+```javascript
+content: ['./src/**/*.{html,js,jsx,ts,tsx}']
+```
+
+**v4:**
+
+Automatic detection. No configuration needed.
+
+**Manual control (if needed):**
+
+```css
+@import 'tailwindcss';
+@source "../packages/ui";
+@source not "./legacy";
+```
+
+### Import Syntax Changes
+
+**v3:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**v4:**
+
+```css
+@import 'tailwindcss';
+```
+
+## Utility Class Renames
+
+### Opacity Modifiers
+
+**v3:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+<div class="text-gray-900 text-opacity-75"></div>
+<div class="border-blue-500 border-opacity-60"></div>
+```
+
+**v4:**
+
+```html
+<div class="bg-black/50"></div>
+<div class="text-gray-900/75"></div>
+<div class="border-blue-500/60"></div>
+```
+
+**Migration pattern:**
+
+- `bg-opacity-{value}` → `bg-{color}/{value}`
+- `text-opacity-{value}` → `text-{color}/{value}`
+- `border-opacity-{value}` → `border-{color}/{value}`
+
+### Flex Utilities
+
+**v3:**
+
+```html
+<div class="flex-shrink-0"></div>
+<div class="flex-shrink"></div>
+<div class="flex-grow-0"></div>
+<div class="flex-grow"></div>
+```
+
+**v4:**
+
+```html
+<div class="shrink-0"></div>
+<div class="shrink"></div>
+<div class="grow-0"></div>
+<div class="grow"></div>
+```
+
+**Migration pattern:**
+
+- `flex-shrink-*` → `shrink-*`
+- `flex-grow-*` → `grow-*`
+
+### Shadow Utilities
+
+**v3:**
+
+```html
+<div class="shadow-sm"></div>
+```
+
+**v4:**
+
+```html
+<div class="shadow-xs"></div>
+```
+
+**Migration:**
+
+- `shadow-sm` → `shadow-xs`
+- All other shadow utilities remain the same
+
+### Ring Width
+
+**v3 default:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 3px
+
+**v4 default:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 1px
+
+**To keep v3 behavior:**
+
+```html
+<input class="ring-3" />
+```
+
+## Color System Changes
+
+### Default Border and Ring Colors
+
+**v3:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: gray-200
+
+**v4:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: currentColor
+
+**To keep v3 behavior:**
+
+```html
+<div class="border border-gray-200"></div>
+```
+
+### OkLCh Color Space
+
+**v3 (RGB):**
+
+```javascript
+colors: {
+  brand: '#3b82f6',
+}
+```
+
+**v4 (OkLCh):**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+Use conversion tool: https://oklch.com/
+
+## PostCSS Configuration
+
+### Plugin Changes
+
+**v3:**
+
+```javascript
+module.exports = {
+  plugins: {
+    'tailwindcss': {},
+    'autoprefixer': {},
+  },
+};
+```
+
+**v4:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+No longer need `autoprefixer` or `postcss-import`.
+
+### Vite Plugin
+
+**v3:**
+
+```javascript
+import tailwindcss from 'tailwindcss';
+import autoprefixer from 'autoprefixer';
+
+export default defineConfig({
+  css: {
+    postcss: {
+      plugins: [tailwindcss(), autoprefixer()],
+    },
+  },
+});
+```
+
+**v4:**
+
+```javascript
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+});
+```
+
+## Preflight Changes
+
+### Placeholder Colors
+
+**v3:**
+
+Placeholder text: gray-400
+
+**v4:**
+
+Placeholder text: currentColor at 50% opacity
+
+**To keep v3 behavior:**
+
+```css
+@layer base {
+  ::placeholder {
+    color: theme('colors.gray.400');
+  }
+}
+```
+
+### Button Cursor
+
+**v3:**
+
+```css
+button {
+  cursor: pointer;
+}
+```
+
+**v4:**
+
+```css
+button {
+  cursor: default;
+}
+```
+
+**To restore v3 behavior:**
+
+```css
+@layer base {
+  button {
+    cursor: pointer;
+  }
+}
+```
+
+## Feature Additions
+
+### Built-in Container Queries
+
+**v3 (plugin required):**
+
+```javascript
+plugins: [require('@tailwindcss/container-queries')]
+```
+
+**v4 (built-in):**
+
+No plugin needed. Use `@container` and `@{breakpoint}:` syntax.
+
+### 3D Transforms
+
+**v3:**
+
+Not available
+
+**v4:**
+
+```html
+<div class="transform-3d rotate-x-45 rotate-y-30 translate-z-12"></div>
+```
+
+### Starting Variant for Animations
+
+**v3:**
+
+Not available
+
+**v4:**
+
+```html
+<div class="opacity-100 starting:opacity-0 transition-opacity"></div>
+```
+
+## Breaking Changes Checklist
+
+- [ ] Update dependencies to v4
+- [ ] Migrate tailwind.config.js to @theme
+- [ ] Replace @tailwind directives with @import
+- [ ] Update PostCSS configuration
+- [ ] Convert opacity utilities (bg-opacity → bg-{color}/{value})
+- [ ] Rename flex utilities (flex-shrink → shrink)
+- [ ] Update shadow-sm to shadow-xs
+- [ ] Add explicit border colors if using bare `border`
+- [ ] Update ring-3 if expecting 3px default
+- [ ] Convert hex colors to oklch()
+- [ ] Remove container-queries plugin (now built-in)
+- [ ] Test placeholder colors
+- [ ] Test button cursor behavior
+- [ ] Update arbitrary value syntax (spaces → underscores)
+
+## Migration Strategy
+
+### Phase 1: Preparation
+
+1. Create new git branch
+2. Ensure all changes committed
+3. Run automated migration tool
+4. Review generated changes
+
+### Phase 2: Configuration
+
+1. Convert tailwind.config.js to CSS @theme
+2. Update PostCSS/Vite configuration
+3. Replace @tailwind directives
+4. Add @source if needed
+
+### Phase 3: Utilities
+
+1. Search and replace opacity modifiers
+2. Rename flex utilities
+3. Update shadow utilities
+4. Add explicit border colors
+5. Convert hex colors to oklch()
+
+### Phase 4: Testing
+
+1. Test all pages/components
+2. Verify responsive behavior
+3. Check dark mode
+4. Test interactive states
+5. Validate production build
+
+### Phase 5: Cleanup
+
+1. Remove unused dependencies
+2. Delete tailwind.config.js
+3. Update documentation
+4. Commit changes
+
+## Common Issues
+
+### Styles Not Applying
+
+Check:
+1. CSS import: `@import "tailwindcss";`
+2. PostCSS plugin: `@tailwindcss/postcss`
+3. Vite plugin: `@tailwindcss/vite`
+4. Template files not in .gitignore
+
+### Class Names Not Working
+
+Ensure:
+1. Class names are complete strings
+2. Not using dynamic concatenation
+3. Using underscores for spaces in arbitrary values
+
+### Colors Look Different
+
+OkLCh uses different color space. Convert hex to oklch using:
+https://oklch.com/
+
+### Build Errors
+
+Check:
+1. Node.js version (20+)
+2. Dependencies updated
+3. PostCSS config using correct plugin
+
+## See Also
+
+- references/breaking-changes.md - Complete breaking changes list
+- references/migration-checklist.md - Step-by-step migration guide

skills/migrating-from-v3/references/breaking-changes.md

@@ -0,0 +1,516 @@
+# Complete Breaking Changes List
+
+## Configuration System
+
+### JavaScript → CSS Configuration
+
+**Breaking:** No more `tailwind.config.js` file.
+
+**v3:**
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: { brand: '#3b82f6' },
+    },
+  },
+};
+```
+
+**v4:**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+**Impact:** All theme customization moves to CSS.
+
+### Content Detection
+
+**Breaking:** No manual content array needed.
+
+**v3:**
+
+```javascript
+content: ['./src/**/*.{html,js}']
+```
+
+**v4:**
+
+Automatic detection. Manual control via `@source` if needed.
+
+**Impact:** Simplified setup, but less explicit control.
+
+## Import Directives
+
+### @tailwind → @import
+
+**Breaking:** Different import syntax.
+
+**v3:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**v4:**
+
+```css
+@import 'tailwindcss';
+```
+
+**Impact:** All templates need updating.
+
+## Utility Class Changes
+
+### Opacity Modifiers Removed
+
+**Breaking:** Separate opacity utilities removed.
+
+**v3:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+<div class="text-gray-900 text-opacity-75"></div>
+<div class="border-blue-500 border-opacity-60"></div>
+<div class="ring-blue-500 ring-opacity-30"></div>
+```
+
+**v4:**
+
+```html
+<div class="bg-black/50"></div>
+<div class="text-gray-900/75"></div>
+<div class="border-blue-500/60"></div>
+<div class="ring-blue-500/30"></div>
+```
+
+**Impact:** Search and replace needed across entire codebase.
+
+**Automated fix:**
+
+```bash
+find . -name "*.html" -o -name "*.jsx" -o -name "*.tsx" | xargs sed -i '' 's/bg-\([a-z-]*\) bg-opacity-\([0-9]*\)/bg-\1\/\2/g'
+```
+
+### Flex Utility Renames
+
+**Breaking:** Utility names changed.
+
+**v3:**
+
+```html
+<div class="flex-shrink-0"></div>
+<div class="flex-shrink"></div>
+<div class="flex-grow-0"></div>
+<div class="flex-grow"></div>
+```
+
+**v4:**
+
+```html
+<div class="shrink-0"></div>
+<div class="shrink"></div>
+<div class="grow-0"></div>
+<div class="grow"></div>
+```
+
+**Impact:** All flex utilities need renaming.
+
+### Shadow Utility Rename
+
+**Breaking:** Smallest shadow renamed.
+
+**v3:**
+
+```html
+<div class="shadow-sm"></div>
+```
+
+**v4:**
+
+```html
+<div class="shadow-xs"></div>
+```
+
+**Impact:** Update all uses of `shadow-sm`.
+
+### Ring Default Width
+
+**Breaking:** Default ring width changed.
+
+**v3:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 3px
+
+**v4:**
+
+```html
+<input class="ring" />
+```
+
+Ring width: 1px
+
+**Fix for v3 behavior:**
+
+```html
+<input class="ring-3" />
+```
+
+**Impact:** All bare `ring` utilities render thinner.
+
+## Color System
+
+### Default Border Color
+
+**Breaking:** Border color changed from gray to currentColor.
+
+**v3:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: gray-200
+
+**v4:**
+
+```html
+<div class="border"></div>
+```
+
+Border color: currentColor (inherits text color)
+
+**Fix for v3 behavior:**
+
+```html
+<div class="border border-gray-200"></div>
+```
+
+**Impact:** Borders may appear different colors.
+
+### Default Ring Color
+
+**Breaking:** Ring color changed from blue to currentColor.
+
+**v3:**
+
+```html
+<input class="ring" />
+```
+
+Ring color: blue-500
+
+**v4:**
+
+```html
+<input class="ring" />
+```
+
+Ring color: currentColor
+
+**Fix for v3 behavior:**
+
+```html
+<input class="ring ring-blue-500" />
+```
+
+**Impact:** Rings inherit text color.
+
+### OkLCh Color Space
+
+**Breaking:** Color values use OkLCh instead of RGB.
+
+**v3:**
+
+```javascript
+colors: {
+  brand: '#3b82f6',
+}
+```
+
+**v4:**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+}
+```
+
+**Impact:** Custom colors need conversion. Colors may look slightly different (more vivid on modern displays).
+
+## PostCSS Changes
+
+### Plugin Name
+
+**Breaking:** Different PostCSS plugin.
+
+**v3:**
+
+```javascript
+plugins: {
+  'tailwindcss': {},
+  'autoprefixer': {},
+}
+```
+
+**v4:**
+
+```javascript
+plugins: {
+  '@tailwindcss/postcss': {},
+}
+```
+
+**Impact:** PostCSS config needs updating. Remove `autoprefixer` and `postcss-import` (no longer needed).
+
+## Preflight Changes
+
+### Placeholder Color
+
+**Breaking:** Placeholder text color changed.
+
+**v3:**
+
+```css
+::placeholder {
+  color: theme('colors.gray.400');
+}
+```
+
+**v4:**
+
+```css
+::placeholder {
+  color: currentColor;
+  opacity: 0.5;
+}
+```
+
+**Impact:** Placeholders inherit text color at 50% opacity.
+
+**Fix for v3 behavior:**
+
+```css
+@layer base {
+  ::placeholder {
+    color: theme('colors.gray.400');
+    opacity: 1;
+  }
+}
+```
+
+### Button Cursor
+
+**Breaking:** Button cursor changed.
+
+**v3:**
+
+```css
+button {
+  cursor: pointer;
+}
+```
+
+**v4:**
+
+```css
+button {
+  cursor: default;
+}
+```
+
+**Impact:** Buttons no longer show pointer cursor by default.
+
+**Fix for v3 behavior:**
+
+```css
+@layer base {
+  button {
+    cursor: pointer;
+  }
+}
+```
+
+Or add explicit classes:
+
+```html
+<button class="cursor-pointer">Click me</button>
+```
+
+## Arbitrary Values
+
+### Space Handling
+
+**Breaking:** Spaces in arbitrary values use underscores.
+
+**v3:**
+
+```html
+<div class="grid-cols-[1fr,500px,2fr]"></div>
+```
+
+**v4:**
+
+```html
+<div class="grid-cols-[1fr_500px_2fr]"></div>
+```
+
+**Impact:** All arbitrary values with commas need updating.
+
+## Browser Support
+
+### Minimum Versions
+
+**Breaking:** Dropped support for older browsers.
+
+**v3:**
+
+- IE 11+
+- Safari 10+
+- Chrome 60+
+
+**v4:**
+
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+
+**Impact:** Projects requiring older browser support cannot upgrade.
+
+## CSS Preprocessors
+
+### No Sass/Less/Stylus Support
+
+**Breaking:** Incompatible with CSS preprocessors.
+
+**v3:**
+
+Can use with Sass, Less, Stylus
+
+**v4:**
+
+Cannot use CSS preprocessors (Tailwind functions as preprocessing layer)
+
+**Impact:** Remove CSS preprocessors from build pipeline.
+
+## Plugin System
+
+### Plugin API Changes
+
+**Breaking:** Plugin API completely rewritten.
+
+**v3 plugin:**
+
+```javascript
+const plugin = require('tailwindcss/plugin');
+
+module.exports = plugin(function ({ addUtilities, theme }) {
+  addUtilities({
+    '.content-auto': {
+      'content-visibility': 'auto',
+    },
+  });
+});
+```
+
+**v4 equivalent:**
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+```
+
+**Impact:** All custom plugins need manual rewrite.
+
+## @apply Restrictions
+
+### Limited @apply Support
+
+**Breaking:** @apply only works for small subset of utilities.
+
+**v3:**
+
+```css
+.btn {
+  @apply px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700;
+}
+```
+
+**v4:**
+
+@apply has limited support. Use @utility instead:
+
+```css
+@utility btn {
+  padding: var(--spacing-2) var(--spacing-4);
+  background: var(--color-blue-600);
+  color: var(--color-white);
+  border-radius: var(--radius-md);
+}
+```
+
+**Impact:** Many @apply patterns need refactoring.
+
+## Mobile Hover Behavior
+
+### Hover on Touch Devices
+
+**Breaking:** Hover styles don't apply on touch devices.
+
+**v3:**
+
+Hover styles triggered on tap
+
+**v4:**
+
+Hover styles only on devices supporting hover
+
+**Impact:** Touch devices won't show hover states (improves UX).
+
+## Container Plugin
+
+### Built-in Container Queries
+
+**Breaking:** Container queries plugin no longer needed.
+
+**v3:**
+
+```javascript
+plugins: [require('@tailwindcss/container-queries')]
+```
+
+**v4:**
+
+Built-in. No plugin needed.
+
+**Impact:** Remove plugin dependency. Syntax remains same.
+
+## Summary Table
+
+| Change | v3 | v4 | Impact |
+|--------|----|----|--------|
+| Config | tailwind.config.js | @theme | High |
+| Import | @tailwind | @import | High |
+| Opacity | bg-opacity-50 | bg-{color}/50 | High |
+| Flex | flex-shrink | shrink | Medium |
+| Shadow | shadow-sm | shadow-xs | Low |
+| Ring width | 3px | 1px | Medium |
+| Border color | gray-200 | currentColor | Medium |
+| Color space | RGB | OkLCh | Medium |
+| PostCSS | tailwindcss | @tailwindcss/postcss | High |
+| Placeholder | gray-400 | currentColor/50 | Low |
+| Button cursor | pointer | default | Low |
+| Browsers | IE 11+ | Safari 16.4+ | High |
+| Preprocessors | Supported | Not supported | High |
+| Plugins | JS API | CSS @utility | High |

skills/migrating-from-v3/references/migration-checklist.md

@@ -0,0 +1,469 @@
+# Step-by-Step Migration Checklist
+
+## Pre-Migration
+
+- [ ] Create new git branch: `git checkout -b upgrade-tailwind-v4`
+- [ ] Commit all current changes
+- [ ] Document current Tailwind version
+- [ ] Backup tailwind.config.js
+- [ ] Review custom plugins in use
+- [ ] Check browser support requirements
+- [ ] Note any CSS preprocessor usage
+
+## Phase 1: Dependencies
+
+### Update Package Dependencies
+
+- [ ] Update Tailwind CSS to v4
+
+```bash
+npm install tailwindcss@next
+```
+
+- [ ] Install appropriate build tool plugin
+
+**For Vite:**
+
+```bash
+npm install @tailwindcss/vite
+```
+
+**For PostCSS:**
+
+```bash
+npm install @tailwindcss/postcss
+```
+
+**For CLI:**
+
+```bash
+npm install @tailwindcss/cli
+```
+
+- [ ] Remove deprecated dependencies
+
+```bash
+npm uninstall autoprefixer postcss-import @tailwindcss/container-queries
+```
+
+- [ ] Update package.json
+
+```json
+{
+  "dependencies": {
+    "tailwindcss": "^4.0.0"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "^4.0.0"
+  }
+}
+```
+
+## Phase 2: Build Configuration
+
+### Vite Configuration
+
+- [ ] Update vite.config.js
+
+```javascript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+- [ ] Remove PostCSS config if using Vite plugin
+- [ ] Test build: `npm run build`
+
+### PostCSS Configuration
+
+- [ ] Update postcss.config.js
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+- [ ] Remove autoprefixer and postcss-import
+- [ ] Test build: `npm run build`
+
+### Next.js Configuration
+
+- [ ] Ensure postcss.config.js exists
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+- [ ] Test: `npm run dev`
+
+## Phase 3: CSS Configuration
+
+### Migrate tailwind.config.js to @theme
+
+- [ ] Open tailwind.config.js
+- [ ] Open main CSS file (e.g., src/index.css)
+- [ ] Replace @tailwind directives
+
+**Old:**
+
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+```
+
+**New:**
+
+```css
+@import 'tailwindcss';
+```
+
+- [ ] Convert theme.extend to @theme
+
+**Example conversion:**
+
+**tailwind.config.js:**
+
+```javascript
+module.exports = {
+  theme: {
+    extend: {
+      colors: {
+        brand: '#3b82f6',
+        accent: '#a855f7',
+      },
+      fontFamily: {
+        sans: ['Inter', 'sans-serif'],
+      },
+      spacing: {
+        18: '4.5rem',
+      },
+    },
+  },
+};
+```
+
+**CSS:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', sans-serif;
+  --color-brand: oklch(0.65 0.25 270);
+  --color-accent: oklch(0.65 0.25 320);
+  --spacing-18: 4.5rem;
+}
+```
+
+- [ ] Convert hex colors to oklch() using https://oklch.com/
+- [ ] Test: colors render correctly
+
+### Content Detection
+
+- [ ] Remove content array (automatic detection)
+- [ ] Add @source directives if needed
+
+```css
+@source "../packages/ui";
+@source not "./legacy";
+```
+
+- [ ] Verify all template files are detected
+- [ ] Check .gitignore excludes node_modules
+
+### Custom CSS
+
+- [ ] Migrate @layer components to CSS
+
+```css
+@layer components {
+  .btn {
+    padding: var(--spacing-2) var(--spacing-4);
+    background: var(--color-blue-600);
+    border-radius: var(--radius-md);
+  }
+}
+```
+
+- [ ] Convert @layer utilities to @utility
+
+**Old:**
+
+```css
+@layer utilities {
+  .content-auto {
+    content-visibility: auto;
+  }
+}
+```
+
+**New:**
+
+```css
+@utility content-auto {
+  content-visibility: auto;
+}
+```
+
+## Phase 4: Utility Class Updates
+
+### Opacity Modifiers
+
+- [ ] Search for opacity utilities
+
+```bash
+grep -r "bg-opacity-" src/
+grep -r "text-opacity-" src/
+grep -r "border-opacity-" src/
+grep -r "ring-opacity-" src/
+```
+
+- [ ] Replace with slash syntax
+
+**Find and replace:**
+
+- `bg-{color} bg-opacity-{value}` → `bg-{color}/{value}`
+- `text-{color} text-opacity-{value}` → `text-{color}/{value}`
+- `border-{color} border-opacity-{value}` → `border-{color}/{value}`
+
+**Example:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+→
+<div class="bg-black/50"></div>
+```
+
+- [ ] Test: opacity values render correctly
+
+### Flex Utilities
+
+- [ ] Search for flex utilities
+
+```bash
+grep -r "flex-shrink" src/
+grep -r "flex-grow" src/
+```
+
+- [ ] Replace with new names
+
+**Find and replace:**
+
+- `flex-shrink-0` → `shrink-0`
+- `flex-shrink` → `shrink`
+- `flex-grow-0` → `grow-0`
+- `flex-grow` → `grow`
+
+### Shadow Utilities
+
+- [ ] Search for shadow-sm
+
+```bash
+grep -r "shadow-sm" src/
+```
+
+- [ ] Replace with shadow-xs
+
+```
+shadow-sm → shadow-xs
+```
+
+### Ring Utilities
+
+- [ ] Search for bare `ring` class
+
+```bash
+grep -r 'class="[^"]*ring[^-"]' src/
+```
+
+- [ ] Add explicit width if expecting 3px default
+
+```html
+<input class="ring" />
+→
+<input class="ring-3" />
+```
+
+### Border Utilities
+
+- [ ] Search for bare `border` class
+
+```bash
+grep -r 'class="[^"]*border[^-"]' src/
+```
+
+- [ ] Add explicit color if expecting gray
+
+```html
+<div class="border"></div>
+→
+<div class="border border-gray-200"></div>
+```
+
+## Phase 5: Arbitrary Values
+
+### Space Handling
+
+- [ ] Search for arbitrary values with commas
+
+```bash
+grep -r "grid-cols-\[.*,.*\]" src/
+```
+
+- [ ] Replace commas with underscores
+
+```html
+<div class="grid-cols-[1fr,500px,2fr]"></div>
+→
+<div class="grid-cols-[1fr_500px_2fr]"></div>
+```
+
+## Phase 6: Testing
+
+### Build Tests
+
+- [ ] Run development build: `npm run dev`
+- [ ] Check console for errors
+- [ ] Verify styles load
+- [ ] Run production build: `npm run build`
+- [ ] Check build output
+- [ ] Test production bundle
+
+### Visual Testing
+
+- [ ] Test home page
+- [ ] Test all major pages
+- [ ] Check responsive breakpoints
+- [ ] Verify dark mode (if used)
+- [ ] Test hover states
+- [ ] Test focus states
+- [ ] Check form inputs
+- [ ] Verify buttons
+- [ ] Check modals/overlays
+- [ ] Test animations
+
+### Component Testing
+
+- [ ] Test each component in isolation
+- [ ] Verify colors match
+- [ ] Check spacing
+- [ ] Test typography
+- [ ] Verify shadows and borders
+- [ ] Check opacity values
+
+### Browser Testing
+
+- [ ] Safari 16.4+
+- [ ] Chrome 111+
+- [ ] Firefox 128+
+- [ ] Mobile Safari
+- [ ] Mobile Chrome
+
+## Phase 7: Cleanup
+
+### Remove Old Files
+
+- [ ] Delete tailwind.config.js
+- [ ] Remove old PostCSS config (if using Vite plugin)
+- [ ] Clean node_modules
+
+```bash
+rm -rf node_modules package-lock.json
+npm install
+```
+
+### Update Documentation
+
+- [ ] Update README.md
+- [ ] Document new setup process
+- [ ] Update contribution guide
+- [ ] Note new browser requirements
+
+### Code Review
+
+- [ ] Review all changed files
+- [ ] Check for missed migrations
+- [ ] Verify no broken styles
+- [ ] Run linter: `npm run lint`
+- [ ] Run tests: `npm test`
+
+## Phase 8: Deploy
+
+### Pre-Deploy Checks
+
+- [ ] All tests passing
+- [ ] No console errors
+- [ ] Production build successful
+- [ ] Visual regression tests pass
+- [ ] Performance metrics acceptable
+
+### Deploy
+
+- [ ] Merge PR to main
+- [ ] Deploy to staging
+- [ ] Test staging environment
+- [ ] Deploy to production
+- [ ] Monitor for issues
+
+### Post-Deploy
+
+- [ ] Verify production site
+- [ ] Check analytics for errors
+- [ ] Monitor performance
+- [ ] Gather feedback
+
+## Common Issues Checklist
+
+- [ ] Styles not applying → Check @import syntax
+- [ ] Build errors → Verify PostCSS/Vite config
+- [ ] Colors different → Convert hex to oklch
+- [ ] Borders wrong color → Add explicit border color
+- [ ] Placeholders wrong → Check preflight changes
+- [ ] Buttons wrong cursor → Add cursor-pointer
+- [ ] Missing utilities → Check for typos
+- [ ] Dark mode broken → Verify class strategy
+
+## Rollback Plan
+
+If migration fails:
+
+- [ ] Revert git branch: `git checkout main`
+- [ ] Delete branch: `git branch -D upgrade-tailwind-v4`
+- [ ] Reinstall dependencies: `npm install`
+- [ ] Document issues encountered
+- [ ] Plan remediation
+
+## Success Criteria
+
+- [ ] All pages render correctly
+- [ ] No console errors
+- [ ] Production build successful
+- [ ] All tests passing
+- [ ] Performance maintained or improved
+- [ ] No visual regressions
+- [ ] Browser support verified
+- [ ] Documentation updated
+
+## Estimated Timeline
+
+- Pre-migration: 1 hour
+- Dependencies & build config: 1-2 hours
+- CSS migration: 2-4 hours
+- Utility updates: 4-8 hours
+- Testing: 4-8 hours
+- Cleanup & documentation: 1-2 hours
+- Deploy: 1-2 hours
+
+**Total: 14-27 hours** depending on project size

skills/reviewing-tailwind-patterns/SKILL.md

@@ -0,0 +1,372 @@
+---
+name: reviewing-tailwind-patterns
+description: Review Tailwind CSS v4 patterns for configuration, theming, and utility usage. Use when reviewing CSS files, Vite configs, or components using Tailwind.
+review: true
+allowed-tools: Read, Grep, Glob
+---
+
+# Reviewing Tailwind v4 Patterns
+
+## Purpose
+
+Review Tailwind CSS v4 implementations for correct configuration, modern patterns, and best practices.
+
+## Review Checklist
+
+### Configuration Review
+
+**Check build tool configuration:**
+
+- [ ] Using `@tailwindcss/vite` for Vite projects (preferred over PostCSS)
+- [ ] Using `@tailwindcss/postcss` for other build tools
+- [ ] No `tailwind.config.js` file (v4 uses CSS configuration)
+- [ ] PostCSS config uses correct plugin name (`@tailwindcss/postcss`)
+- [ ] Not using deprecated plugins (autoprefixer, postcss-import)
+
+**Vite config pattern:**
+
+```javascript
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [react(), tailwindcss()],
+});
+```
+
+**PostCSS config pattern:**
+
+```javascript
+export default {
+  plugins: {
+    '@tailwindcss/postcss': {},
+  },
+};
+```
+
+### CSS File Review
+
+**Check import syntax:**
+
+- [ ] Using `@import 'tailwindcss';` (not @tailwind directives)
+- [ ] @theme directive present for customization
+- [ ] Theme variables use correct namespaces
+- [ ] Colors use oklch() format (not hex or rgb)
+- [ ] @keyframes defined within @theme (not outside)
+
+**Correct pattern:**
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', sans-serif;
+  --color-primary: oklch(0.65 0.25 270);
+  --spacing-18: 4.5rem;
+
+  @keyframes fade-in {
+    0% { opacity: 0; }
+    100% { opacity: 1; }
+  }
+}
+```
+
+**Anti-patterns:**
+
+```css
+@tailwind base;
+
+@theme {
+  --color-primary: #3b82f6;
+}
+
+@keyframes fade-in {
+  0% { opacity: 0; }
+  100% { opacity: 1; }
+}
+```
+
+### Theme Variables Review
+
+**Check namespace usage:**
+
+- [ ] Color variables use `--color-*` prefix
+- [ ] Font families use `--font-*` prefix
+- [ ] Spacing uses `--spacing-*` prefix
+- [ ] Border radius uses `--radius-*` prefix
+- [ ] Animations use `--animate-*` prefix
+- [ ] Semantic naming over generic scales
+
+**Good pattern:**
+
+```css
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+  --color-success: oklch(0.72 0.15 142);
+  --color-error: oklch(0.65 0.22 25);
+}
+```
+
+**Anti-pattern:**
+
+```css
+@theme {
+  --primary: oklch(0.65 0.25 270);
+  --blue: oklch(0.75 0.22 320);
+  --my-color: oklch(0.72 0.15 142);
+}
+```
+
+### Color Format Review
+
+**Check color definitions:**
+
+- [ ] Using oklch() format (not hex, rgb, or hsl)
+- [ ] Lightness between 0-1
+- [ ] Chroma between 0-0.4
+- [ ] Hue between 0-360
+
+**Correct:**
+
+```css
+--color-brand: oklch(0.65 0.25 270);
+```
+
+**Incorrect:**
+
+```css
+--color-brand: #3b82f6;
+--color-accent: rgb(168, 85, 247);
+--color-success: hsl(142, 76%, 36%);
+```
+
+### Utility Usage Review
+
+**Check for v3 patterns:**
+
+- [ ] No `bg-opacity-*` utilities (use `bg-{color}/{opacity}`)
+- [ ] No `flex-shrink-*` (use `shrink-*`)
+- [ ] No `flex-grow-*` (use `grow-*`)
+- [ ] No `shadow-sm` (use `shadow-xs`)
+- [ ] Explicit border colors (not bare `border`)
+- [ ] Explicit ring widths if expecting 3px (use `ring-3`)
+
+**v4 patterns:**
+
+```html
+<div class="bg-black/50"></div>
+<div class="shrink-0 grow"></div>
+<div class="shadow-xs"></div>
+<div class="border border-gray-200"></div>
+<input class="ring-3 ring-blue-500" />
+```
+
+**v3 anti-patterns:**
+
+```html
+<div class="bg-black bg-opacity-50"></div>
+<div class="flex-shrink-0 flex-grow"></div>
+<div class="shadow-sm"></div>
+<div class="border"></div>
+<input class="ring" />
+```
+
+### Container Query Review
+
+**Check container query usage:**
+
+- [ ] Parent has `@container` or `@container/{name}`
+- [ ] Container breakpoints use `@` prefix
+- [ ] Named containers use consistent naming
+- [ ] Mixing container and viewport queries correctly
+
+**Correct pattern:**
+
+```html
+<div class="@container/main">
+  <div class="grid-cols-1 @md/main:grid-cols-2 @lg/main:grid-cols-3"></div>
+</div>
+```
+
+**Anti-pattern:**
+
+```html
+<div>
+  <div class="grid-cols-1 @md:grid-cols-2"></div>
+</div>
+```
+
+### Custom Utility Review
+
+**Check @utility usage:**
+
+- [ ] Using `@utility` (not `@layer utilities`)
+- [ ] Using `--value()` functions correctly
+- [ ] Supporting arbitrary values when appropriate
+- [ ] Providing variant support
+
+**Correct pattern:**
+
+```css
+@utility tab-* {
+  tab-size: --value(--tab-size- *);
+  tab-size: --value(integer);
+  tab-size: --value([integer]);
+}
+```
+
+**Anti-pattern:**
+
+```css
+@layer utilities {
+  .tab-4 {
+    tab-size: 4;
+  }
+}
+```
+
+### Animation Review
+
+**Check animation patterns:**
+
+- [ ] @keyframes defined within @theme
+- [ ] Animation variables use `--animate-*` prefix
+- [ ] Animation shorthand includes timing
+- [ ] Using `starting:` variant for entry animations
+
+**Correct pattern:**
+
+```css
+@theme {
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  @keyframes fade-in {
+    0% { opacity: 0; }
+    100% { opacity: 1; }
+  }
+}
+```
+
+**Anti-pattern:**
+
+```css
+@keyframes fade-in {
+  0% { opacity: 0; }
+  100% { opacity: 1; }
+}
+
+@theme {
+  --animate-fade-in: fade-in;
+}
+```
+
+### Component Pattern Review
+
+**Check component reusability:**
+
+- [ ] Components use container queries for portability
+- [ ] Semantic color names (not numbered scales)
+- [ ] Responsive utilities applied appropriately
+- [ ] Dark mode variants when needed
+
+**Good pattern:**
+
+```html
+<div class="@container">
+  <article class="bg-white dark:bg-gray-900 rounded-lg p-4 @md:p-6">
+    <h2 class="text-lg @md:text-xl font-bold text-primary">Title</h2>
+    <p class="text-sm @md:text-base text-gray-600 dark:text-gray-300">Content</p>
+  </article>
+</div>
+```
+
+### Source Detection Review
+
+**Check content detection:**
+
+- [ ] No manual content array (automatic detection)
+- [ ] Using `@source` only when needed
+- [ ] Excluding unnecessary directories with `@source not`
+- [ ] node_modules in .gitignore
+
+**When to use @source:**
+
+```css
+@source "../packages/ui";
+@source not "./legacy";
+```
+
+**Don't do this:**
+
+```css
+@import 'tailwindcss' source(none);
+@source "./src/**/*.{html,js,jsx,ts,tsx}";
+```
+
+## Common Issues to Flag
+
+### High Priority
+
+1. **Using v3 syntax** - Opacity utilities, flex utilities
+2. **Wrong import syntax** - `@tailwind` instead of `@import`
+3. **Hex colors in theme** - Should use oklch()
+4. **Wrong PostCSS plugin** - Should be `@tailwindcss/postcss`
+5. **Missing @container** - Container queries without parent
+
+### Medium Priority
+
+1. **Non-semantic color names** - Using numbered scales
+2. **Bare border/ring classes** - May render unexpectedly
+3. **@keyframes outside @theme** - Won't generate utilities
+4. **Wrong namespace prefixes** - Won't generate correct utilities
+5. **Using @layer utilities** - Should use @utility
+
+### Low Priority
+
+1. **No dark mode variants** - May be intentional
+2. **Mixing viewport and container queries** - May be correct
+3. **Arbitrary values** - Sometimes necessary
+4. **Not using Vite plugin** - PostCSS is valid alternative
+
+## Review Process
+
+1. **Check configuration** - Vite/PostCSS setup
+2. **Review CSS file** - Import syntax, @theme, @utility
+3. **Scan components** - Utility patterns, container queries
+4. **Test build** - Verify compilation
+5. **Visual check** - Confirm styles apply correctly
+
+## Review Report Template
+
+```markdown
+## Tailwind v4 Review
+
+### Configuration
+- [ ] Build tool: [Vite/PostCSS/Other]
+- [ ] Using correct plugin
+- [ ] No v3 config file
+
+### CSS
+- [ ] Correct import syntax
+- [ ] Theme variables properly namespaced
+- [ ] Colors using oklch()
+- [ ] Animations within @theme
+
+### Components
+- [ ] Container queries used correctly
+- [ ] Semantic naming
+- [ ] No v3 utility patterns
+
+### Issues Found
+1. [Priority] [Description]
+2. [Priority] [Description]
+
+### Recommendations
+- [Specific recommendation]
+- [Specific recommendation]
+```
+
+## See Also
+
+- All other skills in tailwind-4 plugin for detailed patterns
+- RESEARCH.md for comprehensive v4 documentation

skills/using-container-queries/SKILL.md

@@ -0,0 +1,309 @@
+---
+name: using-container-queries
+description: Use container queries for component-based responsive design with @container syntax and named containers. Use when building portable, reusable components that adapt to parent size instead of viewport.
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Using Container Queries
+
+## Purpose
+
+Container queries enable components to respond to their parent container's size instead of the viewport. This creates truly portable, reusable components that work anywhere.
+
+## Basic Container Queries
+
+**Step 1: Mark the container**
+
+```html
+<div class="@container">
+  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4 gap-4">
+    <div>Card 1</div>
+    <div>Card 2</div>
+    <div>Card 3</div>
+    <div>Card 4</div>
+  </div>
+</div>
+```
+
+The `@container` class makes an element a container query context.
+
+**Step 2: Use container breakpoints**
+
+Container breakpoint utilities use `@` prefix:
+
+- `@sm:` - Container width ≥ 640px
+- `@md:` - Container width ≥ 768px
+- `@lg:` - Container width ≥ 1024px
+- `@xl:` - Container width ≥ 1280px
+- `@2xl:` - Container width ≥ 1536px
+
+## Container vs Viewport Queries
+
+**Viewport queries (viewport width):**
+
+```html
+<div class="grid-cols-1 md:grid-cols-2 lg:grid-cols-3"></div>
+```
+
+Responds to browser window width.
+
+**Container queries (parent width):**
+
+```html
+<div class="@container">
+  <div class="grid-cols-1 @md:grid-cols-2 @lg:grid-cols-3"></div>
+</div>
+```
+
+Responds to parent container width.
+
+## Named Containers
+
+Use named containers for nested container queries:
+
+```html
+<div class="@container/main">
+  <div class="@container/sidebar">
+    <div class="flex flex-col @sm/main:flex-row">
+      Main container responsive
+    </div>
+
+    <div class="text-sm @md/sidebar:text-base">
+      Sidebar container responsive
+    </div>
+  </div>
+</div>
+```
+
+**Syntax:** `@container/{name}` for the container, `@{breakpoint}/{name}:` for utilities.
+
+## Portability Patterns
+
+### Reusable Card Component
+
+```html
+<div class="@container">
+  <article class="bg-white rounded-lg shadow-md p-4 @md:p-6">
+    <div class="flex flex-col @md:flex-row @md:gap-6">
+      <img class="w-full @md:w-48 rounded-lg" src="/image.jpg" />
+
+      <div class="flex-1 mt-4 @md:mt-0">
+        <h2 class="text-lg @md:text-xl @lg:text-2xl font-bold">Card Title</h2>
+
+        <p class="mt-2 text-sm @md:text-base text-gray-600">
+          Card description that adapts to container size.
+        </p>
+
+        <button class="mt-4 px-3 py-1.5 @md:px-4 @md:py-2 bg-blue-600 text-white rounded-md">
+          Read More
+        </button>
+      </div>
+    </div>
+  </article>
+</div>
+```
+
+This card works in:
+- Full-width layouts
+- Sidebar layouts
+- Grid layouts
+- Any container size
+
+### Dashboard Widget
+
+```html
+<div class="@container">
+  <div class="bg-white rounded-lg p-4">
+    <div class="flex items-center justify-between">
+      <h3 class="text-base @md:text-lg font-semibold">Widget Title</h3>
+      <button class="text-xs @md:text-sm text-blue-600">View All</button>
+    </div>
+
+    <div class="mt-4 grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 gap-3 @md:gap-4">
+      <div class="p-3 bg-gray-50 rounded">Stat 1</div>
+      <div class="p-3 bg-gray-50 rounded">Stat 2</div>
+      <div class="p-3 bg-gray-50 rounded">Stat 3</div>
+    </div>
+  </div>
+</div>
+```
+
+### Responsive Navigation
+
+```html
+<div class="@container/nav">
+  <nav class="flex flex-col @md/nav:flex-row @md/nav:items-center gap-2 @md/nav:gap-6">
+    <a href="#" class="text-sm @md/nav:text-base">Home</a>
+    <a href="#" class="text-sm @md/nav:text-base">About</a>
+    <a href="#" class="text-sm @md/nav:text-base">Services</a>
+    <a href="#" class="text-sm @md/nav:text-base">Contact</a>
+  </nav>
+</div>
+```
+
+## Complex Layout Example
+
+```html
+<div class="@container">
+  <div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 @xl:grid-cols-4 gap-4 @md:gap-6 @lg:gap-8">
+    <div class="@container/card">
+      <article class="bg-white rounded-lg shadow-md overflow-hidden">
+        <div class="relative h-32 @md/card:h-48 bg-gradient-to-br from-blue-500 to-purple-600">
+          <img class="w-full h-full object-cover" src="/image.jpg" />
+        </div>
+
+        <div class="p-3 @md/card:p-4 @lg/card:p-6">
+          <h3 class="text-base @md/card:text-lg @lg/card:text-xl font-bold">
+            Card Title
+          </h3>
+
+          <p class="mt-2 text-xs @md/card:text-sm @lg/card:text-base text-gray-600 line-clamp-2 @lg/card:line-clamp-3">
+            Description that adapts based on available space in the card container.
+          </p>
+
+          <div class="mt-3 @md/card:mt-4 flex items-center justify-between">
+            <span class="text-xs @md/card:text-sm text-gray-500">2 days ago</span>
+
+            <button class="px-2 py-1 @md/card:px-3 @md/card:py-1.5 text-xs @md/card:text-sm bg-blue-600 text-white rounded">
+              Read
+            </button>
+          </div>
+        </div>
+      </article>
+    </div>
+  </div>
+</div>
+```
+
+## Mixing Container and Viewport Queries
+
+You can combine both for maximum control:
+
+```html
+<div class="@container">
+  <div class="
+    grid
+    grid-cols-1
+    md:grid-cols-2
+    lg:grid-cols-3
+    @lg:grid-cols-2
+    @xl:grid-cols-3
+  ">
+    Components adapt to both viewport and container
+  </div>
+</div>
+```
+
+**Order matters:** Viewport queries first, then container queries to override.
+
+## Container Query Breakpoints
+
+Default container breakpoints:
+
+| Breakpoint | Min Width |
+| ---------- | --------- |
+| `@xs`      | 320px     |
+| `@sm`      | 640px     |
+| `@md`      | 768px     |
+| `@lg`      | 1024px    |
+| `@xl`      | 1280px    |
+| `@2xl`     | 1536px    |
+
+## Custom Container Breakpoints
+
+Define custom container breakpoints in theme:
+
+```css
+@theme {
+  --container-xs: 20rem;
+  --container-sm: 40rem;
+  --container-md: 48rem;
+  --container-lg: 64rem;
+  --container-xl: 80rem;
+}
+```
+
+## Performance Considerations
+
+Container queries are highly performant in modern browsers. They:
+
+- Use native browser APIs
+- Don't require JavaScript
+- Trigger efficient reflows
+- Work with CSS cascade layers
+
+## Browser Support
+
+Container queries require:
+- Safari 16.4+
+- Chrome 111+
+- Firefox 128+
+
+Same as Tailwind v4's minimum browser requirements.
+
+## Best Practices
+
+1. **Use for component portability** - Container queries excel at making components work anywhere
+2. **Name containers when nested** - Use `/name` syntax for clarity
+3. **Prefer container queries for components** - Use viewport queries for page-level layouts
+4. **Combine with viewport queries** - Use both for maximum flexibility
+5. **Test at various sizes** - Verify components work in narrow and wide containers
+
+## Common Patterns
+
+### Sidebar Layout
+
+```html
+<div class="flex gap-6">
+  <aside class="w-64 @container/sidebar">
+    <nav class="space-y-2">
+      <a class="block p-2 text-sm @md/sidebar:text-base">Link 1</a>
+      <a class="block p-2 text-sm @md/sidebar:text-base">Link 2</a>
+    </nav>
+  </aside>
+
+  <main class="flex-1 @container/main">
+    <div class="grid grid-cols-1 @lg/main:grid-cols-2 gap-4">
+      <div>Content 1</div>
+      <div>Content 2</div>
+    </div>
+  </main>
+</div>
+```
+
+### Product Grid
+
+```html
+<div class="@container">
+  <div class="grid grid-cols-2 @md:grid-cols-3 @lg:grid-cols-4 @xl:grid-cols-5 gap-4">
+    <div class="@container/product">
+      <div class="bg-white rounded-lg p-3 @md/product:p-4">
+        <img class="w-full aspect-square rounded" src="/product.jpg" />
+        <h3 class="mt-2 text-sm @md/product:text-base font-medium">Product</h3>
+        <p class="mt-1 text-xs @md/product:text-sm text-gray-600">$99</p>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+### Form Layout
+
+```html
+<div class="@container">
+  <form class="space-y-4 @md:space-y-6">
+    <div class="grid grid-cols-1 @md:grid-cols-2 gap-4 @md:gap-6">
+      <input class="px-3 py-2 @md:px-4 @md:py-3 border rounded" placeholder="First Name" />
+      <input class="px-3 py-2 @md:px-4 @md:py-3 border rounded" placeholder="Last Name" />
+    </div>
+
+    <button class="w-full px-4 py-2 @md:px-6 @md:py-3 bg-blue-600 text-white rounded">
+      Submit
+    </button>
+  </form>
+</div>
+```
+
+## See Also
+
+- RESEARCH.md sections: "Container Queries" and "Usage Patterns"

skills/using-theme-variables/SKILL.md

@@ -0,0 +1,289 @@
+---
+name: using-theme-variables
+description: Define and use theme variables with @theme directive, oklch() color format, semantic naming, and namespaced utilities. Use when customizing design tokens or creating design systems.
+allowed-tools: Read, Write, Edit, Grep, Glob
+---
+
+# Using Theme Variables
+
+## Purpose
+
+Define custom design tokens using the `@theme` directive with CSS variables. Tailwind v4 uses modern color formats (oklch) and namespace-based utility generation.
+
+## Basic Theme Variables
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-display: 'Satoshi', 'sans-serif';
+  --font-body: 'Inter', 'sans-serif';
+
+  --color-brand-primary: oklch(0.65 0.25 270);
+  --color-brand-accent: oklch(0.75 0.22 320);
+
+  --breakpoint-3xl: 120rem;
+  --breakpoint-4xl: 160rem;
+
+  --spacing-18: 4.5rem;
+  --spacing-72: 18rem;
+
+  --radius-4xl: 2rem;
+
+  --shadow-brutal: 8px 8px 0 0 rgb(0 0 0);
+}
+```
+
+## Color Format: oklch()
+
+Tailwind v4 uses OkLCh color space instead of RGB for wider gamut and more vivid colors on modern displays.
+
+**oklch() syntax:**
+
+```
+oklch(Lightness Chroma Hue)
+```
+
+- **Lightness:** 0 (black) to 1 (white)
+- **Chroma:** 0 (gray) to ~0.4 (vivid)
+- **Hue:** 0-360 degrees
+
+**Examples:**
+
+```css
+@theme {
+  --color-blue: oklch(0.65 0.25 270);
+  --color-green: oklch(0.72 0.15 142);
+  --color-red: oklch(0.65 0.22 25);
+  --color-purple: oklch(0.75 0.22 320);
+  --color-orange: oklch(0.78 0.18 60);
+}
+```
+
+## Theme Variable Namespaces
+
+Tailwind generates utilities based on variable name prefixes:
+
+| Namespace         | Utilities Generated                        |
+| ----------------- | ------------------------------------------ |
+| `--color-*`       | bg-, text-, fill-, stroke-, border-, ring- |
+| `--font-*`        | font-family utilities                      |
+| `--text-*`        | font-size utilities                        |
+| `--font-weight-*` | font-weight utilities                      |
+| `--tracking-*`    | letter-spacing utilities                   |
+| `--leading-*`     | line-height utilities                      |
+| `--breakpoint-*`  | responsive breakpoint variants             |
+| `--spacing-*`     | padding, margin, sizing utilities          |
+| `--radius-*`      | border-radius utilities                    |
+| `--shadow-*`      | box-shadow utilities                       |
+| `--animate-*`     | animation utilities                        |
+
+**Example usage:**
+
+```css
+@theme {
+  --color-brand: oklch(0.65 0.25 270);
+  --spacing-18: 4.5rem;
+  --radius-4xl: 2rem;
+}
+```
+
+Generates utilities:
+
+```html
+<div class="bg-brand text-brand border-brand"></div>
+<div class="p-18 m-18 w-18"></div>
+<div class="rounded-4xl"></div>
+```
+
+## Semantic Naming
+
+Use meaningful names instead of generic scales:
+
+```css
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+  --color-success: oklch(0.72 0.15 142);
+  --color-warning: oklch(0.78 0.18 60);
+  --color-error: oklch(0.65 0.22 25);
+
+  --color-text: oklch(0.21 0 0);
+  --color-text-muted: oklch(0.51 0 0);
+  --color-background: oklch(0.99 0 0);
+}
+```
+
+**Usage:**
+
+```html
+<button class="bg-primary text-white hover:opacity-90">Primary Button</button>
+<div class="text-error">Error message</div>
+<p class="text-text-muted">Muted text</p>
+```
+
+## Extending Default Theme
+
+Add new values without removing defaults:
+
+```css
+@theme {
+  --color-lagoon: oklch(0.72 0.11 221.19);
+  --color-coral: oklch(0.74 0.17 40.24);
+  --font-script: 'Great Vibes', cursive;
+  --breakpoint-3xl: 120rem;
+}
+```
+
+All default Tailwind utilities remain available (blue-500, gray-200, etc.).
+
+## Replacing Default Theme
+
+Remove all defaults and define only custom variables:
+
+```css
+@theme {
+  --*: initial;
+
+  --spacing: 4px;
+  --font-body: 'Inter', sans-serif;
+  --color-lagoon: oklch(0.72 0.11 221.19);
+  --color-coral: oklch(0.74 0.17 40.24);
+}
+```
+
+Only utilities based on custom variables will be generated.
+
+## Inline Theme Variables
+
+Reference other variables using the inline option:
+
+```css
+@theme inline {
+  --font-sans: var(--font-inter);
+  --color-primary: var(--color-red-500);
+  --spacing-gutter: var(--spacing-4);
+}
+```
+
+Variables defined in `@theme inline` can reference variables from main `@theme`.
+
+## Static Theme Variables
+
+Generate all CSS variables even if unused:
+
+```css
+@theme static {
+  --color-primary: var(--color-red-500);
+  --color-secondary: var(--color-blue-500);
+}
+```
+
+Useful for runtime JavaScript access:
+
+```javascript
+const styles = getComputedStyle(document.documentElement);
+const primaryColor = styles.getPropertyValue('--color-primary');
+```
+
+## Accessing Variables in JavaScript
+
+```javascript
+const styles = getComputedStyle(document.documentElement);
+const shadow = styles.getPropertyValue('--shadow-xl');
+const color = styles.getPropertyValue('--color-blue-500');
+```
+
+**Setting variables dynamically:**
+
+```javascript
+document.documentElement.style.setProperty('--color-primary', 'oklch(0.70 0.20 180)');
+```
+
+**In animation libraries:**
+
+```jsx
+<motion.div animate={{ backgroundColor: 'var(--color-blue-500)' }} />
+```
+
+## Sharing Themes Across Projects
+
+**Create shared theme file:**
+
+**packages/brand/theme.css:**
+
+```css
+@theme {
+  --*: initial;
+
+  --spacing: 4px;
+  --font-body: 'Inter', sans-serif;
+  --color-lagoon: oklch(0.72 0.11 221.19);
+  --color-coral: oklch(0.74 0.17 40.24);
+}
+```
+
+**Import in projects:**
+
+```css
+@import 'tailwindcss';
+@import '@my-company/brand/theme.css';
+```
+
+## Complex Theme Example
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
+  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+
+  --color-white: #ffffff;
+  --color-black: #000000;
+
+  --color-gray-50: oklch(0.99 0 0);
+  --color-gray-100: oklch(0.97 0 0);
+  --color-gray-900: oklch(0.21 0 0);
+
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+  --color-success: oklch(0.72 0.15 142);
+
+  --spacing: 0.25rem;
+  --spacing-px: 1px;
+  --spacing-1: calc(var(--spacing) * 1);
+  --spacing-4: calc(var(--spacing) * 4);
+
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-full: 9999px;
+
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+
+  --breakpoint-sm: 40rem;
+  --breakpoint-md: 48rem;
+  --breakpoint-lg: 64rem;
+}
+```
+
+## Best Practices
+
+1. **Use semantic names** instead of scales (primary vs blue-500)
+2. **Use oklch()** for color definitions
+3. **Define variables at :root** for performance
+4. **Group related variables** (colors, spacing, typography)
+5. **Reference other variables** with inline theme
+6. **Share themes** across projects using imports
+
+## See Also
+
+- references/color-conversion.md - Hex to oklch conversion table
+- references/namespace-reference.md - Complete namespace documentation

skills/using-theme-variables/references/color-conversion.md

@@ -0,0 +1,179 @@
+# Color Conversion: Hex to oklch()
+
+## Common Color Conversions
+
+### Grays
+
+| Hex       | oklch()              | Description    |
+| --------- | -------------------- | -------------- |
+| `#ffffff` | `oklch(1 0 0)`       | White          |
+| `#f9fafb` | `oklch(0.99 0 0)`    | Gray 50        |
+| `#f3f4f6` | `oklch(0.97 0 0)`    | Gray 100       |
+| `#e5e7eb` | `oklch(0.93 0 0)`    | Gray 200       |
+| `#d1d5db` | `oklch(0.88 0 0)`    | Gray 300       |
+| `#9ca3af` | `oklch(0.74 0 0)`    | Gray 400       |
+| `#6b7280` | `oklch(0.62 0 0)`    | Gray 500       |
+| `#4b5563` | `oklch(0.51 0 0)`    | Gray 600       |
+| `#374151` | `oklch(0.42 0 0)`    | Gray 700       |
+| `#1f2937` | `oklch(0.31 0 0)`    | Gray 800       |
+| `#111827` | `oklch(0.21 0 0)`    | Gray 900       |
+| `#000000` | `oklch(0 0 0)`       | Black          |
+
+### Blues
+
+| Hex       | oklch()              | Description    |
+| --------- | -------------------- | -------------- |
+| `#eff6ff` | `oklch(0.98 0.01 250)` | Blue 50      |
+| `#dbeafe` | `oklch(0.95 0.03 250)` | Blue 100     |
+| `#bfdbfe` | `oklch(0.90 0.06 250)` | Blue 200     |
+| `#93c5fd` | `oklch(0.82 0.10 250)` | Blue 300     |
+| `#60a5fa` | `oklch(0.73 0.16 250)` | Blue 400     |
+| `#3b82f6` | `oklch(0.65 0.25 270)` | Blue 500     |
+| `#2563eb` | `oklch(0.55 0.28 270)` | Blue 600     |
+| `#1d4ed8` | `oklch(0.47 0.27 270)` | Blue 700     |
+| `#1e40af` | `oklch(0.40 0.24 270)` | Blue 800     |
+| `#1e3a8a` | `oklch(0.33 0.20 270)` | Blue 900     |
+
+### Greens
+
+| Hex       | oklch()              | Description    |
+| --------- | -------------------- | -------------- |
+| `#f0fdf4` | `oklch(0.99 0.01 142)` | Green 50     |
+| `#dcfce7` | `oklch(0.97 0.03 142)` | Green 100    |
+| `#bbf7d0` | `oklch(0.93 0.07 142)` | Green 200    |
+| `#86efac` | `oklch(0.87 0.13 142)` | Green 300    |
+| `#4ade80` | `oklch(0.79 0.18 142)` | Green 400    |
+| `#22c55e` | `oklch(0.72 0.15 142)` | Green 500    |
+| `#16a34a` | `oklch(0.61 0.17 142)` | Green 600    |
+| `#15803d` | `oklch(0.50 0.15 142)` | Green 700    |
+| `#166534` | `oklch(0.41 0.13 142)` | Green 800    |
+| `#14532d` | `oklch(0.33 0.11 142)` | Green 900    |
+
+### Reds
+
+| Hex       | oklch()              | Description    |
+| --------- | -------------------- | -------------- |
+| `#fef2f2` | `oklch(0.98 0.01 25)` | Red 50         |
+| `#fee2e2` | `oklch(0.95 0.03 25)` | Red 100        |
+| `#fecaca` | `oklch(0.90 0.06 25)` | Red 200        |
+| `#fca5a5` | `oklch(0.82 0.11 25)` | Red 300        |
+| `#f87171` | `oklch(0.73 0.16 25)` | Red 400        |
+| `#ef4444` | `oklch(0.65 0.22 25)` | Red 500        |
+| `#dc2626` | `oklch(0.55 0.24 25)` | Red 600        |
+| `#b91c1c` | `oklch(0.47 0.22 25)` | Red 700        |
+| `#991b1b` | `oklch(0.40 0.19 25)` | Red 800        |
+| `#7f1d1d` | `oklch(0.33 0.16 25)` | Red 900        |
+
+### Purples
+
+| Hex       | oklch()              | Description      |
+| --------- | -------------------- | ---------------- |
+| `#faf5ff` | `oklch(0.98 0.01 320)` | Purple 50      |
+| `#f3e8ff` | `oklch(0.95 0.04 320)` | Purple 100     |
+| `#e9d5ff` | `oklch(0.89 0.08 320)` | Purple 200     |
+| `#d8b4fe` | `oklch(0.82 0.14 320)` | Purple 300     |
+| `#c084fc` | `oklch(0.73 0.20 320)` | Purple 400     |
+| `#a855f7` | `oklch(0.65 0.25 320)` | Purple 500     |
+| `#9333ea` | `oklch(0.55 0.28 320)` | Purple 600     |
+| `#7e22ce` | `oklch(0.47 0.27 320)` | Purple 700     |
+| `#6b21a8` | `oklch(0.40 0.24 320)` | Purple 800     |
+| `#581c87` | `oklch(0.33 0.20 320)` | Purple 900     |
+
+### Yellows / Oranges
+
+| Hex       | oklch()              | Description      |
+| --------- | -------------------- | ---------------- |
+| `#fef3c7` | `oklch(0.96 0.05 90)` | Yellow 100       |
+| `#fde047` | `oklch(0.90 0.15 90)` | Yellow 300       |
+| `#facc15` | `oklch(0.82 0.18 90)` | Yellow 400       |
+| `#eab308` | `oklch(0.75 0.20 90)` | Yellow 500       |
+| `#fed7aa` | `oklch(0.89 0.07 60)` | Orange 200       |
+| `#fdba74` | `oklch(0.82 0.12 60)` | Orange 300       |
+| `#fb923c` | `oklch(0.75 0.16 60)` | Orange 400       |
+| `#f97316` | `oklch(0.68 0.20 60)` | Orange 500       |
+| `#ea580c` | `oklch(0.60 0.22 60)` | Orange 600       |
+
+### Teals / Cyans
+
+| Hex       | oklch()                | Description    |
+| --------- | ---------------------- | -------------- |
+| `#ccfbf1` | `oklch(0.95 0.04 180)` | Teal 100       |
+| `#99f6e4` | `oklch(0.92 0.08 180)` | Teal 200       |
+| `#5eead4` | `oklch(0.86 0.13 180)` | Teal 300       |
+| `#2dd4bf` | `oklch(0.79 0.16 180)` | Teal 400       |
+| `#14b8a6` | `oklch(0.72 0.17 180)` | Teal 500       |
+| `#cffafe` | `oklch(0.98 0.02 200)` | Cyan 100       |
+| `#a5f3fc` | `oklch(0.94 0.05 200)` | Cyan 200       |
+| `#67e8f9` | `oklch(0.88 0.10 200)` | Cyan 300       |
+| `#22d3ee` | `oklch(0.81 0.15 200)` | Cyan 400       |
+| `#06b6d4` | `oklch(0.73 0.18 200)` | Cyan 500       |
+
+## Conversion Tips
+
+### Understanding oklch() Parameters
+
+**Lightness (0-1):**
+- 0.95-1.0: Very light colors (50-100)
+- 0.80-0.95: Light colors (200-300)
+- 0.65-0.80: Medium colors (400-500)
+- 0.45-0.65: Dark colors (600-700)
+- 0.20-0.45: Very dark colors (800-900)
+- 0-0.20: Near black
+
+**Chroma (0-0.4):**
+- 0: Grayscale
+- 0.01-0.05: Very muted
+- 0.05-0.15: Muted
+- 0.15-0.25: Vibrant
+- 0.25+: Very vivid
+
+**Hue (0-360):**
+- 0-30: Red
+- 30-60: Orange
+- 60-90: Yellow
+- 90-150: Green
+- 150-210: Cyan/Teal
+- 210-270: Blue
+- 270-330: Purple/Violet
+- 330-360: Magenta/Pink
+
+## Online Conversion Tools
+
+1. **OKLCH Color Picker:** https://oklch.com/
+2. **Evil Martians OKLCH Converter:** https://oklch.evilmartians.io/
+3. **Colorjs.io:** https://colorjs.io/apps/convert/
+
+## Manual Conversion Process
+
+1. Convert hex to RGB
+2. Use online tool to convert RGB to OkLCh
+3. Round values to 2 decimal places
+4. Test in browser to verify appearance
+
+**Example:**
+
+```
+Hex: #3b82f6 (Tailwind Blue 500)
+RGB: rgb(59, 130, 246)
+OkLCh: oklch(0.65 0.25 270)
+```
+
+## Custom Color Palette Example
+
+```css
+@theme {
+  --color-brand-purple: oklch(0.65 0.25 320);
+  --color-brand-blue: oklch(0.65 0.25 270);
+  --color-brand-teal: oklch(0.72 0.17 180);
+
+  --color-success: oklch(0.72 0.15 142);
+  --color-warning: oklch(0.78 0.18 60);
+  --color-error: oklch(0.65 0.22 25);
+  --color-info: oklch(0.73 0.18 200);
+
+  --color-text: oklch(0.21 0 0);
+  --color-text-muted: oklch(0.51 0 0);
+  --color-background: oklch(0.99 0 0);
+  --color-surface: oklch(1 0 0);
+}
+```

skills/using-theme-variables/references/namespace-reference.md

@@ -0,0 +1,450 @@
+# Theme Variable Namespace Reference
+
+## Complete Namespace Documentation
+
+### Color Namespace: `--color-*`
+
+**Generates utilities:** bg-, text-, fill-, stroke-, border-, ring-, outline-, decoration-, caret-
+
+**Definition:**
+
+```css
+@theme {
+  --color-primary: oklch(0.65 0.25 270);
+  --color-brand: oklch(0.75 0.22 320);
+  --color-error: oklch(0.65 0.22 25);
+}
+```
+
+**Usage:**
+
+```html
+<div class="bg-primary text-white border-primary"></div>
+<svg class="fill-brand stroke-brand"></svg>
+<input class="ring-error outline-error caret-error" />
+```
+
+**With opacity modifiers:**
+
+```html
+<div class="bg-primary/50 text-brand/75"></div>
+```
+
+### Font Family: `--font-*`
+
+**Generates utilities:** font-{name}
+
+**Definition:**
+
+```css
+@theme {
+  --font-sans: 'Inter', sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+  --font-display: 'Satoshi', sans-serif;
+  --font-script: 'Great Vibes', cursive;
+}
+```
+
+**Usage:**
+
+```html
+<body class="font-sans">
+  <h1 class="font-display">Heading</h1>
+  <code class="font-mono">Code</code>
+  <p class="font-script">Script text</p>
+</body>
+```
+
+### Font Size: `--text-*`
+
+**Generates utilities:** text-{size}
+
+**Definition:**
+
+```css
+@theme {
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+  --text-3xl: 1.875rem;
+  --text-4xl: 2.25rem;
+}
+```
+
+**Usage:**
+
+```html
+<p class="text-sm">Small text</p>
+<h1 class="text-4xl">Large heading</h1>
+```
+
+### Font Weight: `--font-weight-*`
+
+**Generates utilities:** font-{weight}
+
+**Definition:**
+
+```css
+@theme {
+  --font-weight-thin: 100;
+  --font-weight-light: 300;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+  --font-weight-black: 900;
+}
+```
+
+**Usage:**
+
+```html
+<p class="font-light">Light text</p>
+<strong class="font-bold">Bold text</strong>
+<h1 class="font-black">Black weight</h1>
+```
+
+### Letter Spacing: `--tracking-*`
+
+**Generates utilities:** tracking-{size}
+
+**Definition:**
+
+```css
+@theme {
+  --tracking-tighter: -0.05em;
+  --tracking-tight: -0.025em;
+  --tracking-normal: 0em;
+  --tracking-wide: 0.025em;
+  --tracking-wider: 0.05em;
+  --tracking-widest: 0.1em;
+}
+```
+
+**Usage:**
+
+```html
+<p class="tracking-tight">Tight spacing</p>
+<p class="tracking-wide">Wide spacing</p>
+```
+
+### Line Height: `--leading-*`
+
+**Generates utilities:** leading-{size}
+
+**Definition:**
+
+```css
+@theme {
+  --leading-none: 1;
+  --leading-tight: 1.25;
+  --leading-snug: 1.375;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+  --leading-loose: 2;
+}
+```
+
+**Usage:**
+
+```html
+<p class="leading-tight">Tight line height</p>
+<p class="leading-loose">Loose line height</p>
+```
+
+### Breakpoints: `--breakpoint-*`
+
+**Generates responsive variants:** {breakpoint}:
+
+**Definition:**
+
+```css
+@theme {
+  --breakpoint-sm: 40rem;
+  --breakpoint-md: 48rem;
+  --breakpoint-lg: 64rem;
+  --breakpoint-xl: 80rem;
+  --breakpoint-2xl: 96rem;
+  --breakpoint-3xl: 120rem;
+}
+```
+
+**Usage:**
+
+```html
+<div class="grid-cols-1 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4"></div>
+<p class="text-base lg:text-lg 2xl:text-xl 3xl:text-2xl"></p>
+```
+
+### Spacing: `--spacing-*`
+
+**Generates utilities:** p-, m-, w-, h-, gap-, space-, inset-, top-, right-, bottom-, left-
+
+**Definition:**
+
+```css
+@theme {
+  --spacing: 0.25rem;
+  --spacing-px: 1px;
+  --spacing-0: 0;
+  --spacing-1: calc(var(--spacing) * 1);
+  --spacing-2: calc(var(--spacing) * 2);
+  --spacing-4: calc(var(--spacing) * 4);
+  --spacing-8: calc(var(--spacing) * 8);
+  --spacing-16: calc(var(--spacing) * 16);
+  --spacing-18: 4.5rem;
+  --spacing-72: 18rem;
+}
+```
+
+**Usage:**
+
+```html
+<div class="p-4 m-2 w-18 h-72"></div>
+<div class="gap-8 space-x-4"></div>
+<div class="top-16 left-8"></div>
+```
+
+### Border Radius: `--radius-*`
+
+**Generates utilities:** rounded-{size}
+
+**Definition:**
+
+```css
+@theme {
+  --radius-none: 0;
+  --radius-sm: 0.125rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 0.75rem;
+  --radius-2xl: 1rem;
+  --radius-3xl: 1.5rem;
+  --radius-4xl: 2rem;
+  --radius-full: 9999px;
+}
+```
+
+**Usage:**
+
+```html
+<div class="rounded-md"></div>
+<button class="rounded-lg"></button>
+<div class="rounded-4xl"></div>
+<img class="rounded-full" />
+```
+
+### Box Shadow: `--shadow-*`
+
+**Generates utilities:** shadow-{size}
+
+**Definition:**
+
+```css
+@theme {
+  --shadow-xs: 0 1px 2px 0 rgb(0 0 0 / 0.05);
+  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+  --shadow-xl: 0 20px 25px -5px rgb(0 0 0 / 0.1);
+  --shadow-2xl: 0 25px 50px -12px rgb(0 0 0 / 0.25);
+  --shadow-brutal: 8px 8px 0 0 rgb(0 0 0);
+}
+```
+
+**Usage:**
+
+```html
+<div class="shadow-md"></div>
+<div class="shadow-xl hover:shadow-2xl"></div>
+<div class="shadow-brutal"></div>
+```
+
+### Animations: `--animate-*`
+
+**Generates utilities:** animate-{name}
+
+**Definition:**
+
+```css
+@theme {
+  --animate-spin: spin 1s linear infinite;
+  --animate-ping: ping 1s cubic-bezier(0, 0, 0.2, 1) infinite;
+  --animate-pulse: pulse 2s cubic-bezier(0.4, 0, 0.6, 1) infinite;
+  --animate-bounce: bounce 1s infinite;
+  --animate-fade-in: fade-in 0.3s ease-out;
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  @keyframes ping {
+    75%, 100% {
+      transform: scale(2);
+      opacity: 0;
+    }
+  }
+
+  @keyframes pulse {
+    50% {
+      opacity: 0.5;
+    }
+  }
+
+  @keyframes bounce {
+    0%, 100% {
+      transform: translateY(-25%);
+      animation-timing-function: cubic-bezier(0.8, 0, 1, 1);
+    }
+    50% {
+      transform: none;
+      animation-timing-function: cubic-bezier(0, 0, 0.2, 1);
+    }
+  }
+
+  @keyframes fade-in {
+    0% {
+      opacity: 0;
+    }
+    100% {
+      opacity: 1;
+    }
+  }
+}
+```
+
+**Usage:**
+
+```html
+<div class="animate-spin"></div>
+<div class="animate-pulse"></div>
+<div class="animate-fade-in"></div>
+```
+
+### Z-Index: `--z-*`
+
+**Generates utilities:** z-{index}
+
+**Definition:**
+
+```css
+@theme {
+  --z-0: 0;
+  --z-10: 10;
+  --z-20: 20;
+  --z-30: 30;
+  --z-40: 40;
+  --z-50: 50;
+  --z-modal: 100;
+  --z-dropdown: 200;
+  --z-tooltip: 300;
+}
+```
+
+**Usage:**
+
+```html
+<div class="z-10"></div>
+<div class="z-modal"></div>
+<div class="z-tooltip"></div>
+```
+
+### Aspect Ratio: `--aspect-*`
+
+**Generates utilities:** aspect-{ratio}
+
+**Definition:**
+
+```css
+@theme {
+  --aspect-auto: auto;
+  --aspect-square: 1 / 1;
+  --aspect-video: 16 / 9;
+  --aspect-portrait: 3 / 4;
+  --aspect-ultrawide: 21 / 9;
+}
+```
+
+**Usage:**
+
+```html
+<img class="aspect-square" />
+<video class="aspect-video" />
+<div class="aspect-portrait"></div>
+```
+
+## Complete Example
+
+```css
+@import 'tailwindcss';
+
+@theme {
+  --font-sans: 'Inter', -apple-system, sans-serif;
+  --font-mono: 'JetBrains Mono', monospace;
+  --font-display: 'Satoshi', sans-serif;
+
+  --text-xs: 0.75rem;
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.25rem;
+  --text-2xl: 1.5rem;
+
+  --font-weight-light: 300;
+  --font-weight-normal: 400;
+  --font-weight-medium: 500;
+  --font-weight-semibold: 600;
+  --font-weight-bold: 700;
+
+  --tracking-tight: -0.025em;
+  --tracking-normal: 0em;
+  --tracking-wide: 0.025em;
+
+  --leading-tight: 1.25;
+  --leading-normal: 1.5;
+  --leading-relaxed: 1.625;
+
+  --color-white: #ffffff;
+  --color-black: #000000;
+  --color-gray-50: oklch(0.99 0 0);
+  --color-gray-900: oklch(0.21 0 0);
+
+  --color-primary: oklch(0.65 0.25 270);
+  --color-secondary: oklch(0.75 0.22 320);
+  --color-success: oklch(0.72 0.15 142);
+  --color-error: oklch(0.65 0.22 25);
+
+  --spacing: 0.25rem;
+  --spacing-1: calc(var(--spacing) * 1);
+  --spacing-2: calc(var(--spacing) * 2);
+  --spacing-4: calc(var(--spacing) * 4);
+  --spacing-8: calc(var(--spacing) * 8);
+
+  --radius-sm: 0.125rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-full: 9999px;
+
+  --shadow-sm: 0 1px 3px 0 rgb(0 0 0 / 0.1);
+  --shadow-md: 0 4px 6px -1px rgb(0 0 0 / 0.1);
+  --shadow-lg: 0 10px 15px -3px rgb(0 0 0 / 0.1);
+
+  --breakpoint-sm: 40rem;
+  --breakpoint-md: 48rem;
+  --breakpoint-lg: 64rem;
+  --breakpoint-xl: 80rem;
+
+  --animate-spin: spin 1s linear infinite;
+
+  @keyframes spin {
+    to {
+      transform: rotate(360deg);
+    }
+  }
+}
+```