new-api 前端 shadcn/ui 技能（Skill）实战：components.json、CLI、主题与 MCP 全景

new-api 前端 shadcn/ui 技能（Skill）实战：components.json、CLI、主题与 MCP 全景

【免费下载链接】new-apiAI模型聚合管理中转分发系统，一个应用管理您的所有AI模型，支持将多种大模型转为统一格式调用，支持OpenAI、Claude、Gemini等格式，可供个人或者企业内部管理与分发渠道使用。🍥 A Unified AI Model Management & Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api

本篇技术指南围绕仓库中.agents/skills/shadcn-ui/目录下的shadcn-ui技能展开，讲解它是如何让 AI 助手在 new-api 的前端（web应用，基于 Bun + Tailwind v4 + shadcn/ui）中"读懂项目、一次写对代码"的。你将学会如何用它的项目上下文探测（shadcn info --json）、如何查阅 CLI 命令、如何按 CSS 变量体系定制主题、如何接入 shadcn MCP 服务器，以及如何组织 vendored 上游规则来做具体 markup 校验。读完后你能够独立在该前端项目中查找、安装、组合和定制 shadcn 组件，并复现本文给出的可运行命令与真实配置。

技能（Skill）的定位：给 AI 助手注入"项目感知"的 shadcn 上下文

所谓 shadcn "Skill"，本质是一份写给 AI 助手的"项目感知上下文"。它解决的问题是：当你在 new-api 前端里让助手"加一个带邮箱和密码字段的登录表单""做一个带侧边栏、统计卡片和数据表格的仪表盘""把样式切换到某个 preset"时，助手必须先知道当前项目用了哪个框架、哪个别名校、装了哪些组件、图标库是什么、基础库是 radix 还是 base，才能第一次就生成正确的导入路径和 API 调用。

技能的工作方式可以概括为四个环节（摘自 SKILL.md 的 "How it works"）：

1. 项目检测（Project detection）——仅当components.json存在时生效；在 new-api 中对应 web/components.json。
2. 上下文注入（Context injection）——以shadcn info --json的输出作为"唯一事实来源"（ground truth），用于确定导入与 API。
3. 模式约束（Pattern enforcement）——用vendor/shadcn/rules/下的规则文件做具体的 markup 校验；更完整的官方 CLI / registry / preset 工作流见 workflow 参考文档。
4. 组件发现（Component discovery）——通过shadcn docs、shadcn search、MCP 或 registry 查找组件。

技能还给出了几类典型的自然语言触发示例，帮助理解它的适用范围：

• "Add a login form with email and password fields."（加一个登录表单）
• "Create a settings page with a form for updating profile information."（做一个资料设置页）
• "Build a dashboard with a sidebar, stats cards, and a data table."（做一个仪表盘）
• "Switch to --preset [CODE]"（切换 preset）
• "Can you add a hero from @tailark?"（从某个 registry 添加组件）

技能会读取项目的components.json，据此提供框架、别名、已安装组件、图标库和基础库，从而"第一次就写对代码"。

安装与运行：生态安装 vs 本仓库约定

SKILL.md 区分了两种"安装方式"，这一点在 new-api 里尤其重要：

• 官方生态安装：npx skills add shadcn/ui，它会安装到skillsCLI 可用的地方。
• 本仓库约定：同一个意图被收进.agents/skills/shadcn-ui/（本概览文档 + vendored 上游文档），并从前端应用根目录运行 shadcn CLI：

cd web && bunx shadcn@latest info --json

注意两点仓库事实：其一，new-api 前端使用Bun作为包运行器，所以命令前缀是bunx而非npx；其二，shadcn 的所有命令都必须在web/目录下执行，因为components.json位于前端根目录。这一点由 SKILL.md 结尾的 Workflow 提示明确强调："Prefer this root SKILL.md for repo paths (web, Bun)”。

vendored 上游文档快照的来源记录在 UPSTREAM.txt，其中注明了抓取的上游提交与抓取日期（2026-04-29），并特别说明：上游的SKILL.md被重存为official-shadcn-ui-workflow.md，且去掉了原来的 frontmatter，以避免 vendored 副本被当作第二个本地技能发现。

项目上下文：用真实components.json读懂 new-api 前端

shadcn info --json会把components.json解析成结构化上下文。下面结合 new-api 前端的真实配置文件 web/components.json 逐项说明这些字段在这个项目里具体是什么值：

