shadcn/ui

This skill keeps shadcn/ui work project-aware. Components are source files in the app, so always inspect the local project before adding, importing, or rewriting them. When @shadcn/lint is configured, treat its feedback as implementation guidance, not cosmetic noise. The framework repository runs it through the root Oxlint configuration; generated workspaces carry this skill and the MCP workflow, but do not automatically inherit that repository-only lint setup.

First Steps

1. Work from the app root that owns components.json. In this monorepo, that is the selected app/template directory (usually under templates/), not the repository root.
2. In an Agent-Native app, inspect app/design-system.ts and ToolkitProvider before choosing a primitive. A registered company design system takes precedence over the default shadcn adapter.
3. Run pnpm dlx shadcn@latest info --json when you need current project context: framework, Tailwind version, aliases, icon library, installed components, and resolved paths.
4. Use the actual aliases from components.json or shadcn info; do not assume @/components/ui if the project says otherwise.
5. Check app/components/ui/ or the resolved ui path before importing a component.
6. For unfamiliar components, run pnpm dlx shadcn@latest docs <component> and read the returned docs or examples before coding.

MCP Registry Workflow

Each first-party app keeps the official shadcn MCP configuration in .mcp.json next to its components.json. Start the agent from that app root so the MCP server resolves the correct aliases, local UI directory, and Tailwind theme. Do not add a single repository-root server: the root is a workspace, not a shadcn project, and would make installs target the wrong project.

• Use the shadcn MCP to search, inspect, and install registry items when it is connected. Prefer the app's configured registries over copied source.
• Use pnpm dlx shadcn@latest info --json for project context; the MCP has no equivalent project-info tool.
• If the MCP is unavailable, use the equivalent pnpm dlx shadcn@latest command from the same app root and continue following this skill.
• Keep registry URLs and aliases in that app's components.json. Never put registry credentials in MCP config or checked-in source.

Design-System Lint Feedback

