ls-shadcn-ui

name	ls-shadcn-ui
description	Project-aware shadcn/ui guide. Use for shadcn setup, components, CLI/MCP, registry, theming, forms, Radix/Base UI, aliases, updates, and troubleshooting in React UI projects.
metadata	{"version":"1.0"}
compatibility	{"notes":["Includes a read-only verifier for source reachability and skill structure."]}

shadcn/ui

Use this skill when working with shadcn/ui in React projects: setup, adding components, choosing components, theming, forms, registry items, MCP, monorepos, package imports, Radix vs Base UI, or updating customized local components.

First Inspect The Project

Before recommending commands or editing UI code:

• Find the project root: package.json, lockfile, app framework, and nearest components.json.
• Choose the runner from packageManager first, then lockfiles: pnpm dlx, npx, yarn dlx, or bunx.
• Run the current project probe from the relevant root:

<runner> shadcn@latest info

Interpret the project, config, preset, components, and links from the output. If current shadcn info --help confirms --json, you may rerun with --json for structured parsing. If config is absent or reported as null, treat the repo as not initialized and inspect framework setup before running init.

Use config.aliases, components, resolvedPaths, project.rsc, project.typescript, project.tailwindVersion, config.iconLibrary, config.rtl, config.registries, and the derived base (radix or base) when planning code changes. Never assume @/components/ui.

Decision Flow

• New setup: read framework setup, then choose the exact template or manual flow.
• Add a component: inspect component index, run docs/view first for unfamiliar items, then add.
• Forms: use form rules and forms reference.
• Theming: use semantic tokens and theming reference.
• Registry or blocks: preview with view, add --view, or add --dry-run; see registry reference.
• Monorepo: map each components.json to its package root and pass --cwd.
• Update: use add --dry-run, targeted --diff, and manual merge; see safe update procedure.

Core Guardrails

• Do not fetch raw GitHub component source manually. Prefer shadcn docs, shadcn view, registry JSON, or the installed project files.
• Do not overwrite customized local components without previewing the diff.
• Do not invent CLI flags. Prefer live shadcn@latest --help and official docs.
• Use semantic theme tokens over raw colors and variants over custom one-off class strings.
• Use the configured icon library; do not assume lucide-react.
• Respect RSC/client boundaries. Interactive components usually need a client boundary in Next.js App Router projects.
• Radix composition uses asChild; Base UI composition uses render. Use nativeButton={false} only when a Base UI part that defaults to native button behavior is rendered as a non-button element; parts with inverse/default-false behavior may need nativeButton={true} when rendered as a native button.

Reference Map

• Source ledger
• CLI
• Project context
• components.json
• Frameworks
• Theming
• Forms
• Accessibility
• Registry
• MCP
• Troubleshooting
• Update procedure

Component Guides

• Component index
• Forms and inputs
• Buttons and actions
• Layout and navigation
• Overlays and menus
• Feedback, status, and loading
• Data display and dashboards
• Media, typography, and utilities
• Registry patterns

Scenario Examples

Use examples as starting checklists, not as copy-paste source:

• Login form
• Settings page
• Dashboard
• Command dialog
• Destructive alert dialog
• Responsive navigation
• Data table
• Date picker and calendar
• Theme customization
• Monorepo imports
• Custom registry
• Safe component update

Verifier

python3 scripts/verify_shadcn_sources.py --help
python3 scripts/verify_shadcn_sources.py
python3 scripts/verify_shadcn_sources.py --json
python3 scripts/verify_shadcn_sources.py --refresh --json

The default verifier path is offline and checks skill structure. --refresh checks official source reachability and npm latest metadata; it does not replace manual review of syntax-sensitive current docs.