# ui-shadcn

> Build UIs using shadcn/ui components from https://ui.shadcn.com. Use when the task mentions shadcn/ui, ui.shadcn.com, Radix-based UI components, `npx shadcn@latest` (create/init/add/mcp), `components.json`, shadcn registry items, or when you need to compose accessible React UI quickly with Tailwind + shadcn components.

- Author: hidemi-ito
- Repository: hidemi-ito/skills
- Version: 20260209230119
- Stars: 0
- Forks: 0
- Last Updated: 2026-02-09
- Source: https://github.com/hidemi-ito/skills
- Web: https://mule.run/skillshub/@@hidemi-ito/skills~ui-shadcn:20260209230119

---

---
name: "ui-shadcn"
author: hidemi-ito
description: "Build UIs using shadcn/ui components from https://ui.shadcn.com. Use when the task mentions shadcn/ui, ui.shadcn.com, Radix-based UI components, `npx shadcn@latest` (create/init/add/mcp), `components.json`, shadcn registry items, or when you need to compose accessible React UI quickly with Tailwind + shadcn components."
---

# shadcn/ui UI Builder

Use shadcn/ui as an **open-code component distribution**: install component source into the target app, then edit/compose it to match the product UI.

## 0) Ask for minimal context (required)

- Target framework: Next.js / Vite / Remix / Astro / etc.
- Target screens: routes, page sections, and acceptance criteria
- Styling constraints: light/dark, brand colors, density, spacing, typography
- Project state: “new project” vs “existing repo”

If the user does not specify, assume **React + Tailwind** and ask which framework they use.

## 1) Prerequisite check (required)

Before suggesting `npx shadcn@latest ...`, verify `npx` exists:

```bash
command -v npx >/dev/null 2>&1 && echo "npx: ok" || echo "npx: missing"
```

If missing, ask the user to install Node.js/npm.

## 2) Choose setup path (create vs init)

### A) New project

Prefer the official scaffold:

```bash
npx shadcn@latest create
```

### B) Existing project

Ensure shadcn is initialized (creates/updates `components.json`, Tailwind config, etc.):

```bash
npx shadcn@latest init
```

After init, confirm `components.json` exists at the project root. If the repo uses a monorepo layout, run the command **from the app package directory**.

## 3) Add only the needed components (required)

Install the smallest set of components needed for the UI:

```bash
npx shadcn@latest add button card input label textarea select tabs dialog dropdown-menu table form toast
```

Then build screens by composing primitives (Card/Tabs/Dialog/Dropdown/Menu/Form/Table/etc.) instead of introducing new UI libraries.

Notes:
- shadcn/ui is open code: it is normal to modify the installed components.
- Prefer composition patterns over one-off bespoke components.
- Keep accessibility: proper labels, focus states, keyboard navigation, ARIA where needed.

## 4) Build UI by composition (guidelines)

- Import components from `@/components/ui/*` (or the project’s configured alias).
- Use Tailwind utility classes for layout and spacing; keep variants inside the component when it becomes reusable.
- Prefer shadcn patterns: `asChild` for polymorphic triggers/links, consistent `className` merging via the project’s `cn` helper.
- If a component is missing, add it via CLI first, then adapt.

For common page recipes (login, settings, dashboard, landing sections), see: `ui-shadcn/references/recipes.md`.

## 5) Use registries safely (optional)

To add community items:

```bash
npx shadcn add @<registry>/<component>
```

Always review installed code before shipping (third-party registry items vary in quality/security).

## 6) (Optional) Enable the shadcn MCP server

If the user wants natural-language “browse/search/install components” via MCP:

1) In the target project:
```bash
npx shadcn@latest mcp init --client codex
```

2) Manually add this to `~/.codex/config.toml` (the CLI cannot update it automatically):
```toml
[mcp_servers.shadcn]
command = "npx"
args = ["shadcn@latest", "mcp"]
```

Then restart Codex and use prompts like:
- “Show me all available components in the shadcn registry”
- “Add button, dialog, and card”
- “Build a settings page with tabs + form”

## Troubleshooting (fast checks)

- `components.json` missing: run `npx shadcn@latest init` in the correct directory.
- Imports fail (`@/components/...`): fix tsconfig path alias / bundler alias to match.
- Styles look broken: confirm Tailwind is installed and the content globs include `components/` and `app/`/`src/`.
- Component add fails: run `npx shadcn@latest --help` and re-run with verbose logs; if offline, ask the user to run the CLI locally and paste errors.