Production-Ready Rule
•
components/ui/**/*.{tsx,jsx}, components/**/*.{tsx,jsx}
shadcn/ui, Radix UI & Tailwind .cursorrules (.mdc)
Production .cursorrules and .cursor/rules/*.mdc configuration for shadcn/ui and Radix UI. Enforce WCAG 2.1 AA accessibility, polymorphic 'asChild' composition, cn() class merging, and headless component purity.
.cursor/rules/shadcn-ui.mdc
---
description: shadcn/ui, Radix UI primitives, and accessible component engineering standards
globs: components/ui/**/*.{tsx,jsx}, components/**/*.{tsx,jsx}
alwaysApply: false
---
# shadcn/ui & Radix UI Standards
## Component Composition & asChild Pattern
- When wrapping shadcn/ui components (e.g. Button, DialogTrigger) around custom links or buttons, ALWAYS use `asChild` to avoid nested interactive button-in-a-tag HTML errors.
- Never modify files inside `components/ui/` directly unless creating a project-wide variant. Build feature wrappers in `components/`.
## Accessibility (a11y) & ARIA Compliance
- Every interactive element MUST have visible focus rings: `focus-visible:ring-2 focus-visible:ring-offset-2`.
- All icons used as buttons MUST include an accessible `aria-label` or `Label`.
- Dialogs, Sheets, and Drawers MUST contain a `` or `` to satisfy screen readers.
## Styling & Token Consistency
- Always combine conditional classes using the `cn()` utility (clsx + tailwind-merge).
- Rely on semantic HSL CSS variable tokens: `bg-background`, `text-muted-foreground`, `border-input`.
⭐
Using this rule in your open-source project? Reference in your README:
https://cursor.pacebowl.com/rules/shadcn-ui
Frequently Asked Questions & Implementation Notes
Why is the 'asChild' pattern essential in shadcn/ui?
Radix UI uses asChild via the Slot component to merge props into the direct child element, preventing invalid HTML like rendering a
Does this rule guarantee WCAG 2.1 AA accessibility compliance?
Yes, it mandates accessible focus rings, mandatory DialogTitle headers for screen readers, and screen-reader only labels for icon-only action buttons.