ls-shadcn-ui-components
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.
SKILL.mdls/skills/ls-shadcn-ui-components/SKILL.md
GitHubshadcn/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 nearestcomponents.json. - Choose the runner from
packageManagerfirst, then lockfiles:pnpm dlx,npx,yarn dlx, orbunx. - 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 (base, radix, or aria)
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/viewfirst for unfamiliar items, thenadd. - Forms: use form rules and forms reference.
- Theming: use semantic tokens and theming reference.
- Registry or blocks: preview with
view,add --view, oradd --dry-run; see registry reference. - Monorepo: map each
components.jsonto 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 --helpand 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 usesrender. UsenativeButton={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 neednativeButton={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 ls/skills/ls-shadcn-ui-components/scripts/verify_shadcn_sources.py --help
python3 ls/skills/ls-shadcn-ui-components/scripts/verify_shadcn_sources.py
python3 ls/skills/ls-shadcn-ui-components/scripts/verify_shadcn_sources.py --json
python3 ls/skills/ls-shadcn-ui-components/scripts/verify_shadcn_sources.py --refresh --json
Run these repository validation commands from the LocalSetup repository root.
For an installed copy of the skill, run the equivalent scripts/... path from
the ls-shadcn-ui-components skill directory. The default verifier path is offline and
uses only the Python standard library to check skill structure. --refresh
checks official source reachability and npm latest metadata; it does not replace
manual review of syntax-sensitive current docs.