{ "style": "base-nova", "rsc": false, "tsx": true, "tailwind": { "config": "", "css": "src/styles/index.css", "baseColor": "neutral", "cssVariables": true, "prefix": "" }, "iconLibrary": "hugeicons", "aliases": { "components": "@/components", "utils": "@/lib/utils", "ui": "@/components/ui", "lib": "@/lib", "hooks": "@/hooks" }, "menuColor": "inverted", "menuAccent": "subtle", "registries": { "@ai-elements": "https://registry.ai-sdk.dev/{name}.json" } }

从这份真实配置可以读出 new-api 前端的 shadcn 项目画像：

• style: "base-nova"：视觉风格为base-nova（注意 CLI 文档中style字段的取值示例为nova、vega，而这里带base-前缀，反映的是"基于 base 库的 nova 风格"）。
• rsc: false/tsx: true：未启用 React Server Components，但使用 TypeScript。
• tailwind.config: ""且cssVariables: true：这是 Tailwind v4 的"CSS 优先"配置形态——不再依赖独立的tailwind.config.js，而是把主题变量写在全局 CSS 里。全局 CSS 文件为 src/styles/index.css（相对web/根）。
• iconLibrary: "hugeicons"：图标库为 HugeIcons，助手生成图标导入时须用它，而不是默认假设的lucide-react。
• aliases：确定了导入路径约定——组件在@/components、UI 组件在@/components/ui、工具函数在@/lib/utils、hooks 在@/hooks。助手"第一次写对"的关键就在于按这套别名生成 import。
• menuColor: "inverted"/menuAccent: "subtle"：额外的菜单配色定制项。
• registries["@ai-elements"]：注册了自定义 registry，指向https://registry.ai-sdk.dev/{name}.json。这说明 new-api 前端除了内置@shadcnregistry 外，还能从 AI SDK 的 registry 拉取组件（下文 MCP 章节会讲 registry 的配置规则）。

CLI 文档把shadcn info的输出字段整理成三类（见 cli.md）：

• Project Info 字段：framework、frameworkVersion、isSrcDir、isRSC、isTsx、tailwindVersion（"v3"/"v4"）、tailwindConfigFile、tailwindCssFile、aliasPrefix、packageManager。
• Components.json 字段：base（radix或base，决定组件 API 与可用 props）、style、rsc、tsx、tailwind.config、tailwind.css（自定义 CSS 变量所在文件）、iconLibrary、各aliases.*、resolvedPaths（每个别名的绝对路径）、registries。
• Links 字段：组件文档 / 源码 / 示例的模板化 URL；需要解析后的真实 URL 时应改用shadcn docs <component>。

实践建议：在动手改任何组件前，先在web/里跑一次bunx shadcn@latest info，把它当作"项目的 ground truth"，避免助手凭默认假设写错导入路径或图标包。

CLI 命令参考：init / apply / add / search / view / docs / info / build

new-api 仓库 vendored 了一份完整的 CLI 参考（cli.md）。下面提炼最关键的几条命令与约束，命令前缀在本仓库应替换为bunx shadcn@latest并在web/下运行。

运行器约定（CLI 文档的两条 IMPORTANT）

• 始终用项目自己的包运行器：npx shadcn@latest、pnpm dlx shadcn@latest、bunx --bun shadcn@latest。new-api 用 Bun，故用bunx。
• 只使用文档中列出的 flag，不要臆造 flag；CLI 会从 lockfile 自动检测包管理器，没有--package-manager这个 flag。

核心命令速览

init的关键 flag（摘自 CLI 文档表格）

npx shadcn@latest create是init的别名。

add的 dry-run 与 smart merge（重点）

CLI 文档反复强调：要对比本地组件与上游、或预览改动时，必须用add --dry-run、--diff、--view，绝不手动去 GitHub 或其他源抓原始文件——CLI 会自动处理 registry 解析、文件路径与 CSS diff。

# 预览所有改动（不写文件） bunx shadcn@latest add button --dry-run # 显示所有文件的 diff（默认前 5 个） bunx shadcn@latest add button --diff # 只显示某个文件的 diff bunx shadcn@latest add button --diff button.tsx # 查看某个文件的完整内容 bunx shadcn@latest add button --view button.tsx # 查看 CSS 会怎么变 bunx shadcn@latest add button --diff globals.css

文档还特别区分了add --dry-run与view：当用户想"预览对我项目会有何影响"时，优先用add --dry-run/--diff/--view（它会给出解析后的文件路径、相对现有文件的 diff、CSS 更新）；只有当用户想在无项目上下文下浏览 registry 信息时，才用view。

模板与 preset

模板支持表（摘自 CLI 文档）：next、vite、start（TanStack Start）、react-router、astro、laravel，除 Laravel 外均支持 monorepo 脚手架（通过--monorepo）。

