# Pathrule Pattern: shadcn/ui (1.0.0) # ::pathrule:package:shadcn-ui ### [RULE] Treat /components/ui as generated, composable code (path: /src/components/ui) Files under `components/ui` are owned by the shadcn registry workflow, not hand-authored from scratch. - Add or update a primitive with `npx shadcn@latest add ` instead of writing it by hand, so dependencies and registry metadata stay correct. - Before re-running `add`, review changes with the `--diff` and `--dry-run` flags so local customizations are not silently overwritten. - When you need new behavior, build a feature component in `components/` that imports the primitive; do not fork the primitive in place. - Keep the `cn` helper from `lib/utils` (`clsx` + `tailwind-merge`) as the only class-merging utility so variant overrides resolve predictably. --- ### [RULE] Theme only through semantic CSS variables (path: /src/app) shadcn/ui themes via semantic CSS variables defined in your global stylesheet, and every color must flow through them. - Use semantic utility classes (`bg-background`, `text-foreground`, `border-border`, `bg-primary`, `text-muted-foreground`) instead of `bg-white`, `text-zinc-900`, or hex values. - Define and adjust the palette by editing the `--background`, `--foreground`, `--primary`, and related CSS variables in your global CSS, not by sprinkling colors across components. - Provide both `:root` and `.dark` blocks so dark mode resolves from the same token names; never branch with `dark:bg-[#...]` hardcodes. - With Tailwind v4 leave `tailwind.config` blank in `components.json` and rely on the `@import` driven setup and `@theme` tokens. --- ### [MEMORY] How shadcn/ui actually works in this repo (path: /) shadcn/ui is a code distribution system, not a component dependency, so the source of truth lives in our own files. - Running the CLI copies component source into `components/ui` and wires aliases from `components.json` (`components`, `ui`, `lib`, `utils`, `hooks`); there is no `@shadcn/ui` runtime import. - As of 2026 primitives sit on the unified `radix-ui` package (single import surface) styled with Tailwind v4 and `class-variance-authority` variants. - The `components.json` `style` is `new-york` and `baseColor` picks the token palette (`neutral`, `stone`, `zinc`, `mauve`, and similar); `cssVariables: true` is what enables semantic-token theming. - Treat the `cn` helper, the CSS-variable tokens, and the registry-managed primitives as the three pillars: edit tokens for theme, compose for features, re-run the CLI for upstream fixes. --- ### [MEMORY] CLI v4, namespaced registries, and the MCP server (path: /src/components) The shadcn CLI v4 plus registries are how we install and extend UI; learn the workflow before adding components. - Core commands: `init` (scaffolds and writes `components.json`), `add`, `search`, `view`, `build`, plus `info` and `docs` for inspecting installed components and reading their docs. - Namespaced registries let you install with `@registry/name` syntax; declare them in `components.json` under `registries`, for example `"@acme": "https://acme.com/r/{name}.json"`, and use header-based auth with env vars for private registries. - Pin private or pro registries to a tag or digest in the URL so installs are reproducible, and prefer kebab-case item names with accurate `registryDependencies`. - The shadcn MCP server (`npx shadcn@latest mcp init --client claude`) lets an agent search, preview, and add components across configured registries in natural language with zero extra config. --- ### [SKILL] shadcn-ui-review (path: /) --- name: shadcn-ui-review description: Review a shadcn/ui change before merge. Verifies CSS-variable theming, component composition over forking, correct CLI and registry usage, and accessibility. Use when adding or editing components under components/ui or any UI built on shadcn primitives. --- # shadcn/ui review - [ ] No `@shadcn/ui` or external UI-library runtime imports; primitives live in `components/ui` and were added via the CLI. - [ ] Colors use semantic tokens (`bg-background`, `text-foreground`, `bg-primary`) with no hardcoded hex or raw palette classes. - [ ] Theme changes were made by editing CSS variables in global CSS, with matching `:root` and `.dark` blocks. - [ ] New behavior is composed in `components/` around primitives rather than forking the generated primitive. - [ ] Class merging goes through the `cn` helper so variant overrides resolve via `tailwind-merge`. - [ ] `components.json` is intact: Tailwind v4 `tailwind.config` blank, `cssVariables: true`, aliases unchanged. - [ ] Registry installs use correct namespaces and pinned versions; private registries authenticate via env-var headers. - [ ] Accessibility preserved: Radix primitive props, `aria-*`, focus states, and keyboard interaction are not stripped. - [ ] Dark mode and both color schemes verified visually for the changed components.