@draekien/create-d9-app 0.0.2 → 0.0.4

package/templates/base/.agents/skills/shadcn/scripts/showcase-coverage.mjs

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+// Lists installed UI components that no file in the showcase imports.
+// Usage: node showcase-coverage.mjs <ui-dir> <showcase-dir...>
+import { readdirSync, readFileSync, statSync } from "node:fs"
+import { basename, extname, join, resolve } from "node:path"
+
+const [uiArg, ...roots] = process.argv.slice(2)
+
+if (!uiArg || roots.length === 0) {
+  console.error("Usage: node showcase-coverage.mjs <ui-dir> <showcase-dir...>")
+  process.exit(1)
+}
+
+const uiDir = resolve(uiArg)
+
+const components = readdirSync(uiDir)
+  .filter((file) => [".tsx", ".ts"].includes(extname(file)))
+  .map((file) => basename(file, extname(file)))
+
+function walk(path) {
+  if (statSync(path).isFile()) {
+    return [path]
+  }
+
+  return readdirSync(path).flatMap((entry) => {
+    const child = join(path, entry)
+    // Skip the ui directory so components don't count as using each other.
+    if (entry === "node_modules" || child === uiDir) {
+      return []
+    }
+    return walk(child)
+  })
+}
+
+const source = roots
+  .map((root) => resolve(root))
+  .flatMap(walk)
+  .filter((file) => /\.(tsx?|jsx?)$/.test(file))
+  .map((file) => readFileSync(file, "utf8"))
+  .join("\n")
+
+const missing = components.filter(
+  (name) => !new RegExp(`/ui/${name}["']`).test(source)
+)
+
+console.log(
+  `${components.length - missing.length}/${components.length} components shown.`
+)
+
+if (missing.length > 0) {
+  console.log(`Missing: ${missing.join(", ")}`)
+  process.exit(1)
+}

