cfsa-antigravity 1.0.0

package/template/.agent/skill-library/stack/css/tailwind-design-system/SKILL.md

@@ -0,0 +1,490 @@
+---
+name: tailwind-design-system
+description: Build production-ready design systems with Tailwind CSS v4, including CSS-first configuration, design tokens, component variants, responsive patterns, and accessibility. Use when building component libraries with Tailwind v4, implementing design tokens and theming with CSS-first configuration, standardizing UI patterns, migrating from Tailwind v3 to v4, or setting up dark mode with native CSS features. Triggers on @theme, @custom-variant, CVA, design tokens, OKLCH, Tailwind v4, @utility.
+---
+
+# Tailwind Design System (v4)
+
+Build production-ready design systems with Tailwind CSS v4, including CSS-first configuration, design tokens, component variants, responsive patterns, and accessibility.
+
+> **Note:** This skill targets Tailwind CSS v4 (2024+). For v3 projects, refer to the [upgrade guide](https://tailwindcss.com/docs/upgrade-guide).
+
+## When to Use This Skill
+
+- Creating a component library with Tailwind v4
+- Implementing design tokens and theming with CSS-first configuration
+- Building responsive and accessible components
+- Standardizing UI patterns across a codebase
+- Migrating from Tailwind v3 to v4
+- Setting up dark mode with native CSS features
+
+## Key v4 Changes
+
+| v3 | v4 |
+|----|-----|
+| `tailwind.config.ts` | `@theme` |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
+| `darkMode: "class"` | `@custom-variant dark (&:where(.dark, .dark *))` |
+| `theme.extend.colors` | `@theme { --color-*: value }` |
+| `require("tailwindcss-animate")` | `@keyframes` + `@theme` + `@starting-style` |
+
+## Quick Start
+
+```css
+/* app.css - Tailwind v4 CSS-first configuration */
+@import "tailwindcss";
+
+/* Define your theme with @theme */
+@theme {
+  /* Semantic color tokens using OKLCH for better color perception */
+  --color-background: oklch(100% 0 0);
+  --color-foreground: oklch(14.5% 0.025 264);
+  --color-primary: oklch(14.5% 0.025 264);
+  --color-primary-foreground: oklch(98% 0.01 264);
+  --color-secondary: oklch(96% 0.01 264);
+  --color-secondary-foreground: oklch(14.5% 0.025 264);
+  --color-muted: oklch(96% 0.01 264);
+  --color-muted-foreground: oklch(46% 0.02 264);
+  --color-accent: oklch(96% 0.01 264);
+  --color-accent-foreground: oklch(14.5% 0.025 264);
+  --color-destructive: oklch(53% 0.22 27);
+  --color-destructive-foreground: oklch(98% 0.01 264);
+  --color-border: oklch(91% 0.01 264);
+  --color-ring: oklch(14.5% 0.025 264);
+  --color-card: oklch(100% 0 0);
+  --color-card-foreground: oklch(14.5% 0.025 264);
+
+  /* Ring offset for focus states */
+  --color-ring-offset: oklch(100% 0 0);
+
+  /* Radius tokens */
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+  --radius-xl: 0.75rem;
+
+  /* Animation tokens */
+  --animate-fade-in: fade-in 0.2s ease-out;
+  --animate-fade-out: fade-out 0.2s ease-in;
+  --animate-slide-in: slide-in 0.3s ease-out;
+  --animate-slide-out: slide-out 0.3s ease-in;
+
+  @keyframes fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+  @keyframes fade-out {
+    from { opacity: 1; }
+    to { opacity: 0; }
+  }
+  @keyframes slide-in {
+    from { transform: translateY(-0.5rem); opacity: 0; }
+    to { transform: translateY(0); opacity: 1; }
+  }
+  @keyframes slide-out {
+    from { transform: translateY(0); opacity: 1; }
+    to { transform: translateY(-0.5rem); opacity: 0; }
+  }
+}
+
+/* Dark mode variant */
+@custom-variant dark (&:where(.dark, .dark *));
+
+/* Dark mode theme overrides */
+.dark {
+  --color-background: oklch(14.5% 0.025 264);
+  --color-foreground: oklch(98% 0.01 264);
+  --color-primary: oklch(98% 0.01 264);
+  --color-primary-foreground: oklch(14.5% 0.025 264);
+  --color-secondary: oklch(22% 0.02 264);
+  --color-secondary-foreground: oklch(98% 0.01 264);
+  --color-muted: oklch(22% 0.02 264);
+  --color-muted-foreground: oklch(65% 0.02 264);
+  --color-accent: oklch(22% 0.02 264);
+  --color-accent-foreground: oklch(98% 0.01 264);
+  --color-destructive: oklch(42% 0.15 27);
+  --color-destructive-foreground: oklch(98% 0.01 264);
+  --color-border: oklch(22% 0.02 264);
+  --color-ring: oklch(83% 0.02 264);
+  --color-card: oklch(14.5% 0.025 264);
+  --color-card-foreground: oklch(98% 0.01 264);
+  --color-ring-offset: oklch(14.5% 0.025 264);
+}
+
+/* Base styles */
+@layer base {
+  * { @apply border-border; }
+  body { @apply bg-background text-foreground antialiased; }
+}
+```
+
+## Core Concepts
+
+### 1. Design Token Hierarchy
+
+```
+Brand Tokens (abstract)
+  └── Semantic Tokens (purpose)
+        └── Component Tokens (specific)
+
+Example: oklch(45% 0.2 260) → --color-primary → bg-primary
+```
+
+### 2. Component Architecture
+
+```
+Base styles → Variants → Sizes → States → Overrides
+```
+
+## Patterns
+
+### Pattern 1: CVA (Class Variance Authority) Components
+
+```tsx
+// components/ui/button.tsx
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+import { cn } from '@/lib/utils'
+
+const buttonVariants = cva(
+  'inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:pointer-events-none disabled:opacity-50',
+  {
+    variants: {
+      variant: {
+        default: 'bg-primary text-primary-foreground hover:bg-primary/90',
+        destructive: 'bg-destructive text-destructive-foreground hover:bg-destructive/90',
+        outline: 'border border-border bg-background hover:bg-accent hover:text-accent-foreground',
+        secondary: 'bg-secondary text-secondary-foreground hover:bg-secondary/80',
+        ghost: 'hover:bg-accent hover:text-accent-foreground',
+        link: 'text-primary underline-offset-4 hover:underline',
+      },
+      size: {
+        default: 'h-10 px-4 py-2',
+        sm: 'h-9 rounded-md px-3',
+        lg: 'h-11 rounded-md px-8',
+        icon: 'size-10',
+      },
+    },
+    defaultVariants: {
+      variant: 'default',
+      size: 'default',
+    },
+  }
+)
+
+export interface ButtonProps
+  extends React.ButtonHTMLAttributes<HTMLButtonElement>,
+    VariantProps<typeof buttonVariants> {
+  asChild?: boolean
+}
+
+// React 19: No forwardRef needed
+export function Button({
+  className, variant, size, asChild = false, ref, ...props
+}: ButtonProps & { ref?: React.Ref<HTMLButtonElement> }) {
+  const Comp = asChild ? Slot : 'button'
+  return (
+    <Comp className={cn(buttonVariants({ variant, size, className }))} ref={ref} {...props} />
+  )
+}
+```
+
+### Pattern 2: Compound Components (React 19)
+
+```tsx
+// components/ui/card.tsx
+import { cn } from '@/lib/utils'
+
+export function Card({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('rounded-lg border border-border bg-card text-card-foreground shadow-sm', className)} {...props} />
+}
+
+export function CardHeader({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('flex flex-col space-y-1.5 p-6', className)} {...props} />
+}
+
+export function CardTitle({ className, ref, ...props }: React.HTMLAttributes<HTMLHeadingElement> & { ref?: React.Ref<HTMLHeadingElement> }) {
+  return <h3 ref={ref} className={cn('text-2xl font-semibold leading-none tracking-tight', className)} {...props} />
+}
+
+export function CardContent({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('p-6 pt-0', className)} {...props} />
+}
+
+export function CardFooter({ className, ref, ...props }: React.HTMLAttributes<HTMLDivElement> & { ref?: React.Ref<HTMLDivElement> }) {
+  return <div ref={ref} className={cn('flex items-center p-6 pt-0', className)} {...props} />
+}
+```
+
+### Pattern 3: Form Components
+
+```tsx
+// components/ui/input.tsx
+import { cn } from '@/lib/utils'
+
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: string
+  ref?: React.Ref<HTMLInputElement>
+}
+
+export function Input({ className, type, error, ref, ...props }: InputProps) {
+  return (
+    <div className="relative">
+      <input
+        type={type}
+        className={cn(
+          'flex h-10 w-full rounded-md border border-border bg-background px-3 py-2 text-sm ring-offset-background file:border-0 file:bg-transparent file:text-sm file:font-medium placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:cursor-not-allowed disabled:opacity-50',
+          error && 'border-destructive focus-visible:ring-destructive',
+          className
+        )}
+        ref={ref}
+        aria-invalid={!!error}
+        aria-describedby={error ? `${props.id}-error` : undefined}
+        {...props}
+      />
+      {error && (
+        <p id={`${props.id}-error`} className="mt-1 text-sm text-destructive" role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}
+```
+
+### Pattern 4: Responsive Grid System
+
+```tsx
+// components/ui/grid.tsx
+import { cn } from '@/lib/utils'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+const gridVariants = cva('grid', {
+  variants: {
+    cols: {
+      1: 'grid-cols-1',
+      2: 'grid-cols-1 sm:grid-cols-2',
+      3: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-3',
+      4: 'grid-cols-1 sm:grid-cols-2 lg:grid-cols-4',
+    },
+    gap: {
+      none: 'gap-0',
+      sm: 'gap-2',
+      md: 'gap-4',
+      lg: 'gap-6',
+      xl: 'gap-8',
+    },
+  },
+  defaultVariants: { cols: 3, gap: 'md' },
+})
+
+const containerVariants = cva('mx-auto w-full px-4 sm:px-6 lg:px-8', {
+  variants: {
+    size: {
+      sm: 'max-w-screen-sm',
+      md: 'max-w-screen-md',
+      lg: 'max-w-screen-lg',
+      xl: 'max-w-screen-xl',
+      full: 'max-w-full',
+    },
+  },
+  defaultVariants: { size: 'xl' },
+})
+```
+
+### Pattern 5: Native CSS Animations (v4)
+
+```css
+/* Native @starting-style for entry animations */
+@theme {
+  --animate-dialog-in: dialog-fade-in 0.2s ease-out;
+  --animate-dialog-out: dialog-fade-out 0.15s ease-in;
+}
+
+@keyframes dialog-fade-in {
+  from { opacity: 0; transform: scale(0.95) translateY(-0.5rem); }
+  to { opacity: 1; transform: scale(1) translateY(0); }
+}
+
+/* Native popover animations using @starting-style */
+[popover] {
+  transition: opacity 0.2s, transform 0.2s, display 0.2s allow-discrete;
+  opacity: 0;
+  transform: scale(0.95);
+}
+[popover]:popover-open { opacity: 1; transform: scale(1); }
+@starting-style {
+  [popover]:popover-open { opacity: 0; transform: scale(0.95); }
+}
+```
+
+### Pattern 6: Dark Mode with CSS (v4)
+
+```tsx
+// providers/ThemeProvider.tsx
+'use client'
+import { createContext, useContext, useEffect, useState } from 'react'
+
+type Theme = 'dark' | 'light' | 'system'
+
+const ThemeContext = createContext<{ theme: Theme; setTheme: (t: Theme) => void; resolvedTheme: 'dark' | 'light' } | undefined>(undefined)
+
+export function ThemeProvider({ children, defaultTheme = 'system', storageKey = 'theme' }: {
+  children: React.ReactNode; defaultTheme?: Theme; storageKey?: string
+}) {
+  const [theme, setTheme] = useState<Theme>(defaultTheme)
+  const [resolvedTheme, setResolvedTheme] = useState<'dark' | 'light'>('light')
+
+  useEffect(() => {
+    const stored = localStorage.getItem(storageKey) as Theme | null
+    if (stored) setTheme(stored)
+  }, [storageKey])
+
+  useEffect(() => {
+    const root = document.documentElement
+    root.classList.remove('light', 'dark')
+    const resolved = theme === 'system'
+      ? (window.matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light')
+      : theme
+    root.classList.add(resolved)
+    setResolvedTheme(resolved)
+  }, [theme])
+
+  return (
+    <ThemeContext.Provider value={{
+      theme,
+      setTheme: (t) => { localStorage.setItem(storageKey, t); setTheme(t) },
+      resolvedTheme,
+    }}>
+      {children}
+    </ThemeContext.Provider>
+  )
+}
+
+export const useTheme = () => {
+  const ctx = useContext(ThemeContext)
+  if (!ctx) throw new Error('useTheme must be used within ThemeProvider')
+  return ctx
+}
+```
+
+## Utility Functions
+
+```ts
+// lib/utils.ts
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export const focusRing = cn(
+  "focus-visible:outline-none focus-visible:ring-2",
+  "focus-visible:ring-ring focus-visible:ring-offset-2",
+);
+
+export const disabled = "disabled:pointer-events-none disabled:opacity-50";
+```
+
+## Advanced v4 Patterns
+
+### Custom Utilities with @utility
+
+```css
+@utility line-t {
+  @apply relative before:absolute before:top-0 before:-left-[100vw]
+    before:h-px before:w-[200vw] before:bg-gray-950/5 dark:before:bg-white/10;
+}
+
+@utility text-gradient {
+  @apply bg-gradient-to-r from-primary to-accent bg-clip-text text-transparent;
+}
+```
+
+### Theme Modifiers
+
+```css
+/* Use @theme inline when referencing other CSS variables */
+@theme inline {
+  --font-sans: var(--font-inter), system-ui;
+}
+
+/* Use @theme static to always generate CSS variables (even when unused) */
+@theme static {
+  --color-brand: oklch(65% 0.15 240);
+}
+```
+
+### Namespace Overrides
+
+```css
+@theme {
+  /* Clear all default colors and define your own */
+  --color-*: initial;
+  --color-white: #fff;
+  --color-black: #000;
+  --color-primary: oklch(45% 0.2 260);
+  --color-secondary: oklch(65% 0.15 200);
+}
+```
+
+### Semi-transparent Color Variants
+
+```css
+@theme {
+  --color-primary-50: color-mix(in oklab, var(--color-primary) 5%, transparent);
+  --color-primary-100: color-mix(in oklab, var(--color-primary) 10%, transparent);
+  --color-primary-200: color-mix(in oklab, var(--color-primary) 20%, transparent);
+}
+```
+
+### Container Queries
+
+```css
+@theme {
+  --container-xs: 20rem;
+  --container-sm: 24rem;
+  --container-md: 28rem;
+  --container-lg: 32rem;
+}
+```
+
+## v3 to v4 Migration Checklist
+
+- [ ] Replace `tailwind.config.ts` with CSS `@theme` block
+- [ ] Change `@tailwind base/components/utilities` to `@import "tailwindcss"`
+- [ ] Move color definitions to `@theme { --color-*: value }`
+- [ ] Replace `darkMode: "class"` with `@custom-variant dark`
+- [ ] Move `@keyframes` inside `@theme` blocks
+- [ ] Replace `require("tailwindcss-animate")` with native CSS animations
+- [ ] Update `h-10 w-10` to `size-10` (new utility)
+- [ ] Remove `forwardRef` (React 19 passes ref as prop)
+- [ ] Consider OKLCH colors for better color perception
+- [ ] Replace custom plugins with `@utility` directives
+
+## Best Practices
+
+### Do's
+- Use `@theme` blocks — CSS-first configuration is v4's core pattern
+- Use OKLCH colors — Better perceptual uniformity than HSL
+- Compose with CVA — Type-safe variants
+- Use semantic tokens — `bg-primary` not `bg-blue-500`
+- Use `size-*` — New shorthand for `w-* h-*`
+- Add accessibility — ARIA attributes, focus states
+
+### Don'ts
+- Don't use `tailwind.config.ts` — Use CSS `@theme` instead
+- Don't use `@tailwind` directives — Use `@import "tailwindcss"`
+- Don't use `forwardRef` — React 19 passes ref as prop
+- Don't use arbitrary values — Extend `@theme` instead
+- Don't hardcode colors — Use semantic tokens
+- Don't forget dark mode — Test both themes
+
+## Resources
+
+- [Tailwind CSS v4 Documentation](https://tailwindcss.com/docs)
+- [Tailwind v4 Beta Announcement](https://tailwindcss.com/blog/tailwindcss-v4-beta)
+- [CVA Documentation](https://cva.style/docs)
+- [shadcn/ui](https://ui.shadcn.com/)
+- [Radix Primitives](https://www.radix-ui.com/primitives)