In the framework repository, pnpm lint runs Oxlint with @shadcn/lint for the scoped template UI paths. Run it after UI changes and fix every shadcn/* finding before handing off. Template packages use the workspace lint configuration; do not create a second local lint configuration just for one app.

Before claiming that shadcn lint ran in another workspace, inspect its root package.json and .oxlintrc.json. The generic generated workspace currently exposes pnpm lint as formatting-only and does not ship @shadcn/lint or the framework repository's Oxlint config. In that scaffold, use this skill plus the connected shadcn MCP (or the CLI fallback) for design-system guidance, and do not report shadcn/* checks as having run. If the workspace owner adopts the linter, add the dependency, scoped config, and lint script together.

The Plan template is intentionally excluded from this rollout. Its files remain under templates/plan/**, but the root Oxlint ignore list keeps them out of the shadcn checks until that template has a separate lint baseline.

• no-restyle: use the component's variant, size, and semantic props; put layout on a parent and add a component variant only when the design system genuinely needs a new treatment.
• no-raw-colors: use the theme tokens in the app's global.css, not raw Tailwind palette classes or hard-coded color attributes.
• no-arbitrary-values: use the theme scale or a declared token instead of one-off bracket values.
• no-inline-styles: use classes or CSS custom properties for dynamic layout; keep intentional editor/export exceptions scoped to their owning subsystem.
• no-unknown-classes and require-static-classes: use classes Tailwind can generate and keep class strings statically discoverable.

The local primitive source is the contract boundary. Product code should consume its props and variants; update packages/toolkit/src/ui/ or an app's components/ui/ only when the design-system contract itself changes.

Agent-Native Adapter Rule

Pages, routes, and domain components import controls through the app's local UI adapter layer. Never import @agent-native/toolkit/ui/* directly in app product code. Direct imports bypass app/design-system.ts and make Toolkit/Core surfaces use different controls from the app.

When shadcn is the app's adapter, add or update the local primitive and keep product code on that local import. When a company design system is registered, adapt its components to the semantic contracts from @agent-native/toolkit/design-system; do not recreate a parallel shadcn surface. The semantic API is styling-runtime agnostic, so do not require Tailwind, CVA, or className in customer adapters.

For shared Toolkit features, customize presentation through semantic components, a feature-level controller, and product-level render slots. Keep the same controller for default and custom views. Use the conformance kit for behavior components whose focus, portal, keyboard, dismissal, or stacking behavior comes from the company design system.

Adding Or Updating Components

• Add missing primitives with pnpm dlx shadcn@latest add <component> from the app root.
• Before overwriting an existing component, use pnpm dlx shadcn@latest add <component> --dry-run and --diff to inspect the change.
• After adding registry code, read the generated files. Fix import aliases, icon imports, missing subcomponents, and composition issues before using the component.
• Do not fetch raw component files manually from GitHub when the shadcn CLI can resolve the registry item.
• If a user asks to add a third-party block but does not name a registry, ask which registry to use instead of guessing.

Component Composition

• Use existing primitives before custom markup: Alert for callouts, Badge for small status labels, Separator for dividers, Skeleton for placeholders, Table for tabular data, and Card for framed content.
• Compose cards from CardHeader, CardTitle, CardContent, and CardFooter. Leave CardDescription out: a card gets a title or a description, never both. See frontend-design → Default Surface Density.
• Dialog, Sheet, Drawer, and AlertDialog content must include an accessible title. Use visually hidden titles only when the visible UI already communicates the title.
• Put items inside their group components: SelectItem in SelectGroup, DropdownMenuItem in DropdownMenuGroup, CommandItem in CommandGroup, and equivalent menu groups.
• TabsTrigger belongs inside TabsList.
• Avatar always needs AvatarFallback.
• Buttons do not have magic loading props. Compose loading with disabled, Spinner, and clear text.

Forms And Inputs

• Use the app's shadcn form primitives instead of raw div stacks.
• If Field, FieldGroup, FieldSet, or InputGroup are installed or worth adding, use them for form layout, grouped fields, and input add-ons.
• Do not place buttons inside inputs with absolute positioning. Use InputGroup and InputGroupAddon when available.
• Use ToggleGroup for small option sets, RadioGroup for one-of-many choices, Checkbox for multi-select, Switch for settings toggles, Select or Combobox for predefined choices, and Slider or numeric input for numeric values.
• Validation must be accessible: pair visual invalid states with aria-invalid, and connect descriptions/errors to controls.

Styling And Theming

• Use semantic tokens (bg-background, text-foreground, text-muted-foreground, bg-primary, border-border, text-destructive) instead of raw colors for reusable app UI.
• Prefer built-in variants and sizes before custom classes.
• Use className mostly for layout and spacing; avoid overriding component colors and typography unless the component is intentionally being extended.
• Use gap-* instead of space-x-* / space-y-*.
• Use size-* when width and height are equal.
• Use truncate for single-line clipping.
• Use cn() for conditional classes.
• Do not add manual z-index to overlay primitives unless you are fixing a verified stacking bug.
• Add custom colors as CSS variables in the existing Tailwind CSS file reported by shadcn info. For Tailwind v4, register variables with @theme inline.

Transitions And Motion

shadcn's built-in component animations are the right level of polish — keep them. The goal is a snappy, clean UI, not a motionless one. Match shadcn's motion vocabulary; don't strip it and don't pile on decorative custom animation.

• Never remove or override a shadcn component's default animation. data-[state=open]:animate-in, data-[state=closed]:animate-out, fade-in/out, zoom-in/out, slide-in-from-*, accordion height, the tailwindcss-animate utilities — these ship for a reason. Leave them as-is.
• Custom transitions are fine when they communicate a state change and match shadcn's feel. Reuse the same vocabulary: short durations (~120–200ms), ease-out, opacity/transform only, gated on data-[state=...]. Examples that are good and welcome:
  • A portaled custom popover/tooltip/sheet that fades + scales/slides in on data-[state=delayed-open] / data-[state=closed], mirroring Radix's own content animation.
  • A list row or toast that fades/slides in on mount and out on dismiss.
  • A chevron/caret rotate on expand, a subtle opacity/color hover on an icon button, skeleton shimmer, a progress/height transition on a collapsible.
  • Continuous, product-defining motion where it is the experience (e.g. a multi-stage booking flow's stage transitions) — fine, and framer-motion is acceptable there.
• Avoid decorative, attention-seeking, or slow motion: hand-rolled duration-700 hero fade-ins, parallax, bouncing/spring entrances on ordinary content, animated gradients, staggered cascades on long lists, anything that delays the user seeing or acting on content. If an animation makes the UI feel slower, cut it.
• Rule of thumb: if the motion clarifies what just changed and is over in well under a quarter-second, it's polish; if it's there to look impressive, it's bloat.

Icons

• Agent-Native apps use @tabler/icons-react. Do not add lucide-react because a registry example used it.
• If registry code imports a different icon package, replace those imports with Tabler equivalents before finishing.
• Let shadcn components size icons through their CSS. Avoid manual icon sizing inside buttons, menus, alerts, and sidebars unless the local component API requires it.

Base-Specific APIs

Check the project context before using trigger composition APIs:

• Radix-based components use asChild for custom triggers.
• Base UI components may use render and sometimes nativeButton={false}.

Do not wrap triggers in extra divs just to place a Button or Link inside them.

Related Skills

• frontend-design — Product UX, visual direction, responsive polish, and verification
• customizing-agent-native — Registered design systems, controllers, slots, conformance, and ejection
• actions — Data fetching and mutation patterns for agent-native apps
• security — User data, forms, external input, and action safety