Initial commit

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