# Shadcn UI

> Expert guidance for integrating shadcn/ui components in this Next.js monorepo (apps/ui). Handles component discovery, installation via CLI, customization to local conventions (cn() in @/lib/styles, Tailwind v4, radix-ui primitives), and best practices. Use this skill whenever the user wants to add, install, customize, or troubleshoot a shadcn/ui component — even if they just say 'add a button' or 'install tabs'. Also triggers on: shadcn, radix, UI component, cn utility, component library.

- Skill: `strapi/shadcn-ui` (Agent Skill)
- Install (CLI): `npx skillmds@latest add strapi/shadcn-ui`
- Raw SKILL.md: https://api.skillmd.com/api/skills/strapi/shadcn-ui/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: strapi (https://skillmd.com/u/strapi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/strapi/shadcn-ui

---


# shadcn/ui Essentials (Repo-Specific)

Use this skill to add or adapt shadcn/ui components in this monorepo without fighting local conventions.

## Scope

- Focus on `apps/ui`.
- Keep instructions lean and stable.
- Use official shadcn docs for evolving details instead of copying full docs into this skill

## Source of Truth

Read these files first in the target repo:

- `apps/ui/components.json`
- `apps/ui/package.json`
- `apps/ui/src/lib/styles.ts`
- `apps/ui/src/styles/globals.css`

Current repo conventions to preserve:

- `cn()` lives in `@/lib/styles` (not `@/lib/utils`).
- UI components are in `apps/ui/src/components/ui`.
- Aliases are defined in `apps/ui/components.json`.
- Existing primitives commonly import from the `radix-ui` package in this repo.
- Tailwind is configured for v4-style CSS entry (`components.json.tailwind.css`).

## Workflow

1. Confirm target component(s) and whether this is add vs. refactor.
2. Run shadcn CLI from `apps/ui`:
   - `pnpm dlx shadcn@latest add <component>`
3. Run the post-install fixup checklist (see below).
4. Integrate component usage where requested.
5. Validate:
   - `pnpm --filter @repo/ui typecheck`
   - `pnpm --filter @repo/ui lint`

## Post-Install Fixup Checklist

After `shadcn add`, review generated files for these common issues:

1. **`cn()` import path**: The CLI should generate `@/lib/styles` (aliased in `components.json`). If it generates `@/lib/utils`, fix the import. This is the most common issue after shadcn upgrades.
2. **Radix imports**: This repo uses the unified `radix-ui` package. If generated code imports from `@radix-ui/react-*` (scoped packages), convert to `radix-ui` imports unless both coexist in `package.json`.
3. **Tailwind v4 CSS variables**: Shadcn v4 components use CSS custom properties (`--radius`, `--primary`, etc.) defined in `apps/ui/src/styles/globals.css`. Verify new components reference variables that exist in globals.css — add missing ones if needed.
4. **`"use client"` directive**: Shadcn components with interactivity include `"use client"`. Keep it — this is a React Server Components project.
5. **Naming conflicts**: Check `apps/ui/src/components/ui/` for existing files before adding. If a component already exists, diff and merge rather than overwrite.

## Common Pitfalls

- **Don't use `tailwind.config.js`**: This project uses Tailwind v4 with CSS-based config (`src/styles/globals.css`). Theme tokens live in `packages/design-system/src/theme.css`. Never create or reference a JS config file.
- **Don't install duplicate primitives**: Before adding a shadcn component that depends on a Radix primitive, check if that primitive is already installed. Run `pnpm --filter @repo/ui list radix-ui` to check.
- **Don't override design system tokens**: Shadcn components may define their own color/spacing variables. Always prefer existing tokens from `packages/design-system/src/theme.css` over shadcn defaults.

## Guardrails

- Do not paste frozen dependency matrices into this skill.
- Do not assume old Tailwind v3 config patterns (`tailwind.config.js`, `@tailwind base` blocks).
- Do not force conversion between `radix-ui`, `@radix-ui/*`, or Base UI unless user requests migration.
- Follow existing codebase patterns over generic shadcn examples.

## Official References

- Docs home: https://ui.shadcn.com/docs
- Shadcn LLM Docs: https://ui.shadcn.com/llms.txt
- Next.js install: https://ui.shadcn.com/docs/installation/next
- Tailwind v4: https://ui.shadcn.com/docs/tailwind-v4
- CLI: https://ui.shadcn.com/docs/cli
- Components: https://ui.shadcn.com/docs/components