stitch-shadcn-ui

用途

stitch-shadcn-ui 是一个前端工程技能，用于指导开发者集成和构建基于 shadcn/ui 的应用。当用户询问 shadcn/ui、Stitch + React + shadcn，或使用 shadcn 组件构建 React UI 时适用。该技能定位为专注于 shadcn/ui 的前端工程师——处理可复用、可访问、可定制的组件（基于 Radix UI 或 Base UI + Tailwind），帮助发现、安装、定制和扩展组件，并遵循最佳实践。

核心原则

shadcn/ui 不是传统意义上的库——组件是被复制进你的项目中的：

• 完全所有权：代码存在于你的仓库中，而非 node_modules。
• 完全定制：样式、行为和结构均由你掌控。
• 无版本锁定：由你决定何时更新组件。
• 零运行时开销：不增加额外打包体积，只包含你添加的代码。

主要能力

组件发现与安装

• 列出组件：使用 shadcn MCP 的 list_components（或浏览 ui.shadcn.com）。
• 安装（推荐）：npx shadcn@latest add [component-name]。该命令会下载源码、安装依赖、将文件放入 components/ui/，并更新 components.json。
• 手动方式：使用 MCP 的 get_component 获取源码；创建 components/ui/[name].tsx；安装对等依赖。

项目设置

• 新项目：npx shadcn@latest create（可配置 style、baseColor、RSC 等）。
• 已有项目：npx shadcn@latest init → 创建 components.json，包含：
  • style：default、new-york（classic），或更新的视觉风格（Vega、Nova、Maia、Lyra、Mira）。
  • baseColor：slate、gray、zinc、neutral、stone。
  • cssVariables、tailwind 路径、别名、rsc（React Server Components）、rtl（可选）。
• 依赖：React 18+、Tailwind 3+、Radix UI 或 Base UI、class-variance-authority、clsx、tailwind-merge。

自定义注册表（可选）

对于自定义或第三方注册表（在 components.json 中定义）：使用 MCP 的 get_project_registries、list_items_in_registries、view_items_in_registries、search_items_in_registries 来发现和安装组件。

架构

• 文件结构：src/components/ui/ 用于 shadcn 组件；src/components/[custom]/ 用于你组合的组件。
• cn() 工具：所有 shadcn 组件使用 cn()（clsx + tailwind-merge）进行类名合并；保留 lib/utils.ts 中的该辅助函数。

定制

• 主题：编辑 Tailwind 配置和 globals.css 中的 CSS 变量（:root 和 .dark）。
• 变体：使用 cva 处理变体逻辑（例如 button 的 variant/size）。
• 包装器：在 components/（而非 components/ui/）中创建包装组件来扩展 shadcn 组件。

Blocks 与复杂组件

shadcn 提供 blocks（auth、dashboard、sidebar 等）：使用 MCP 的 list_blocks、get_block 获取并安装。Blocks 按类别组织（例如 calendar、dashboard、login、sidebar、products）。

验证与质量（与官方对齐）

提交组件前：

• 类型检查：运行 tsc --noEmit。
• Lint：运行项目 linter。
• 无障碍：使用 axe DevTools 等工具。
• 视觉 QA：测试浅色和深色模式。
• 响应式：在不同断点验证。

无障碍

组件使用 Radix 原语：键盘导航、ARIA、焦点管理。定制时，需保留 ARIA、键盘处理器和焦点指示器。

与 Stitch 集成

• 使用 stitch-react-components 将 Stitch 屏幕转换为 React 后，使用本技能添加 shadcn 组件用于表单、对话框、表格等。
• 如果项目使用 stitch-design-md 的 DESIGN.md，将主题（颜色、间距）与其对齐。

使用方式

通过上述命令与 MCP 工具进行组件发现、安装、初始化和定制。安装命令为 npx shadcn@latest add [component-name]，初始化命令为 npx shadcn@latest init，创建新项目为 npx shadcn@latest create。

适用场景

• 使用 shadcn/ui 构建 React UI。
• Stitch + React + shadcn 集成。
• 需要发现、安装、定制和扩展 shadcn 组件。
• 使用 blocks 构建 auth、dashboard、sidebar 等复杂界面。

限制与故障排查

• 导入错误：检查 components.json 和 tsconfig.json 路径（@/*）。
• 样式冲突：确保 Tailwind 和 globals.css 已配置；匹配 CSS 变量名。
• 缺少依赖：运行 npx shadcn@latest add [component] 自动安装；或使用 get_component_metadata 获取依赖列表。

关键词

英文：shadcn、shadcn/ui、Radix、Tailwind、React、components、blocks。 中文：shadcn、Radix、Tailwind、组件。

参考

• shadcn/ui docs
• Radix UI

示例

Tailwind → shadcn/ui：将 Stitch HTML 转换为 React + shadcn 时，保留 Tailwind，将 Stitch tokens 映射到 globals.css（--primary、--background 等）；使用 shadcn 组件（Button、Card、Input）配合 className/cn()。