AGENT SKILL

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

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 info to refresh. Run pnpm exec shadcn@latest docs <component> for docs.

Principles

  1. Use existing components first. pnpm exec shadcn@latest search before custom UI.
  2. Compose, don't reinvent. Combine components for complex patterns.
  3. Built-in variants first. variant="outline", size="sm", etc.
  4. Semantic colors only. bg-primary, text-muted-foreground -- never bg-blue-500.
  5. Suspense-first. useSuspenseQuery + <Suspense> with <Skeleton> fallbacks.

Code Style (ESLint/Prettier enforced)

  • Named function declarations for components (not arrow functions)
  • import type for type-only imports; follow Prettier import sort order
  • Single quotes, 4-space indent, 120 char width, trailing comma es5
  • No forwardRef (React 19 -- pass ref as prop)
  • No arrow callbacks in useEffect/useLayoutEffect (use named functions)
  • gap-* not space-x-*/space-y-*; size-* not w-* h-* when equal

Critical Rules

Each links to a file with Incorrect/Correct pairs:

  • Styling -- Semantic colors, cn(), gap-*, size-*, truncate, no dark:, no z-index on overlays
  • Forms -- FieldGroup + Field + TanStack Form, data-invalid/aria-invalid
  • Composition -- Items in Groups, Card/Dialog/Sheet structure, Button isLoading, Suspense + Skeleton
  • Icons -- data-icon on buttons, no sizing classes, pass as objects
  • Base UI APIs -- render (not asChild), nativeButton={false}, Select items prop
  • 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

  1. Check installed -- list src/components/ui/ before running add
  2. Get docs -- pnpm exec shadcn@latest docs <component> and fetch URLs
  3. Add -- pnpm exec shadcn@latest add <component> (preview with --dry-run/--diff)
  4. Review -- verify imports, composition, Critical Rules; replace icons with lucide-react
  5. Integrate -- wire TanStack Query/Form per data-loading.md and forms.md

References

04 同仓库更多 Skills

Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

web-security

Enforce web security and avoid security vulnerabilities.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

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.

★ 1
Phenomenon-Studio
Phenomenon-Studio/phenomenon-configs

react

Build clean, modern React components that apply common best practices and avoid common pitfalls like unnecessary state management or useEffect usage.

★ 1