start-vibing-stacks 2.18.0 → 2.20.0

package/stacks/frontend/react/skills/shadcn-ui/SKILL.md

@@ -1,97 +1,325 @@
 ---
 name: shadcn-ui
-version: 1.0.0
+version: 2.0.0
+description: "shadcn/ui CLI v4 (March 2026) for React 19 + Tailwind v4. Components updated to remove forwardRef (refs as props in R19), every primitive carries a data-slot attribute for targeted styling, HSL → OKLCH tokens, size-* utility replaces w-h pairs, default style deprecated in favor of new-york. CLI v4 brings shadcn/skills (AI agent context for component registry), --preset (shareable design-system bundle), --dry-run / --diff / --view (inspect changes before applying), --template scaffolds (Next.js, Vite, Laravel, React Router, Astro, TanStack Start), --base flag (Radix vs Base UI primitives), and `shadcn info` / `shadcn docs` commands for agents. Includes components.json schema, registry-item.json, blocks. Invoke when adding, customising, theming, or scaffolding shadcn components."
 ---
 
-# shadcn/ui — Component Library Patterns
+# shadcn/ui — CLI v4 + React 19 + Tailwind v4 (2026)
 
-**ALWAYS invoke when adding or modifying shadcn/ui components.**
+**ALWAYS invoke when adding, customising, theming, or scaffolding shadcn components.**
 
-## Installation
+> shadcn/ui is a copy-paste component system, not an npm dependency — components live **in your repo**, get owned and modified there. The CLI keeps them in sync with the upstream registry without hiding the source.
+
+## What's new in 2026 (CLI v4 — March 2026)
+
+| Change | Impact |
+|---|---|
+| **Tailwind v4 + React 19 first-class** | All components updated; v3+R18 still works (non-breaking) |
+| **`forwardRef` removed** | React 19 treats `ref` as a prop — components are simpler |
+| **`data-slot="…"` on every primitive** | Style any sub-element from outside without overriding source |
+| **HSL → OKLCH** colour tokens | Smoother gradients, perceptual uniformity |
+| **`size-*` utility** | `size-9` instead of `w-9 h-9` |
+| **`default` style deprecated** | Use **`new-york`** (the new default in `components.json`) |
+| **`shadcn/skills`** | AI-agent registry context — agents discover components via the CLI |
+| **`--preset` flag** | Pack colours/theme/fonts/radius into a shareable code string |
+| **`--dry-run` / `--diff` / `--view`** | Inspect registry changes before writing files |
+| **`--template`** | Scaffolds for Next.js, Vite, Laravel, React Router, Astro, TanStack Start |
+| **`--base`** | Choose between **Radix** and **Base UI** primitives |
+| **`shadcn info` / `shadcn docs`** | Context commands for agents and humans |
+
+## Initialisation
 
 ```bash
-npx shadcn@latest init
-npx shadcn@latest add button card dialog input
+# Pick a template (CLI v4 — March 2026)
+npx shadcn@latest init --template next-app
+# Other templates: vite, laravel, react-router, astro, tanstack-start
+
+# Add components — non-interactive, idempotent
+npx shadcn@latest add button card dialog input form
+
+# Inspect before writing (new in v4)
+npx shadcn@latest add button --dry-run --diff
+
+# Use Base UI primitives instead of Radix
+npx shadcn@latest add dialog --base baseui
 ```
 
-## Theming
+## `components.json` (Tailwind v4 shape)
+
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "src/app/globals.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "iconLibrary": "lucide"
+}
+```
+
+> For Tailwind v4 the `tailwind.config` field stays empty — there's no JS config file in v4.
+
+## Theming with OKLCH
 
 ```css
