--- name: build-ui-with-shadcn description: Builds a React interface with shadcn/ui the way it is meant to be used - set up with the shadcn CLI, add components as editable source files, compose them into forms, dialogs and tables, check diffs before updates and keep custom changes. Use when adding shadcn/ui to a project, installing or updating shadcn components, building screens from them, or setting up a custom shadcn registry. license: CC-BY-4.0 compatibility: Needs a React project with Tailwind CSS (Next.js, Vite, React Router, TanStack Start, Astro or Laravel) and Node.js metadata: category: frontend tags: "shadcn,react,ui,tailwind" author: johnny-bravo version: "1.0" updated: "2026-10-31" status: published aliases: "shadcn,shadcn-ui,shadcn-components" --- # Build UI with shadcn/ui shadcn/ui is not a package you install and import. Its CLI copies each component's source code into your project, so you own and can edit it. That makes it easy to customise, but updates need care. This skill covers set-up, adding components, building screens and updating safely. ## When to use - You are starting a React app and want good-looking, accessible components quickly. - You need to add shadcn components such as Button, Dialog, Form, Table or Sidebar. - You want to update components or check what changed upstream without losing your edits. - You are publishing your own components as a shadcn registry for other projects. ## Steps 1. **Check the project.** Run `npx shadcn@latest info`. If a `components.json` exists, shadcn is set up: skip to step 3. Note the framework, Tailwind version and the `ui` folder path. 2. **Set it up.** Run `npx shadcn@latest init`. For a new app, pick a template with `-t` (next, vite, start, react-router, astro or laravel). This creates `components.json`, adds the `cn()` helper in `lib/utils`, and adds theme CSS variables to your global CSS. 3. **Add components with the CLI.** `npx shadcn@latest add button dialog form`. Search first if you are unsure of the name: `npx shadcn@latest search @shadcn -q "date"`. Read usage with `npx shadcn@latest docs calendar`. Do not hand-copy code from the website. 4. **Build screens by composing.** Import from your own folder (`@/components/ui/button`). Combine small parts into bigger ones in a separate folder, for example `components/settings-form.tsx`. Use the built-in variants (`variant="outline"`, `size="sm"`) before adding new classes. 5. **Style with the theme, not one-off colours.** Use the semantic classes (`bg-primary`, `text-muted-foreground`, `border-border`) that map to CSS variables. To change the look, edit the variables or apply a preset with `npx shadcn@latest apply --only theme`. For deeper token work, see `design-tailwind-theme-tokens`. 6. **Keep forms accessible.** Use the Field or Form components with a label and an error message for every input. Validate with a schema library such as Zod, and show errors next to the field. 7. **Customise in place.** You own the files, so edit them directly. Add a new variant to the component's `cva` list instead of passing long class strings everywhere. Keep a short comment on anything you changed on purpose. 8. **Update with a diff first.** Before overwriting, see what would change: `npx shadcn@latest add button --diff` or `--dry-run`. Merge upstream fixes by hand if you have local edits. Use `--overwrite` only on files you never changed. Use `npx shadcn@latest migrate` for listed upgrades (for example icons or radix imports). 9. **Share components (optional).** Describe your components in `registry.json`, run `npx shadcn@latest build` to write the JSON files to `public/r`, and install them elsewhere with `npx shadcn@latest add https://your-site.com/r/name.json`. 10. **Check.** Run the typecheck and build, use each new component with the keyboard, and look at it in light and dark mode. ## Gotchas - shadcn components need Tailwind. A project without it needs Tailwind set up first. - `add` can overwrite a file you edited. Commit before running it, and use `--diff` to look first. - Mixing shadcn's theme variables with hard-coded colours (`bg-blue-500`) breaks dark mode and themes. - Component APIs differ a little between the Radix and Base UI versions. Check the `base` setting in `components.json` before copying examples. ## Safety - Only install from registries you trust. A registry item is code that runs in your app, and it can add dependencies. - Do not put API keys, tokens or other secrets in components or `registry.json`. Anything in a published registry is public. ## Works with other stacks shadcn/ui is React only. If you use Vue or Svelte, community ports such as shadcn-vue and shadcn-svelte work the same way with their own CLI. Instead of shadcn, Radix Themes, Mantine or MUI are installed packages: easier to update, harder to customise. ## Done when - `components.json` exists, and every component was added with the CLI into the `ui` folder. - Screens use theme classes and built-in variants, and work in light and dark mode and by keyboard. - The typecheck and build pass, and any update was checked with `--diff` first. ## Credits Written by TheSkillVault in our own words, CC BY 4.0, from the public shadcn/ui CLI documentation (ui.shadcn.com/docs/cli). No text was copied. ## Example prompt "Add shadcn/ui to my Next.js app and build a settings page with a form, a confirmation dialog and a toast, using the theme colours."