shadcn
shadcn/ui component library best practices and patterns (formerly shadcn-ui). This skill should be used when writing, reviewing, or refactoring shadcn/ui components to ensure proper architecture, accessibility, and performance. Triggers on tasks involving Radix primitives, Tailwind styling, form validation with React Hook Form, data tables, theming, or component composition patterns.
- Installs
- 727
- Last 24h
- —
- Trending rank
- —
- Security
- Not audited
Install
Works with every agent the skills CLI supports.
npx skills add https://github.com/pproenca/dot-skills --skill shadcn- 01
Install
Run the command in your project. The CLI asks which agents to install for.
- 02
Describe the task
Ask your agent for something this skill covers. It loads shadcn automatically when relevant.
- 03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.
SKILL.md
The instructions your agent reads when the skill is triggered.
shadcn/ui Community Best Practices
Comprehensive best practices guide for shadcn/ui applications, maintained by the shadcn/ui community. Contains 58 rules across 10 categories, prioritized by impact to guide automated refactoring and code generation.
When to Apply
Reference these guidelines when:
- Installing and configuring shadcn/ui in a project
- 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 | CLI & Project Setup | CRITICAL | setup- |
| 2 | Component Architecture | CRITICAL | arch- |
| 3 | Accessibility Preservation | CRITICAL | ally- |
| 4 | Styling & Theming | HIGH | style- |
| 5 | Form Patterns | HIGH | form- |
| 6 | Data Display | MEDIUM-HIGH | data- |
| 7 | Layout & Navigation | MEDIUM | layout- |
| 8 | Component Composition | MEDIUM | comp- |
| 9 | Performance Optimization | MEDIUM | perf- |
| 10 | State Management | LOW-MEDIUM | state- |
Quick Reference
1. CLI & Project Setup (CRITICAL)
setup-components-json- Configure components.json before adding componentssetup-path-aliases- Configure TypeScript path aliases to match components.jsonsetup-cn-utility- Create the cn utility before using componentssetup-use-cli-not-copy- Use CLI to add components instead of copy-pastesetup-css-variables-theme- Enable CSS variables for consistent themingsetup-rsc-configuration- Set RSC flag based on framework support
2. Component Architecture (CRITICAL)
arch-use-asChild-for-custom-triggers- Use asChild prop for custom trigger elementsarch-preserve-radix-primitive-structure- Maintain Radix compound component hierarchyarch-extend-variants-with-cva- Use Class Variance Authority for type-safe variantsarch-use-cn-for-class-merging- Use cn() utility for safe Tailwind class mergingarch-forward-refs-for-composable-components- Forward refs for form and focus integrationarch-isolate-component-variants- Separate base styles from variant-specific styles
3. Accessibility Preservation (CRITICAL)
ally-preserve-aria-attributes- Keep Radix ARIA attributes intactally-provide-sr-only-labels- Add screen reader labels for icon buttonsally-maintain-focus-management- Preserve focus trapping in modalsally-preserve-keyboard-navigation- Keep WAI-ARIA keyboard patternsally-ensure-color-contrast- Maintain WCAG color contrast ratiosally-dialog-title-required- Always include DialogTitle for screen readersally-form-field-labels- Associate labels with form controlsally-aria-invalid-errors- Use aria-invalid for form error statesally-checkbox-label-association- Wrap Checkbox with Label for click targetally-focus-visible-styles- Preserve focus visible styles for keyboard navigation
4. Styling & Theming (HIGH)
style-use-css-variables-for-theming- Use CSS variables for theme colorsstyle-avoid-important-overrides- Never use !important for style overridesstyle-use-tailwind-theme-extend- Extend Tailwind theme for design tokensstyle-consistent-spacing-scale- Use consistent Tailwind spacing scalestyle-responsive-design-patterns- Apply mobile-first responsive designstyle-dark-mode-support- Support dark mode with CSS variables
5. Form Patterns (HIGH)
form-use-react-hook-form-integration- Integrate with React Hook Formform-use-zod-for-schema-validation- Use Zod for type-safe validationform-show-validation-errors-correctly- Show errors at appropriate timesform-handle-async-validation- Debounce async validation callsform-reset-form-state-correctly- Reset form state after submission
6. Data Display (MEDIUM-HIGH)
data-use-tanstack-table-for-complex-tables- Use TanStack Table for sorting/filteringdata-virtualize-large-lists- Virtualize lists with 100+ itemsdata-use-skeleton-loading-states- Use Skeleton for loading statesdata-paginate-server-side- Paginate large datasets server-sidedata-empty-states-with-guidance- Provide actionable empty states
7. Layout & Navigation (MEDIUM)
layout-sidebar-provider- Wrap layout with SidebarProviderlayout-sidebar-collapsible- Configure sidebar collapsible behaviorlayout-sidebar-groups- Organize sidebar navigation with groupslayout-sheet-mobile-nav- Use Sheet for mobile navigation overlaylayout-breadcrumb-navigation- Implement breadcrumbs for deep navigation
8. Component Composition (MEDIUM)
comp-compose-with-compound-components- Use compound component patternscomp-use-drawer-for-mobile-modals- Use Drawer on mobile devicescomp-combine-command-with-popover- Create searchable selects with Commandcomp-nest-dialogs-correctly- Manage nested dialog focus correctlycomp-create-reusable-form-fields- Extract reusable form field componentscomp-use-slot-pattern-for-flexibility- Use slot pattern for flexible content
9. Performance Optimization (MEDIUM)
perf-lazy-load-heavy-components- Lazy load components over 50KBperf-memoize-expensive-renders- Memoize list items and expensive componentsperf-optimize-icon-imports- Use direct imports for Lucide iconsperf-avoid-unnecessary-rerenders-in-forms- Isolate form field watchingperf-debounce-search-inputs- Debounce search and filter inputs
10. State Management (LOW-MEDIUM)
state-prefer-uncontrolled-for-simple-inputs- Use uncontrolled for simple formsstate-lift-state-to-appropriate-level- Lift state to lowest common ancestorstate-use-controlled-dialog-state- Control dialogs for programmatic accessstate-colocate-state-with-components- Keep state close to where it's used
How to Use
Read individual reference files for detailed explanations and code examples:
- Section definitions - Category structure and impact levels
- Rule template - Template for adding new rules
Full Compiled Document
For a single-file reference containing all rules, see AGENTS.md.
Reference Files
| File | Description |
|---|---|
| AGENTS.md | Complete compiled guide with all rules |
| references/_sections.md | Category definitions and ordering |
| assets/templates/_template.md | Template for new rules |
| metadata.json | Version and reference information |
FAQ
What does the shadcn skill do?
shadcn/ui component library best practices and patterns (formerly shadcn-ui). This skill should be used when writing, reviewing, or refactoring shadcn/ui components to ensure proper architecture, accessibility, and performance. Triggers on tasks involving Radix primitives, Tailwind styling, form validation with React Hook Form, data tables, theming, or component composition patterns.
How do I install shadcn?
Run npx skills add https://github.com/pproenca/dot-skills --skill shadcn in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/shadcn/ (personal) or .claude/skills/shadcn/ (project).
Which AI agents can use shadcn?
Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.
Is shadcn safe to install?
No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.
Who maintains shadcn?
It is published by pproenca in pproenca/dot-skills. It has 727 recorded installs.
More from pproenca/dot-skills
zod
pproenca/dot-skills
Zod schema validation best practices for type safety, parsing, and error handling. This skill should be used when defining z.object schemas, using z.string validations, safeParse, or z.infer. This skill does NOT cover React Hook Form integration patterns (use react-hook-form skill) or OpenAPI client generation (use orval skill).
vitest
pproenca/dot-skills
Vitest testing framework patterns for test setup, async testing, mocking with vi., snapshots, and test performance (formerly test-vitest). This skill should be used when writing or debugging Vitest tests. This skill does NOT cover TDD methodology (use test-tdd skill), API mocking with MSW (use test-msw skill), or Jest-specific APIs.
react-hook-form
pproenca/dot-skills
React Hook Form performance optimization for client-side form validation using useForm, useWatch, useController, useFieldArray, the subscribe() API, and the Watch / FormStateSubscribe / FieldArray render-prop components. Covers RHF 7.82 additions including resetDefaultValues() and the disabled field-array option. This skill should be used when building client-side controlled forms with React Hook Form library. This skill does NOT cover React 19 Server Actions, useActionState, or server-side form handling (use react-19 skill for those).
emilkowal-animations
pproenca/dot-skills
Emil Kowalski's animation best practices for web interfaces. Use when writing, reviewing, or implementing animations in React, CSS, or Framer Motion. Triggers on tasks involving transitions, easing, gestures, toasts, drawers, or motion.
nuqs
pproenca/dot-skills
nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
clean-architecture
pproenca/dot-skills
Clean Architecture principles and best practices from Robert C. Martin's book. This skill should be used when designing software systems, reviewing code structure, or refactoring applications to achieve better separation of concerns. Triggers on tasks involving layers, boundaries, dependency direction, entities, use cases, or system architecture.
Popular frontend & design skills
setup-matt-pocock-skills
mattpocock/skills
Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.
frontend-design
anthropics/skills
Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.
hyperframes-animation
heygen-com/hyperframes
All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.
prototype
mattpocock/skills
Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.
hyperframes-core
heygen-com/hyperframes
The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.
vercel-react-best-practices
vercel-labs/agent-skills
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.