@1aboveio/skills 0.10.0

package/skills/fullstack/shadcn/evals/evals.json

@@ -0,0 +1,90 @@
+{
+  "skill_name": "shadcn",
+  "evals": [
+    {
+      "id": 1,
+      "prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
+      "expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
+      "files": [],
+      "expectations": [
+        "Uses FieldGroup and Field components for form layout instead of raw div with space-y",
+        "Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
+        "Uses data-invalid on Field and aria-invalid on the input control for validation states",
+        "Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
+        "Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
+        "No manual dark: color overrides"
+      ]
+    },
+    {
+      "id": 2,
+      "prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
+      "expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
+      "files": [],
+      "expectations": [
+        "Includes DialogTitle for accessibility (visible or with sr-only class)",
+        "Avatar component includes AvatarFallback",
+        "Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
+        "No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
+        "Uses tabler icons (@tabler/icons-react) instead of lucide-react",
+        "Uses asChild for custom triggers (radix preset)"
+      ]
+    },
+    {
+      "id": 3,
+      "prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
+      "expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
+      "files": [],
+      "expectations": [
+        "Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
+        "Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
+        "Uses Badge component for percentage change instead of custom styled spans",
+        "Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
+        "Uses gap-* instead of space-y-* or space-x-* for spacing",
+        "Uses size-* when width and height are equal instead of separate w-* h-*"
+      ]
+    },
+    {
+      "id": 4,
+      "prompt": "Our signup form needs real validation. It's a Next.js App Router app on shadcn (radix-nova, lucide). Fields are email, password, confirm password. We use react-hook-form with a zod resolver. When a field fails, show the message under it in red, and make sure screen readers actually announce it — our a11y audit flagged that our current form errors are silent.",
+      "expected_output": "A client component using FieldGroup/Field, FieldError (not FieldDescription) for messages, data-invalid on Field and aria-invalid on the control driven from formState.errors.",
+      "files": [],
+      "expectations": [
+        "Error messages render in FieldError, not FieldDescription",
+        "Does not hand-roll an error element such as a <p className=\"text-destructive\"> or a custom role=alert div",
+        "Field receives data-invalid driven from the form's error state",
+        "The control receives aria-invalid driven from the same error state",
+        "Uses FieldGroup + Field for layout rather than div with space-y-* or grid gap-*",
+        "Includes the \"use client\" directive, since react-hook-form needs client-side state"
+      ]
+    },
+    {
+      "id": 5,
+      "prompt": "I need a /admin/orders page in our Next.js App Router app (shadcn radix-nova, pnpm, lucide icons). It has to list orders with filtering by status, sorting by date and total, and pagination — and the filters need to survive a refresh and be shareable as a link, because support staff paste these URLs to each other. Orders table is big, ~400k rows, so it can't all come down to the browser.",
+      "expected_output": "Installs the DiceUI data-table from a working registry URL, wires an RSC page that parses searchParams and queries server-side, and a client table component using useDataTable with a required pageCount.",
+      "files": [],
+      "expectations": [
+        "Any shadcn add command for the data table uses a registry URL ending in .json (an extensionless diceui.com/r/ URL 404s)",
+        "Passes pageCount to useDataTable rather than omitting it or relying on client-side pagination",
+        "Filtering, sorting and pagination are performed in the server query, not over an in-memory array of all rows",
+        "Filterable columns set enableColumnFilter: true and supply column meta (label/variant, plus options for select filters)",
+        "Wraps the app with NuqsAdapter or notes it is already required for URL state",
+        "The page component reads searchParams on the server; only the table component is a client component",
+        "Parses sort on the server with the shipped getSortingStateParser (or an equivalent nuqs loader) rather than treating the sort param as a plain field:asc string, since it is JSON-encoded",
+        "Flags or installs zod, which lib/parsers.ts imports but the registry item does not declare"
+      ]
+    },
+    {
+      "id": 6,
+      "prompt": "we're on shadcn and i customized components/ui/button.tsx a while back (added a 'warning' variant and tweaked the focus ring). upstream has moved on and i want the new button improvements without losing my changes. also we're switching the whole app off lucide to tabler icons. what's the safe way to do both?",
+      "expected_output": "Uses add --dry-run/--diff to review upstream changes and merge manually rather than --overwrite, and uses migrate icons --from lucide --to tabler rather than hand-editing imports.",
+      "files": [],
+      "expectations": [
+        "Uses shadcn add button --dry-run and/or --diff to inspect upstream changes before writing",
+        "Does not run --overwrite without flagging that local customizations would be lost and asking first",
+        "Does not fetch button.tsx from GitHub or any raw source URL to diff manually",
+        "Recommends shadcn migrate icons --from lucide --to tabler instead of manually rewriting import statements",
+        "Notes that iconLibrary in components.json should end up as tabler so future added components match"
+      ]
+    }
+  ]
+}

