shadcn-registry-first

Shadcn registry first

Darkmatter pays for the @shadcnblocks block registry and wires both it and the free @shadcn registry into the shadcn MCP. That means most common UI surfaces — heroes, navbars, footers, pricing tables, feature grids, dashboards, login screens, data tables — already exist as production-quality, accessible, themeable blocks you can install in one command. Reaching for them first is faster and produces better output than writing JSX from a blank file.

The default failure mode this skill corrects: an agent silently hand-rolls a hero or a pricing table that the registry already has, burning tokens and shipping something less polished. Before you write a new component from scratch, check whether the registry already carries it.

When to use

• Building a new marketing/landing section: hero, feature grid, CTA band, testimonial, logo cloud, footer, pricing.
• Building app chrome: navbar, sidebar, dashboard shell, settings panel.
• Building common interactive surfaces: forms, auth screens, data tables, command palettes, file upload, calendars, charts.
• Restyling or replacing an existing component where a cleaner registry block would do.
• The user says "add a X section", "build a Y page", "I need a Z component" and Z is a recognizable web UI pattern.

When NOT to use

• The component is genuinely domain-specific (e.g. a liquidity-range tick chart, a protocol-specific position card) — no general registry will carry it, so build it, ideally composing registry primitives.
• The project isn't React, or has no components.json with registries configured. Check first (see below); if nothing is configured, this skill doesn't apply.
• A tiny one-off element (a single styled button, a label) where installing a block is heavier than writing the line.
• You're editing an existing component's internals, not adding a new surface.

Workflow

1. Confirm registries are configured

Use the shadcn MCP get_project_registries tool (or read components.json). You want to see @shadcnblocks and/or @shadcn listed. If @shadcnblocks is present but the API key isn't resolving, see "Registry access" below — don't fall back to hand-rolling just because the key is missing; fix the key.

2. Search and shortlist at least three candidates

Use search_items_in_registries with the pattern you need, scoped to the configured registries. Search the thing, not keywords:

• search_items_in_registries(registries=["@shadcnblocks"], query="hero dark")
• search_items_in_registries(registries=["@shadcnblocks"], query="pricing toggle")
• search_items_in_registries(registries=["@shadcnblocks"], query="dashboard analytics")

@shadcnblocks is large (1000+ blocks); a search like "hero" returns hundreds. Narrow with a qualifier ("hero split", "hero video", "hero dark") and skim the descriptions — they're written to be skimmable and tell you layout, columns, and notable features.

From the results, pick at least three distinct candidates that each plausibly satisfy the brief. Favour genuine variety — different layouts, density, or visual emphasis — not three near-identical blocks. The point is to give the user a real choice, the same way you'd offer multiple font or palette options rather than deciding silently.

The search output can be very large. If a single call returns a giant truncated list, don't read the whole dump into your own context — delegate processing to an explore agent with Grep/Read over the saved tool-output file, or re-run with a tighter query.

3. Preview each candidate

For every shortlisted candidate, inspect what you're committing to:

• get_item_examples_from_registries — find the demo and its full source so you see the actual markup and props.
• view_items_in_registries — see the item's files, dependencies, and registry dependencies (other components it pulls in).

Confirm each fits the project's design system (theme tokens, fonts, radius). Many blocks assume the default shadcn theme; if the project overrides tokens (e.g. a terminal theme with --radius: 0), the block will adapt to those tokens, but check for hardcoded colors or rounded corners you'll need to reconcile.

4. Install all the variations

Get each add command with get_add_command_for_items and run it (typically bunx shadcn@latest add @shadcnblocks/<name>). This writes each component into the project's ui/components aliases and installs dependencies. Keep the variations isolated from each other — install them under clearly named files or a scratch directory so swapping or deleting one doesn't disturb the others.

5. Build a comparison surface

Always give the user a way to see the variations side by side and built, not just names in chat. Mirror the font-comparison pattern: render every variation on one screen, each clearly labelled, wired with the same representative content so the only difference is the block itself.

• Web app with routing (TanStack Router, Next): add a temporary route such as /compare/<feature> that imports and stacks all variations with a heading per option. Mark it clearly as throwaway (a // TODO: remove after selection comment) and make sure it bypasses any auth/boot gating so it's viewable.
• Component / Storybook: a gallery story rendering each variation in a row.
• Run the dev server and hand the user a working preview URL (e.g. the Tailscale-served dev URL for this environment). Don't ask them to imagine the result — let them look at it.

The comparison surface must build cleanly (lsp_diagnostics, check-types, and the project build) before you present it.

6. Let the user choose, then adapt the winner

Present the labelled options and the preview URL, and ask which to keep. Once they pick:

• Wire the winner to real data and routes, strip demo placeholder copy, reconcile theme mismatches, and remove parts you don't need.
• Delete the other variations and the temporary comparison surface so they don't rot in the codebase.

The win is starting from a polished, accessible structure and letting the user choose between real, built options — not shipping the first block you found or leaving lorem ipsum behind.

7. Audit

After settling on the winner and removing the rest, run the shadcn MCP get_audit_checklist and work through it (imports resolve, dependencies installed, no leftover demo data or comparison scaffolding, types clean). Then run the project's own checks (lsp_diagnostics, check-types, build).

Registry access

The @shadcnblocks registry requires an API key in the Authorization header of components.json. In darkmatter repos this is handled per-project:

• components.json is gitignored and carries the resolved key (or the shadcn MCP reads ${SHADCNBLOCKS_API_KEY} from the environment).
• components.json.template is committed with the ${SHADCNBLOCKS_API_KEY} placeholder.
• The key lives in the secret store (himitsu: himitsu read shadcnblocks-api-key, or a SOPS-encrypted secret). A small scripts/setup-components-json.ts renders the template with the key.

Before running any bunx shadcn command

The rendered components.json must exist and be fresh — a stale one from a previous session may carry an expired key. Always do these two steps first:

1. Build components.json: run bun scripts/setup-components-json.ts from the repo root. This reads the current key from himitsu and writes the gitignored components.json. Skip this and you'll get 401 auth failures.
2. cd into the app directory (e.g. apps/web/) before running bunx shadcn@latest add .... The CLI resolves registries from components.json in the current working directory. Running from the monorepo root will fail.
3. Use --overwrite flag to skip interactive prompts about existing files (utils.ts, button.tsx, etc.) that the block may depend on but already exist in the project.

Typical invocation:

# From repo root:
bun scripts/setup-components-json.ts
cd apps/web
bunx shadcn@latest add @shadcnblocks/hero253 --overwrite

If a registry call fails with a missing-env-var or auth error, the fix is to populate the key from the secret store — not to abandon the registry and hand-roll the component. See the sops-secret-access skill for the encrypted- config side of this and the expected secret-handling pattern.

Graduate stable pieces from the screen into the repo's shared UI package (name is per-repo; see ADR-0013).

Relationship to other skills

• sops-secret-access — how to access the encrypted registry config and keys. This skill is about preferring registry components; that one is about the plumbing to reach a private registry.
• ui-ux-pro-max — design intelligence (styles, palettes, layout, a11y). Use it to decide what good UI looks like; use this skill to source the components that realize it. They compose: pick the aesthetic with ui-ux-pro-max, then search the registry for blocks that match.
• vercel-react-best-practices — performance patterns for the React you write around and inside installed blocks.