From c2f28e3ef56b44032e650c212ba19edf519bbc5e Mon Sep 17 00:00:00 2001 From: shadcn Date: Fri, 27 Feb 2026 11:45:50 +0400 Subject: [PATCH] feat: update skills --- skills/shadcn/SKILL.md | 24 ++++- skills/shadcn/cli.md | 46 +++++++++ skills/shadcn/customization.md | 20 ++++ skills/shadcn/patterns.md | 141 +++++++++++++++++++++++----- skills/shadcn/registry-authoring.md | 14 +++ 5 files changed, 220 insertions(+), 25 deletions(-) diff --git a/skills/shadcn/SKILL.md b/skills/shadcn/SKILL.md index d52fb8d8ff..97cd4eae48 100644 --- a/skills/shadcn/SKILL.md +++ b/skills/shadcn/SKILL.md @@ -75,15 +75,26 @@ shadcn docs button dialog select 1. **Get project context** — already injected above. Run `shadcn info` again if you need to refresh. 2. **Check installed components** — look in the `resolvedPaths.ui` directory before importing or adding. Don't import components that haven't been added, and don't re-add ones already installed. 3. **Find components** — MCP `shadcn:search_items_in_registries` or `shadcn search`. -4. **Get docs and examples** — run `shadcn docs ` to get URLs, then fetch them. Alternatively use MCP `shadcn:view_items_in_registries` or `shadcn view`. -5. **Install** — MCP `shadcn:get_add_command_for_items` or `shadcn add`. +4. **Get docs and examples** — run `shadcn docs ` to get URLs, then fetch them. Alternatively use MCP `shadcn:view_items_in_registries` or `shadcn view`. Note: `shadcn view` is for browsing registry items you haven't installed. To preview changes to installed components, use `shadcn add --diff`. +5. **Install or update** — MCP `shadcn:get_add_command_for_items` or `shadcn add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below). 6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `shadcn info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project. 7. **Verify** — MCP `shadcn:get_audit_checklist`. - 8. **Switching presets** — Before running `shadcn init --preset ` in an existing project, always ask the user if they'd like to reinstall existing UI components. If yes, use the `--reinstall` flag to overwrite them with the new preset styles. If MCP is unavailable, use CLI: `shadcn search`, `shadcn view`, `shadcn add`. +## Updating Components + +When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.** + +1. Run `shadcn add --dry-run` to see all files that would be affected. +2. For each file, run `shadcn add --diff ` to see what changed upstream vs local. +3. Decide per file based on the diff: + - No local changes → safe to overwrite. + - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications. + - User says "just update everything" → use `--overwrite`, but confirm first. +4. **Never use `--overwrite` without the user's explicit approval.** + ## Quick Reference ```bash @@ -104,6 +115,11 @@ shadcn add button card dialog shadcn add @magicui/shimmer-button shadcn add --all +# Preview changes before adding/updating. +shadcn add button --dry-run +shadcn add button --diff button.tsx +shadcn add button --view button.tsx + # Search registries. shadcn search @shadcn -q "sidebar" shadcn search @blocks -q "stats" @@ -111,7 +127,7 @@ shadcn search @blocks -q "stats" # Get component docs and example URLs. shadcn docs button dialog select -# View item details. +# View registry item details (for items not yet installed). shadcn view @shadcn/button ``` diff --git a/skills/shadcn/cli.md b/skills/shadcn/cli.md index d323788f06..be6abc47f3 100644 --- a/skills/shadcn/cli.md +++ b/skills/shadcn/cli.md @@ -4,6 +4,13 @@ All commands use `shadcn `. Configuration is read from `components.json > **IMPORTANT:** Always use the `shadcn` command directly. Never prefix with `npx`, `pnpm dlx`, or any package runner. +## Contents + +- Commands: init, add (dry-run, smart merge), search, view, docs, diff, info, build +- Templates: next, vite, start, react-router, astro +- Presets: named, code, URL formats and fields +- Switching presets + --- ## Commands @@ -35,6 +42,8 @@ Initializes shadcn/ui in an existing project or creates a new project (when `--n ### `add` — Add components +> **IMPORTANT:** To compare local components against upstream or to preview changes, ALWAYS use `shadcn add --dry-run`, `--diff`, or `--view`. NEVER fetch raw files from GitHub or other sources manually. The CLI handles registry resolution, file paths, and CSS diffing automatically. + ```bash shadcn add [components...] [options] ``` @@ -49,6 +58,43 @@ Accepts component names, registry-prefixed names (`@magicui/shimmer-button`), UR | `--all` | `-a` | Add all available components | `false` | | `--path ` | `-p` | Target path for the component | — | | `--silent` | `-s` | Mute output | `false` | +| `--dry-run` | | Preview all changes without writing files | `false` | +| `--diff ` | | Show the diff for a specific file (implies `--dry-run`) | — | +| `--view ` | | Show the full content of a specific file (implies `--dry-run`) | — | + +#### Dry-Run Mode + +Use `--dry-run` to preview what `add` would do without writing any files. `--diff` and `--view` both imply `--dry-run`. + +```bash +# Preview all changes. +shadcn add button --dry-run + +# Show the diff for a specific file. +shadcn add button --diff button.tsx + +# Show the full content of a specific file. +shadcn add button --view button.tsx + +# Works with URLs too. +shadcn add https://api.npoint.io/abc123 --dry-run + +# CSS diffs. +shadcn add button --diff globals.css +``` + +**When to use dry-run:** + +- When the user asks "what files will this add?" or "what will this change?" — use `--dry-run`. +- Before overwriting existing components — use `--diff` to preview the changes first. +- When the user wants to inspect component source code without installing — use `--view`. +- When checking what CSS changes would be made to `globals.css` — use `--diff globals.css`. + +> **`shadcn add --dry-run` vs `shadcn view`:** Prefer `shadcn add --dry-run/--diff/--view` over `shadcn view` when the user wants to preview changes to their project. `shadcn view` only shows raw registry metadata. `shadcn add --dry-run` shows exactly what would happen in the user's project: resolved file paths, diffs against existing files, and CSS updates. Use `shadcn view` only when the user wants to browse registry info without a project context. + +#### Smart Merge from Upstream + +See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full workflow. ### `search` — Search registries diff --git a/skills/shadcn/customization.md b/skills/shadcn/customization.md index 4305664b7e..21670f63aa 100644 --- a/skills/shadcn/customization.md +++ b/skills/shadcn/customization.md @@ -2,6 +2,17 @@ Components reference semantic CSS variable tokens. Change the variables to change every component. +## Contents + +- How it works (CSS variables → Tailwind utilities → components) +- Color variables and OKLCH format +- Dark mode setup +- Changing the theme (presets, CSS variables) +- Adding custom colors (Tailwind v3 and v4) +- Border radius +- Customizing components (variants, className, wrappers) +- Checking for updates + --- ## How It Works @@ -178,3 +189,12 @@ export function ConfirmDialog({ title, description, onConfirm, children }) { shadcn diff # all components with available updates shadcn diff button # specific component ``` + +To preview exactly what would change before updating, use `--dry-run` and `--diff`: + +```bash +shadcn add button --dry-run # see all affected files +shadcn add button --diff button.tsx # see the diff for a specific file +``` + +See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow. diff --git a/skills/shadcn/patterns.md b/skills/shadcn/patterns.md index eab49c2508..ce1f76f095 100644 --- a/skills/shadcn/patterns.md +++ b/skills/shadcn/patterns.md @@ -4,6 +4,17 @@ Rules and examples for composing shadcn/ui components. > **Note:** Examples below use `@/` as the import prefix. Always use the actual `aliasPrefix` from `shadcn info` for the target project. Similarly, icon imports depend on the project's `iconLibrary` — use `lucide-react` for `lucide`, `@tabler/icons-react` for `tabler`, `@phosphor-icons/react` for `phosphor`, etc. Never assume `lucide-react`. +## Contents + +- Component selection table +- Forms (FieldGroup, Field, form controls) +- Toggle groups +- Alerts +- Overlays +- Empty states +- Toast notifications +- Base-specific patterns + --- ## Component Selection @@ -190,41 +201,129 @@ toast("File deleted.", { }) ``` + + --- -## Composition Rules +## Base-Specific Patterns -1. **Use `asChild` (radix) or `render` (base) for custom triggers.** Don't wrap triggers in extra elements. Check the `base` field from `shadcn info` to determine which prop to use. +Check the `base` field from `shadcn info` to determine which patterns to use. -2. **Use `Field` components for forms, not raw divs.** Never use `div` with `space-y-*` or `grid gap-*` for form layout. Use `FieldGroup` for the form container and `Field` for each control. Use `FieldLabel` for labelled inputs, `FieldTitle` for headings, `FieldDescription` for helper text. +### Composition: asChild (radix) vs render (base) -3. **Use existing UI components before custom markup.** Before writing a styled `div`, check if a component already exists: `Alert` for callouts, `ToggleGroup` for option sets, `Empty` for empty states, etc. +Radix uses `asChild` to replace the default element. Base UI uses `render` instead. -4. **Use `className` for layout, not styling.** Add layout utilities (`w-full`, `grid`, `flex`, `gap-*`) but avoid overriding component colors or typography. +```tsx +// radix. + + + -5. **Prefer built-in variants.** Use `variant="outline"`, `variant="ghost"`, `size="sm"` etc. before adding custom classes. +// base. +}>Open +``` -6. **Compose, don't customize.** Build complex UIs by composing multiple simple components rather than heavily customizing a single one. +```tsx +// radix. + + + -7. **Add `"use client"` at RSC boundaries.** When `isRSC` is `true` (from `shadcn info`), components that use `useState`, `useEffect`, event handlers (`onClick`, `onChange`, etc.), or browser APIs must start with `"use client"`. Keep client boundaries as low in the tree as possible. +// base. +}> + Menu + +``` -8. **Keep components small and focused.** A component should render itself and its own interactions (e.g. a card + its dialog). Page-level layout, data arrays, and loops belong in the page, not the component. +### Button as a link (base only) -9. **Pass data directly, not keys.** When passing icons or other references through props, pass the actual objects (e.g. `icon={ComputerTerminal01Icon}`), not string keys to a lookup map. +When `render` changes a `Button` to a non-button element (``, ``), add `nativeButton={false}` so Base UI doesn't apply button-specific behavior. -10. **Always wrap items and labels in a Group.** For menu-like components, items, labels, and subs must be direct children of their group component. Never place them directly inside the content container. - - `DropdownMenuItem`, `DropdownMenuLabel`, `DropdownMenuSub` → inside `DropdownMenuGroup` - - `MenubarItem`, `MenubarLabel`, `MenubarSub` → inside `MenubarGroup` - - `ContextMenuItem`, `ContextMenuLabel`, `ContextMenuSub` → inside `ContextMenuGroup` - - `SelectItem`, `SelectLabel` → inside `SelectGroup` - - `CommandItem` → inside `CommandGroup` +```tsx +// base. + -11. **Always use `data-icon` on icons inside buttons.** When placing an icon inside a `Button`, add `data-icon="inline-start"` for prefix icons or `data-icon="inline-end"` for suffix icons. This ensures correct spacing. Never add sizing classes to the icon — the button handles sizing automatically. +// radix equivalent. + +``` -12. **Always use `InputGroupInput` and `InputGroupTextarea` inside an `InputGroup`.** Never use the base `Input` or `Textarea` components directly inside an `InputGroup`. The input-group variants reset borders, backgrounds, and focus rings to compose correctly within the group. +### Non-button trigger elements (base only) -13. **Buttons inside inputs use `InputGroup` + `InputGroupAddon`.** Never place a `Button` directly inside or adjacent to an `Input` with custom positioning. Wrap in `InputGroup` and use `InputGroupAddon` for the button. +When a trigger's `render` is not a `Button` (e.g. `InputGroupAddon`), add `nativeButton={false}`. -14. **`InputGroupAddon` must use `InputGroupButton`.** Never place a raw `Button` inside `InputGroupAddon`. Always use `InputGroupButton` instead. +```tsx +// base. +} nativeButton={false}> + Pick date + +``` -15. **`InputGroupButton` sizing depends on addon alignment.** When `InputGroupAddon` is `align="inline-start"` or `align="inline-end"`, prefer `size="icon-sm"` or `size="icon-xs"` (icon-only buttons). When `align="block-start"` or `align="block-end"`, prefer `size="xs"` or `size="sm"` (buttons with text). +### Select: items prop (base only) + +Base `Select` requires an `items` prop on the root. It also supports `multiple` and `itemToStringValue` props. + +```tsx +// base. +const items = ["Admin", "Member", "Viewer"] + + +``` + +Radix `Select` uses JSX only — no `items` prop. Use `placeholder` on `SelectValue`. + +```tsx +// radix. + +``` + +### Accordion: type prop (radix only) + +Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. The `defaultValue` is a string. + +```tsx +// radix. + + ... + +``` + +Base uses no `type` prop. Use the `multiple` prop for multi-select. The `defaultValue` is an array. + +```tsx +// base. + + ... + + +// base multi-select. + + ... + ... + +``` + +--- + +For composition rules (asChild/render, className usage, Groups, data-icon, InputGroup, etc.), see the **Critical Rules** section in [SKILL.md](./SKILL.md#critical-rules). diff --git a/skills/shadcn/registry-authoring.md b/skills/shadcn/registry-authoring.md index e1d633a92d..0e4c82688f 100644 --- a/skills/shadcn/registry-authoring.md +++ b/skills/shadcn/registry-authoring.md @@ -2,6 +2,20 @@ Build and publish your own shadcn/ui-compatible component registry. Registries let you distribute reusable components, blocks, hooks, and utilities that others can install with a single command. +## Contents + +- Overview and directory structure +- registry.json format (required fields, item fields) +- Item types (registry:ui, registry:block, registry:hook, etc.) +- File objects and target paths +- Dependencies (NPM and registry) +- CSS variables and CSS rules +- Environment variables +- Building and hosting +- User configuration (simple, authenticated) +- Community registry index +- Examples (minimal registry, multi-file block) + --- ## Overview