Skip to main content
skill CX Codex

shadcn-ui · oakoss — Claude Code skill: what it does, how to install

Teaches the agent to add shadcn/ui components through the CLI and keep them consistent: oklch themes, Zod-validated forms.

MIT 176 installs ★ 29 updated 2026-08-17

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add oakoss/agent-skills --skill shadcn-ui -a claude-code
Open on GitHub

What shadcn-ui does

The skill hands the agent a working map of shadcn/ui. Components get generated into your source tree by the CLI (npx shadcn@latest add) instead of arriving as an npm package, so you own and edit them. A quick-reference table covers the usual commands and the mistakes that come with them, and four reference files go deeper on theming, component variants, forms, and the CLI with registries.

Colors live as CSS variables in :root using oklch values, mapped to Tailwind via @theme inline; dark mode swaps them under .dark. For forms the current path is <Field /> with React Hook Form or TanStack Form plus a Zod schema. The older <Form /> still runs but is no longer developed.

It assumes React 19 and Tailwind CSS 4. On another framework, or in a project without Tailwind, there is nothing for it to attach to — shadcn-vue and shadcn-svelte are the ports for Vue and Svelte. One detail it keeps repeating: forwardRef is deprecated in React 19, so ref goes in as an ordinary prop.

What it helps with

  • add a shadcn/ui component without pulling it in as an npm dependency
  • move color tokens to oklch and wire up dark mode
  • build a form with Zod validation
  • define button variants with cva()
  • publish your own component registry as JSON

Example prompts for the agent

  • Add the dialog component with the shadcn CLI and tell me where the files landed
  • Convert our color tokens to oklch and set up dark mode with the .dark class
  • Build a login form with <Field />, React Hook Form and a Zod schema

How to install shadcn-ui

1Skills CLI (Vercel)

npx skills add oakoss/agent-skills --skill shadcn-ui -a claude-code

2Manually: put the files in place

~/.claude/skills/shadcn-ui/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/shadcn-ui/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about shadcn-ui

How to install shadcn-ui in Claude Code?

Run npx skills add oakoss/agent-skills --skill shadcn-ui -a claude-code. The skill file then sits at ~/.claude/skills/shadcn-ui/SKILL.md.

What does the shadcn-ui skill do?

It gives the agent conventions for shadcn/ui work: CLI-added components, oklch theming, forms checked by Zod, and custom registries.

Does it work outside React?

No. The skill targets React 19 with Tailwind CSS 4. Vue and Svelte users have shadcn-vue and shadcn-svelte instead.

Source text

SKILL.md · MIT
---
name: shadcn-ui
description: 'Builds accessible, customizable component libraries using shadcn/ui with Radix UI or Base UI, Tailwind CSS 4, and React 19. Covers component ownership, oklch CSS theming, type-safe forms with Field and Zod, CLI workflows, and registry patterns. Use when adding shadcn/ui components, configuring themes, building forms with Zod, creating custom registries, or composing accessible component variants. Use for shadcn CLI, dark mode, component variants, form validation.'
license: MIT
metadata:
  author: oakoss
  version: '1.0'
  source: 'https://ui.shadcn.com/docs'
user-invocable: false
---

# shadcn/ui

## Overview

Guides building accessible, customizable UI with shadcn/ui as a code generation platform (not an npm dependency). Components are copied into your project via the CLI and fully owned. Supports Radix UI or Base UI primitives, Tailwind CSS 4 with oklch color tokens, React 19 direct ref patterns, and type-safe form validation with the Field component and Zod.

**When to use:** Adding shadcn/ui components, theming with CSS variables and oklch colors, building forms with React Hook Form or TanStack Form, creating custom registries, composing accessible component variants, setting up dark mode.

**When NOT to use:** Non-React frameworks (use shadcn-vue or shadcn-svelte instead), projects using a different component library (MUI, Chakra), projects not using Tailwind CSS.

## Quick Reference

| Pattern              | API / Approach                             | Key Points                                            |
| -------------------- | ------------------------------------------ | ----------------------------------------------------- |
| Init project         | `npx shadcn@latest init`                   | Auto-detects framework, configures CSS variables      |
| Add component        | `npx shadcn@latest add [name]`             | Copies source code into your project                  |
| Custom project       | `npx shadcn@latest create`                 | Pick library (Radix/Base UI), style, theme, fonts     |
| Check updates        | `npx shadcn@latest diff [component]`       | Shows upstream changes for your components            |
| Search registry      | `npx shadcn@latest search @registry`       | Browse and install from namespaced registries         |
| Build registry       | `npx shadcn@latest build`                  | Generate registry JSON from `registry.json`           |
| Theme tokens         | `:root` vars + `@theme inline` mapping     | oklch color values, dark mode via `.dark` class       |
| Dark mode            | `@custom-variant dark (&:is(.dark *))`     | Swaps CSS variables under `.dark` selector            |
| Component variant    | `cva()` from `class-variance-authority`    | Type-safe variant definitions                         |
| Polymorphic slot     | `asChild` prop with `<Slot>` from Radix    | Merge props onto child element                        |
| Direct ref           | `ref` as a regular prop                    | `forwardRef` is deprecated in React 19                |
| Form (current)       | `<Field />` + React Hook Form + Zod        | Replaces legacy `<Form />` component                  |
| Form (legacy)        | `<Form />` + `<FormField />` + Zod         | Still works but no longer actively developed          |
| Class merging        | `cn()` utility wrapping `clsx` + `twMerge` | Safely merge Tailwind classes without conflicts       |
| Toast / notification | Sonner (`npx shadcn@latest add sonner`)    | Default notification approach; auto-dismiss, stacking |
| Init with blocks     | `npx shadcn@latest init sidebar-01`        | Bootstrap project with pre-built page blocks          |
| RTL support          | `dir="rtl"` on root element                | Built-in RTL layout support for all components        |
| New components       | `Spinner`, `Kbd`, `ButtonGroup`            | Recently added utility and layout components          |