preset 有三种指定方式：

1. 命名：--preset nova或--preset lyra
2. code：--preset a2r6bw（带版本前缀的 base62 字符串，如a2r6bw或b0）
3. URL：--preset "https://ui.shadcn.com/init?base=radix&style=nova&..."

两条强约束：preset code 是不透明的，绝不要试图手动解码 / 抓取 / 解析它，直接传给 CLI 让它解析即可；切换已有项目 preset 用apply --preset <code>。

切换 preset 的三选一（先问用户）：

• Overwrite / Re-install→apply --preset <code>，用新 preset 样式覆盖所有被检测到的组件文件。适用于用户没自定义组件时。
• Merge→init --preset <code> --force --no-reinstall，再info拿到已装组件列表，逐一走 smart merge 更新并保留本地改动。适用于用户已自定义组件。
• Skip→init --preset <code> --force --no-reinstall，只更新 config 与 CSS 变量，保留现有组件不动。

preset 命令必须在用户项目目录内运行；apply只对有components.json的已有项目生效；CLI 会自动从components.json保留当前 base（basevsradix）。若必须在临时目录（如做 dry-run 对比）使用，需显式传--base <current-base>，因为 preset code 并不编码 base。

主题与定制：CSS 变量 → Tailwind 工具类 → 组件

new-api 前端用 Tailwind v4（由 web/components.json 的空tailwind.config+cssVariables: true印证），其主题定制遵循 vendored 的 customization.md 描述的三层链路：

1. CSS 变量定义在:root（亮色）与.dark（暗色）里；
2. Tailwind 把它们映射成工具类：bg-primary、text-muted-foreground等；
3. 组件使用这些工具类——改一个变量，所有引用它的组件随之改变。

颜色变量命名约定：每个颜色遵循name/name-foreground约定，基础变量用于背景，-foreground用于其上的文字 / 图标。常用变量包括--background/--foreground（页面背景与默认文字）、--card、--primary（主按钮与主操作）、--secondary、--muted（弱化 / 禁用态）、--accent（悬停与强调态）、--destructive（错误与破坏性操作）、--border、--input（表单输入边框）、--ring（聚焦环）、--chart-1~--chart-5（图表）、--sidebar-*、--surface。

颜色格式为 OKLCH：例如--primary: oklch(0.205 0 0)，三元组依次是亮度（0–1）、色度（0=灰）、色相（0–360）。

暗色模式：通过在根元素上切换.dark类实现 class 策略。在 Next.js 中通常用next-themes的ThemeProvider（attribute="class"+defaultTheme="system"+enableSystem）。new-api 前端非 Next.js（rsc: false、Vite/Rsbuild 体系），因此暗色切换的落点在其全局 CSS 与运行时主题逻辑上，但.darkclass 机制与语义变量体系完全一致。

改主题的两种方式

# 用 preset code 应用（覆盖式） bunx shadcn@latest apply --preset a2r6bw # 位置参数简写同样可用 bunx shadcn@latest apply a2r6bw # 切换命名 preset 并覆盖现有组件 bunx shadcn@latest apply --preset nova # 保留现有组件不覆盖 bunx shadcn@latest init --preset nova --force --no-reinstall

或者直接编辑全局 CSS 变量——在 new-api 中即 src/styles/index.css。

添加自定义颜色（三步）

文档强调：自定义颜色要加到shadcn info中tailwindCssFile指向的文件（new-api 即src/styles/index.css），不要为此新建 CSS 文件。

/* 1. 在全局 CSS 文件里定义 */ :root { --warning: oklch(0.84 0.16 84); --warning-foreground: oklch(0.28 0.07 46); } .dark { --warning: oklch(0.41 0.11 46); --warning-foreground: oklch(0.99 0.02 95); }

/* 2a. Tailwind v4：用 @theme inline 注册 */ @theme inline { --color-warning: var(--warning); --color-warning-foreground: var(--warning-foreground); }

若tailwindVersion是"v3"（先用shadcn info确认），则改为在tailwind.config.js的theme.extend.colors里注册：

module.exports = { theme: { extend: { colors: { warning: "oklch(var(--warning) / <alpha-value>)", "warning-foreground": "oklch(var(--warning-foreground) / <alpha-value>)", }, }, }, }

// 3. 在组件里使用 <div className="bg-warning text-warning-foreground">Warning</div>

由于 new-api 前端是 Tailwind v4，走的是2a 的@theme inline路径。

圆角：--radius全局控制圆角，组件从它派生（rounded-lg=var(--radius)，rounded-md=calc(var(--radius) - 2px)）。

