@1aboveio/skills 0.10.0

package/skills/fullstack/shadcn/rules/composition.md

@@ -0,0 +1,195 @@
+# Component Composition
+
+## Contents
+
+- Items always inside their Group component
+- Callouts use Alert
+- Empty states use Empty component
+- Toast notifications use sonner
+- Choosing between overlay components
+- Dialog, Sheet, and Drawer always need a Title
+- Card structure
+- Button has no isPending or isLoading prop
+- TabsTrigger must be inside TabsList
+- Avatar always needs AvatarFallback
+- Use Separator instead of raw hr or border divs
+- Use Skeleton for loading placeholders
+- Use Badge instead of custom styled spans
+
+---
+
+## Items always inside their Group component
+
+Never render items directly inside the content container.
+
+**Incorrect:**
+
+```tsx
+<SelectContent>
+  <SelectItem value="apple">Apple</SelectItem>
+  <SelectItem value="banana">Banana</SelectItem>
+</SelectContent>
+```
+
+**Correct:**
+
+```tsx
+<SelectContent>
+  <SelectGroup>
+    <SelectItem value="apple">Apple</SelectItem>
+    <SelectItem value="banana">Banana</SelectItem>
+  </SelectGroup>
+</SelectContent>
+```
+
+This applies to all group-based components:
+
+| Item | Group |
+|------|-------|
+| `SelectItem`, `SelectLabel` | `SelectGroup` |
+| `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` | `DropdownMenuGroup` |
+| `MenubarItem` | `MenubarGroup` |
+| `ContextMenuItem` | `ContextMenuGroup` |
+| `CommandItem` | `CommandGroup` |
+
+---
+
+## Callouts use Alert
+
+```tsx
+<Alert>
+  <AlertTitle>Warning</AlertTitle>
+  <AlertDescription>Something needs attention.</AlertDescription>
+</Alert>
+```
+
+---
+
+## Empty states use Empty component
+
+```tsx
+<Empty>
+  <EmptyHeader>
+    <EmptyMedia variant="icon"><FolderIcon /></EmptyMedia>
+    <EmptyTitle>No projects yet</EmptyTitle>
+    <EmptyDescription>Get started by creating a new project.</EmptyDescription>
+  </EmptyHeader>
+  <EmptyContent>
+    <Button>Create Project</Button>
+  </EmptyContent>
+</Empty>
+```
+
+---
+
+## Toast notifications use sonner
+
+```tsx
+import { toast } from "sonner"
+
+toast.success("Changes saved.")
+toast.error("Something went wrong.")
+toast("File deleted.", {
+  action: { label: "Undo", onClick: () => undoDelete() },
+})
+```
+
+---
+
+## Choosing between overlay components
+
+| Use case | Component |
+|----------|-----------|
+| Focused task that requires input | `Dialog` |
+| Destructive action confirmation | `AlertDialog` |
+| Side panel with details or filters | `Sheet` |
+| Mobile-first bottom panel | `Drawer` |
+| Quick info on hover | `HoverCard` |
+| Small contextual content on click | `Popover` |
+
+---
+
+## Dialog, Sheet, and Drawer always need a Title
+
+`DialogTitle`, `SheetTitle`, `DrawerTitle` are required for accessibility. Use `className="sr-only"` if visually hidden.
+
+```tsx
+<DialogContent>
+  <DialogHeader>
+    <DialogTitle>Edit Profile</DialogTitle>
+    <DialogDescription>Update your profile.</DialogDescription>
+  </DialogHeader>
+  ...
+</DialogContent>
+```
+
+---
+
+## Card structure
+
+Use full composition — don't dump everything into `CardContent`:
+
+```tsx
+<Card>
+  <CardHeader>
+    <CardTitle>Team Members</CardTitle>
+    <CardDescription>Manage your team.</CardDescription>
+  </CardHeader>
+  <CardContent>...</CardContent>
+  <CardFooter>
+    <Button>Invite</Button>
+  </CardFooter>
+</Card>
+```
+
+---
+
+## Button has no isPending or isLoading prop
+
+Compose with `Spinner` + `data-icon` + `disabled`:
+
+```tsx
+<Button disabled>
+  <Spinner data-icon="inline-start" />
+  Saving...
+</Button>
+```
+
+---
+
+## TabsTrigger must be inside TabsList
+
+Never render `TabsTrigger` directly inside `Tabs` — always wrap in `TabsList`:
+
+```tsx
+<Tabs defaultValue="account">
+  <TabsList>
+    <TabsTrigger value="account">Account</TabsTrigger>
+    <TabsTrigger value="password">Password</TabsTrigger>
+  </TabsList>
+  <TabsContent value="account">...</TabsContent>
+</Tabs>
+```
+
+---
+
+## Avatar always needs AvatarFallback
+
+Always include `AvatarFallback` for when the image fails to load:
+
+```tsx
+<Avatar>
+  <AvatarImage src="/avatar.png" alt="User" />
+  <AvatarFallback>JD</AvatarFallback>
+</Avatar>
+```
+
+---
+
+## Use existing components instead of custom markup
+
+| Instead of | Use |
+|---|---|
+| `<hr>` or `<div className="border-t">` | `<Separator />` |
+| `<div className="animate-pulse">` with styled divs | `<Skeleton className="h-4 w-3/4" />` |
+| `<span className="rounded-full bg-green-100 ...">` | `<Badge variant="secondary">` |

