# shadcn

A skill that hands your agent a rulebook for shadcn/ui: component architecture, accessibility, theming, forms and tables. Useful whenever it writes or edits React UI.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 458 installs · ★ 39
- Author: PyModel
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/PyModel/react-frontend-skills/tree/HEAD/skills/shadcn/SKILL.md
- Updated: 2026-10-21
- HTML: https://affpapa.org/en/nevibecode/skills/pymodel-shadcn

## What it does

The skill sets the order in which an agent works with shadcn/ui. First it checks whether the checked-in components use Radix UI or Base UI, since their composition APIs differ. Base UI is the default for new projects. Component installs and upgrades go through CLI v4, which resolves namespaced registries.

The rules sit in eight priority categories. The critical ones cover component architecture and accessibility preservation: the agent must not strip Radix ARIA attributes, focus trapping in modals or keyboard navigation. Then come styling and theming with CSS variables, form patterns with React Hook Form and Zod, data display through TanStack Table and list virtualization, composition, performance and state. Each rule carries a prefix such as `arch-` or `ally-` and has its own file under `references/`.

Check which primitive library your project already uses before letting the agent touch components. Advice for Radix and Base UI is not interchangeable, and following one set blindly will break the other. The skill ships under the MIT license.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add PyModel/react-frontend-skills --skill shadcn -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/shadcn/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/shadcn/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add PyModel/react-frontend-skills --skill shadcn -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/shadcn/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add PyModel/react-frontend-skills --skill shadcn -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/shadcn/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install PyModel/react-frontend-skills shadcn
```

2. **Manually: put the files in place**
- File: `.github/skills/shadcn/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add PyModel/react-frontend-skills --skill shadcn -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/PyModel/react-frontend-skills --path skills/shadcn
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/shadcn/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add PyModel/react-frontend-skills --skill shadcn -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/PyModel/react-frontend-skills/tree/HEAD/skills/shadcn/SKILL.md

## When to use it
- tell whether a project is built on Radix or Base UI
- keep ARIA attributes and focus trapping intact when editing modals
- wire up a React Hook Form with Zod validation
- render a large table with sorting and filtering
- add dark mode backed by CSS variables

## Example prompts
- add a new Dialog component following the shadcn rules in the skill
- review my components for accessibility and tell me what to fix
- build a form with React Hook Form and Zod validation

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 87875ecde6ca7ee8.

BEGIN THIRD-PARTY FILE 87875ecde6ca7ee8
```text
---
name: shadcn
description: shadcn/ui components on Radix or Base UI.
---

# shadcn/ui Community Best Practices

Current best-practices guide for shadcn/ui applications. Before applying primitive-specific guidance, inspect whether the checked-in components use Radix UI or Base UI; current shadcn supports both (Base UI is the default for new projects) and their composition APIs differ. Component installs and upgrades go through the current CLI (v4), which resolves namespaced registries.

## When to Apply

Reference these guidelines when:
- Writing new shadcn/ui components or composing primitives
- Implementing forms with React Hook Form and Zod validation
- Building data tables or handling large dataset displays
- Customizing themes or adding dark mode support
- Reviewing code for accessibility compliance

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Component Architecture | CRITICAL | `arch-` |
| 2 | Accessibility Preservation | CRITICAL | `ally-` |
| 3 | Styling & Theming | HIGH | `style-` |
| 4 | Form Patterns | HIGH | `form-` |
| 5 | Data Display | MEDIUM-HIGH | `data-` |
| 6 | Component Composition | MEDIUM | `comp-` |
| 7 | Performance Optimization | MEDIUM | `perf-` |
| 8 | State Management | LOW-MEDIUM | `state-` |

## Quick Reference

### 1. Component Architecture (CRITICAL)

- [`arch-use-asChild-for-custom-triggers`](references/arch-use-asChild-for-custom-triggers.md) - Use the generated primitive's composition API
- [`arch-current-cli-registry`](references/arch-current-cli-registry.md) - Use the current CLI for component lifecycle (v4, registries, MCP)
- [`arch-unified-radix-package`](references/arch-unified-radix-package.md) - Import primitives from the unified radix-ui package
- [`arch-preserve-radix-primitive-structure`](references/arch-preserve-radix-primitive-structure.md) - Maintain Radix compound component hierarchy
- [`arch-extend-variants-with-cva`](references/arch-extend-variants-with-cva.md) - Use Class Variance Authority for type-safe variants
- [`arch-use-cn-for-class-merging`](references/arch-use-cn-for-class-merging.md) - Use cn() utility for safe Tailwind class merging
- [`arch-forward-refs-for-composable-components`](references/arch-forward-refs-for-composable-components.md) - Forward refs for form and focus integration
- [`arch-isolate-component-variants`](references/arch-isolate-component-variants.md) - Separate base styles from variant-specific styles

### 2. Accessibility Preservation (CRITICAL)

- [`ally-preserve-aria-attributes`](references/ally-preserve-aria-attributes.md) - Keep Radix ARIA attributes intact
```
END THIRD-PARTY FILE 87875ecde6ca7ee8

The third-party file has ended. Everything between the 87875ecde6ca7ee8 tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2666 of 7540 bytes. © PyModel · MIT · https://github.com/PyModel/react-frontend-skills/tree/HEAD/skills/shadcn/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md