shadcn/ui
Pathrule2 Rules • 2 Memories • 1 Skill
shadcn/ui is a code distribution system that copies accessible, Tailwind-styled React components straight into your repo via a CLI and registries, so you own and edit every line. This pattern keeps your team aligned on theming through CSS variables, safe component composition, and the CLI and registry workflow. It encodes the current 2026 conventions: Tailwind v4, the unified Radix UI package, namespaced registries, and the shadcn MCP server.
Suggested path map
Pathrule places each piece on the matching path, so your assistant only sees it where it belongs. This is the scoping you get on import; you can adjust it in your workspace.
/ workspace root
How shadcn/ui actually works in this repo
shadcn-ui-review
src/
components/
CLI v4, namespaced registries, and the MCP server
ui/
Treat /components/ui as generated, composable code
app/
Theme only through semantic CSS variables
Rules
2Treat /components/ui as generated, composable code/src/components/uiAdd and update primitives through the CLI; compose around them rather than rewriting them.
| 1 | Files under `components/ui` are owned by the shadcn registry workflow, not hand-authored from scratch. |
| 2 | |
| 3 | - Add or update a primitive with `npx shadcn@latest add <component>` instead of writing it by hand, so dependencies and registry metadata stay correct. |
| 4 | - Before re-running `add`, review changes with the `--diff` and `--dry-run` flags so local customizations are not silently overwritten. |
| 5 | - When you need new behavior, build a feature component in `components/` that imports the primitive; do not fork the primitive in place. |
| 6 | - Keep the `cn` helper from `lib/utils` (`clsx` + `tailwind-merge`) as the only class-merging utility so variant overrides resolve predictably. |
Theme only through semantic CSS variables/src/apphighstrictStyle with token classes like bg-background and text-primary, never raw hex or palette colors.
| 1 | shadcn/ui themes via semantic CSS variables defined in your global stylesheet, and every color must flow through them. |
| 2 | |
| 3 | - 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. |
| 4 | - 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. |
| 5 | - Provide both `:root` and `.dark` blocks so dark mode resolves from the same token names; never branch with `dark:bg-[#...]` hardcodes. |
| 6 | - With Tailwind v4 leave `tailwind.config` blank in `components.json` and rely on the `@import` driven setup and `@theme` tokens. |
Memories
2How shadcn/ui actually works in this repo/rootComponents are copied into the codebase via CLI and registries; nothing is imported from a UI package.
| 1 | shadcn/ui is a code distribution system, not a component dependency, so the source of truth lives in our own files. |
| 2 | |
| 3 | - 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. |
| 4 | - As of 2026 primitives sit on the unified `radix-ui` package (single import surface) styled with Tailwind v4 and `class-variance-authority` variants. |
| 5 | - 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. |
| 6 | - 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. |
CLI v4, namespaced registries, and the MCP server/src/componentsUse the v4 CLI plus namespaced registries and the shadcn MCP server to add and discover components.
| 1 | The shadcn CLI v4 plus registries are how we install and extend UI; learn the workflow before adding components. |
| 2 | |
| 3 | - Core commands: `init` (scaffolds and writes `components.json`), `add`, `search`, `view`, `build`, plus `info` and `docs` for inspecting installed components and reading their docs. |
| 4 | - 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. |
| 5 | - 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`. |
| 6 | - 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. |
Skills
1shadcn-ui-review/rootPre-merge checklist for shadcn/ui changes covering theming, composition, and the CLI workflow.
| 1 | --- |
| 2 | name: shadcn-ui-review |
| 3 | 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. |
| 4 | --- |
| 5 | |
| 6 | # shadcn/ui review |
| 7 | |
| 8 | - [ ] No `@shadcn/ui` or external UI-library runtime imports; primitives live in `components/ui` and were added via the CLI. |
| 9 | - [ ] Colors use semantic tokens (`bg-background`, `text-foreground`, `bg-primary`) with no hardcoded hex or raw palette classes. |
| 10 | - [ ] Theme changes were made by editing CSS variables in global CSS, with matching `:root` and `.dark` blocks. |
| 11 | - [ ] New behavior is composed in `components/` around primitives rather than forking the generated primitive. |
| 12 | - [ ] Class merging goes through the `cn` helper so variant overrides resolve via `tailwind-merge`. |
| 13 | - [ ] `components.json` is intact: Tailwind v4 `tailwind.config` blank, `cssVariables: true`, aliases unchanged. |
| 14 | - [ ] Registry installs use correct namespaces and pinned versions; private registries authenticate via env-var headers. |
| 15 | - [ ] Accessibility preserved: Radix primitive props, `aria-*`, focus states, and keyboard interaction are not stripped. |
| 16 | - [ ] Dark mode and both color schemes verified visually for the changed components. |
Why this pattern
AI agents treat shadcn/ui like an npm package, hand-editing generated primitives and hardcoding colors instead of theming through CSS variables.
Built for React and Next.js teams using shadcn/ui with Tailwind v4.
Keeps your assistant from:
- Importing shadcn/ui as a runtime dependency instead of copying components into the repo
- Hardcoding hex colors or Tailwind palette classes instead of using semantic CSS-variable tokens
- Forking generated primitives by editing them in place instead of composing new components around them
- License
- Apache-2.0
- Version
- 1.0.0
- Updated
- 2026-06-09