package/skills/fullstack/shadcn/mcp.md

@@ -0,0 +1,101 @@
+# shadcn MCP Server
+
+The CLI includes an MCP server that lets AI assistants search, browse, view, and install components from registries.
+
+---
+
+## Setup
+
+```bash
+shadcn mcp                                # start the MCP server (stdio)
+shadcn mcp init                           # write config for your editor (prompts)
+shadcn mcp init --client claude           # claude | cursor | vscode | codex | opencode
+```
+
+Editor config files:
+
+| Editor | Config file |
+|--------|------------|
+| Claude Code | `.mcp.json` |
+| Cursor | `.cursor/mcp.json` |
+| VS Code | `.vscode/mcp.json` |
+| OpenCode | `opencode.json` |
+| Codex | `~/.codex/config.toml` (manual) |
+
+---
+
+## Tools
+
+> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
+
+### `shadcn:get_project_registries`
+
+Returns registry names from `components.json`. Errors if no `components.json` exists.
+
+**Input:** none
+
+### `shadcn:list_items_in_registries`
+
+Lists all items from one or more registries.
+
+**Input:** `registries` (string[]), `types` (string[], optional — e.g. `ui`, `block`, `hook`), `limit` (number, optional), `offset` (number, optional)
+
+### `shadcn:search_items_in_registries`
+
+Fuzzy search across registries.
+
+**Input:** `registries` (string[]), `query` (string), `types` (string[], optional), `limit` (number, optional), `offset` (number, optional)
+
+### `shadcn:view_items_in_registries`
+
+View item details including full file contents.
+
+**Input:** `items` (string[]) — e.g. `["@shadcn/button", "@shadcn/card"]`
+
+### `shadcn:get_item_examples_from_registries`
+
+Find usage examples and demos with source code.
+
+**Input:** `registries` (string[]), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
+
+### `shadcn:get_add_command_for_items`
+
+Returns the CLI install command.
+
+**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
+
+### `shadcn:get_audit_checklist`
+
+Returns a checklist for verifying components (imports, deps, lint, TypeScript).
+
+**Input:** none
+
+---
+
+## Configuring Registries
+
+Registries are set in `components.json`. The `@shadcn` registry is always built-in, as `https://ui.shadcn.com/r/styles/{style}/{name}.json`.
+
+Prefer `npx shadcn@latest registry add @acme` (or `@acme=https://acme.com/r/{name}.json`) over hand-editing this object.
+
+```json
+{
+  "registries": {
+    "@acme": "https://acme.com/r/{name}.json",
+    "@private": {
+      "url": "https://private.com/r/{name}.json",
+      "params": { "version": "2" },
+      "headers": { "Authorization": "Bearer ${MY_TOKEN}" }
+    }
+  }
+}
+```
+
+- Names must start with `@`.
+- URLs must contain `{name}`. `{style}` is also substituted, from `components.json`'s `style` (the full `<base>-<preset>`, e.g. `radix-nova`) — only use it if the registry really is style-segmented, or resolution will 404.
+- Object form supports `url` (required), `params` (query string), and `headers`.
+- `${VAR}` references are resolved from environment variables.
+
+Community registry index: `https://ui.shadcn.com/r/registries.json`. Verify a template from that index actually resolves before trusting it — some entries publish a `{style}` URL whose items don't exist per-style.
+
+Validate a registry you author with `npx shadcn@latest registry validate`.

package/skills/fullstack/shadcn/rules/base-vs-radix.md