## Common Mistakes

| Mistake                                                   | Correct Pattern                                                         |
| --------------------------------------------------------- | ----------------------------------------------------------------------- |
| Installing shadcn/ui as an npm dependency                 | Use the CLI (`npx shadcn@latest add`) to copy source into your project  |
| Using `forwardRef` with React 19 components               | Pass `ref` directly as a prop -- `forwardRef` is deprecated in React 19 |
| Using HSL values for color tokens                         | Use oklch format: `--primary: oklch(0.205 0 0)`                         |
| Wrapping variables with `hsl()` or `oklch()` in utilities | Reference CSS variables directly: `var(--primary)`                      |
| Putting tokens directly in `@theme {}`                    | Use `:root` for values + `@theme inline` to map them to Tailwind        |
| Using legacy `<Form />` for new forms                     | Use `<Field />` component with React Hook Form or TanStack Form         |
| Skipping Zod validation in form components                | Always pair forms with Zod schemas for type-safe validation             |
| Using `div` elements for interactive controls             | Use Radix or Base UI primitives for semantic HTML and accessibility     |
| Modifying components in `node_modules`                    | Components live in your source tree -- own and customize directly       |
| Using old CLI command `shadcn-ui@canary`                  | Use `npx shadcn@latest` for all CLI operations                          |

## Delegation

- **Component discovery and primitive lookup**: Use `Explore` agent
- **Theme migration or multi-file refactoring**: Use `Task` agent
- **Design system architecture planning**: Use `Plan` agent
- **Registry setup and distribution**: Use `Task` agent

> If the `tanstack-form` skill is available, delegate advanced form state management (array fields, linked fields, async validation) to it.
> If the `tailwind` skill is available, delegate utility class patterns and design token architecture to it.

## References

- [Theming and dark mode](references/theming-and-dark-mode.md)
- [Component patterns and variants](references/component-patterns.md)
- [Form patterns with Field, React Hook Form, and Zod](references/form-patterns.md)
- [CLI and registry](references/cli-and-registry.md)

© oakoss · MIT · oakoss/agent-skills

Similar skills

All skills for Frontend and UI →

shadcn-ui by other authors comes first.

shadcn-ui official google-labs-code Helps discover, add, and customize shadcn/ui components in React projects. Useful when building interfaces with Tailwind CSS. CX Codex +1 55,400installs shadcn-ui nexu-io Builds UI components with shadcn/ui. Works alongside the Stitch design loop to ship structured, accessible components. CX Codex +1 3,100installs shadcn-ui giuseppe-trisciuoglio Tells the agent how to install and configure shadcn/ui components: buttons, dialogs, tables, and forms with React Hook Form and Zod. CX Codex +1 22,800installs shadcn-ui jezweb Installs and configures shadcn/ui components in a React project: picks them by task, keeps install order and dependencies straight. CX Codex +1 3,600installs shadcn-ui existential-birds Teaches the agent shadcn/ui component patterns — CVA variants, compound components, data-slot attributes. Fires on Button, Card, Dialog, cn() and Radix primitives. CX Codex +1 358installs shadcn PyModel This Claude Code skill guides shadcn/ui component work across forms, tables, themes, and accessibility. It also covers Radix UI and Base UI differences. CX Codex +1 599installs tanstack-start-shadcn-tailwind official github The tanstack-start-shadcn-tailwind rule standardizes architecture and coding patterns within TanStack Start projects. It enforces strict TypeScript typing, Zod validation, and Shadcn/ui component usage. CX Codex +1 ★ 41,430repo stars shadcn-component-review mattbx shadcn-component-review reviews finished components and layouts against shadcn patterns: spacing, semantic tokens, primitive composition, and the project's chosen visual style. CX Codex +1 676installs shadcn-layouts jwynia shadcn-layouts teaches the agent the CSS models behind shadcn and Tailwind layouts, so height, scroll and flex/grid problems get fixed instead of guessed at. CX Codex +1 463installs json-render-shadcn vercel-labs json-render-shadcn is a Claude Code skill that adds ready-made shadcn/ui components to json-render catalogs and web UIs. It activates for work with @json-render/shadcn. CX Codex +1 257installs shadcn-code-review existential-birds shadcn-code-review audits React components built with shadcn/ui, Radix primitives, and Tailwind CSS. Catches CVA mistakes, broken asChild slots, and missing accessibility states. CX Codex +1 206installs

From the same set106

The whole set →

Project sponsors

Companies that keep this analytics open