58 community-maintained best practices for shadcn/ui component development, organized by priority and impact.
Works with
Covers 10 rule categories spanning CLI setup, component architecture, accessibility, styling, forms, data display, layout, composition, performance, and state management
Each rule includes specific guidance on Radix primitives, Tailwind styling, React Hook Form integration, and accessibility compliance
Prioritized by impact: CRITICAL rules for setup and architecture, HIGH for
AI-first code editor with Composer
Before installing skills in Cursor, ensure your development environment meets these requirements:
node --versionshadcnExecute the skills CLI command in your project's root directory to begin installation:
Fetches shadcn from pproenca/dot-skills and configures it for Cursor.
The CLI shows a list of agents. Use arrow keys and space to select Cursor:
Confirm successful installation by checking the skill directory location:
Restart Cursor to activate shadcn. Access via /shadcn in your agent's command palette.
We perform automated surface-level scans (Gen AI Scanner, Socket, Snyk) during installation. These checks detect common vulnerabilities but do not guarantee complete security. Always review skill source code and verify the publisher's reputation before production use.
Skills execute code in your environment. Always review source, verify the publisher, and test in isolation before production.
Submit your Claude Code skill and start earning
Create detailed user stories, acceptance criteria, and feature specs
Example
Generate user stories for 'password reset feature' with acceptance criteria, edge cases, and test scenarios
Reduce spec writing time by 50%, ensure comprehensive coverage
Research competitors, compare features, identify gaps
Example
Analyze 5 competitor products, create feature comparison matrix, suggest differentiation opportunities
Complete competitive research in 2 hours instead of 2 days
Evaluate features using frameworks (RICE, ICE, Kano) and create prioritized backlogs
Example
Score 20 feature ideas using RICE framework, generate prioritized roadmap with rationale
0
total installs
0
this week
95
GitHub stars
0
upvotes
Run in your terminal
0
installs
0
this week
95
stars
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.
Reference these guidelines when:
| 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- |
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 supportarch-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 stylesally-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 navigationstyle-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 variablesform-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 submissiondata-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 stateslayout-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 navigationcomp-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 contentperf-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 inputsstate-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 usedRead individual reference files for detailed explanations and code examples:
For a single-file reference containing all rules, see AGENTS.md.
| 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 |
Make data-driven prioritization decisions faster
Draft PRDs, status updates, and stakeholder presentations
Example
Create executive summary of Q3 roadmap, monthly progress report, feature launch announcement
Save 3-5 hours/week on communication overhead
Prerequisites
Time Estimate
30-60 minutes to see productivity improvements
Steps
Common Pitfalls
✓ Do
✗ Don't
💡 Pro Tips
✓ Use when
Use for user story writing, competitive research, roadmap prioritization, stakeholder communication, and PRD drafting. Best for reducing repetitive documentation and research work.
✗ Avoid when
Avoid for strategic product vision (requires deep customer empathy), pricing decisions (needs market and financial expertise), or when face-to-face customer discovery is more valuable than speed.
pproenca/dot-skills
pproenca/dot-skills
mattpocock/skills
parcadei/continuous-claude-v3
cursor/plugins
ailabs-393/ai-labs-claude-skills
shadcn fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
Registry listing for shadcn matched our evaluation — installs cleanly and behaves as described in the markdown.
shadcn has been reliable in day-to-day use. Documentation quality is above average for community skills.
shadcn is among the better-maintained entries we tried; worth keeping pinned for repeat workflows.
Useful defaults in shadcn — fewer surprises than typical one-off scripts, and it plays nicely with `npx skills` flows.
I recommend shadcn for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.
Keeps context tight: shadcn is the kind of skill you can hand to a new teammate without a long onboarding doc.
Keeps context tight: shadcn is the kind of skill you can hand to a new teammate without a long onboarding doc.
I recommend shadcn for anyone iterating fast on agent tooling; clear intent and a small, reviewable surface area.
shadcn fits our agent workflows well — practical, well scoped, and easy to wire into existing repos.
showing 1-10 of 41