package/templates/base/.agents/skills/upgrade-dependencies/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: upgrade-dependencies
+description: Upgrades outdated patch and minor dependency pins in a pnpm, npm, yarn or bun workspace to exact versions, runs build, check, typecheck and test, and reports every change. Applies when asked to "upgrade dependencies", "update packages", "bump versions", or "update deps".
+argument-hint: "[--accept]"
+allowed-tools: Bash(npm view *), Bash(gh release view *), Bash(gh api *), Bash(pnpm *), Bash(npm *), Bash(yarn *), Bash(bun *), Bash(git diff *), Bash(git status *)
+---
+
+# Upgrade dependencies
+
+Arguments: `$ARGUMENTS`. `--accept` means the developer accepts the breaking-change list in advance; proceed at step 4 without stopping.
+
+Apply patch and minor upgrades only. Never apply a major; list it as `held: major`.
+
+## 1. Read the workspace
+
+- Package manager: root `package.json` field `packageManager` (`pnpm@11.25.0` means `pnpm`). Call it `<pm>` below.
+- Manifests: root `package.json`, `apps/*/package.json`, `packages/*/package.json`.
+- Pins: entries in `dependencies`, `devDependencies`, `optionalDependencies`. Skip `workspace:*`, `link:`, `file:`, `git`, `npm:` alias and URL specs.
+- Minimum age in minutes: `minimumReleaseAge` in `pnpm-workspace.yaml` or `.npmrc`; if unset, `1440`.
+
+## 2. Find upgrades
+
+Run once per distinct package name:
+
+```sh
+npm view <pkg> versions time --json
+```
+
+```json
+{
+  "versions": ["5.9.2", "5.9.3", "6.0.0-beta", "6.0.2", "6.0.3"],
+  "time": {
+    "created": "2012-10-01T15:35:39.553Z",
+    "modified": "2026-10-10T08:24:07.208Z",
+    "5.9.3": "2025-09-30T21:19:38.784Z",
+    "6.0.0-beta": "2026-02-11T18:26:37.557Z",
+    "6.0.2": "2026-03-23T16:14:45.521Z",
+    "6.0.3": "2026-04-16T23:38:27.905Z"
+  }
+}
+```
+
+A package with one version returns `versions` as a string, not an array.
+
+Candidates: versions without a `-` prerelease suffix, with `time[version]` at least the minimum age before now.
+
+- Same major as the pin, newer than the pin: take the highest. Type is `minor` if the minor differs, else `patch`.
+- Higher major exists: record `held: major` with the highest eligible version. Do not apply it.
+- No candidate newer than the pin: current.
+
+If every pin is current, change no files, report `all pins current`, and stop.
+
+## 3. Read release notes
+
+For each package to upgrade, read the notes for every release after the old version up to and including the new one.
+
+```sh
+gh release view v<version> --repo <owner>/<repo> --json body
+```
+
+- Repository: `npm view <pkg> repository.url`.
+- No GitHub release for the tag: read `CHANGELOG.md` in the repository for the same range.
+- Record each breaking change, deprecation and migration step per package.
+
+## 4. Surface and stop
+
+Print one list: package, old version, new version, type, breaking changes and migrations (or `none found`). Then:
+
+- Without `--accept`: stop and ask the developer to accept or exclude packages. Edit nothing before the answer.
+- With `--accept`: continue.
+
+## 5. Apply
+
+- Set each upgraded pin to the exact new version: no `^`, no `~`, no `latest`.
+- Run `<pm> install`.
+- Run each project script with `<pm> run <script>` in this order: `build`, `check`, `typecheck`, `test`. Skip a script the root `package.json` does not define.
+
+## 6. Handle a failing check
+
+For each failure:
+
+- The release notes read in step 3 name the change and its migration: apply the migration, then re-run `<pm> install` and all four scripts.
+- Otherwise: set the package that caused the failure back to its old version, re-run `<pm> install` and all four scripts. Report it as `held: check failed` with the error text.
+
+Repeat until `build`, `check`, `typecheck` and `test` all exit 0. Never finish with a failing check.
+
+## 7. Report
+
+Print a table of changed packages:
+
+| Package | Old | New | Type |
+| --- | --- | --- | --- |
+| typescript | 5.9.2 | 5.9.3 | patch |
+
+Below it list:
+
+- `held: major`: package, current version, newest eligible major.
+- `held: check failed`: package, old version, attempted version, error text.
+- Migrations applied, with the file changed.

package/templates/base/.claude/rules/components.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "**/*.tsx"
+---
+
+# Components
+
+- Render is pure: no DOM reads, network, or subscriptions during render. Those belong in effects or handlers.
+- Route errors: set `errorComponent` on the route (`defaultErrorComponent` on the router); in it, `useRouter().invalidate()` retries a failed load, `reset` retries a render. Throw `notFound()` for a missing resource.
+- Subtree errors inside a route: `<CatchBoundary getResetKey={() => key} errorComponent={…}>` from `@tanstack/react-router`.
+- Query errors: `throwOnError` to the boundary, reset with `useQueryErrorResetBoundary()` in its `onReset`.

package/templates/base/.claude/rules/generated-files.md

@@ -0,0 +1,11 @@
+---
+paths:
+  - "apps/*/src/**/*.gen.*"
+  - "apps/*/src/**/*.g.*"
+  - "packages/*/src/**/*.gen.*"
+  - "packages/*/src/**/*.g.*"
+---
+
+# Generated files
+
+- Never edit by hand. Rerun the generator; if the generator is unknown, ask which one.

package/templates/base/.claude/rules/testing.md

@@ -0,0 +1,13 @@
+---
+paths:
+  - "**/*.test.ts"
+  - "**/*.test.tsx"
+  - "**/*.spec.ts"
+  - "**/*.spec.tsx"
+---
+
+# Tests
+
+- Test behaviour through the public surface: `userEvent` and `getByRole`, assert outcomes (`toHaveBeenCalledWith`, rendered text). Never assert DOM structure or internals.
+- Cover edge cases and boundaries. Prioritise business logic, external integrations and authorisation over CRUD.
+- A test that breaks on a refactor with no behaviour change is rewritten or deleted.

package/templates/base/.claude/rules/typescript.md

