@sylix/coworker 2.0.11 → 2.0.14

package/dist/skills/defaults/frontend/tailwind-design-system.md

@@ -0,0 +1,337 @@
+---
+name: tailwind-design-system
+description: Build scalable design systems with Tailwind CSS v4, design tokens, component libraries, and responsive patterns. Use when creating component libraries, implementing design systems, or standardizing UI patterns.
+---
+
+# 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.
+
+## 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 Pattern                            | v4 Pattern                                                            |
+| ------------------------------------- | --------------------------------------------------------------------- |
+| `tailwind.config.ts`                  | `@theme` in CSS                                                       |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"`                                               |
+| `darkMode: "class"`                   | `@custom-variant dark (&:where(.dark, .dark *))`                      |
+| `theme.extend.colors`                 | `@theme { --color-*: value }`                                         |
+| `require("tailwindcss-animate")`      | CSS `@keyframes` in `@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 */
+  --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-muted: oklch(96% 0.01 264);
+  --color-destructive: oklch(53% 0.22 27);
+
+  --color-border: oklch(91% 0.01 264);
+  --radius-sm: 0.25rem;
+  --radius-md: 0.375rem;
+  --radius-lg: 0.5rem;
+
+  --animate-fade-in: fade-in 0.2s ease-out;
+
+  @keyframes fade-in {
+    from { opacity: 0; }
+    to { opacity: 1; }
+  }
+}
+
+/* Dark mode variant */
+@custom-variant dark (&:where(.dark, .dark *));
+
+.dark {
+  --color-background: oklch(14.5% 0.025 264);
+  --color-foreground: oklch(98% 0.01 264);
+  --color-primary: oklch(98% 0.01 264);
+}
+```
+
+## 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
+```
+
+## Patterns
+
+### Pattern 1: CVA (Class Variance Authority) Components
+
+```typescript
+import { Slot } from '@radix-ui/react-slot'
+import { cva, type VariantProps } from 'class-variance-authority'
+
+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 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',
+        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
+}
+
+export function Button({ className, variant, size, asChild = false, ...props }: ButtonProps) {
+  const Comp = asChild ? Slot : 'button'
+  return <Comp className={buttonVariants({ variant, size, className })} {...props} />
+}
+
+// Usage
+<Button variant="destructive" size="lg">Delete</Button>
+<Button asChild><Link href="/home">Home</Link></Button>
+```
+
+### Pattern 2: Compound Components
+
+```typescript
+export function Card({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return (
+    <div
+      className="rounded-lg border border-border bg-card text-card-foreground shadow-sm"
+      {...props}
+    />
+  )
+}
+
+export function CardHeader({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className="flex flex-col space-y-1.5 p-6" {...props} />
+}
+
+export function CardTitle({ className, ...props }: React.HTMLAttributes<HTMLHeadingElement>) {
+  return <h3 className="text-2xl font-semibold leading-none tracking-tight" {...props} />
+}
+
+export function CardDescription({ className, ...props }: React.HTMLAttributes<HTMLParagraphElement>) {
+  return <p className="text-sm text-muted-foreground" {...props} />
+}
+
+export function CardContent({ className, ...props }: React.HTMLAttributes<HTMLDivElement>) {
+  return <div className="p-6 pt-0" {...props} />
+}
+
+// Usage
+<Card>
+  <CardHeader>
+    <CardTitle>Account</CardTitle>
+    <CardDescription>Manage your account settings</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <form>...</form>
+  </CardContent>
+</Card>
+```
+
+### Pattern 3: Form Components
+
+```typescript
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+  error?: string
+}
+
+export function Input({ className, type, error, ...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',
+          'placeholder:text-muted-foreground focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+          'disabled:cursor-not-allowed disabled:opacity-50',
+          error && 'border-destructive focus-visible:ring-destructive',
+          className
+        )}
+        aria-invalid={!!error}
+        {...props}
+      />
+      {error && (
+        <p className="mt-1 text-sm text-destructive" role="alert">
+          {error}
+        </p>
+      )}
+    </div>
+  )
+}
+```
+
+### Pattern 4: Responsive Grid System
+
+```typescript
+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: {
+      sm: 'gap-2',
+      md: 'gap-4',
+      lg: 'gap-6',
+    },
+  },
+  defaultVariants: {
+    cols: 3,
+    gap: 'md',
+  },
+})
+
+export function Grid({ className, cols, gap, ...props }: GridProps) {
+  return <div className={gridVariants({ cols, gap, className })} {...props} />
+}
+
+// Usage
+<Grid cols={4} gap="lg">
+  {products.map((product) => (
+    <ProductCard key={product.id} product={product} />
+  ))}
+</Grid>
+```
+
+### Pattern 5: Native CSS Animations (v4)
+
+```css
+@theme {
+  --animate-dialog-in: dialog-fade-in 0.2s ease-out;
+}
+
+@keyframes dialog-fade-in {
+  from {
+    opacity: 0;
+    transform: scale(0.95);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+/* 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)
+
+```typescript
+export function ThemeToggle() {
+  const { resolvedTheme, setTheme } = useTheme()
+
+  return (
+    <Button
+      variant="ghost"
+      size="icon"
+      onClick={() => setTheme(resolvedTheme === 'dark' ? 'light' : 'dark')}
+    >
+      <Sun className="size-5 rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
+      <Moon className="absolute size-5 rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
+      <span className="sr-only">Toggle theme</span>
+    </Button>
+  )
+}
+```
+
+## Utility Functions
+
+```typescript
+import { type ClassValue, clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+```
+
+## 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)
+- [ ] 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`
+- **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 hardcode colors** - Use semantic tokens
+- **Don't forget dark mode** - Test both themes