-/* globals.css — CSS variables for theming */
-@layer base {
-  :root {
-    --background: 0 0% 100%;
-    --foreground: 222.2 84% 4.9%;
-    --primary: 222.2 47.4% 11.2%;
-    --primary-foreground: 210 40% 98%;
-    --muted: 210 40% 96.1%;
-    --muted-foreground: 215.4 16.3% 46.9%;
-    --border: 214.3 31.8% 91.4%;
-    --ring: 222.2 84% 4.9%;
-    --radius: 0.5rem;
-  }
-  .dark {
-    --background: 222.2 84% 4.9%;
-    --foreground: 210 40% 98%;
-    --primary: 210 40% 98%;
-    --primary-foreground: 222.2 47.4% 11.2%;
-  }
+/* src/app/globals.css */
+@import "tailwindcss";
+
+@theme inline {
+  /* Light theme — OKLCH (replaces v1 HSL tokens) */
+  --color-background:        oklch(1.000 0 0);
+  --color-foreground:        oklch(0.145 0 0);
+
+  --color-primary:           oklch(0.205 0 0);
+  --color-primary-foreground: oklch(0.985 0 0);
+
+  --color-secondary:         oklch(0.970 0 0);
+  --color-secondary-foreground: oklch(0.205 0 0);
+
+  --color-muted:             oklch(0.970 0 0);
+  --color-muted-foreground:  oklch(0.556 0 0);
+
+  --color-destructive:       oklch(0.577 0.245 27.325);
+  --color-destructive-foreground: oklch(0.985 0 0);
+
+  --color-border:            oklch(0.922 0 0);
+  --color-ring:              oklch(0.708 0 0);
+
+  --radius:                  0.625rem;  /* slightly larger than v1's 0.5rem */
+}
+
+@theme dark inline {
+  --color-background:        oklch(0.145 0 0);
+  --color-foreground:        oklch(0.985 0 0);
+  --color-primary:           oklch(0.985 0 0);
+  --color-primary-foreground: oklch(0.205 0 0);
+  /* … rest of dark overrides */
+}
+```
+
+OKLCH ranges (rough guide): lightness 0–1, chroma 0–~0.4, hue 0–360°. Pick lightness on the same axis for siblings — gradients stay perceptually smooth.
+
+## Components without `forwardRef`
+
+```tsx
+// React 19 — refs are props, no forwardRef needed
+import * as React from "react";
+import { cn } from "@/lib/utils";
+
+function Button({
+  ref,                                   // ← just a normal prop
+  className,
+  variant = "default",
+  size = "default",
+  ...props
+}: React.ButtonHTMLAttributes<HTMLButtonElement> & {
+  ref?: React.Ref<HTMLButtonElement>;
+  variant?: "default" | "outline" | "ghost" | "destructive";
+  size?: "default" | "sm" | "lg" | "icon";
+}) {
+  return (
+    <button
+      ref={ref}
+      data-slot="button"                 // ← every primitive carries data-slot
+      className={cn(buttonVariants({ variant, size }), className)}
+      {...props}
+    />
+  );
 }
+
+export { Button };
+```
+
+`forwardRef` still works — but the new components ship without it.
+
+## `data-slot` — style sub-parts from outside
+
+```tsx
+// Style the icon inside a Button without touching the Button source
+<Button className="[&_[data-slot=icon]]:size-4 [&_[data-slot=icon]]:text-primary">
+  <CheckIcon data-slot="icon" />
+  Confirm
+</Button>
+
+// Style the trigger of a Dialog from a parent
+<Dialog>
+  <DialogTrigger className="[&[data-slot=trigger]]:rounded-full" asChild>
+    <Button>Open</Button>
+  </DialogTrigger>
+</Dialog>
 ```
 
-## Component Customization
+This replaces the old "expose every internal class through props" pattern — the contract is the slot name, not the className.
+
+## Customisation — extend, don't fork
 
 ```tsx
 // CORRECT — extend via className + variants
-import { Button } from '@/components/ui/button';
-<Button variant="outline" size="lg" className="rounded-full">Custom</Button>
+<Button variant="outline" size="lg" className="rounded-full">
+  Custom
+</Button>
 
-// WRONG — modify component source for one-off styles
+// CORRECT — wrap a shadcn primitive when you need a project-specific variant
+function PageHeading({ children, className, ...rest }: ComponentProps<"h1">) {
+  return (
+    <h1 data-slot="page-heading" className={cn("text-2xl font-semibold tracking-tight", className)} {...rest}>
+      {children}
+    </h1>
+  );
+}
+
+// WRONG — modifying the shadcn source for one-off styles
+// → upgrade path breaks; intent gets lost
 ```
 
-## Composition Pattern
+## Composition
 
 ```tsx
-import { Card, CardContent, CardDescription, CardHeader, CardTitle } from '@/components/ui/card';
-import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from '@/components/ui/dialog';
+import { Card, CardContent, CardDescription, CardHeader, CardTitle } from "@/components/ui/card";
+import { Dialog, DialogContent, DialogHeader, DialogTitle, DialogTrigger } from "@/components/ui/dialog";
 
-// Compose primitives, don't create monolithic components
 <Dialog>
   <DialogTrigger asChild>
     <Button variant="outline">Open</Button>
   </DialogTrigger>
   <DialogContent>
     <DialogHeader>
-      <DialogTitle>Title</DialogTitle>
+      <DialogTitle>Edit profile</DialogTitle>
     </DialogHeader>
-    <Card><CardContent>...</CardContent></Card>
+    <Card>
+      <CardHeader>
+        <CardTitle>Account</CardTitle>
+        <CardDescription>Update your information.</CardDescription>
+      </CardHeader>
+      <CardContent>{/* form fields */}</CardContent>
+    </Card>
   </DialogContent>
 </Dialog>
 ```
 
-## Form Pattern (with Zod)
+## Forms — shadcn Form + React Hook Form + Zod 4
 
 ```tsx
-import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from '@/components/ui/form';
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-
-const form = useForm<z.infer<typeof schema>>({ resolver: zodResolver(schema) });
-
-<Form {...form}>
-  <FormField control={form.control} name="email" render={({ field }) => (
-    <FormItem>
-      <FormLabel>Email</FormLabel>
-      <FormControl><Input {...field} /></FormControl>
-      <FormMessage />
-    </FormItem>
-  )} />
-</Form>
+"use client";
+import { z } from "zod";
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { Form, FormControl, FormField, FormItem, FormLabel, FormMessage } from "@/components/ui/form";
+import { Input } from "@/components/ui/input";
+import { Button } from "@/components/ui/button";
+
+const Schema = z.object({
+  email: z.email("Enter a valid email"),                  // Zod 4 top-level
+  password: z.string().min(8, "At least 8 characters"),
+});
+
+type FormValues = z.infer<typeof Schema>;
+
+export function LoginForm() {
+  const form = useForm<FormValues>({
+    resolver: zodResolver(Schema),
+    defaultValues: { email: "", password: "" },
+  });
+
+  function onSubmit(values: FormValues) { /* call your API */ }
+
+  return (
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-4">
+        <FormField control={form.control} name="email" render={({ field }) => (
+          <FormItem>
+            <FormLabel>Email</FormLabel>
+            <FormControl><Input type="email" autoComplete="email" {...field} /></FormControl>
+            <FormMessage />
+          </FormItem>
+        )}/>
+        <FormField control={form.control} name="password" render={({ field }) => (
+          <FormItem>
+            <FormLabel>Password</FormLabel>
+            <FormControl><Input type="password" autoComplete="current-password" {...field} /></FormControl>
+            <FormMessage />
+          </FormItem>
+        )}/>
+        <Button type="submit" className="w-full">Sign in</Button>
+      </form>
+    </Form>
+  );
+}
+```
+
+## Blocks — copy-paste full UI sections
+
+```bash
+# List blocks (auth, dashboards, charts, sidebars, calendars, …)
+npx shadcn@latest add --list-blocks
+
+# Add a specific block
+npx shadcn@latest add login-04
+```
+
+Blocks are full sections (login pages, dashboard shells, billing screens) registered as `registry:block` in the catalog. They land in `components/` and you own them after that.
+
+## Custom registries
+
+```json
+// registry-item.json — share components across your team / org
+{
+  "$schema": "https://ui.shadcn.com/schema/registry-item.json",
+  "name": "data-table",
+  "type": "registry:component",
+  "dependencies": ["@tanstack/react-table"],
+  "registryDependencies": ["button", "input"],
+  "files": [{ "path": "components/data-table.tsx", "type": "registry:component" }]
+}
+```
+
+Host the JSON anywhere (GitHub Pages, Vercel) and consume:
+
+```bash
+npx shadcn@latest add https://your-registry.com/r/data-table.json
+```
+
+## CLI v4 — workflow commands
+
+```bash
+shadcn info                        # show project + dependency context (great for AI agents)
+shadcn docs <component>            # open docs for a specific component
+shadcn add button --dry-run --view # show what would change, don't write
+shadcn add button --diff           # show diff against current files
+shadcn add --preset <hash>         # bootstrap an entire design-system from a preset hash
 ```
 
 ## FORBIDDEN
 
-1. **Modifying component source for one-off needs** — use className/variants
-2. **Installing without init** — always `npx shadcn@latest init` first
-3. **Ignoring dark mode** — all components must work in both themes
-4. **Skipping accessibility** — shadcn components have built-in a11y, don't break it
+| ❌ Don't | Why |
+|---|---|
+| Modify component source for one-off styles | Use `className` + `variant` + slots |
+| Skip `init` | The CLI needs `components.json` for paths/aliases |
+| Stay on the deprecated `default` style | Use `new-york` (new CLI default) |
+| Use `forwardRef` in new R19 components | Refs are plain props now |
+| Add `w-10 h-10` instead of `size-10` | Tailwind v4 `size-*` is the recommended utility |
+| HSL tokens for new themes | OKLCH gives smoother gradients & a11y-friendly mixing |
+| Add a component then `npm install` it as a package | shadcn lives **in your repo**, never as a runtime dependency |
+| Break built-in a11y (aria, focus, escape handlers) | Radix/Base UI primitives wire it correctly out of the box |
+
+## See Also
+
+- `tailwind-patterns` v2 — `@theme`, container queries, OKLCH
+- `react-patterns` v2 — refs as props in R19, `useActionState`, `useOptimistic`
+- `react-standards` v2 — STYLES/LABELS const pattern that pairs with shadcn slots
+- `zod-validation` v2 — Zod 4 + `@hookform/resolvers/zod`
+- `react-ui-patterns` v2 — loading/error/empty states using shadcn primitives
+- `_shared/skills/ui-ux-audit` v2 — WCAG 2.2 AA on shadcn components

package/stacks/frontend/react/skills/tailwind-patterns/SKILL.md

@@ -1,21 +1,37 @@
 ---
 name: tailwind-patterns
-version: 1.0.0
+version: 2.0.0
+description: "Tailwind CSS v4 (stable Jan 22 2025) CSS-first design system with the Rust-based Oxide engine — 3.78× faster full builds, 8.8× faster incremental, 100× faster on no-CSS-change runs. CSS-first config via `@theme` directive (no `tailwind.config.js`), automatic content detection, native container queries (`@container` + `@md:`), OKLCH color space (perceptual uniformity), modern CSS features (cascade layers, `@property`, `color-mix()`), `@import \"tailwindcss\"` single line. Covers the v3 → v4 migration, semantic-token architecture, mobile-first + container-query responsive strategy, dark mode via `@theme dark`, and the 4px spacing scale. Invoke whenever writing Tailwind classes, theming a project, or designing responsive layouts."
 ---
 
-# TailwindCSS 4 — CSS-First Design System
+# Tailwind CSS v4 — CSS-First Design System (2026)
 
 **ALWAYS invoke when writing Tailwind classes, theming, or responsive layouts.**
 
-## What Changed (v3 → v4)
+## v4 Status (2026)
 
-| v3 (Legacy) | v4 (Current) |
+- **Tailwind v4.0 stable**: January 22, 2025
+- **Oxide engine** (Rust) — full builds **3.78× faster** (378ms → 100ms), incremental rebuilds **8.8× faster** (44ms → 5ms), no-CSS-change rebuilds **100× faster** (35ms → 192µs)
+- **No `tailwind.config.js`** — config lives in CSS via `@theme`
+- **Automatic content detection** — no `content: [...]` paths to maintain
+- **Native container queries** — no plugin
+- **OKLCH** color space everywhere (perceptual uniformity, smoother gradients)
+- Built-in support for cascade layers, `@property`, `color-mix()`, modern CSS
+
+## v3 → v4 cheatsheet
+
+| v3 (legacy) | v4 (current) |
 |---|---|
-| `tailwind.config.js` | CSS `@theme` directive |
-| PostCSS plugin | Oxide engine (10x faster) |
-| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
-| Colors in JS config | Colors as CSS variables |
-| `@apply` everywhere | Components > `@apply` |
+| `tailwind.config.js` (JS) | `@theme { … }` block (CSS) |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` (single line) |
+| `content: ["./src/**/*.tsx"]` | Auto-detected (no setup) |
+| Colors in JS object | CSS variables (`--color-primary`) |
+| HSL or hex tokens | **OKLCH** (recommended) |
+| `@tailwindcss/container-queries` plugin | Native (`@container`, `@md:flex-row`) |
+| `dark:` only | `dark:` **and** `@theme dark { … }` for token switching |
+| `@apply` for everything | React components + tokens; reserve `@apply` for legacy CSS |
+
+Migration is non-breaking for existing v3 codebases — both can coexist. Run `npx @tailwindcss/upgrade@latest` to automate the bulk.
 
 ## Setup (v4)
 
@@ -262,17 +278,60 @@ Section gaps: space-y-6 md:space-y-8
 Card padding: p-4 md:p-6
 ```
 
+## Modern CSS — leverage what v4 unlocks
+
+```css
+/* color-mix() — derive variants from semantic tokens */
+.btn-primary-soft {
+  background: color-mix(in oklch, var(--color-primary) 12%, transparent);
+}
+
+/* @property — animatable custom properties */
+@property --gradient-angle {
+  syntax: '<angle>';
+  inherits: false;
+  initial-value: 0deg;
+}
+
+/* Cascade layers — predictable specificity (Tailwind already uses these) */
+@layer components {
+  .card-hero { /* your custom layer */ }
+}
+```
+
+## `size-*` utility (use over `w-N h-N`)
+
+```tsx
+{/* OK — single utility, less repetition */}
+<img className="size-10 rounded-full" />
+<button className="size-9 grid place-items-center">
+
+{/* Avoid the duplicate */}
+<img className="w-10 h-10 rounded-full" />
+```
+
 ## FORBIDDEN
 
 | ❌ Don't | ✅ Do |
 |---|---|
 | `tailwind.config.js` in v4 | `@theme` in CSS |
-| `@apply` for everything | React components |
-| `!important` | Fix specificity |
+| `@apply` for everything | React components + token classes |
+| `!important` | Fix specificity (or use cascade layers) |
 | `style={{ color: 'red' }}` | `text-destructive` |
-| Arbitrary values for tokens | Define in `@theme` |
-| `bg-white dark:bg-gray-900` | `bg-background` (semantic) |
-| `@tailwind base` | `@import "tailwindcss"` (v4) |
-| Dynamic class strings | Static complete strings (purge-safe) |
-| `text-[#FF5733]` inline | `--color-accent` in `@theme` |
+| Arbitrary values for design tokens (`text-[#2563eb]`) | Define `--color-*` in `@theme` |
+| `bg-white dark:bg-gray-900` | `bg-background` (semantic + `@theme dark`) |
+| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
+| Dynamic class strings (`bg-${color}-500`) | Static complete strings (Oxide can't see derived ones) |
+| HSL tokens for new themes | OKLCH (perceptual uniformity, smoother gradients) |
+| `w-10 h-10` pairs | `size-10` |
+| `forwardRef`-style ref-as-prop indirection | Refs are just props in React 19 |
+| `content: [...]` arrays | Auto-detection in v4 |
 | Inconsistent spacing | Follow 4px scale |
+
+## See Also
+
+- `react-standards` — STYLES const pattern using these tokens
+- `shadcn-ui` — components built on top of Tailwind v4 + OKLCH + `data-slot`
+- `preline-ui` — alternative token system on top of Tailwind v4
+- `react-ui-patterns` — loading/error/empty states using semantic tokens
+- `_shared/skills/ui-ux-audit` — WCAG 2.2 AA contrast checks against semantic tokens