shadcn-core-blocks AI 스킬 사용법

어떤 스킬인가요?

Use when scaffolding a full page (dashboard, login, signup, sidebar layout, calendar app), bootstrapping a starter template from shadcn's gallery, evaluating block vs hand-composed components, choosing between the default / new-york / sera / luma styles, or recovering after a `shadcn add <block>` rerun overwrote local customisations. Prevents six common block-system failures : treating blocks as immutable starter templates (they are owned code, edit freely), running `shadcn add <block>` over a customised copy without `--diff` and losing work, mixing multiple style enum values inside one project, importing block sub-components from package paths instead of the local copied location, expecting blocks to auto-update when shadcn ships new revisions, and conflating blocks with components in CLI invocation when they accept different mental models for ownership and customisation. Covers the blocks distribution surface (a separate gallery at /blocks distinct from /components), block category landscape (dashboard, sidebar, login, signup, calendar, authentication), the block-add CLI flow (same `shadcn add` command, multi-file output), the style enum values (default, new-york, sera Apr 2026, luma Mar 2026) and when to choose each, the post-add ownership model, and the block-versus-component decision logic for whole-page versus building-block scope. Keywords: shadcn blocks, scaffold dashboard, starter template, shadcn full page, what is a block, block vs component, npx shadcn add dashboard, sidebar-07, dashboard-01, login-03, login-04, blocks gallery, ui.shadcn.com/blocks, page template, layout starter, multi-file block, block customisation, style enum, new-york style, default style, sera style, luma style, typographic style, shadcn full app shell, scaffold an admin panel, blank dashboard, copy paste page, page section, pre-built layout, how do I get a dashboard, how do I add a login page, shadcn template, opinionated starter, free open source blocks.

설치 방법

프로젝트 폴더에서 아래 명령어를 실행하고, 설치할 에이전트를 선택하세요.

npx skills add impertio-studio/shadcn-ui-claude-skill-package --skill shadcn-core-blocks

설치 명령을 직접 실행해야 적용됩니다. 지원 에이전트와 필요한 권한·라이선스는 제작자의 안내를 확인하세요.

스킬 원문 파일

`references/anti-patterns.md`

# shadcn-core-blocks : Anti-Patterns

Five canonical anti-patterns that produce real, recurring failures with shadcn blocks. Each entry documents WHY the anti-pattern fails and the deterministic fix. Verified against `SOURCES.md` primary URLs on 2026-05-19.

## Anti-Pattern 1 : Treating blocks as immutable starter templates

### Symptom

The team installs `dashboard-01`, sees a complete page, and treats the copied files as a sealed template. They build a wrapper component (`DashboardWrapper`) that imports the block page and tries to override sections via props or context. Customisation requirements pile up into a multi-layer indirection of wrappers, slots, and conditionals.

### Why this fails

