About

Imported from shipshitdev/skills (skills/shadcn/SKILL.md). Install upstream with npx skills add shipshitdev/skills --skill shadcn. Copyright stays with the author.

shadcn/ui Community Best Practices

Name: shadcn
Author: shipshitdev

58 rules across 10 categories for shadcn/ui, prioritized by impact to guide automated refactoring and code generation.

When to Apply

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 components
setup-path-aliases - Configure TypeScript path aliases to match components.json
setup-cn-utility - Create the cn utility before using components
setup-use-cli-not-copy - Use CLI to add components instead of copy-paste
setup-css-variables-theme - Enable CSS variables for consistent theming
setup-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 elements
arch-preserve-radix-primitive-structure - Maintain Radix compound component hierarchy
arch-extend-variants-with-cva - Use Class Variance Authority for type-safe variants
arch-use-cn-for-class-merging - Use cn() utility for safe Tailwind class merging
arch-forward-refs-for-composable-components - Forward refs for form and focus integration
arch-isolate-component-variants - Separate base styles from variant-specific styles

3. Accessibility Preservation (CRITICAL)

ally-preserve-aria-attributes - Keep Radix ARIA attributes intact
ally-provide-sr-only-labels - Add screen reader labels for icon buttons
ally-maintain-focus-management - Preserve focus trapping in modals
ally-preserve-keyboard-navigation - Keep WAI-ARIA keyboard patterns
ally-ensure-color-contrast - Maintain WCAG color contrast ratios
ally-dialog-title-required - Always include DialogTitle for screen readers
ally-form-field-labels - Associate labels with form controls
ally-aria-invalid-errors - Use aria-invalid for form error states
ally-checkbox-label-association - Wrap Checkbox with Label for click target
ally-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 colors
style-avoid-important-overrides - Never use !important for style overrides
style-use-tailwind-theme-extend - Extend Tailwind theme for design tokens
style-consistent-spacing-scale - Use consistent Tailwind spacing scale
style-responsive-design-patterns - Apply mobile-first responsive design
style-dark-mode-support - Support dark mode with CSS variables

5. Form Patterns (HIGH)

form-use-react-hook-form-integration - Integrate with React Hook Form
form-use-zod-for-schema-validation - Use Zod for type-safe validation
form-show-validation-errors-correctly - Show errors at appropriate times
form-handle-async-validation - Debounce async validation calls
form-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/filtering
data-virtualize-large-lists - Virtualize lists with 100+ items
data-use-skeleton-loading-states - Use Skeleton for loading states
data-paginate-server-side - Paginate large datasets server-side
data-empty-states-with-guidance - Provide actionable empty states

7. Layout & Navigation (MEDIUM)

layout-sidebar-provider - Wrap layout with SidebarProvider
layout-sidebar-collapsible - Configure sidebar collapsible behavior
layout-sidebar-groups - Organize sidebar navigation with groups
layout-sheet-mobile-nav - Use Sheet for mobile navigation overlay
layout-breadcrumb-navigation - Implement breadcrumbs for deep navigation

8. Component Composition (MEDIUM)

comp-compose-with-compound-components - Use compound component patterns
comp-use-drawer-for-mobile-modals - Use Drawer on mobile devices
comp-combine-command-with-popover - Create searchable selects with Command
comp-nest-dialogs-correctly - Manage nested dialog focus correctly
comp-create-reusable-form-fields - Extract reusable form field components
comp-use-slot-pattern-for-flexibility - Use slot pattern for flexible content

9. Performance Optimization (MEDIUM)

perf-lazy-load-heavy-components - Lazy load components over 50KB
perf-memoize-expensive-renders - Memoize list items and expensive components
perf-optimize-icon-imports - Use direct imports for Lucide icons
perf-avoid-unnecessary-rerenders-in-forms - Isolate form field watching
perf-debounce-search-inputs - Debounce search and filter inputs

10. State Management (LOW-MEDIUM)

state-prefer-uncontrolled-for-simple-inputs - Use uncontrolled for simple forms
state-lift-state-to-appropriate-level - Lift state to lowest common ancestor
state-use-controlled-dialog-state - Control dialogs for programmatic access
state-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

Reference Files

File	Description
references/_sections.md	Category definitions and ordering
assets/templates/_template.md	Template for new rules

Use it

Copy one of these into your project. Installing also returns the manifest and these snippets.

yaml

targets:
  - https://api.opensmartroute.ai/api/v1/registry/shipshitdev-skills-shadcn/manifest   # or paste the manifest below

Manifest

An Open Capability Manifest: the router reads it to know what this does, what it costs and when to pick it.

shipshitdev-skills-shadcn.ocm.jsonjson

{
  "ocm": "1",
  "id": "shipshitdev-skills-shadcn",
  "kind": "skill",
  "name": "shadcn",
  "description": "Provides shadcn/ui component library best practices and patterns. Triggers when writing, reviewing, or refactoring shadcn/ui components; when working with Radix primitives, Tailwind styling, React Hook Form validation, data tables, theming, or component composition patterns.",
  "publisher": "shipshitdev",
  "version": "1.0.0",
  "capabilities": {
    "domains": [
      "general"
    ],
    "tags": [
      "skill-md",
      "shadcn",
      "ui",
      "react",
      "skills-sh"
    ],
    "languages": [
      "en"
    ]
  },
  "quality_prior": 0.6,
  "examples": [
    "Provides shadcn/ui component library best practices and patterns. Triggers when writing, reviewing, or refactoring shadcn/ui components; when working with Radix primitives, Tailwind styling, React Hook Form validation, data tables, theming, or component composition patterns."
  ],
  "primary": false,
  "metadata": {
    "source": {
      "provider": "skills.sh",
      "repository": "https://github.com/shipshitdev/skills",
      "path": "skills/shadcn/SKILL.md",
      "ref": "HEAD",
      "url": "https://github.com/shipshitdev/skills/blob/HEAD/skills/shadcn/SKILL.md",
      "key": "shipshitdev/skills/skills/shadcn/SKILL.md"
    }
  },
  "instructions": "# shadcn/ui Community Best Practices\n\n58 rules across 10 categories for shadcn/ui, prioritized by impact to guide automated refactoring and code generation.\n\n## When to Apply\n\n- Installing and configuring shadcn/ui in a project\n- Writing new shadcn/ui components or composing primitives\n- Implementing forms with React Hook Form and Zod validation\n- Building data tables or handling large dataset displays\n- Customizing themes or adding dark mode support\n- Reviewing code for accessibility compliance\n\n## Rule Categories by Priority\n\n| Priority | Category | Impact | Prefix |\n|----------|----------|-",
  "cost": {
    "context_tokens": 2301
  }
}

Fetch it by URL: GET /api/v1/registry/shipshitdev-skills-shadcn/manifest?version=1.0.0

Reviews

Star ratings from people who tried it. One review per account; edit yours any time.

No reviews yet. Install it, try it, and be the first to rate it.