@@ -0,0 +1,29 @@
+---
+paths:
+  - "**/*.{ts,tsx}"
+---
+
+# TypeScript
+
+- Model states and results as a discriminated union on a literal field (`kind`, `success`); never optional fields, never thrown control flow.
+- Narrow before use: type guard, `instanceof`, `in`, exhaustive `switch`. Close an if/else chain over a union with `return assertNever(value)`.
+- Treat `null` and `undefined` as cases to handle. `?.` and `??` only where absence is a valid state; otherwise check and throw.
+- Constrain every generic the body depends on (`T extends { id: string }`); leave `T` bare only for type-transparent functions. Name constrained parameters (`TBase`, `TOverride`).
+- Declare return types on exported functions; let locals infer. Annotate where inference widens (`string` where a literal union was meant).
+- `readonly`, `Readonly<T>`, `ReadonlyArray<T>` where mutation would be a bug; not everywhere.
+- Unavoidable assertion: contain it at the integration boundary under `// biome-ignore lint/nursery/noUnsafeTypeAssertion: <invariant>`; the asserted value never leaves that function.
+- Prop callbacks are `on<Event>`.
+
+## React state and effects
+
+- State is immutable: spread at every changed level, `setState((prev) => ({ ...prev, profile: { ...prev.profile, name } }))`. Aliases of state are state.
+- Derive during render. `useEffect` + `setState` only to sync with an external system; a form initialised once from query data is the one exception.
+- An effect that starts async work returns a cleanup that cancels it: `AbortController` or an `ignore` flag.
+- Lift stateful or async logic into a `use*` hook; one responsibility per component.
+
+## TanStack Query
+
+- Every variable `queryFn` reads is in `queryKey`. Keys come from one factory module per entity (`userKeys.detail(id)`).
+- Dependent query: `enabled: id !== undefined`. Independent queries run in parallel, never chained.
+- Override `staleTime` per query only when its freshness differs from the global default.
+- Render `mutation.error`. Optimistic update only for interactive, write-heavy UI: `onMutate` cancel and snapshot, `onError` restore, `onSettled` invalidate.

package/templates/base/.claude/skills/shadcn/SKILL.md