package/skills/fullstack/shadcn/rules/data-table.md

@@ -0,0 +1,201 @@
+# Data Tables & List Pages
+
+**On a portal list/index page the data table is DiceUI's — that's the default.** Choosing a bare `Table` there is the decision that needs justifying, not the other way round. Away from list pages it's a judgment call: DiceUI once the table needs server-side filter/sort/paginate, plain `Table` when it's display.
+
+DiceUI DataTable is built on **TanStack Table** and isn't bundled with shadcn, so it needs an explicit install — a setup step, not a reason to reconsider it. DiceUI components are shadcn-style, so the skill's [Critical Rules](../SKILL.md#critical-rules) (semantic colors, `gap-*`, `data-icon`, `cn()`, etc.) still apply to anything you add or edit.
+
+## Which to use
+
+| Case | Use |
+|---|---|
+| Portal list/index page | **DiceUI DataTable** (`@diceui/data-table`) — default |
+| Large/remote dataset — filter/sort/paginate on the **server**, shareable URLs | **DiceUI DataTable** |
+| A few rows, static/read-only, nothing to slice | shadcn **`Table`** |
+| "I'll just wire `useReactTable` with a custom toolbar" | That's DiceUI, reimplemented without the URL state. Use DiceUI |
+
+## URL state is the point
+
+`nuqs` isn't an implementation detail you can swap out — `useDataTable` calls `useQueryState` internally, so it's a hard dependency and the app must be wrapped once in `NuqsAdapter` or the hook throws.
+
+That coupling is deliberate, and it's the reason to pick DiceUI in the first place. Filters, sort, and page are exactly the state people bookmark, paste into a ticket, and expect to survive a refresh. Keeping them in `useState` loses all of that *and* strands the values on the client, where the server query that actually needs them can't see them. Put them in the URL and the RSC page re-reads them on every navigation for free.
+
+Corollary: don't keep a `useState` copy alongside the URL values. Two sources of truth is what makes the back button feel broken.
+
+## Install
+
+Use the project's package runner (`npx`/`pnpm dlx`/`bunx --bun`). The **URL form works with no config** — but the `.json` extension is **required**; an extensionless registry URL 404s.
+
+The data-table items are served from **tablecn.com** (`diceui.com/r/<name>.json` 308-redirects there, so either host works; tablecn is canonical):
+
+```bash
+npx shadcn@latest add "https://tablecn.com/r/data-table.json"
+# optional add-ons:
+npx shadcn@latest add "https://tablecn.com/r/data-table-sort-list.json"
+npx shadcn@latest add "https://tablecn.com/r/data-table-filter-list.json"
+npx shadcn@latest add "https://tablecn.com/r/data-table-filter-menu.json"
+# row-selection action bar (this one lives on diceui.com, not tablecn):
+npx shadcn@latest add "https://diceui.com/r/action-bar.json"
+```
+
+The `@diceui/...` namespace form (`npx shadcn@latest add @diceui/data-table`) only resolves if `components.json` declares the registry. Prefer `npx shadcn@latest registry add "@diceui=https://diceui.com/r/{name}.json"` over hand-editing, and use exactly this template:
+
+```jsonc
+// components.json
+{
+  "registries": {
+    "@diceui": "https://diceui.com/r/{name}.json"
+  }
+}
+```
+
+> **Do not use the `{style}` form.** shadcn's public registry index lists `@diceui` as `https://diceui.com/r/{style}/{name}.json`. That template breaks the data-table items — the CLI substitutes the project's full style (e.g. `radix-nova`) and the resulting URL 404s. `{name}.json` resolves every DiceUI item, including the style-segmented ones.
+
+### Dependencies the registry doesn't declare
+
+The item declares `@tanstack/react-table`, `nuqs`, and `lucide-react`, and its registry dependencies (`badge`, `button`, `calendar`, `command`, `dropdown-menu`, `input`, `popover`, `select`, `separator`, `slider`, `table`) come in automatically. But the shipped files import more than that, and the gap doesn't surface until the build fails on a missing module:
+
+| Package | Needed by | Declared? |
+|---|---|---|
+| `zod` | `lib/parsers.ts` in the base item and both filter add-ons | **No — install it** |
+| `@dnd-kit/core`, `@dnd-kit/modifiers`, `@dnd-kit/sortable`, `@dnd-kit/utilities` | `ui/sortable.tsx`, pulled in by `data-table-sort-list` and `data-table-filter-list` | **No — install them** |
+| `radix-ui` | `ui/sortable.tsx` | Only implicitly. Fine on a `radix` base; on a `base`/`aria` project you must add it |
+| `react-day-picker`, `date-fns` | date filters | Yes — via the `calendar` registry dependency |
+
+So after adding, install the gaps with the project's package manager — e.g. `pnpm add zod` for the base item, plus the four `@dnd-kit/*` packages if you took either add-on.
+
+`npx shadcn@latest migrate radix` converts a project still on individual `@radix-ui/react-*` packages to the unified `radix-ui`.
+
+If the project's `iconLibrary` isn't `lucide`, run `npx shadcn@latest migrate icons --from lucide --to <lib>` over the added files rather than rewriting the imports by hand.
+
+After adding, follow the skill's review step: rewrite third-party import paths to the project `aliases`, swap icons to the project `iconLibrary`, and verify composition against the Critical Rules.
+
+## Server-side rendering pattern (Next.js App Router)
+
+Three pieces, in this order. (The broader URL-state convention — when to keep state in the URL vs React at all — lives in the project's `nextjs-fullstack` skill → `frontend-conventions.md`.)
+
+1) Wrap the app once with the nuqs adapter (root layout). **Not a setup detail you can defer** — `useDataTable` throws without it, and the failure surfaces inside the table component, far from the missing provider:
+
+```tsx
+// app/layout.tsx
+import { NuqsAdapter } from "nuqs/adapters/next/app";
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <NuqsAdapter>{children}</NuqsAdapter>
+      </body>
+    </html>
+  );
+}
+```
+
+2) Parse search params and fetch on the server — an RSC page, no `"use client"`.
+
+**Parse with the same parsers the client writes with; don't hand-read `searchParams`.** `sort` and (in advanced mode) `filters` are **JSON-encoded** in the URL, not `field:asc` strings — `getSortingStateParser` does a `JSON.parse` and validates the shape with zod, rejecting unknown column ids. Read them as plain strings on the server and you get a silent mismatch: the URL updates, the page re-renders, and the sort quietly never applies. Build a loader from the shipped parsers so both sides share one definition:
+
+```tsx
+// app/(portal)/users/search-params.ts
+import { createLoader, parseAsInteger, parseAsString } from "nuqs/server";
+import { getSortingStateParser } from "@/lib/parsers";
+
+export const usersSearchParams = {
+  page: parseAsInteger.withDefault(1),
+  perPage: parseAsInteger.withDefault(10),
+  sort: getSortingStateParser<User>().withDefault([{ id: "createdAt", desc: true }]),
+  status: parseAsString.withDefault(""),   // one entry per filterable column id
+};
+
+export const loadUsersSearchParams = createLoader(usersSearchParams);
+```
+
+```tsx
+// app/(portal)/users/page.tsx
+import { loadUsersSearchParams } from "./search-params";
+
+export default async function UsersPage({
+  searchParams,
+}: {
+  searchParams: Promise<Record<string, string | string[] | undefined>>;
+}) {
+  const sp = await loadUsersSearchParams(searchParams);  // typed: page, perPage, sort, filters
+  const { rows, pageCount } = await getUsers(sp); // do the filter/sort/paginate IN the query
+  return <UsersTable data={rows} pageCount={pageCount} />;
+}
+```
+
+3) Build the table on the client with `useDataTable` (needs `"use client"` when the project has `rsc: true`):
+
+```tsx
+"use client";
+import { useDataTable } from "@/hooks/use-data-table";          // paths follow your resolvedPaths/aliases
+import { DataTable } from "@/components/data-table/data-table";
+import { DataTableToolbar } from "@/components/data-table/data-table-toolbar";
+import { columns } from "./columns";
+
+export function UsersTable({ data, pageCount }: { data: User[]; pageCount: number }) {
+  const { table } = useDataTable({
+    data,
+    columns,                  // TanStack column defs; see the column contract below
+    pageCount,                // REQUIRED — server-driven page count
+    getRowId: (row) => row.id,
+    initialState: { sorting: [{ id: "createdAt", desc: true }] },
+  });
+
+  return (
+    <DataTable table={table}>
+      <DataTableToolbar table={table} />
+      {/* advanced: pass enableAdvancedFilter to useDataTable, then
+          <DataTableAdvancedToolbar table={table}>
+            <DataTableFilterList table={table} />
+            <DataTableSortList table={table} />
+          </DataTableAdvancedToolbar> */}
+    </DataTable>
+  );
+}
+```
+
+### The column contract (easy to get wrong)
+
+`useDataTable` sets `defaultColumn: { enableColumnFilter: false }`. A column is **not** filterable until you opt in, and the toolbar's filter control is chosen from `meta`:
+
+```tsx
+{
+  id: "status",                 // `id` must be set — the URL filter key is the column id
+  accessorKey: "status",
+  header: ({ column }) => <DataTableColumnHeader column={column} title="Status" />,
+  enableColumnFilter: true,     // required, or the column gets no filter
+  meta: {
+    label: "Status",            // shown in the toolbar / view options
+    variant: "multiSelect",     // drives the filter control
+    options: [                  // presence of `options` → array parser (comma-separated in the URL)
+      { label: "Active", value: "active" },
+      { label: "Banned", value: "banned" },
+    ],
+  },
+}
+```
+
+Other `meta` fields: `placeholder`, `range` (`[min, max]` for slider/range filters), `unit`, `icon`.
+
+### What the hook actually does
+
+- **`pageCount` is required** (typed `Required<Pick<TableOptions, "pageCount">>`), and the hook hardcodes `manualPagination`, `manualSorting`, and `manualFiltering` to `true`. **There is no client-side mode** — the server always does the work.
+- It returns `{ table, shallow, debounceMs, throttleMs }`, not just `table`. The toolbar components consume the extra fields.
+- URL keys it reads/writes: `page`, `perPage`, `sort`, plus one key per filterable column id. In advanced mode (`enableAdvancedFilter: true`) per-column keys are replaced by a single `filters` key plus `joinOperator`. Rename any of them via `queryKeys`.
+- Other options: `initialState`, `queryKeys`, `history` (`"push"` | `"replace"`, default `"replace"`), `debounceMs` (300), `throttleMs` (50), `clearOnDefault`, `enableAdvancedFilter`, `scroll`, `shallow`, `startTransition`.
+- `enableRowSelection` is on by default.
+
+## Components
+
+`useDataTable` (hook) · `DataTable` (accepts an `actionBar` prop for the row-selection bar) · `DataTableToolbar` / `DataTableAdvancedToolbar` · `DataTableFilterList` / `DataTableFilterMenu` · `DataTableSortList` · `DataTableColumnHeader` · `DataTableViewOptions` · `DataTablePagination` · `DataTableFacetedFilter` · `DataTableSliderFilter` · `DataTableDateFilter` · `DataTableRangeFilter` · `DataTableSkeleton`.
+
+`DataTableAdvancedToolbar`, `DataTableFilterList`, and `DataTableRangeFilter` ship with the `data-table-filter-list` / `data-table-filter-menu` add-ons, not the base item.
+
+## Small, local datasets
+
+`useDataTable` cannot do client-side pagination — it always requires `pageCount` and always runs manual mode. For a small in-memory dataset, either compute `pageCount` yourself and slice locally, or skip DiceUI and use shadcn `Table` with plain TanStack `useReactTable`.
+
+---
+
+Imports and paths above are **illustrative** — use the actual destinations from `npx shadcn@latest info` (`config.resolvedPaths`) and the project `aliases`. The DiceUI API evolves; confirm the current props/exports at <https://diceui.com/docs/components/radix/data-table> before implementing. (`npx shadcn@latest docs` only resolves first-party shadcn components, not DiceUI ones.)

