Skip to content
Back to skills

Shadcn Ui

ASecurity

How to use the shadcn CLI in packages/web: searching and installing components, the preset and style in components.json, the vendored components/ui folder, and the rule to look for a shadcn component before writing one. Covers keeping relative imports instead of the @/* alias after every CLI run. Use when adding, updating or searching UI components, buttons, dialogs, sheets, inputs or when styling the web interface.

  • 10 stars
  • 0 votes
  • 0 copies
  • 0 views
  • Added November 14, 2026
ai-agentsbashreact

Works with

  • cli

Security analysis

A100/100

Scanned November 14, 2026

npx -y skills add douglasjunior/agent-remote-control --skill shadcn-ui --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of Shadcn Ui?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for Shadcn Ui
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/douglasjunior-shadcn-ui/badge)](https://www.skillsdirectory.com/skills/douglasjunior-shadcn-ui)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: shadcn-ui
description: >
  How to use the shadcn CLI in packages/web: searching and installing components, the preset
  and style in components.json, the vendored components/ui folder, and the rule to look for a
  shadcn component before writing one. Covers keeping relative imports instead of the @/* alias
  after every CLI run. Use when adding, updating or searching UI components, buttons, dialogs,
  sheets, inputs or when styling the web interface.
---

# shadcn/ui

> **Maintaining this skill**
>
> Update this document whenever the shadcn setup changes: preset, style, aliases, scripts or the
> import workaround. A visual tweak to a single component leaves it untouched.

## Rule: shadcn first

Before writing any UI component, **search shadcn for it**. Only build a component of our own when shadcn
has no suitable one, and then compose it from shadcn primitives (`Button`, `Card`, `Badge`, ...) found in
`src/components/ui/`. Never reimplement what the registry offers (dialog, sheet, select, tabs, input,
dropdown, tooltip, skeleton, ...).

```bash
cd packages/web
npx shadcn@latest search @shadcn -q button   # search the registry (the @shadcn namespace is required)
npx shadcn@latest view card             # show a component's source and dependencies before installing
```

## Rule: icon-only buttons have a tooltip

A button that shows only an icon names itself with a tooltip, never with `aria-label` alone. Use
`IconButton` (`src/components/icon-button.tsx`), which takes a required `label` and renders it as the
`aria-label` and as the shadcn `Tooltip` shown on hover and keyboard focus; it composes `Button`, so
`variant`, `size` (default `icon`), `className` and `disabled` pass through. As the `render` target of a
trigger (`<DropdownMenuTrigger render={<IconButton label="Theme" variant="outline" />}>`) it keeps both
the menu and the tooltip. A disabled button does not receive pointer events, so its tooltip only shows
while it is enabled. Buttons with visible text do not need one.

## Setup

- `components.json` records the project setup. It was created with
  `npx shadcn@latest init --preset b6XG5WQ02q`: style `base-nova` (built on `@base-ui/react`, **not** Radix),
  base color `mist`, Lucide icons, Instrument Sans for the body. The heading font (`--font-heading`) is Bricolage Grotesque and the mono font (`--font-mono`, tickers and timers) is JetBrains Mono, both from `@fontsource-variable`. Keep that preset; do not
  re-run `init` with another one.
- Theme tokens (`--primary`, `--muted`, ...) live in `src/index.css`. Style through these tokens and
  Tailwind utilities, never with hard-coded colors.
- `src/lib/utils.ts` re-exports `cn` from the `cn` package; components import `cn` from it.

## Installing and updating components

```bash
cd packages/web
pnpm ui:add <component> [<component> ...]     # = npx shadcn add; add --overwrite to update one
pnpm ui:relativize                             # mandatory right after every CLI run
pnpm lint:fix                                  # from the repository root: formats the generated code
```

The files land in `src/components/ui/` as vendored source. They are excluded from coverage, and
`react-refresh/only-export-components` is off for that folder only (generated files export variants
next to components). Change a vendored file only when the app cannot do without it; prefer composing it.
Components built on Base UI use `render` props instead of Radix `asChild`, and Base UI parts have their
own names (for example `Collapsible.Panel`): read the generated file before using a component.

## The `@/*` alias and relative imports

The CLI refuses to run without a path alias and writes `@/components/...` imports, while this repository
uses relative imports with the `.js` suffix (see `web-app`). The workaround has two parts:

1. `tsconfig.json` keeps `"paths": { "@/*": ["./src/*"] }` **only so the CLI can validate the project**.
   Application code never uses the alias, and `components.json` keeps its `@/` aliases for the same reason.
2. `pnpm ui:relativize` (`scripts/relativize-imports.mjs`) rewrites every `@/x` import under `src/` to a
   relative path ending in `.js`. Run it after every `init`, `add` or `--overwrite`, then `pnpm lint:fix`.

`ui/sonner.tsx` imports `useTheme` from the app's `theme/theme-context.ts` (`light`, `dark` or `system`),
because the generated file reads it from `next-themes`, which the app does not use. Re-apply that import after
`--overwrite` of `sonner`. `<Toaster />` is mounted once, in `AppLayout`.

An `@/` import left in `src/` is a defect: it type-checks through `paths` but breaks the convention.
Check with `grep -rn "from [\"']@/" packages/web/src`.

## Checklist for a new UI piece

1. `npx shadcn@latest search @shadcn -q <name>`: is there a component for it?
2. Yes: `pnpm ui:add <name>`, `pnpm ui:relativize`, `pnpm lint:fix`, then use it.
3. No: compose it in `src/components/` from the vendored primitives, with a spec file next to it.

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.