Frontend · How to use a skill

build-ui-with-shadcn

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.

Version 1.0 · Updated 2026-10-31

View raw SKILL.md

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-ui-with-shadcn/raw' -o ~/'.claude/skills/build-ui-with-shadcn/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-ui-with-shadcn/raw' -o '.cursor/skills/build-ui-with-shadcn/SKILL.md'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/build-ui-with-shadcn/raw' -o '.agents/skills/build-ui-with-shadcn/SKILL.md'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

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 <preset> --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."

Licence: CC BY 4.0. Attribution when you reuse it: From TheSkillVault, https://theskillvault.ai, CC BY 4.0