1. **Defeats the Open Code pillar.** The official shadcn doctrine (verified verbatim at https://ui.shadcn.com/docs) is : "The top layer of your component code is open for modification." A block is owned code from the moment `shadcn add` finishes ; treating it as immutable inverts the design intent.
2. **Wrapper indirection costs more than direct editing.** Each wrapper layer adds prop-drilling, conditional logic, and a place where a future engineer must understand "what is this wrapper actually doing". Editing the block file directly is a single change.
3. **AI assistants lose effectiveness.** The AI-Ready pillar is predicated on Claude reading the local source. When the source is hidden behind a wrapper that conditionally renders sections, Claude cannot reason over the actual UI surface.
4. **Type safety degrades.** Wrappers that expose every block section as an optional prop produce TypeScript signatures with twenty optional properties, no two of which are ever set together.

### Fix

ALWAYS edit the block files in place. Delete unused sub-components. Rename props that read awkwardly in your domain. Replace data sources with your own server queries. The block IS your code.

NEVER build a `BlockWrapper` component that delegates to the original. If you find yourself writing one, stop and edit the block file instead.

## Anti-Pattern 2 : Running `shadcn add <block-id> --overwrite` on a customised block

### Symptom

Six months after installing `dashboard-01` and customising it extensively, the team wants the latest shadcn block updates. They run :

```bash
pnpm dlx shadcn@latest add dashboard-01 --overwrite
```

All customisations vanish. The files are restored to the canonical upstream version. Hours or weeks of work are lost.

### Why this fails

1. **`--overwrite` is binary and silent.** The flag writes the upstream version to every file the block touches. There is no per-file confirmation, no merge, no preview. The CLI has done exactly what was requested.
2. **The block is a multi-file scaffold.** A component overwrite touches one file ; a block overwrite touches many. The blast radius is correspondingly larger.
3. **Underlying primitive auto-install can compound the damage.** If the block depends on `sidebar` and `data-table`, those primitives may also be overwritten. Customisations to `components/ui/sidebar.tsx` disappear too.
4. **Git history is the only recovery path.** If the customisations were never committed (e.g. on a feature branch waiting for review), recovery is impossible.

### Fix

ALWAYS preview the upstream changes first :

```bash
pnpm dlx shadcn@latest add dashboard-01 --diff
```

Decide per file :
- Sub-component never touched locally → `--overwrite --path <file>` is safe.
- Sub-component customised locally → SKIP the overwrite ; apply the upstream diff manually using `git apply` or hand-edit.

ALWAYS commit the customisations to git BEFORE any rerun, so recovery via `git reset` is always available. NEVER trust `--overwrite` without a clean working tree.

## Anti-Pattern 3 : Mixing multiple `style` enum values in one project

### Symptom

The team initialised the project with `default` years ago. They install a new dashboard block today and decide they prefer `new-york`. They edit `components.json` :

```json
{ "style": "new-york" }
```

They then run `pnpm dlx shadcn@latest add dashboard-01`. The new block uses `new-york` defaults (tight radii, geometric character). The pre-existing buttons, dialogs, and cards still use `default` (softer radii, original character). The visual language fragments. Spacing, radii, and typography no longer compose into a coherent system.

### Why this fails

1. **`style` controls baked-in classes, not just future installs.** Each `shadcn add` reads the current `style` value and copies the components OR blocks with that style's classes and variants baked into the file. Editing `style` post-init does NOT retroactively re-style already-installed code ; it only changes what FUTURE installs produce.
2. **Radii, spacing, and typography differ per style.** `default` uses a softer radius and looser layout. `new-york` uses tighter radii and a more geometric layout. `sera` uses underline controls and uppercase headings. `luma` uses softer ambient gradients. Mixing them produces a UI where buttons look like one design system and cards look like another.
3. **No automatic migration exists.** The CLI provides no `migrate style` command. The documentation does not list one. (Verified at https://ui.shadcn.com/docs/cli, 2026-05-19.)
4. **Block dependencies amplify the mismatch.** A `dashboard-01` block under `new-york` depends on `sidebar`, `data-table`, `card`, etc. If those primitives were installed under `default` and remain in place, the dashboard inherits a half-`new-york`, half-`default` look.

### Fix

ALWAYS choose ONE style at `init` time and keep it. NEVER edit `components.json#style` casually.

If a style migration is genuinely required, do it as a project-wide refactor (see `references/examples.md`, Example 4) :

1. Snapshot the inventory of installed components and blocks.
2. Delete `components.json` and `components/ui/`.
3. Re-init with the new style.
4. Re-add every previously-installed component and block.
5. Port customisations forward from git history.
6. Run a full visual review.

NEVER attempt a partial migration ; it always produces fragmentation.

## Anti-Pattern 4 : Importing a block sub-component from a non-local path

### Symptom

After installing `sidebar-07` (which produces `components/app-sidebar.tsx` and several sub-components), a developer writes :

```tsx
// WRONG : invented package path
import { AppSidebar } from "shadcn-ui/blocks/sidebar-07/app-sidebar"

// WRONG : invented scoped package
import { AppSidebar } from "@shadcn/blocks"

// WRONG : copy-pasted from outdated tutorial
import { AppSidebar } from "@/components/ui/app-sidebar"   // wrong subfolder
```

The build fails with `Module not found` errors, or the import resolves to nothing and the page renders blank.

### Why this fails

1. **There is no runtime shadcn package.** As documented in [shadcn-core-architecture](../../shadcn-core-architecture/SKILL.md), no `shadcn-ui`, `@shadcn/ui`, or `@shadcn/blocks` runtime npm package exists. The shadcn CLI is invoked via `dlx`/`npx` at install time and copies SOURCE into the consumer project. There is nothing to import from.
2. **Block sub-components are local files at known paths.** When `shadcn add sidebar-07` copies `app-sidebar.tsx`, it places the file at the path determined by `components.json` aliases. With default aliases that is `@/components/app-sidebar` (NOT `@/components/ui/app-sidebar` ; the `ui` subfolder is reserved for primitives like `button`, `card`, the `sidebar` PRIMITIVE itself).
3. **AI training data is often outdated.** LLMs frequently invent imports from `shadcn-ui` or `@shadcn/ui` because old tutorials and AI-generated blog posts cited those paths. Verifying against the actual local file tree is the only reliable check.
4. **The same block-id can resolve to different paths in different projects.** A project that customised `components.json` aliases (e.g. `"components": "@/src/components"`) will have the block sub-components at `@/src/components/app-sidebar`, not `@/components/app-sidebar`.

### Fix

ALWAYS run `ls` or use the editor's file tree to confirm WHERE the CLI actually wrote the block files, then import from that exact local path :

```bash
# verify the actual file location
ls components/
# components/app-sidebar.tsx
# components/nav-projects.tsx
# components/nav-secondary.tsx
# components/nav-user.tsx
# components/ui/sidebar.tsx                       <-- primitive, different file
```

```tsx
// CORRECT : import from the actual local alias path
import { AppSidebar } from "@/components/app-sidebar"
import { SidebarProvider } from "@/components/ui/sidebar"
```

NEVER import from a package path that does not exist. If a path-resolution fails, the FIRST debug step is to verify the file's actual location on disk.

## Anti-Pattern 5 : Expecting blocks to auto-update when shadcn ships new revisions

### Symptom

The team installed `dashboard-01` in January, customised it, committed it, and moved on. In June, they read that shadcn shipped an improved version of `dashboard-01` with a new chart variant. They run `pnpm update` (or `pnpm dlx shadcn@latest`) and expect the dashboard to pick up the new chart. Nothing changes.

### Why this fails

1. **There is no library to update.** The `pnpm update` command updates npm packages. The shadcn CLI is one such package, but its update only refreshes the CLI binary, not the components or blocks already copied into the project. The components and blocks ARE the project's source code, not runtime dependencies.
2. **Same ownership doctrine as components.** As documented in [shadcn-core-architecture](../../shadcn-core-architecture/SKILL.md), shadcn explicitly inverts the library model. The maintainer publishes recipes ; the consumer owns the kitchen. Upgrades are explicit, manual, and per-file.
3. **There is no semver-driven rollout for blocks.** A new block revision does not produce a semver bump that triggers an `npm update` cascade. The block is updated only when the consumer chooses to re-run `shadcn add <block-id>` with `--overwrite` or `--diff` and a manual merge.
4. **Block dependencies on underlying components compound the issue.** A "new" block revision may also depend on new component revisions ; re-running `add` for the block may also touch the underlying primitives.

### Fix

ALWAYS treat upgrades as explicit, manual operations :

```bash
# 1. preview the new upstream version
pnpm dlx shadcn@latest add dashboard-01 --diff

# 2. compare against the local customised version
git diff <commit-when-block-was-added> -- app/dashboard/ components/dashboard/

# 3. decide per file and per change : overwrite, skip, or hand-merge

# 4. commit the merge separately from any unrelated work
git add app/dashboard/ components/dashboard/
git commit -m "feat(dashboard): merge upstream dashboard-01 chart-variant"
```

ALWAYS pin the working state of block files in git immediately after `add`. ALWAYS verify https://ui.shadcn.com/docs/changelog for breaking changes in underlying primitives BEFORE re-adding a block. NEVER expect block updates to flow in via `npm update` ; the ownership doctrine is non-negotiable.

## Sources

- https://ui.shadcn.com/docs (Open Code, AI-Ready pillars, "not a component library" framing)
- https://ui.shadcn.com/docs/cli (`--diff`, `--overwrite`, `--path` semantics)
- https://ui.shadcn.com/docs/components-json (`style` field, immutability)
- https://ui.shadcn.com/docs/changelog (style additions, breaking-change history)
- https://ui.shadcn.com/blocks (block gallery and file inventory)
- https://github.com/shadcn-ui/ui/issues (real-world recurrence of overwrite, style-mix, import-path failures)

Verified 2026-05-19.

# shadcn-core-blocks : Examples Working code samples and CLI sessions for the block distribution surface. All examples verified against `SOURCES.md` primary URLs on 2026-05-19. ALWAYS treat copied block files as project source ; NEVER as vendored dependencies. ## Example 1 : Add a dashboard block Add `dashboard-01` from the default `@shadcn` registry to a Next.js App Router project that has been initialised with `pnpm dlx shadcn@latest init` and the `new-york` style. ### CLI invocation ```bash # preview first (no disk writes) pnpm dlx shadcn@latest add dashboard-01 --dry-run # inspect a single file before install pnpm dlx shadcn@latest add dashboard-01 --view app/dashboard/page.tsx # perform the install pnpm dlx shadcn@latest add dashboard-01 ``` ### Expected file output The exact tree is documented at the per-block preview on https://ui.shadcn.com/blocks. A typical `dashboard-01` install produces : ``` app/ dashboard/ page.tsx # block page entry (registry:page) data.json # demo data (registry:file) components/ dashboard/ nav-main.tsx # block sub-component nav-user.tsx # block sub-component app-sidebar.tsx # block sub-component data-table.tsx # block sub-component chart-area-interactive.tsx # block sub-component section-cards.tsx # block sub-component site-header.tsx # block sub-component ui/ sidebar.tsx # auto-installed primitive (registry:ui) chart.tsx # auto-installed primitive data-table.tsx # auto-installed primitive card.tsx # auto-installed primitive ... (any other missing primitives) lib/ utils.ts # auto-installed if missing ``` ALWAYS commit ALL of these files in the SAME commit. The block is now project source. ### Verify post-install ```bash # confirm the page route serves the block pnpm dev # visit http://localhost:3000/dashboard # type-check pnpm tsc --noEmit # lint pnpm lint ``` NEVER move the copied files to a vendored or `node_modules`-shaped path. They live in `app/`, `components/`, `lib/` as first-class application code. ## Example 2 : Customise a block after add Scenario : the team installed `dashboard-01` and wants to replace the demo data source with a Supabase query. ### Before (as shipped by the block) ```tsx // app/dashboard/page.tsx (as copied by `shadcn add dashboard-01`) import data from "./data.json" import { DataTable } from "@/components/dashboard/data-table" export default function Page() { return <DataTable data={data} /> } ``` ### After (customised) ```tsx // app/dashboard/page.tsx (customised by the team) import { createServerClient } from "@/lib/supabase/server" import { DataTable } from "@/components/dashboard/data-table" export default async function Page() { const supabase = createServerClient() const { data, error } = await supabase.from("transactions").select("*") if (error) throw error return <DataTable data={data} /> } ``` ### What this demonstrates - The block file is owned code ; editing it is the intended workflow. - The page becomes an async Server Component because Next.js App Router supports it ; the block was a starter, not an immutable contract. - The local sub-component `@/components/dashboard/data-table` continues to work because its imports were never package-shaped. ALWAYS commit customisations on the SAME branch where the block was initially added. NEVER mix the `add` commit with the customisation commit ; keeping them separate makes future re-add merges tractable. ## Example 3 : Re-adding a customised block safely Scenario : six months later the team wants to pull updates from `dashboard-01`. The local `app/dashboard/page.tsx` has been heavily customised. ### Wrong workflow ```bash # DESTRUCTIVE : overwrites customisations without warning pnpm dlx shadcn@latest add dashboard-01 --overwrite ``` This is the single most common block-system disaster ; the customisation work disappears. ### Correct workflow ```bash # 1. preview the diff for each file the block would write pnpm dlx shadcn@latest add dashboard-01 --diff # example diff output for one file : # app/dashboard/page.tsx # - import data from "./data.json" # + import data from "./data.json" # + import { revalidatePath } from "next/cache" # ... 12 more changed lines ... # 2. decide per file : # - block sub-component you never touched → overwrite is safe # - file you customised → SKIP or hand-merge # # 3. for individual files you want to overwrite : pnpm dlx shadcn@latest add dashboard-01 --overwrite --path components/dashboard/section-cards.tsx # 4. for files you customised, do NOT overwrite ; apply the diff by hand using git : git diff HEAD~1 -- app/dashboard/page.tsx # manually merge the upstream changes into your customised file ``` ALWAYS preview with `--diff` before any rerun. NEVER use `--overwrite` blanket on a customised block. ## Example 4 : Switching style enum mid-project (the only correct path) Scenario : the team initialised the project with `default` and wants to migrate to `new-york`. ### Why the obvious approach fails ```bash # WRONG : editing components.json manually does NOT re-style existing components sed -i 's/"style": "default"/"style": "new-york"/' components.json ``` The already-installed components have the `default` style's classes and variant compositions baked in. Editing `components.json` only changes what FUTURE `shadcn add` runs produce. The project ends up half in `default`, half in `new-york`. Visually broken. ### The only correct workflow ```bash # 1. snapshot the project on a branch git checkout -b chore/style-migration # 2. record the list of installed components and blocks pnpm dlx shadcn@latest info > installed-before.txt # 3. delete the existing components.json and the components/ui/ folder rm components.json rm -rf components/ui/ # 4. re-init with the new style pnpm dlx shadcn@latest init --style new-york # 5. re-add every component and block that was previously installed pnpm dlx shadcn@latest add button card dialog sidebar data-table pnpm dlx shadcn@latest add dashboard-01 sidebar-07 login-03 # (etc. for the full inventory recorded in step 2) # 6. manually reconcile any customisations from the deleted files using git history git log --all -- components/ui/button.tsx git show <commit>:components/ui/button.tsx # retrieve the customised version # port the customisations into the new new-york version of button.tsx # 7. run type-check, lint, and visual review before merging pnpm tsc --noEmit pnpm lint pnpm test ``` ALWAYS treat a style migration as a project-wide refactor, not a config tweak. NEVER edit the `style` field in isolation ; the result is silent visual fragmentation. ## Example 5 : Block + component composition Use `sidebar-07` as the layout shell, then drop a hand-built panel into the inset. ### Step 1 : install the sidebar block ```bash pnpm dlx shadcn@latest add sidebar-07 ``` This produces (typical) : ``` app/ layout.tsx (or page.tsx) # block layout entry components/ app-sidebar.tsx # block sidebar component nav-projects.tsx # block sub-component nav-secondary.tsx # block sub-component nav-user.tsx # block sub-component ui/ sidebar.tsx # primitive (auto-installed) ``` ### Step 2 : write the hand-built panel ```tsx // components/projects-panel.tsx (NOT shipped by any block ; the team's own code) import { Card, CardContent, CardHeader, CardTitle } from "@/components/ui/card" import { Button } from "@/components/ui/button" import { PlusIcon } from "lucide-react" export function ProjectsPanel({ projects }: { projects: { id: string; name: string }[] }) { return ( <Card> <CardHeader> <CardTitle>Projects</CardTitle> <Button size="sm"> <PlusIcon className="mr-1 size-4" /> New </Button> </CardHeader> <CardContent> <ul> {projects.map((p) => ( <li key={p.id}>{p.name}</li> ))} </ul> </CardContent> </Card> ) } ``` ### Step 3 : compose them in the page ```tsx // app/page.tsx (edited block output) import { SidebarProvider, SidebarInset } from "@/components/ui/sidebar" import { AppSidebar } from "@/components/app-sidebar" // from sidebar-07 block import { ProjectsPanel } from "@/components/projects-panel" // hand-built export default function HomePage() { return ( <SidebarProvider> <AppSidebar /> <SidebarInset className="p-6"> <ProjectsPanel projects={[{ id: "1", name: "Alpha" }, { id: "2", name: "Beta" }]} /> </SidebarInset> </SidebarProvider> ) } ``` ALWAYS treat blocks as page skeletons and components as organs inside them. NEVER feel obliged to keep block sub-components untouched ; replace, refactor, or delete them as the project demands. ## Sources - https://ui.shadcn.com/blocks (per-block file inventory, gallery preview) - https://ui.shadcn.com/docs/cli (`add`, `--dry-run`, `--diff`, `--view`, `--overwrite`, `--path`) - https://ui.shadcn.com/docs/components-json (`style` field, immutability) - https://ui.shadcn.com/docs/changelog (style enum dates, CLI version gates) Verified 2026-05-19.

# shadcn-core-blocks : Methods Reference Complete API signatures and identifiers relevant to the block distribution surface. Verified against `SOURCES.md` primary URLs on 2026-05-19. ## CLI : block-add invocation The CLI uses the SAME `add` verb for blocks and components. The block-id (`dashboard-01`, `sidebar-07`, `login-03`, etc.) is the only signal of multi-file scaffold output. ### Canonical signature ``` pnpm dlx shadcn@latest add <name> [...names] [flags] npx shadcn@latest add <name> [...names] [flags] bunx shadcn@latest add <name> [...names] [flags] yarn dlx shadcn@latest add <name> [...names] [flags] ``` `<name>` accepts : - A component identifier : `button`, `card`, `sidebar`. - A block identifier : `dashboard-01`, `sidebar-07`, `login-03`. - A custom-registry reference : `@acme/datepicker`. - A direct registry URL : `https://registry.example.com/login.json`. - A preset code. ### Flags relevant to block install Verified verbatim at https://ui.shadcn.com/docs/cli : | Flag | Short | Purpose | |------|-------|---------| | `--yes` | `-y` | skip confirmation prompt (default false) | | `--overwrite` | `-o` | overwrite existing files (default false) | | `--cwd <cwd>` | `-c` | working directory (defaults to current) | | `--all` | `-a` | add all available components (default false) | | `--path <path>` | `-p` | path to add the component to | | `--silent` | `-s` | mute output (default false) | | `--dry-run` | | preview changes without writing files (default false) | | `--diff [path]` | | show diff for a file | | `--view [path]` | | show file contents | The `--diff` and `--view` flags are the safe-preview surface ALWAYS used before re-running `add` on customised blocks. ### Multi-file output Blocks produce multi-file scaffolds. The CLI documentation does not enumerate the file output per block ; the canonical inventory is the gallery preview at https://ui.shadcn.com/blocks (per-block detail view shows the file tree). Expected file categories for a typical dashboard block : | Category | Example path | Notes | |----------|--------------|-------| | Page entry | `app/<route>/page.tsx` (Next.js App Router) ; `src/pages/<route>.tsx` (Pages Router) ; `app/routes/<route>.tsx` (React Router v7) | The framework-specific path is resolved by the CLI from `components.json` aliases. | | Sub-component folder | `components/<block-name>/` | One `.tsx` per sub-component. | | Data file | `app/<route>/data.json` or `data.ts` | Only when the block demos data-driven UI. | | Primitive dependencies | `components/ui/sidebar.tsx`, `components/ui/data-table.tsx`, etc. | Auto-installed if missing. | | `lib/utils.ts` | `lib/utils.ts` | Auto-installed if missing (contains the `cn` helper). | ALWAYS use `--dry-run` to enumerate the exact file list for a specific block before installing. ## components.json : style enum Verified at https://ui.shadcn.com/docs/components-json and https://ui.shadcn.com/docs/changelog (2026-05-19) : ```json { "$schema": "https://ui.shadcn.com/schema.json", "style": "new-york", "tailwind": { "baseColor": "neutral", "cssVariables": true }, "rsc": true, "tsx": true, "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" } } ``` ### Style enum values (verified) | Value | Status | Introduced | CLI minimum | Visual character | |-------|--------|-----------|-------------|------------------| | `"default"` | Legacy. Retained for backward compatibility. Deprecated for new projects. | Original (pre-2024) | any | The original shadcn look ; softer than `new-york`. | | `"new-york"` | Current. Recommended for most new projects. | 2024 | any | Geometric, tight radii, design-system-grade. | | `"luma"` | Current. | March 2026 | `shadcn@4.1.2` | Soft, ambient, gradient-friendly. SaaS-modern. | | `"sera"` | Current. | April 2026 | `shadcn@4.3.0` | Typography-first. Print-design principles. Underline controls, uppercase headings. | ### Immutability of `style` The `style` field is set once at `init` and is operationally **immutable** : - The CLI provides NO documented `--style-switch` or migration command. - Manually editing `components.json#style` does NOT retroactively re-style already-installed components (they were copied with the OLD style's classes / variants baked in). - The only correct "style switch" is : full re-init + re-add of every component and block + manual reconciliation of any local customisations. ALWAYS treat `style` as a one-time architectural decision. NEVER attempt to mix styles within a project. ## registry.json : block discriminator Verified at https://ui.shadcn.com/docs/registry. The `registry.json` schema (used by anyone publishing a custom registry) accepts a `type` discriminator on each registry item : ```json { "name": "my-dashboard", "type": "registry:block", "registryDependencies": ["sidebar", "data-table", "card"], "files": [ { "path": "app/dashboard/page.tsx", "type": "registry:page", "target": "app/dashboard/page.tsx" }, { "path": "components/dashboard/nav.tsx", "type": "registry:component", "target": "components/dashboard/nav.tsx" } ] } ``` ### `type` values observed in registry items | Value | Use | |-------|-----| | `registry:ui` | A primitive component going into `components/ui/`. | | `registry:component` | A composed component (not a primitive). | | `registry:block` | A multi-file scaffold (page + sub-components). | | `registry:page` | An individual page file inside a block. | | `registry:lib` | A library helper (e.g. `lib/utils.ts`). | | `registry:hook` | A custom hook. | | `registry:theme` | A theme override file. | | `registry:style` | A style preset. | Consumers do NOT supply these values ; the registry publisher does. The CLI reads them to decide where to copy files. ALWAYS see [shadcn-core-registry](../../shadcn-core-registry/SKILL.md) for the full schema. ## CLI version checks Verify the installed CLI version before installing a block that depends on a recent style : ```bash pnpm dlx shadcn@latest --version # expected : 4.7.0 or newer as of 2026-05-19 ``` | Feature | Minimum CLI | |---------|-------------| | Block install (`add <block-id>`) | `shadcn@3.x` and later | | `sera` style | `shadcn@4.3.0` | | `luma` style | `shadcn@4.1.2` | | `--dry-run` flag | `shadcn@4.0.0` | | `--diff` flag | `shadcn@4.0.0` | | `--view` flag | `shadcn@4.0.0` | | Package imports / `files.target` aliases | `shadcn@4.7.0` | ALWAYS bump the CLI before installing a block from a recent style. NEVER assume an older CLI handles the modern style enum values. ## Sources - https://ui.shadcn.com/docs/cli (verbatim flag list) - https://ui.shadcn.com/docs/components-json (style enum and schema) - https://ui.shadcn.com/docs/registry (registry item type discriminator) - https://ui.shadcn.com/docs/changelog (style introduction dates and CLI version gates) - https://ui.shadcn.com/blocks (gallery and per-block file inventory) Verified 2026-05-19.

`SKILL.md`

---
name: shadcn-core-blocks
description: >
  Use when scaffolding a full page (dashboard, login, signup, sidebar layout,
  calendar app), bootstrapping a starter template from shadcn's gallery,
  evaluating block vs hand-composed components, choosing between the
  default / new-york / sera / luma styles, or recovering after a `shadcn add
  <block>` rerun overwrote local customisations.
  Prevents six common block-system failures : treating blocks as immutable
  starter templates (they are owned code, edit freely), running `shadcn add
  <block>` over a customised copy without `--diff` and losing work, mixing
  multiple style enum values inside one project, importing block
  sub-components from package paths instead of the local copied location,
  expecting blocks to auto-update when shadcn ships new revisions, and
  conflating blocks with components in CLI invocation when they accept
  different mental models for ownership and customisation.
  Covers the blocks distribution surface (a separate gallery at
  /blocks distinct from /components), block category landscape (dashboard,
  sidebar, login, signup, calendar, authentication), the block-add CLI
  flow (same `shadcn add` command, multi-file output), the style enum
  values (default, new-york, sera Apr 2026, luma Mar 2026) and when to
  choose each, the post-add ownership model, and the block-versus-component
  decision logic for whole-page versus building-block scope.
  Keywords: shadcn blocks, scaffold dashboard, starter template, shadcn
  full page, what is a block, block vs component, npx shadcn add dashboard,
  sidebar-07, dashboard-01, login-03, login-04, blocks gallery,
  ui.shadcn.com/blocks, page template, layout starter, multi-file block,
  block customisation, style enum, new-york style, default style,
  sera style, luma style, typographic style, shadcn full app shell,
  scaffold an admin panel, blank dashboard, copy paste page, page section,
  pre-built layout, how do I get a dashboard, how do I add a login page,
  shadcn template, opinionated starter, free open source blocks.
license: MIT
compatibility: "Designed for Claude Code. Requires shadcn ui evergreen-2026."
metadata:
  author: OpenAEC-Foundation
  version: "1.0"
---

# shadcn ui : Core Blocks

Blocks are shadcn's whole-page distribution surface. They are NOT a separate technology from components : they are multi-file scaffolds copied into the consumer project via the same `shadcn add` CLI, governed by the same ownership doctrine. ALWAYS treat a block as a starting point for a page, NEVER as an immutable template.

## Quick Reference

### Block in one sentence

ALWAYS describe a block as : a **multi-file composition of shadcn components, copied into the consumer project as owned source code, that delivers a complete page or large UI surface (dashboard, login page, sidebar shell)**. Components are building bricks ; blocks are pre-stacked walls.

The blocks gallery is its own surface : https://ui.shadcn.com/blocks (distinct from https://ui.shadcn.com/components). Verified verbatim from the gallery : "Clean, modern building blocks. Copy and paste into your apps. Works with all React frameworks. Open Source. Free forever."

### Four invariants

1. ALWAYS install a block with `pnpm dlx shadcn@latest add <block-id>` (or `npx`, `bunx`, `yarn dlx`). The CLI command is IDENTICAL to component install ; the block-id (e.g. `dashboard-01`, `sidebar-07`, `login-03`) signals the multi-file scaffold.
2. ALWAYS expect MULTIPLE files to be written when adding a block (page entry + sub-components + data file). NEVER assume a block is a single file like a component.
3. ALWAYS run `shadcn add <block-id> --diff` before re-running on an already-customised block. NEVER `--overwrite` blind ; the block is your code now.
4. ALWAYS pick ONE style enum value per project at `init` time and keep it. NEVER mix `new-york` and `sera` and `luma` blocks in the same project ; visual coherence breaks.

### Block versus component : decision in one line

ALWAYS choose a BLOCK when the unit of work is a whole page or major layout shell. ALWAYS choose individual COMPONENTS when composing a custom layout from scratch or extending an existing page with one new control.

## Decision Tree 1 : Block or hand-composed components?

```
Q1. Do you need a whole-page surface (login page, full dashboard, sidebar shell, calendar app)?
    no  → ALWAYS hand-compose with individual components. See shadcn-core-cli.
    yes → Q2

Q2. Does the shadcn blocks gallery offer a category that matches?
    Categories observed at /blocks (verified 2026-05-19) :
      dashboard, sidebar, login, signup, authentication, calendar
    no  → ALWAYS hand-compose ; do NOT force-fit an unrelated block
    yes → Q3

Q3. Will the team customise the layout heavily (rearrange sections, swap data sources)?
    yes → ALWAYS use the block as a starter, then edit freely (Open Code pillar)
    no  → ALWAYS use the block as-is, but still commit it as project source
```

## Decision Tree 2 : Which style enum value?

The `style` field in `components.json` selects the visual character of every component and block copied into the project. It is set at `init` time and is **immutable** after init.

```
Q1. Is this a NEW project being initialised in 2026?
    no  → ALWAYS keep the existing `style` value. NEVER edit it post-init.
    yes → Q2

Q2. What visual character does the design language need?
    typography-driven, editorial, print-design feel
                                   → ALWAYS choose `sera` (introduced Apr 2026,
                                     CLI >= 4.3.0). Underline controls, uppercase
                                     headings, typographic emphasis.
    soft, ambient, gradient-friendly, modern SaaS feel
                                   → ALWAYS choose `luma` (introduced Mar 2026,
                                     CLI >= 4.1.2). Lighter visual weight.
    geometric, design-system-grade, the modern default
                                   → ALWAYS choose `new-york`. Tight radii,
                                     opinionated defaults. Recommended for
                                     most new projects.
    legacy compatibility with pre-2024 shadcn projects only
                                   → ALWAYS choose `default` (the original
                                     style ; deprecated for new work but
                                     retained for compatibility).
```

ALWAYS install blocks AFTER `init` so they inherit the chosen style. NEVER attempt to "switch style" mid-project by editing `components.json` ; the only correct switch is a full re-init + re-add of every component and block.

## Decision Tree 3 : Adding a block to the project

```
Q1. Has `pnpm dlx shadcn@latest init` been run (does `components.json` exist)?
    no  → ALWAYS run `init` first and choose `style`, `baseColor`,
          `cssVariables`, aliases. These are immutable.
    yes → Q2

Q2. Does the local copy of the block already exist (e.g. `app/dashboard/page.tsx` + `components/dashboard/...`)?
    no  → `pnpm dlx shadcn@latest add <block-id>` copies the full scaffold.
    yes → Q3 (re-install scenario)

Q3. Has the local copy been customised?
    no  → `pnpm dlx shadcn@latest add <block-id> --overwrite` is safe.
    yes → ALWAYS run `--diff` first, decide per file : skip, overwrite,
          or hand-merge. See `references/examples.md`.
```

## Decision Tree 4 : Did the block break after a rerun?

```
Q1. Did you re-run `shadcn add <block-id> --overwrite` and lose customisations?
    yes → ALWAYS recover from git. The local block files ARE your version control.
          See [shadcn-errors-cli-sync-mismatch] for the merge workflow.
    no  → Q2

Q2. Did the visual style suddenly look inconsistent across the page?
    yes → check whether multiple blocks installed at different times used
          different `style` values (highly unlikely if `components.json` is
          stable, but possible if `style` was edited manually). See
          `references/anti-patterns.md` anti-pattern 3.
    no  → Q3

Q3. Did an internal sub-component fail to import?
    yes → ALWAYS verify imports point at the LOCAL alias where the block was
          copied (e.g. `@/components/dashboard/...`), NOT at any external
          package path. See `references/anti-patterns.md` anti-pattern 4.
    no  → unrelated to blocks ; consult the component-specific error skill
```

## Patterns

### Pattern 1 : Block catalog overview

Verified at https://ui.shadcn.com/blocks (2026-05-19). The gallery groups blocks into categories. Headline examples observed :

| Category | Headline blocks (verified IDs) | Typical use |
|----------|-------------------------------|-------------|
| Dashboard | `dashboard-01` | Full admin / SaaS dashboard with sidebar, header, charts, data table |
| Sidebar | `sidebar-03`, `sidebar-07` | Standalone sidebar shells with various navigation patterns |
| Login | `login-03`, `login-04` | Authentication entry forms with branded layout |
| Signup | (gallery entry, verify current IDs at /blocks) | Signup / registration entry forms |
| Authentication | (gallery entry) | Broader auth flows (forgot password, two-factor, etc.) |
| Calendar | (gallery entry) | Calendar-centric layouts |

ALWAYS browse https://ui.shadcn.com/blocks before committing to a block-id ; the gallery is the canonical inventory. NEVER assume a block-id from memory or training data ; verify at install time.

### Pattern 2 : Block-add CLI flow

The CLI command is the SAME as for components ; the block-id is what signals a multi-file scaffold :

```bash
# component (single file output)
pnpm dlx shadcn@latest add button

# block (multi-file scaffold output)
pnpm dlx shadcn@latest add dashboard-01
```

After `add dashboard-01` the CLI typically copies :

- A page entry (e.g. `app/dashboard/page.tsx` on Next.js App Router projects).
- A folder of sub-components (e.g. `components/dashboard/`).
- Optionally a data file (e.g. `app/dashboard/data.json`) when the block demos data-driven UI.
- Any missing primitives the block depends on (e.g. `components/ui/sidebar.tsx`, `components/ui/data-table.tsx`).

The exact file list is documented per-block at the gallery preview. ALWAYS run `shadcn add <block-id> --dry-run` if uncertain about file output ; the dry-run prints the planned writes without touching disk. ALWAYS run `--view` to inspect a single file before installing.

For full CLI flag detail (`--overwrite`, `--diff`, `--dry-run`, `--view`, `--yes`, `--path`), see [shadcn-core-cli](../shadcn-core-cli/SKILL.md).

### Pattern 3 : Style enum (default / new-york / sera / luma)

Verified from https://ui.shadcn.com/docs/changelog (2026-05-19) :

| Style | Introduced | CLI minimum | Character |
|-------|-----------|-------------|-----------|
| `default` | Original (pre-2024) | any | Legacy. Deprecated for new projects. Retained for backward compatibility. |
| `new-york` | 2024 | any | Geometric, tight radii, design-system-grade. The conventional 2025-2026 choice. |
| `luma` | March 2026 | `shadcn@4.1.2` | Soft, ambient, gradient-friendly. SaaS-modern visual weight. |
| `sera` | April 2026 | `shadcn@4.3.0` | Typography-first. Built on print design principles. Underline controls, uppercase headings. |

The style is selected at `init` time :

```bash
pnpm dlx shadcn@latest init    # interactive prompt selects style
# or non-interactively :
pnpm dlx shadcn@latest init --style new-york
```

ALWAYS choose ONE style and keep it. NEVER mix styles within a project ; the visual language fragments because radii, spacing, and typographic defaults differ per style. The `style` field in `components.json` is **immutable** post-init in the operational sense : the CLI does not provide a switch command, and any attempt to edit it manually leaves the already-installed components in the OLD style.

### Pattern 4 : Customisation after add (ownership reinforcement)

Blocks inherit the **Open Code** pillar from `shadcn-core-architecture`. After `pnpm dlx shadcn@latest add dashboard-01` the consumer owns every file copied. Five concrete obligations :

1. ALWAYS commit every block file (`app/dashboard/page.tsx`, `components/dashboard/*`, data files) to source control as first-class application code.
2. ALWAYS lint and type-check block files together with the rest of the codebase.
3. ALWAYS expect re-adding the block to be a MANUAL merge operation, not an automatic upgrade.
4. ALWAYS feel free to delete or refactor any sub-component shipped with the block ; if the dashboard sidebar is irrelevant, remove its file.
5. ALWAYS prefer editing the block files in place over wrapping them in further indirection. Wrapper components defeat the Open Code pillar.

### Pattern 5 : Block and component composition

Blocks and components compose without friction. A common pattern : install a block for the page shell, then drop hand-composed components into the body slot.

```tsx
// app/dashboard/page.tsx (copied from `dashboard-01` block, then customised)
import { SidebarProvider, SidebarInset } from "@/components/ui/sidebar"
import { AppSidebar } from "@/components/dashboard/app-sidebar"   // block sub-component
import { CustomMetricsPanel } from "@/components/metrics-panel"   // hand-built component

export default function DashboardPage() {
  return (
    <SidebarProvider>
      <AppSidebar />
      <SidebarInset>
        <CustomMetricsPanel />
      </SidebarInset>
    </SidebarProvider>
  )
}
```

ALWAYS treat a block as the page skeleton and components as the organs inside it. NEVER feel obliged to keep block sub-components untouched ; they are owned code and can be replaced wholesale.

### Pattern 6 : Block vs custom-registry relationship

Blocks live in the default `@shadcn` registry alongside components. The `registry.json` schema (see [shadcn-core-registry](../shadcn-core-registry/SKILL.md)) accepts a `type` discriminator that identifies the registry item as a block (`registry:block`) or a component (`registry:ui`, `registry:lib`, etc.). The CLI uses this discriminator internally to decide how to copy files. Consumers do NOT supply the type ; the registry does.

Custom registries (private internal design systems) CAN publish their own blocks by setting `type: "registry:block"` on registry items. ALWAYS see [shadcn-core-registry](../shadcn-core-registry/SKILL.md) for the full schema. NEVER hand-edit registry JSON files in the consumer project ; the registry is the publisher's surface, not the consumer's.

### Pattern 7 : Versioning quirks specific to blocks

Blocks depend on specific components (a dashboard block depends on Sidebar, DataTable, Card, etc.). When the shadcn project ships a new version of an underlying component, the block may quietly depend on the new API surface. Implications :

- ALWAYS pin the working state of block files in git immediately after `add`. The committed source IS the version.
- ALWAYS verify breaking changes via https://ui.shadcn.com/docs/changelog BEFORE re-adding a block (especially after a Calendar v9 transition or cmdk drift incident).
- ALWAYS lock underlying runtime dependencies (`radix-ui`, `cva`, `tailwind-merge`, `react-day-picker`, `cmdk`, `lucide-react`) in `package.json` so that re-adding a block does not silently install a new major of an underlying primitive.

NEVER expect blocks to auto-upgrade. The ownership doctrine is non-negotiable.

## Anti-patterns (summary ; full catalogue in references/anti-patterns.md)

NEVER do these :

1. NEVER treat a block as an immutable starter template : a block is owned code and SHOULD be edited freely after `add`.
2. NEVER re-run `shadcn add <block-id> --overwrite` on a customised block without first running `--diff` : the overwrite is irreversible and loses work.
3. NEVER mix multiple `style` enum values in one project : visual coherence breaks because radii, spacing, and typography differ per style.
4. NEVER import a block sub-component from any path other than the local alias where it was copied (e.g. `@/components/dashboard/...`).
5. NEVER expect blocks to auto-update when shadcn ships new block revisions : they are local source ; upgrades are manual re-add + merge.

## Reference Links

- [references/methods.md](references/methods.md) : CLI signatures for `add`, registry-item `type` discriminator, exact style-enum values and minimum CLI versions
- [references/examples.md](references/examples.md) : dashboard block install, file-output expectations, customisation diff, style switch workaround, block + component composition
- [references/anti-patterns.md](references/anti-patterns.md) : five canonical anti-patterns with WHY each fails and the fix

## Companion Skills

- [shadcn-core-architecture](../shadcn-core-architecture/SKILL.md) : ownership doctrine reinforcement (blocks obey the same Open Code pillar)
- [shadcn-core-cli](../shadcn-core-cli/SKILL.md) : full CLI surface (`init`, `add`, `--diff`, `--overwrite`, `--dry-run`, `--view`)
- [shadcn-core-registry](../shadcn-core-registry/SKILL.md) : `registry.json` schema, `type: "registry:block"` discriminator
- [shadcn-core-theming](../shadcn-core-theming/SKILL.md) : how the style enum interacts with CSS variables and dark mode
- [shadcn-errors-cli-sync-mismatch](../../shadcn-errors/shadcn-errors-cli-sync-mismatch/SKILL.md) : recovering from accidental overwrite of customised blocks

## Sources

All claims in this skill trace to URLs in `SOURCES.md` :

- https://ui.shadcn.com/blocks (gallery inventory, categories, headline block IDs, verbatim tagline)
- https://ui.shadcn.com/docs/cli (the `add` command and its flags, identical for blocks and components)
- https://ui.shadcn.com/docs/changelog (style enum additions : `luma` March 2026, `sera` April 2026, CLI version gates)
- https://ui.shadcn.com/docs/components-json (style field semantics, immutability after init)
- https://ui.shadcn.com/docs/registry (registry item type discriminator)

Verified 2026-05-19.