@@ -0,0 +1,323 @@
+# Base vs Radix
+
+API differences between `base` (Base UI) and `radix` (Radix UI). Check `config.base` from `npx shadcn@latest info`.
+
+## Contents
+
+- A third base: aria
+- Composition: asChild vs render
+- Button / trigger as non-button element
+- Select (items prop, placeholder, positioning, multiple, object values)
+- ToggleGroup (type vs multiple)
+- Slider (scalar vs array)
+- Accordion (type and defaultValue)
+
+---
+
+## A third base: `aria`
+
+`config.base` can also be **`aria`** — components built on Adobe's [React Aria](https://react-aria.adobe.com). It's selected at init with `npx shadcn@latest init --base aria` and stored in `components.json` as `style: "aria-<preset>"`.
+
+The rules below are documented for `base` and `radix` only and **do not describe the aria API**. When a project's base is `aria`, don't extrapolate from either column — pull the real API first:
+
+```bash
+npx shadcn@latest docs button select --base aria
+```
+
+Docs resolve to `https://ui.shadcn.com/docs/components/aria/<component>`, with an `api` link into the React Aria reference.
+
+One aria-specific trap worth carrying: **don't use `<Button>` for links.** React Aria's `Button` always applies `role="button"`, which overrides the link semantics of an `<a>`. Use the `buttonVariants` helper on a plain `<a>` instead.
+
+---
+
+## Composition: asChild (radix) vs render (base)
+
+Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
+
+**Incorrect:**
+
+```tsx
+<DialogTrigger>
+  <div>
+    <Button>Open</Button>
+  </div>
+</DialogTrigger>
+```
+
+**Correct (radix):**
+
+```tsx
+<DialogTrigger asChild>
+  <Button>Open</Button>
+</DialogTrigger>
+```
+
+**Correct (base):**
+
+```tsx
+<DialogTrigger render={<Button />}>Open</DialogTrigger>
+```
+
+This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
+
+---
+
+## Button / trigger as non-button element (base only)
+
+When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
+
+**Incorrect (base):** missing `nativeButton={false}`.
+
+```tsx
+<Button render={<a href="/docs" />}>Read the docs</Button>
+```
+
+**Correct (base):**
+
+```tsx
+<Button render={<a href="/docs" />} nativeButton={false}>
+  Read the docs
+</Button>
+```
+
+**Correct (radix):**
+
+```tsx
+<Button asChild>
+  <a href="/docs">Read the docs</a>
+</Button>
+```
+
+Same for triggers whose `render` is not a `Button`:
+
+```tsx
+// base.
+<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
+  Pick date
+</PopoverTrigger>
+```
+
+---
+
+## Select
+
+**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
+
+**Incorrect (base):**
+
+```tsx
+<Select>
+  <SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>
+</Select>
+```
+
+**Correct (base):**
+
+```tsx
+const items = [
+  { label: "Select a fruit", value: null },
+  { label: "Apple", value: "apple" },
+  { label: "Banana", value: "banana" },
+]
+
+<Select items={items}>
+  <SelectTrigger>
+    <SelectValue />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      {items.map((item) => (
+        <SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
+      ))}
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Correct (radix):**
+
+```tsx
+<Select>
+  <SelectTrigger>
+    <SelectValue placeholder="Select a fruit" />
+  </SelectTrigger>
+  <SelectContent>
+    <SelectGroup>
+      <SelectItem value="apple">Apple</SelectItem>
+      <SelectItem value="banana">Banana</SelectItem>
+    </SelectGroup>
+  </SelectContent>
+</Select>
+```
+
+**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
+
+**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
+
+```tsx
+// base.
+<SelectContent alignItemWithTrigger={false} side="bottom">
+
+// radix.
+<SelectContent position="popper">
+```
+
+---
+
+## Select — multiple selection and object values (base only)
+
+Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
+
+**Correct (base — multiple selection):**
+
+```tsx
+<Select items={items} multiple defaultValue={[]}>
+  <SelectTrigger>
+    <SelectValue>
+      {(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}
+    </SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+**Correct (base — object values):**
+
+```tsx
+<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
+  <SelectTrigger>
+    <SelectValue>{(value) => value.name}</SelectValue>
+  </SelectTrigger>
+  ...
+</Select>
+```
+
+---
+
+## ToggleGroup
+
+Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
+
+**Incorrect (base):**
+
+```tsx
+<ToggleGroup type="single" defaultValue="daily">
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (base):**
+
+```tsx
+// Single (no prop needed), defaultValue is always an array.
+<ToggleGroup defaultValue={["daily"]} spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup multiple>
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Correct (radix):**
+
+```tsx
+// Single, defaultValue is a string.
+<ToggleGroup type="single" defaultValue="daily" spacing={2}>
+  <ToggleGroupItem value="daily">Daily</ToggleGroupItem>
+  <ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
+</ToggleGroup>
+
+// Multi-selection.
+<ToggleGroup type="multiple">
+  <ToggleGroupItem value="bold">Bold</ToggleGroupItem>
+  <ToggleGroupItem value="italic">Italic</ToggleGroupItem>
+</ToggleGroup>
+```
+
+**Controlled single value:**
+
+```tsx
+// base — wrap/unwrap arrays.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
+
+// radix — plain string.
+const [value, setValue] = React.useState("normal")
+<ToggleGroup type="single" value={value} onValueChange={setValue}>
+```
+
+---
+
+## Slider
+
+Base accepts a plain number for a single thumb. Radix always requires an array.
+
+**Incorrect (base):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+**Correct (base):**
+
+```tsx
+<Slider defaultValue={50} max={100} step={1} />
+```
+
+**Correct (radix):**
+
+```tsx
+<Slider defaultValue={[50]} max={100} step={1} />
+```
+
+Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
+
+```tsx
+// base.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
+
+// radix.
+const [value, setValue] = React.useState([0.3, 0.7])
+<Slider value={value} onValueChange={setValue} />
+```
+
+---
+
+## Accordion
+
+Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
+
+**Incorrect (base):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (base):**
+
+```tsx
+<Accordion defaultValue={["item-1"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+
+// Multi-select.
+<Accordion multiple defaultValue={["item-1", "item-2"]}>
+  <AccordionItem value="item-1">...</AccordionItem>
+  <AccordionItem value="item-2">...</AccordionItem>
+</Accordion>
+```
+
+**Correct (radix):**
+
+```tsx
+<Accordion type="single" collapsible defaultValue="item-1">
+  <AccordionItem value="item-1">...</AccordionItem>
+</Accordion>
+```

package/skills/fullstack/shadcn/rules/component-selection.md

@@ -0,0 +1,67 @@
+# Component Selection
+
+Reach for an existing component before writing markup. Almost every "just a styled `div`" in a shadcn codebase is a component someone didn't know existed — and the hand-rolled version misses the states (focus, disabled, invalid, dark mode) that the real one already handles.
+
+| Need | Use |
+| --- | --- |
+| Button/action | `Button` — variants: `default`, `outline`, `secondary`, `ghost`, `destructive`, `link` |
+| Related buttons in a row | `ButtonGroup` (+ `ButtonGroupSeparator`, `ButtonGroupText`) |
+| Form layout | `Field` family — see [forms.md](./forms.md) for the full export list |
+| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Input with affix/button | `InputGroup` + `InputGroupInput` + `InputGroupAddon` / `InputGroupButton` / `InputGroupText` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` |
+| List rows (not a table) | `Item` family — `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemActions` |
+| Data display | `Table`, `Card`, `Badge`, `Avatar` — static/read-only only |
+| Portal list/index page | **DiceUI DataTable** — the default there, not a bare `Table`. See [data-table.md](./data-table.md) |
+| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` |
+| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) |
+| Feedback | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner` |
+| Command palette | `Command` inside `Dialog` |
+| Charts | `Chart` (wraps Recharts) |
+| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` |
+| Empty states | `Empty` (+ `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`) |
+| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` |
+| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |
+
+Not sure whether something exists? `npx shadcn@latest search @shadcn -q "<thing>"` answers it in one call — cheaper than building the wrong thing and cheaper than guessing.
+
+## Key patterns
+
+The handful of shapes that most often separate correct shadcn code from plausible-looking code. Edge cases live in the rule files linked from [SKILL.md](../SKILL.md#critical-rules).
+
+```tsx
+// Form layout: FieldGroup + Field, not div + Label.
+<FieldGroup>
+  <Field>
+    <FieldLabel htmlFor="email">Email</FieldLabel>
+    <Input id="email" />
+  </Field>
+</FieldGroup>
+
+// Validation: data-invalid on Field, aria-invalid on the control, error in FieldError.
+// FieldError carries role="alert"; FieldDescription is muted helper text and announces nothing.
+<Field data-invalid={!!error}>
+  <FieldLabel htmlFor="email">Email</FieldLabel>
+  <Input id="email" aria-invalid={!!error} />
+  <FieldError>Enter a valid email address.</FieldError>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes — the component sizes its own icons.
+<Button>
+  <SearchIcon data-icon="inline-start" />
+  Search
+</Button>
+
+// Spacing: gap-*, not space-y-*.
+<div className="flex flex-col gap-4">  // correct
+<div className="space-y-4">           // wrong
+
+// Equal dimensions: size-*, not w-* h-*.
+<Avatar className="size-10">   // correct
+<Avatar className="w-10 h-10"> // wrong
+
+// Status colors: Badge variants or semantic tokens, not raw colors.
+// Badge has no `success` variant — an invalid one falls back silently.
+<Badge variant="secondary">+20.1%</Badge>        // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```