sickn33/antigravity-awesome-skills/shadcn

shadcn/ui

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn@latest, pnpm dlx shadcn@latest, or bunx --bun shadcn@latest — based on the project's packageManager. Examples below use npx shadcn@latest but substitute the correct runner for the project.

When to Use

• Use when adding new components from shadcn/ui or community registries.
• Use when styling, composing, or debugging existing shadcn/ui components.
• Use when initializing a new project or switching design system presets.
• Use to retrieve component documentation, examples, and API references.

Current Project Context

Read components.json, the package manifest/lockfile and the installed component source first. If the approved CLI is available, run its info command in the intended project directory and inspect errors directly. Skill Markdown does not inject command output automatically; do not interpret the command text as project JSON or treat any CLI failure as evidence that initialization is needed.

Use the project's existing approved CLI version and package runner when available. The @latest examples download and execute a mutable npm package; establish the intended version and registry before running them.

Principles

1. Use existing components first. Use npx shadcn@latest search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These are defaults for the documented presets; installed source, accessibility requirements and explicit user design choices take precedence. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• `className` for layout, not styling. Never override component colors or typography.
• No `space-x-*` or `space-y-*`. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• Use `size-*` when width and height are equal. size-10 not w-10 h-10.
• Use `truncate` shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual `dark:` color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use `cn()` for conditional classes. Don't write manual template literal ternaries.
• Prefer the component overlay stacking defaults; diagnose portal/stacking contexts before overriding them. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → forms.md

• Forms prefer installed `FieldGroup` + `Field`. Never use raw div with space-y-* or grid gap-* for form layout.
• `InputGroup` uses `InputGroupInput`/`InputGroupTextarea`. Never raw Input/Textarea inside InputGroup.
• Buttons inside inputs use `InputGroup` + `InputGroupAddon`.
• Toggle controls can use `ToggleGroup`; independent boolean settings use switches or checkboxes. Don't loop Button with manual active state.
• `FieldSet` + `FieldLegend` for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses `data-invalid` + `aria-invalid`. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Component Structure → composition.md

• Items always inside their Group. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Use `asChild` (radix) or `render` (base) for custom triggers. Check base field from npx shadcn@latest info. → base-vs-radix.md
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="sr-only" if visually hidden.
• Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
• Button has no `isPending`/`isLoading`. Compose with Spinner + data-icon + disabled.
• `TabsTrigger` must be inside `TabsList`. Never render triggers directly in Tabs.
• `Avatar` always needs `AvatarFallback`. For when the image fails to load.

Use Components, Not Custom Markup → composition.md

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use `Alert`. Don't build custom styled divs.
• Empty states use `Empty`. Don't build custom empty state markup.
• Toast via `sonner`. Use toast() from sonner.
• Use `Separator` instead of <hr> or <div className="border-t">.
• Use `Skeleton` for loading placeholders. No custom animate-pulse divs.
• Use `Badge` instead of custom styled spans.

Icons → icons.md

• Icons in `Button` use `data-icon`. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as objects, not string keys. icon={CheckIcon}, not a string lookup.

CLI

• Never decode or fetch preset codes manually. Pass them directly to npx shadcn@latest init --preset <code>.

Key Patterns

These are the most common patterns that differentiate correct shadcn/ui code. For edge cases, see the linked rule files above.

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="email">Email</FieldLabel>
    <Input id="email" />
  </Field>
</FieldGroup>
// Validation: data-invalid on Field, aria-invalid on the control.
<Field data-invalid>
  <FieldLabel htmlFor="invalid-email">Email</FieldLabel>
  <Input id="invalid-email" aria-invalid aria-describedby="invalid-email-error" />
  <FieldDescription id="invalid-email-error">Invalid email.</FieldDescription>
</Field>
// Icons in buttons: data-icon, no sizing classes.
<Button>
  <SearchIcon data-icon="inline-start" />
  Search
</Button>
// Spacing: gap-*, not space-y-*.
<div className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong
// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong
// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Key Fields

The observed project context contains these key fields:

• `aliases` → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• `isRSC` → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
• `tailwindVersion` → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
• `tailwindCssFile` → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
• `style` → component visual treatment (e.g. nova, vega).
• `base` → primitive library (radix or base). Affects component APIs and available props.
• `iconLibrary` → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.
• `resolvedPaths` → exact file-system destinations for components, utils, hooks, etc.
• `framework` → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
• `packageManager` → use this for any non-shadcn dependency installs (e.g. pnpm add date-fns vs npm install date-fns).

See cli.md — `info` command for the full field reference.

Component Docs, Examples, and Usage

Run npx shadcn@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

npx shadcn@latest docs button dialog select

When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow