shadcn-registry-first

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Shadcn registry first

优先使用Shadcn注册表

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.

Darkmatter 付费采购了

@shadcnblocks

块注册表，并将其与免费的

@shadcn

注册表一同接入shadcn MCP。这意味着大多数常见的UI界面——hero区、导航栏、页脚、定价表、功能网格、仪表盘、登录页、数据表——都已经有生产级质量、无障碍支持、可自定义主题的块组件，你只需一条命令即可安装。优先使用这些组件比从零编写JSX效率更高，输出质量也更好。

本技能旨在纠正的常见错误模式：Agent悄无声息地手动编写了注册表中已有的hero区或定价表组件，既消耗token，最终产出的完成度也更低。在从零编写新组件之前，请先检查注册表中是否已有对应组件。

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.

构建新的营销/落地页区块：hero区、功能网格、CTA栏、客户评价、logo墙、页脚、定价模块。
构建应用框架：导航栏、侧边栏、仪表盘外壳、设置面板。
构建常见交互界面：表单、认证页面、数据表、命令面板、文件上传、日历、图表。
对现有组件进行样式重设或替换，且注册表中有更简洁的块组件可满足需求。
用户提出“添加一个X区块”、“构建一个Y页面”、“我需要一个Z组件”，且Z是可识别的通用Web UI模式。

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.

组件是真正的特定领域组件（例如流动性区间tick图表、特定协议的持仓卡片）——通用注册表不会提供这类组件，因此需要自行构建，最好是基于注册表的基础组件组合实现。
项目不是React技术栈，或者没有配置注册表的
```
components.json
```
文件。请先检查（见下文）；如果没有配置任何注册表，本技能不适用。
极小的一次性元素（单个带样式的按钮、一个标签），安装块组件的成本比直接写代码更高。
你正在编辑现有组件的内部逻辑，而非添加新的界面模块。

Workflow

工作流程

1. Confirm registries are configured

1. 确认注册表已配置

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.

使用shadcn MCP的

get_project_registries

工具（或读取

components.json

文件），确认列表中包含

@shadcnblocks

和/或

@shadcn

。如果已配置

@shadcnblocks

但API密钥无法解析，请参阅下文的“注册表访问”部分——不要因为缺少密钥就退而求其次手动编写组件，先修复密钥问题。

2. Search and shortlist at least three candidates

2. 搜索并筛选至少三个候选组件

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.

使用

search_items_in_registries

工具，在已配置的注册表范围内搜索你需要的UI模式。要搜索具体的组件类型，而非零散关键词：

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

的体量很大（1000+块组件）；搜索“hero”这类关键词会返回数百条结果。可以通过限定词缩小范围（例如“hero split”、“hero video”、“hero dark”），然后快速浏览描述——这些描述设计得便于快速阅读，会说明布局、列数和核心特性。

从搜索结果中挑选至少三个不同的候选组件，每个都应能合理满足需求。优先选择真正有差异的方案——不同的布局、信息密度或视觉重点——而不是三个几乎一模一样的块。这样做的目的是给用户提供真实的选择，就像你会提供多种字体或配色方案供选择，而不是悄悄自己做决定。

搜索输出可能非常大。如果单次调用返回了被截断的超长列表，不要把整个输出都塞进你的上下文里——可以将处理工作委派给

explore

Agent，让它通过Grep/读取操作处理保存的工具输出文件，或者用更精准的查询重新运行搜索。

3. Preview each candidate

3. 预览每个候选组件

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.

对于每个入围的候选组件，都要检查清楚你将要引入的内容：

```
get_item_examples_from_registries
```
— 查找演示示例及其完整源码，这样你可以看到实际的标记结构和props。
```
view_items_in_registries
```
— 查看组件的文件、依赖项，以及注册表依赖（它会引入的其他组件）。

确认每个组件都适配项目的设计系统（主题token、字体、圆角半径）。很多块组件默认使用shadcn的默认主题；如果项目覆盖了token（例如设置了

--radius: 0

的终端主题），块组件会适配这些token，但仍需检查是否有硬编码的颜色或圆角需要调整。

4. Install all the variations

4. 安装所有变体

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.

使用

get_add_command_for_items

获取每个组件的安装命令并运行（通常是

bunx shadcn@latest add @shadcnblocks/<name>

）。这会将每个组件写入项目的

ui

components

别名路径，并安装依赖项。请让各个变体相互隔离——将它们安装在命名清晰的文件或临时目录下，这样替换或删除其中一个不会影响其他变体。

5. Build a comparison surface

5. 构建对比界面

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.

始终要让用户能够看到已构建好的、并排展示的变体，而不仅仅是聊天中的名称。参考字体对比的模式：将所有变体渲染在同一个页面上，每个都有清晰的标签，并且使用相同的代表性内容，这样唯一的区别就是块组件本身。

带路由的Web应用（TanStack Router、Next）：添加一个临时路由，例如
```
/compare/<feature>
```
，导入所有变体并堆叠展示，每个选项都有标题。明确标记这是临时内容（添加
```
// TODO: remove after selection
```
注释），并确保它绕过所有认证/启动拦截，以便可以直接访问。
组件 / Storybook：创建一个画廊式的story，将所有变体排成一行渲染。
运行开发服务器，给用户提供一个可访问的预览URL（例如本环境的Tailscale提供的开发URL）。不要让用户去想象效果——让他们直接看到实际效果。

在展示给用户之前，对比界面必须能够无错误构建（通过

lsp_diagnostics

、

check-types

检查，以及项目构建）。

6. Let the user choose, then adapt the winner

6. 让用户选择，然后适配选中的方案

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.

展示带标签的选项和预览URL，询问用户要保留哪一个。用户选定后：

将选中的组件接入真实数据和路由，移除演示占位文本，调整主题不匹配的地方，删除不需要的部分。
删除其他变体和临时对比界面，避免它们在代码库中遗留变质。

这样做的好处是从一个完善、无障碍的结构开始，让用户在真实的、已构建的选项中做选择——而不是直接交付你找到的第一个块，或者留下一堆占位文本。

7. Audit

7. 审计

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).

确定最终方案并删除其他内容后，运行shadcn MCP的

get_audit_checklist

并逐项检查（导入可解析、依赖已安装、无遗留的演示数据或对比脚手架、类型无错误）。然后运行项目自身的检查（

lsp_diagnostics

、

check-types

、构建）。

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.

@shadcnblocks

注册表需要在

components.json

的

Authorization

头中配置API密钥。在Darkmatter仓库中，这是按项目处理的：

```
components.json
```
被加入gitignore，包含解析后的密钥（或者shadcn MCP从环境变量中读取
```
${SHADCNBLOCKS_API_KEY}
```
）。
```
components.json.template
```
会被提交到仓库，其中包含
```
${SHADCNBLOCKS_API_KEY}
```
占位符。
密钥存储在密钥仓库中（himitsu：运行
```
himitsu read shadcnblocks-api-key
```
获取，或者是SOPS加密的密钥）。有一个小型脚本
```
scripts/setup-components-json.ts
```
会用密钥渲染模板。

Before running any

bunx shadcn

command

运行任何

bunx shadcn

命令之前

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:

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.
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.
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:

bash

undefined

渲染后的

components.json

必须存在且是最新的——上一次会话留下的旧文件可能包含已过期的密钥。请始终先执行以下两个步骤：

构建components.json：在仓库根目录运行
```
bun scripts/setup-components-json.ts
```
。这会从himitsu读取当前密钥，并写入被gitignore的
```
components.json
```
文件。跳过这一步会导致401认证错误。
运行
```
bunx shadcn@latest add ...
```
之前，cd
到应用目录（例如
```
apps/web/
```
）。CLI会从当前工作目录的
```
components.json
```
中解析注册表配置。从monorepo根目录运行会失败。
使用
--overwrite
标志，跳过关于项目中已存在的、块组件可能依赖的文件（
```
utils.ts
```
、
```
button.tsx
```
等）的交互式提示。

典型调用示例：

bash

undefined

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](../../docs/adr/0013-shared-ui-is-its-own-package.md)).

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


如果注册表调用因缺少环境变量或认证错误而失败，解决方法是从密钥仓库中填充密钥——而不是放弃使用注册表，手动编写组件。关于加密配置部分和预期的密钥处理模式，请参阅`sops-secret-access`技能。

将稳定的组件从临时界面迁移到仓库的共享UI包中（包名因仓库而异；参见[ADR-0013](../../docs/adr/0013-shared-ui-is-its-own-package.md)）。

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.

```
sops-secret-access
```
— 如何访问加密的注册表配置和密钥。本技能是关于优先使用注册表组件；而该技能是关于访问私有注册表的底层配置。
```
ui-ux-pro-max
```
— 设计能力（样式、配色、布局、无障碍）。用它来决定好的UI应该是什么样；用本技能来寻找实现该UI的组件。两者是互补的：用
```
ui-ux-pro-max
```
确定美学风格，然后在注册表中搜索匹配的块组件。
```
vercel-react-best-practices
```
— 你在已安装的块组件周围和内部编写的React代码的性能优化模式。

shadcn-registry-first

Original

Translation

Shadcn registry first

优先使用Shadcn注册表

When to use

适用场景

When NOT to use

不适用场景

Workflow

工作流程

1. Confirm registries are configured

1. 确认注册表已配置

2. Search and shortlist at least three candidates

2. 搜索并筛选至少三个候选组件

3. Preview each candidate

3. 预览每个候选组件

4. Install all the variations

4. 安装所有变体

5. Build a comparison surface

5. 构建对比界面

6. Let the user choose, then adapt the winner

6. 让用户选择，然后适配选中的方案

7. Audit

7. 审计

Registry access

注册表访问

Before running any
`bunx shadcn`
command

运行任何
`bunx shadcn`
命令之前

From repo root:

From repo root:

Relationship to other skills

与其他技能的关系

shadcn-registry-first

Original

Translation

Shadcn registry first

优先使用Shadcn注册表

When to use

适用场景

When NOT to use

不适用场景

Workflow

工作流程

1. Confirm registries are configured

1. 确认注册表已配置

2. Search and shortlist at least three candidates

2. 搜索并筛选至少三个候选组件

3. Preview each candidate

3. 预览每个候选组件

4. Install all the variations

4. 安装所有变体

5. Build a comparison surface

5. 构建对比界面

6. Let the user choose, then adapt the winner

6. 让用户选择，然后适配选中的方案

7. Audit

7. 审计

Registry access

注册表访问

Before running any bunx shadcn command

运行任何bunx shadcn命令之前

From repo root:

From repo root:

Relationship to other skills

与其他技能的关系

Before running any
`bunx shadcn`
command

运行任何
`bunx shadcn`
命令之前