shadcn-ui/ui

Overview

This skill manages shadcn components and projects: adding, searching, fixing, debugging, styling, and composing UI using the shadcn CLI and your project context. It provides project-aware guidance, component docs/usage links, and concrete code patterns to keep components accessible, composable, and consistent with your design system. Follow its rules when running shadcn commands, switching presets, or working with a components.json file.

How this skill works

The skill reads the injected project context (aliases, base, framework, tailwindVersion, iconLibrary, resolvedPaths, isRSC, packageManager) and uses the shadcn CLI workflow to inspect or modify components. It recommends exact CLI commands (via the project's package runner), fetches component docs URLs, validates composition and styling rules, and guides safe adds/updates with --dry-run and --diff. It enforces critical rules (styling, forms, composition, icons, CLI usage) and gives step-by-step instructions for merges, preset switches, and import fixes.

When to use it

• Adding a component or block to the project (use npx shadcn@latest add).
• Searching registries or fetching docs for a component (use search/docs/view).
• Updating components while preserving local changes (follow dry-run and diff workflow).
• Initializing or switching project presets (ask reinstall/merge/skip first).
• Fixing third-party registry imports or aligning icon libraries and aliases.

Best practices

• Always run CLI via the project’s package runner (npx/pnpm dlx/bunx) and use npx shadcn@latest info to refresh context.
• Check installed components before adding; never import components that aren’t present. Use search and docs first.
• Prefer built-in component variants and semantic tokens over custom styles; use cn() for conditional classes.
• Use prescribed compositions: FieldGroup/Field for forms, asChild/render for custom triggers, full Card composition, and required Titles on overlays.
• Use --dry-run and --diff when updating; never overwrite without explicit user approval. Ask before switching presets (reinstall/merge/skip).

Example use cases

• Add a login block from a specified registry and then adjust icon imports to the project’s iconLibrary.
• Update Select component from upstream: run add --dry-run, inspect diffs per file, then merge changes while preserving local edits.
• Switch to a new preset: ask whether to reinstall, merge, or skip and run the corresponding init command with --force and the correct flags.
• Fix a third-party component that uses hardcoded '@/components/...' imports by rewriting to the project alias from npx shadcn@latest info.