shadcn
Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
- License 许可
- MIT
- 最近更新
- 2026-10-23
- Stars
- ★ 1
- Forks
- 0
01 前言 Front Matter
- name
- shadcn
- description
- Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
- user-invocable
- false
02 资源文件 13
- 参考文档agents/openai.yml238 B
- 资产文件assets/shadcn-small.png1.0 KB
- 资产文件assets/shadcn.png3.8 KB
- 参考文档cli.md15.1 KB
- 参考文档customization.md5.8 KB
- 参考文档data-loading.md5.6 KB
- 参考文档evals/evals.json3.8 KB
- 参考文档mcp.md2.3 KB
- 参考文档rules/base-ui.md4.4 KB
- 参考文档rules/composition.md5.8 KB
- 参考文档rules/forms.md8.2 KB
- 参考文档rules/icons.md1.4 KB
- 参考文档rules/styling.md3.2 KB
03 SKILL.md 正文
shadcn/ui
Project Context
| Field | Value |
|---|---|
| Style / Base | base-nova / base (@base-ui/react) |
| Icons | lucide-react |
| Framework | Vite SPA (no RSC, no "use client") |
| Tailwind | v4, CSS variables in src/styles/index.css |
| UI path | src/components/ui/ |
| Alias | @/ -> ./src/ |
| Package manager | pnpm |
| Forms | TanStack Form + Zod (not React Hook Form) |
| Data fetching | TanStack Query v5 (Suspense-first) |
| HTTP client | ky (http/httpPrivate) |
Run
pnpm exec shadcn@latest infoto refresh. Runpnpm exec shadcn@latest docs <component>for docs.
Principles
- Use existing components first.
pnpm exec shadcn@latest searchbefore custom UI. - Compose, don't reinvent. Combine components for complex patterns.
- Built-in variants first.
variant="outline",size="sm", etc. - Semantic colors only.
bg-primary,text-muted-foreground-- neverbg-blue-500. - Suspense-first.
useSuspenseQuery+<Suspense>with<Skeleton>fallbacks.
Code Style (ESLint/Prettier enforced)
- Named
functiondeclarations for components (not arrow functions) import typefor type-only imports; follow Prettier import sort order- Single quotes, 4-space indent, 120 char width, trailing comma
es5 - No
forwardRef(React 19 -- passrefas prop) - No arrow callbacks in
useEffect/useLayoutEffect(use named functions) gap-*notspace-x-*/space-y-*;size-*notw-* h-*when equal
Critical Rules
Each links to a file with Incorrect/Correct pairs:
- Styling -- Semantic colors,
cn(),gap-*,size-*,truncate, nodark:, noz-indexon overlays - Forms --
FieldGroup+Field+ TanStack Form,data-invalid/aria-invalid - Composition -- Items in Groups, Card/Dialog/Sheet structure, Button
isLoading, Suspense + Skeleton - Icons --
data-iconon buttons, no sizing classes, pass as objects - Base UI APIs --
render(notasChild),nativeButton={false}, Selectitemsprop - Data Loading -- Suspense patterns, mutation states, empty states, error toasts
Component Selection
| Need | Use |
|---|---|
| Button/action | Button with variant (isLoading for pending) |
| Form inputs | Input, PasswordInput, Select, Switch, Checkbox, RadioGroup, Textarea, Slider |
| Toggle 2-5 options | ToggleGroup + ToggleGroupItem |
| Data display | Table, Card, Badge, Avatar (always with AvatarFallback) |
| Navigation | Sidebar, Breadcrumb, Tabs, Pagination |
| Overlays | Dialog (modal), Sheet (side panel), Drawer (bottom), AlertDialog (confirm) |
| Feedback | Toast (toast.add, Base UI), Alert, Skeleton, Loader, Empty |
| Layout | Card, Separator, Accordion, Collapsible |
| Menus | DropdownMenu, ContextMenu |
| Tooltips | Tooltip, HoverCard, Popover |
Workflow
- Check installed -- list
src/components/ui/before runningadd - Get docs --
pnpm exec shadcn@latest docs <component>and fetch URLs - Add --
pnpm exec shadcn@latest add <component>(preview with--dry-run/--diff) - Review -- verify imports, composition, Critical Rules; replace icons with
lucide-react - Integrate -- wire TanStack Query/Form per data-loading.md and forms.md
References
- rules/forms.md -- Field system + TanStack Form
- rules/composition.md -- Component composition, overlays, loading
- rules/styling.md -- Semantic colors, Tailwind conventions
- rules/icons.md -- Icon usage patterns
- rules/base-ui.md -- Base UI API specifics
- data-loading.md -- TanStack Query + shadcn integration
- cli.md -- CLI commands and flags
- customization.md -- Theming and CSS variables
- mcp.md -- MCP server tools
04 同仓库更多 Skills
web-security
Enforce web security and avoid security vulnerabilities.
typescript
Write clean, efficient TypeScript code that follows project conventions and advanced type patterns. Use when writing or reviewing TypeScript code, defining types, creating generics, handling errors, or working with React components, Zod schemas, and TanStack libraries.
tanstack-router
TanStack Router patterns for this repo — file-based routing, auth guards, search params, data loading, TanStack Query integration, navigation, and code splitting. Use when creating routes, adding pages, implementing auth flows, working with search/path params, or integrating loaders with TanStack Query.
tanstack-query
TanStack Query patterns for this repo — queryOptions/mutationOptions factories, query key hierarchies, service layer integration, optimistic updates, Suspense usage, error handling, and TanStack Router data loading. Use when creating queries, mutations, API services, query keys, cache invalidation, optimistic updates, or integrating data fetching with routes.
tanstack-form
Build forms using TanStack Form with the project's useAppForm composition, composable field components, Zod validation schemas, FormFieldWrapper error tracking, and form.AppField vs form.Field patterns. Use when creating new forms, adding form fields, writing form validation, or working with TanStack Form in this project.
react
Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.