package/skills/fullstack/shadcn/rules/forms.md

@@ -0,0 +1,255 @@
+# Forms & Inputs
+
+## Contents
+
+- The Field family (what each part is for)
+- Forms use FieldGroup + Field
+- InputGroup requires InputGroupInput/InputGroupTextarea
+- Buttons inside inputs use InputGroupButton + InputGroupAddon
+- Option sets (2–7 choices) use ToggleGroup
+- FieldSet + FieldLegend for grouping related fields
+- Field validation and disabled states
+- Error messages use FieldError
+
+---
+
+## The Field family
+
+Knowing the full export list prevents the two common failures: hand-rolling a part that already exists, and putting text in the wrong slot.
+
+| Component | Use for |
+|---|---|
+| `Field` | One control + its label/description/error. Props: `orientation="vertical" \| "horizontal" \| "responsive"` |
+| `FieldGroup` | Vertical stack of `Field`s. This is the form's layout primitive |
+| `FieldLabel` | The label. Pair with `htmlFor` |
+| `FieldTitle` | A heading for a field that has no single focusable control (e.g. a labelled `ToggleGroup`) |
+| `FieldDescription` | Helper text — muted, informational. **Not for errors** |
+| `FieldError` | The error message. Renders `role="alert"` in destructive color |
+| `FieldContent` | Wraps label+description when a control sits beside them (horizontal layouts) |
+| `FieldSet` + `FieldLegend` | Groups related checkboxes/radios/switches |
+| `FieldSeparator` | Divider between fields |
+
+---
+
+## Forms use FieldGroup + Field
+
+Always use `FieldGroup` + `Field` — never raw `div` with `space-y-*`:
+
+```tsx
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" type="email" />
+  </Field>
+  <Field>
+    <FieldLabel htmlFor="password">Password</FieldLabel>
+    <Input id="password" type="password" />
+  </Field>
+</FieldGroup>
+```
+
+Use `Field orientation="horizontal"` for settings pages. Use `FieldLabel className="sr-only"` for visually hidden labels.
+
+**Choosing form controls:**
+
+- Simple text input → `Input`
+- Dropdown with predefined options → `Select`
+- Searchable dropdown → `Combobox`
+- Native HTML select (no JS) → `native-select`
+- Boolean toggle → `Switch` (for settings) or `Checkbox` (for forms)
+- Single choice from few options → `RadioGroup`
+- Toggle between 2–5 options → `ToggleGroup` + `ToggleGroupItem`
+- OTP/verification code → `InputOTP`
+- Multi-line text → `Textarea`
+
+---
+
+## InputGroup requires InputGroupInput/InputGroupTextarea
+
+Never use raw `Input` or `Textarea` inside an `InputGroup`.
+
+**Incorrect:**
+
+```tsx
+<InputGroup>
+  <Input placeholder="Search..." />
+</InputGroup>
+```
+
+**Correct:**
+
+```tsx
+import { InputGroup, InputGroupInput } from "@/components/ui/input-group"
+
+<InputGroup>
+  <InputGroupInput placeholder="Search..." />
+</InputGroup>
+```
+
+---
+
+## Buttons inside inputs use InputGroupButton + InputGroupAddon
+
+Never place a `Button` directly inside or adjacent to an `Input` with custom positioning.
+
+Two details make or break this one:
+
+- Use **`InputGroupButton`**, not `Button`. It presets `variant="ghost"` and an input-scaled `size` — a plain `Button` inside an addon is too tall for the group and keeps its solid fill.
+- `InputGroupAddon` defaults to `align="inline-start"`. A **trailing** control needs `align="inline-end"`, or it silently renders on the left. Also available: `block-start` / `block-end`, which turn the group into a column (useful for a toolbar under a textarea).
+
+**Incorrect:**
+
+```tsx
+<div className="relative">
+  <Input placeholder="Search..." className="pr-10" />
+  <Button className="absolute right-0 top-0" size="icon">
+    <SearchIcon />
+  </Button>
+</div>
+```
+
+**Correct:**
+
+```tsx
+import {
+  InputGroup, InputGroupInput, InputGroupAddon, InputGroupButton,
+} from "@/components/ui/input-group"   // use the project's aliases.ui
+
+<InputGroup>
+  <InputGroupAddon>
+    <SearchIcon />
+  </InputGroupAddon>
+  <InputGroupInput placeholder="Search..." />
+  <InputGroupAddon align="inline-end">
+    <InputGroupButton size="icon-xs" aria-label="Clear">
+      <XIcon />
+    </InputGroupButton>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+`InputGroupText` is there for static affixes (`https://`, `.com`, a unit) — those aren't buttons and shouldn't be.
+
+---
+
+## Option sets (2–7 choices) use ToggleGroup
+
+Don't manually loop `Button` components with active state.
+
+**Incorrect:**
+
+```tsx
+const [selected, setSelected] = useState("daily")
+
+<div className="flex gap-2">
+  {["daily", "weekly", "monthly"].map((option) => (
+    <Button
+      key={option}
+      variant={selected === option ? "default" : "outline"}
+      onClick={() => setSelected(option)}
+    >
+      {option}
+    </Button>
+  ))}
+</div>
+```
+
+**Correct:**
+
+```tsx
+import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"
+
+<ToggleGroup>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+  <ToggleGroupItem value="monthly">Monthly</ToggleGroupItem>
+</ToggleGroup>
+```
+
+`spacing` defaults to `2` on both bases, so don't pass it just to restate the default. Pass `spacing={0}` when you want the segmented-control look — joined items with shared borders and squared inner corners.
+
+Combine with `Field` for labelled toggle groups. A `ToggleGroup` has no single focusable control to point a `FieldLabel` at, so use `FieldTitle` plus `aria-labelledby`:
+
+```tsx
+<Field orientation="horizontal">
+  <FieldTitle id="theme-label">Theme</FieldTitle>
+  <ToggleGroup aria-labelledby="theme-label" spacing={0}>
+    <ToggleGroupItem value="light">Light</ToggleGroupItem>
+    <ToggleGroupItem value="dark">Dark</ToggleGroupItem>
+    <ToggleGroupItem value="system">System</ToggleGroupItem>
+  </ToggleGroup>
+</Field>
+```
+
+> **Note:** `defaultValue` and `type`/`multiple` props differ between base and radix. See [base-vs-radix.md](./base-vs-radix.md#togglegroup).
+
+---
+
+## FieldSet + FieldLegend for grouping related fields
+
+Use `FieldSet` + `FieldLegend` for related checkboxes, radios, or switches — not `div` with a heading:
+
+```tsx
+<FieldSet>
+  <FieldLegend variant="label">Preferences</FieldLegend>
+  <FieldDescription>Select all that apply.</FieldDescription>
+  <FieldGroup className="gap-3">
+    <Field orientation="horizontal">
+      <Checkbox id="dark" />
+      <FieldLabel htmlFor="dark" className="font-normal">Dark mode</FieldLabel>
+    </Field>
+  </FieldGroup>
+</FieldSet>
+```
+
+---
+
+## Field validation and disabled states
+
+Both attributes are needed — `data-invalid`/`data-disabled` styles the field (label, description), while `aria-invalid`/`disabled` styles the control and carries the state to assistive tech.
+
+```tsx
+// Invalid.
+<Field data-invalid>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid />
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+
+// Disabled.
+<Field data-disabled>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" disabled />
+</Field>
+```
+
+Works for all controls: `Input`, `Textarea`, `Select`, `Checkbox`, `RadioGroupItem`, `Switch`, `Slider`, `NativeSelect`, `InputOTP`.
+
+**Drive it from state, don't conditionally spread.** `Field` styles on `data-[invalid=true]`, and React serializes a boolean `data-*` value to the string `"true"`/`"false"`. So a plain expression is enough — `data-invalid={false}` leaves the attribute in the DOM as `"false"` and correctly stays unstyled. There's no need for the `{...(bad && { "data-invalid": true })}` trick people reach for:
+
+```tsx
+<Field data-invalid={!!errors.email}>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid={!!errors.email} />
+  <FieldError errors={errors.email ? [errors.email] : undefined} />
+</Field>
+```
+
+---
+
+## Error messages use FieldError
+
+`FieldError` is not a styled `FieldDescription` — it renders `role="alert"`, so screen readers announce the failure when it appears. `FieldDescription` is muted helper text with no live-region semantics, so an error placed there is invisible to assistive tech and the wrong color.
+
+It takes either children or an `errors` array:
+
+```tsx
+// Plain message.
+<FieldError>Passwords do not match.</FieldError>
+
+// From a validation library — the array shape is `{ message?: string }[]`,
+// which is exactly what react-hook-form / Zod resolvers hand back.
+<FieldError errors={[errors.password, errors.confirm]} />
+```
+
+Two behaviors worth relying on rather than reimplementing: it returns `null` when there's nothing to show (no empty-state guard needed at the call site), and given multiple errors it de-duplicates by message and renders a bulleted list.