定制组件的优先顺序（文档给出 4 级策略）：

1. 内置 variants：<Button variant="outline" size="sm">
2. Tailwind 类经className：<Card className="mx-auto max-w-md">
3. 新增一个 variant：编辑组件源码，用cva加一个 variant（如warning: "bg-warning text-warning-foreground hover:bg-warning/90"）
4. 封装 wrapper 组件：把 shadcn 原语组合成更高层组件，例如用AlertDialog系列封装出ConfirmDialog。

shadcn MCP 服务器：让助手跨 registry 检索与安装

new-api 仓库 vendored 的 mcp.md 描述了 CLI 内置的 MCP 服务器——它让 AI 助手能搜索、浏览、查看并安装来自各 registry 的组件。

启动与编辑器接入

shadcn mcp # 启动 MCP 服务器（stdio） shadcn mcp init # 为你的编辑器写配置

关键区分：MCP 工具负责registry 操作（search / view / install）；而项目配置（别名、框架、Tailwind 版本）请用shadcn info——MCP 没有对应工具。

MCP 工具清单

registry 配置：registry 在components.json里设置，内置@shadcn始终存在。配置格式：

{ "registries": { "@acme": "https://acme.com/r/{name}.json", "@private": { "url": "https://private.com/r/{name}.json", "headers": { "Authorization": "Bearer ${MY_TOKEN}" } } } }

规则：名字必须以@开头；URL 必须包含{name}；${VAR}会从环境变量解析。new-api 前端的 web/components.json 正是一个真实实例——它注册了@ai-elements指向https://registry.ai-sdk.dev/{name}.json，说明这套 registry 机制在该项目里是实际启用的能力。

vendored 上游规则包：具体 markup 校验的"检查清单"

SKILL.md 把 vendored 上游文档组织成一棵结构清晰的树（路径相对本仓库根）：

上游快照来源与提交信息见 UPSTREAM.txt。

使用这些文档的分工（摘自 SKILL.md 结尾 Workflow）：

• 优先读根SKILL.md来获取仓库路径（web、Bun）；
• 只有当你需要完整的官方组件 / registry / preset 工作流时，才读vendor/shadcn/official-shadcn-ui-workflow.md；
• 当你要校验具体 markup（表单写法、组件组合、图标用法、样式、base 与 radix 的差异）时，用vendor/shadcn/rules/*.md。

rules/下的每篇规则都给出"错误写法 / 正确写法"的对照，是助手落地生成代码前的最后一道约束。例如 Styling 规则与 customization 文档互相引用，帮助判断"改主题该动 CSS 变量还是该加 variant"。

小结：在 new-api 前端使用 shadcn 技能的标准动作

把上面的证据串起来，在 new-api 前端（web/，Bun + Tailwind v4 + shadcn，base-nova风格，图标库 hugeicons）使用这套技能时，推荐的操作序列是：

1. 进入web/，运行bunx shadcn@latest info拿到项目 ground truth（框架、别名、Tailwind 版本、已装组件）。
2. 依据 web/components.json 的aliases生成正确的导入路径（@/components/ui、@/lib/utils等），图标导入走 hugeicons。
3. 添加 / 更新组件时一律用add --dry-run/--diff/--view预览，不手动抓上游文件。
4. 改主题时改src/styles/index.css里的 OKLCH 语义变量（Tailwind v4 用@theme inline注册自定义色），而不是新建 CSS 文件。
5. 需要跨 registry（含本项目注册的@ai-elements）检索 / 安装时，用 MCP 工具或search/view/docs。
6. 校验具体 markup 前，对照vendor/shadcn/rules/下对应规则；涉及完整 preset / registry 工作流再翻official-shadcn-ui-workflow.md。

这套技能的价值，不在于"再造一遍 shadcn 文档"，而在于把"项目感知"固化下来——让 AI 助手在 new-api 前端里第一次就生成符合项目别名、图标库、Tailwind 版本与 preset 约定的正确代码，同时为 vendored 上游规则保留了做具体校验的权威依据。

【免费下载链接】new-apiAI模型聚合管理中转分发系统，一个应用管理您的所有AI模型，支持将多种大模型转为统一格式调用，支持OpenAI、Claude、Gemini等格式，可供个人或者企业内部管理与分发渠道使用。🍥 A Unified AI Model Management & Distribution System. Aggregate all your LLMs into one app and access them via an OpenAI-compatible API, with native support for Claude (Messages) and Gemini formats.项目地址: https://gitcode.com/QuantumNous/new-api