@@ -0,0 +1,295 @@
+---
+name: shadcn
+description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI, including chat interfaces. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", "switch to --preset", and for building a design system or applying a DESIGN.md or brand spec to shadcn/ui.
+user-invocable: false
+allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
+---
+
+# shadcn/ui
+
+A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.
+
+> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
+
+## Current Project Context
+
+```json
+!`npx shadcn@latest info --json`
+```
+
+The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
+
+## Principles
+
+1. **Use existing components first.** Use `npx shadcn@latest search` to check registries before writing custom UI. Check community registries too.
+2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
+3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
+4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.
+
+## Critical Rules
+
+These rules are **always enforced**. Each links to a file with Incorrect/Correct code pairs.
+
+### Styling & Tailwind → [styling.md](./rules/styling.md)
+
+- **`className` for layout, not styling.** Never override component colors or typography.
+- **No `space-x-*` or `space-y-*`.** Use `flex` with `gap-*`. For vertical stacks, `flex flex-col gap-*`.
+- **Use `size-*` when width and height are equal.** `size-10` not `w-10 h-10`.
+- **Use `truncate` shorthand.** Not `overflow-hidden text-ellipsis whitespace-nowrap`.
+- **No manual `dark:` color overrides.** Use semantic tokens (`bg-background`, `text-muted-foreground`).
+- **Use `cn()` for conditional classes.** Don't write manual template literal ternaries.
+- **No manual `z-index` on overlay components.** Dialog, Sheet, Popover, etc. handle their own stacking.
+
+### Forms & Inputs → [forms.md](./rules/forms.md)
+
+- **Forms use `FieldGroup` + `Field`.** Never use raw `div` with `space-y-*` or `grid gap-*` for form layout.
+- **`InputGroup` uses `InputGroupInput`/`InputGroupTextarea`.** Never raw `Input`/`Textarea` inside `InputGroup`.
+- **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.**
+- **Option sets (2–7 choices) use `ToggleGroup`.** Don't loop `Button` with manual active state.
+- **`FieldSet` + `FieldLegend` for grouping related checkboxes/radios.** Don't use a `div` with a heading.
+- **Field validation uses `data-invalid` + `aria-invalid`.** `data-invalid` on `Field`, `aria-invalid` on the control. For disabled: `data-disabled` on `Field`, `disabled` on the control.
+
+### Component Structure → [composition.md](./rules/composition.md)
+
+- **Items always inside their Group.** `SelectItem` → `SelectGroup`. `DropdownMenuItem` → `DropdownMenuGroup`. `CommandItem` → `CommandGroup`.
+- **Use `asChild` (radix) or `render` (base) for custom triggers.** Check `base` field from `npx shadcn@latest info`. → [base-vs-radix.md](./rules/base-vs-radix.md)
+- **Dialog, Sheet, and Drawer always need a Title.** `DialogTitle`, `SheetTitle`, `DrawerTitle` required for accessibility. Use `className="sr-only"` if visually hidden.
+- **Use full Card composition.** `CardHeader`/`CardTitle`/`CardDescription`/`CardContent`/`CardFooter`. Don't dump everything in `CardContent`.
+- **Button has no `isPending`/`isLoading`.** Compose with `Spinner` + `data-icon` + `disabled`.
+- **`TabsTrigger` must be inside `TabsList`.** Never render triggers directly in `Tabs`.
+- **`Avatar` always needs `AvatarFallback`.** For when the image fails to load.
+
+### Use Components, Not Custom Markup → [composition.md](./rules/composition.md)
+
+- **Use existing components before custom markup.** Check if a component exists before writing a styled `div`.
+- **Callouts use `Alert`.** Don't build custom styled divs.
+- **Empty states use `Empty`.** Don't build custom empty state markup.
+- **Toast follows the project base.** Use `toast` from the `toast` component for
+  Base UI projects. Use `toast()` from `sonner` for Radix and React Aria
+  projects.
+- **Use `Separator`** instead of `<hr>` or `<div className="border-t">`.
+- **Use `Skeleton`** for loading placeholders. No custom `animate-pulse` divs.
+- **Use `Badge`** instead of custom styled spans.
+
+### Icons → [icons.md](./rules/icons.md)
+
+- **Icons in `Button` use `data-icon`.** `data-icon="inline-start"` or `data-icon="inline-end"` on the icon.
+- **No sizing classes on icons inside components.** Components handle icon sizing via CSS. No `size-4` or `w-4 h-4`.
+- **Pass icons as objects, not string keys.** `icon={CheckIcon}`, not a string lookup.
+
+### Chat & Messaging → [chat.md](./rules/chat.md)
+
+- **Chat UI composes the chat primitives.** Conversations use `MessageScroller`, rows use `Message`, surfaces use `Bubble`. Never hand-rolled bubble `div`s or a raw scroll container.
+- **`MessageScroller` owns scroll behavior.** Streaming follow, anchoring, and jump-to-latest (`MessageScrollerButton`) are built in. Don't write a `useStickToBottom`/`ResizeObserver` hook.
+- **Attachments use `Attachment`; system notes and dividers use `Marker`.** Not `Item` cards or `Separator` + a label.
+
+### CLI
+
+- **Never decode preset codes or build preset URLs manually.** Use `npx shadcn@latest preset decode <code>`, `preset url <code>`, or `preset open <code>`. For project-aware preset detection, use `npx shadcn@latest preset resolve`.
+- **Apply preset codes directly with the CLI.** Use `npx shadcn@latest apply <code>` for existing projects, or `npx shadcn@latest init --preset <code>` when initializing.
+
+## Key Patterns
+
+These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.
+
+```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.
+<Field data-invalid>
+  <FieldLabel>Email</FieldLabel>
+  <Input aria-invalid />
+  <FieldDescription>Invalid email.</FieldDescription>
+</Field>
+
+// Icons in buttons: data-icon, no sizing classes.
+<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 variant="secondary">+20.1%</Badge>    // correct
+<span className="text-emerald-600">+20.1%</span> // wrong
+```
+
+## Component Selection
+
+| Need                       | Use                                                                                                 |
+| -------------------------- | --------------------------------------------------------------------------------------------------- |
+| Button/action              | `Button` with appropriate variant                                                                   |
+| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
+| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
+| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
+| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
+| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
+| Feedback                   | `toast` (Base UI), `sonner` (Radix/Aria), `Alert`, `Progress`, `Skeleton`, `Spinner`                 |
+| Command palette            | `Command` inside `Dialog`                                                                           |
+| Charts                     | `Chart` (wraps Recharts)                                                                            |
+| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
+| Empty states               | `Empty`                                                                                             |
+| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
+| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
+| Chat / conversation UI     | `MessageScroller`, `Message`, `Bubble`, `Attachment`, `Marker`                                      |
+
+## Key Fields
+
+The injected project context contains these key fields:
+
+- **`aliases`** → use the actual alias prefix for imports (e.g. `@/`, `~/`), never hardcode.
+- **`isRSC`** → when `true`, components using `useState`, `useEffect`, event handlers, or browser APIs need `"use client"` at the top of the file. Always reference this field when advising on the directive.
+- **`tailwindVersion`** → `"v4"` uses `@theme inline` blocks; `"v3"` uses `tailwind.config.js`.
+- **`tailwindCssFile`** → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
+- **`style`** → component visual treatment (e.g. `nova`, `vega`).
+- **`base`** → primitive library (`radix` or `base`). Affects component APIs and available props.
+- **`iconLibrary`** → determines icon imports. Use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, etc. Never assume `lucide-react`.
+- **`resolvedPaths`** → exact file-system destinations for components, utils, hooks, etc.
+- **`framework`** → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
+- **`packageManager`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
+- **`preset`** → resolved preset code and values for the current project. Use `npx shadcn@latest preset resolve --json` when you only need preset information.
+
+See [cli.md — `info` command](./cli.md) for the full field reference.
+
+## Component Docs, Examples, and Usage
+
+Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
+
+```bash
+npx shadcn@latest docs button dialog select
+```
+
+**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
+
+## Workflow
+
+1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
+2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
+3. **Find components** — `npx shadcn@latest search`.
+4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
+5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
+6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
+7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
+8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, `owner/repo`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
+9. **Switching presets** — Ask the user first: **overwrite**, **partial**, **merge**, or **skip**?
+   - **Inspect current preset**: `npx shadcn@latest preset resolve`. Use `--json` when you need structured values.
+   - **Inspect incoming preset**: `npx shadcn@latest preset decode <code>`. Use `preset url <code>` or `preset open <code>` to share or open the preset builder.
+   - **Overwrite**: `npx shadcn@latest apply <code>`. Overwrites detected components, fonts, and CSS variables.
+   - **Partial**: `npx shadcn@latest apply <code> --only theme,font`. Updates only the selected preset parts without reinstalling UI components. Supported values are `theme` and `font`; comma-separated combinations are allowed. `icon` is intentionally not supported, because icon changes may require full component reinstall and transforms.
+   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
+   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
+   - **Important**: Always run preset commands inside the user's project directory. `apply` only works in an existing project with a `components.json` file. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
+
+## Design Systems from DESIGN.md
+
+When the user asks for a design system from a `DESIGN.md` (or a brand spec), with or without a preset, follow [design-system.md](./design-system.md) end to end:
+
+1. `init --preset <code> --template <vite|next> --name <app> --no-monorepo -y`. Without a preset code, pick the closest style and pass `--base base --preset <style>`. Then `add --all -y`.
+2. Read the DESIGN.md frontmatter, Do's and Don'ts, and Known Gaps before editing.
+3. Map its tokens onto the shadcn variables in `tailwindCssFile`. Pin the radius scale, shadows, fonts and `type-*` utilities.
+4. Restyle components by editing their `cva` variants. Change control heights together.
+5. Build the design system page per [design-system-page.md](./design-system-page.md): contrast-checked color roles, type specimens, pinned state matrices, edge cases, do/don't pairs, recipes. Check coverage with `scripts/showcase-coverage.mjs`.
+6. Verify in a browser: typecheck, no console errors, loads at the top, no horizontal overflow, dark mode.
+
+## Updating Components
+
+When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
+
+1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
+2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
+3. Decide per file based on the diff:
+   - No local changes → safe to overwrite.
+   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
+   - User says "just update everything" → use `--overwrite`, but confirm first.
+4. **Never use `--overwrite` without the user's explicit approval.**
+
+## Quick Reference
+
+```bash
+# Create a new project.
+npx shadcn@latest init --name my-app --preset base-nova
+npx shadcn@latest init --name my-app --preset a2r6bw --template vite
+
+# Create a design system app (then follow design-system.md).
+npx shadcn@latest init --name my-ds --preset b0 --template vite --no-monorepo -y
+npx shadcn@latest init --name my-ds --base base --preset maia --template vite --no-monorepo -y
+npx shadcn@latest add --all -y
+
+# Create a monorepo project.
+npx shadcn@latest init --name my-app --preset base-nova --monorepo
+npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
+
+# Initialize existing project.
+npx shadcn@latest init --preset base-nova
+npx shadcn@latest init --defaults  # shortcut: --template=next --preset=nova (base style implied)
+
+# Apply a preset to an existing project.
+npx shadcn@latest apply a2r6bw
+npx shadcn@latest apply a2r6bw --only theme
+npx shadcn@latest apply a2r6bw --only font
+npx shadcn@latest apply a2r6bw --only theme,font
+
+# Inspect preset codes and project preset state.
+npx shadcn@latest preset decode a2r6bw
+npx shadcn@latest preset url a2r6bw
+npx shadcn@latest preset open a2r6bw
+npx shadcn@latest preset resolve
+npx shadcn@latest preset resolve --json
+
+# Add components.
+npx shadcn@latest add button card dialog
+npx shadcn@latest add @magicui/shimmer-button
+npx shadcn@latest add owner/repo/item
+npx shadcn@latest add --all
+
+# Preview changes before adding/updating.
+npx shadcn@latest add button --dry-run
+npx shadcn@latest add button --diff button.tsx
+npx shadcn@latest add @acme/form --view button.tsx
+npx shadcn@latest add owner/repo/item --dry-run
+
+# Search registries.
+npx shadcn@latest search @shadcn -q "sidebar"
+npx shadcn@latest search @tailark -q "stats"
+npx shadcn@latest search owner/repo -q "login"
+npx shadcn@latest search                          # all configured registries
+npx shadcn@latest search @shadcn -q "menu" -t ui  # filter by item type
+
+# Get component docs and example URLs.
+npx shadcn@latest docs button dialog select
+
+# View registry item details (for items not yet installed).
+npx shadcn@latest view @shadcn/button
+npx shadcn@latest view owner/repo/item
+```
+
+**Named presets:** `nova`, `vega`, `maia`, `lyra`, `mira`, `luma`
+**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
+**Preset codes:** Version-prefixed base62 strings (e.g. `a2r6bw` or `b0`), from [ui.shadcn.com](https://ui.shadcn.com).
+
+## Detailed References
+
+- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
+- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
+- [rules/chat.md](./rules/chat.md) — MessageScroller, Message, Bubble, Attachment, Marker; streaming, anchoring, jump-to-latest
+- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
+- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
+- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
+- [cli.md](./cli.md) — Commands, flags, presets, templates
+- [registry.md](./registry.md) — Authoring source registries, `include`, item definitions, dependencies, GitHub registry rules
+- [customization.md](./customization.md) — Theming, CSS variables, extending components
+- [design-system.md](./design-system.md): DESIGN.md (with or without a preset) to a themed app: style picking, token mapping, radius, fonts, type scale, control heights, showcase traps, verification
+- [design-system-page.md](./design-system-page.md): What goes on a design system page and how: foundations, component tiers, pinned state matrices, contrast pairs, edge cases, do/don't, recipes

package/templates/base/.claude/skills/shadcn/agents/openai.yml

@@ -0,0 +1,5 @@
+interface:
+  display_name: "shadcn/ui"
+  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
+  icon_small: "./assets/shadcn-small.png"
+  icon_large: "./assets/shadcn.png"

package/templates/base/.claude/skills/shadcn/assets/showcase/color-pair.tsx

@@ -0,0 +1,126 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+// Resolves any CSS color (hex, rgb, oklch, color-mix) to sRGB by painting one pixel.
+// Translucent colors are composited over the backdrop, as the browser would.
+function toRgb(color: string, backdrop = "#fff") {
+  const canvas = document.createElement("canvas")
+  canvas.width = canvas.height = 1
+  const context = canvas.getContext("2d", { willReadFrequently: true })
+  if (!context) {
+    return null
+  }
+  context.fillStyle = backdrop
+  context.fillRect(0, 0, 1, 1)
+  context.fillStyle = color
+  context.fillRect(0, 0, 1, 1)
+  const [r, g, b] = context.getImageData(0, 0, 1, 1).data
+  return [r, g, b]
+}
+
+function toHex(rgb: number[]) {
+  return `#${rgb.map((value) => value.toString(16).padStart(2, "0")).join("")}`
+}
+
+function luminance([r, g, b]: number[]) {
+  const [R, G, B] = [r, g, b].map((value) => {
+    const channel = value / 255
+    return channel <= 0.03928
+      ? channel / 12.92
+      : ((channel + 0.055) / 1.055) ** 2.4
+  })
+  return 0.2126 * R + 0.7152 * G + 0.0722 * B
+}
+
+function contrast(a: number[], b: number[]) {
+  const [light, dark] = [luminance(a), luminance(b)].sort((x, y) => y - x)
+  return (light + 0.05) / (dark + 0.05)
+}
+
+export function ColorPair({
+  name,
+  background,
+  foreground,
+  className,
+}: {
+  name: string
+  background: string
+  foreground: string
+  className?: string
+}) {
+  const ref = React.useRef<HTMLDivElement>(null)
+  const [info, setInfo] = React.useState<{ ratio: number; bg: string } | null>(
+    null
+  )
+
+  React.useEffect(() => {
+    const element = ref.current
+    if (!element) {
+      return
+    }
+    // Re-measure when the theme class on <html> changes.
+    const measure = () => {
+      const style = getComputedStyle(element)
+      const page = getComputedStyle(document.body).backgroundColor
+      const bg = toRgb(style.backgroundColor, page)
+      if (!bg) {
+        return
+      }
+      const fg = toRgb(style.color, toHex(bg))
+      if (fg) {
+        setInfo({ ratio: contrast(bg, fg), bg: toHex(bg) })
+      }
+    }
+    measure()
+    const observer = new MutationObserver(measure)
+    observer.observe(document.documentElement, { attributes: true })
+    return () => observer.disconnect()
+  }, [])
+
+  const level = !info
+    ? ""
+    : info.ratio >= 7
+      ? "AAA"
+      : info.ratio >= 4.5
+        ? "AA"
+        : info.ratio >= 3
+          ? "AA Large"
+          : "Fail"
+
+  return (
+    <div
+      className={cn(
+        "flex flex-col overflow-hidden rounded-xl border",
+        className
+      )}
+    >
+      <div
+        ref={ref}
+        style={{
+          backgroundColor: `var(--${background})`,
+          color: `var(--${foreground})`,
+        }}
+        className="flex h-24 items-end justify-between p-4"
+      >
+        <span className="text-2xl font-medium">Aa</span>
+        {info && (
+          <span className="rounded-full border border-current/20 px-2 py-0.5 font-mono text-xs">
+            {info.ratio.toFixed(2)} {level}
+          </span>
+        )}
+      </div>
+      <div className="flex flex-col gap-0.5 bg-background p-3">
+        <span className="text-sm font-medium">{name}</span>
+        <span className="font-mono text-xs text-muted-foreground">
+          --{background} / --{foreground}
+        </span>
+        {info && (
+          <span className="font-mono text-xs text-muted-foreground">
+            {info.bg}
+          </span>
+        )}
+      </div>
+    </div>
+  )
+}