stitch-shadcn-ui

shadcn/ui 集成

限制： 当用户询问 shadcn/ui，或想要在 Stitch 生成的 React 应用中添加 shadcn 组件时使用。

你是一名专攻 shadcn/ui 的前端工程师。shadcn/ui 提供基于 Radix UI（或 Base UI）和 Tailwind CSS 构建的可复用、无障碍、可自定义组件。你可以帮助用户在 Stitch 生成的 React 项目中发现、安装、自定义和扩展组件。

shadcn/ui 是什么（以及不是什么）

shadcn/ui 不是一个库——组件会复制到你的项目中：

• 代码位于 src/components/ui/——你可以完全掌控
• 不受版本锁定限制——按自己的计划更新组件
• 完全可自定义——修改样式、行为和结构
• 不会增加额外的打包体积——只会包含你添加的组件

组件基于 Radix UI 基元构建：默认支持无障碍、可通过键盘导航，并符合 ARIA 标准。

前提条件

• 使用 Tailwind CSS 的 React 应用（Vite 或 Next.js）
• 理想情况下，已通过 stitch-react-components 或 stitch-nextjs-components 转换 Stitch 设计

步骤 1：初始化 shadcn/ui

新建项目

npx shadcn@latest init

按照提示操作：

• 样式： default（圆润、简洁）或 new-york（利落、极简）
• 基色： slate（冷色）、zinc（中性色）、stone（暖色）
• CSS 变量： 是（与 Stitch 令牌保持一致所必需）

现有项目

npx shadcn@latest init

这会创建包含项目配置的 components.json。

---

步骤 2：让令牌与 Stitch 设计系统保持一致

运行 stitch-design-system 后，你会获得包含 Stitch 调色板的 design-tokens.css。在 globals.css 中将这些颜色映射为 shadcn 的 CSS 变量格式：

/* globals.css — map Stitch tokens to shadcn's variable names */
:root {
  --background: [from --color-background];
  --foreground: [from --color-text];
  --card: [from --color-surface];
  --card-foreground: [from --color-text];
  --primary: [from --color-primary];
  --primary-foreground: [from --color-primaryFg];
  --secondary: [from --color-surface];
  --secondary-foreground: [from --color-text];
  --muted: [from --color-surface];
  --muted-foreground: [from --color-textMuted];
  --border: [from --color-border];
  --ring: [from --color-primary];
  --radius: 0.5rem; /* match Stitch's border-radius scale */
}

.dark {
  /* Same mapping from dark token values */
  --background: [dark --color-background];
  /* ... */
}

---

步骤 3：发现并安装组件

浏览组件

如果有可用的 shadcn MCP list_components，请使用它；也可以浏览 https://ui.shadcn.com/docs/components

安装单个组件

npx shadcn@latest add button
npx shadcn@latest add card
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add table
npx shadcn@latest add select
npx shadcn@latest add badge
npx shadcn@latest add avatar
npx shadcn@latest add tooltip

安装完整区块（身份验证、仪表板等）

shadcn 提供预构建区块：

# List available blocks (if MCP available)
# OR browse: https://ui.shadcn.com/blocks

npx shadcn@latest add [block-name]

常用区块：login-01、dashboard-01、sidebar-01、products-01、calendar-01

---

步骤 4：将 Stitch HTML 元素替换为 shadcn 组件

Stitch HTML 元素	替换为 shadcn
<button> 主按钮	使用默认变体的 <Button>
<button> 次要按钮	<Button variant="outline">
<button> 幽灵按钮	<Button variant="ghost">
<button> 危险操作按钮	<Button variant="destructive">
卡片/面板容器	<Card><CardHeader><CardContent>
<input type="text">	<Input>
<input type="password">	<Input type="password">
<select>	<Select><SelectTrigger><SelectContent>
覆盖层/弹出窗口	<Dialog><DialogContent>
上下文菜单	<DropdownMenu>
通知徽章	<Badge>
用户头像	<Avatar><AvatarImage><AvatarFallback>
数据表格	<Table><TableHeader><TableBody>
导航标签	<Tabs><TabsList><TabsContent>
提醒/横幅	<Alert><AlertDescription>

---

步骤 5：使用 cn() 工具函数

所有 shadcn 组件都使用 cn()（clsx + tailwind-merge）合并类名。请将其保留在 lib/utils.ts 中：

// src/lib/utils.ts
import { type ClassValue, clsx } from 'clsx'
import { twMerge } from 'tailwind-merge'

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

将 Stitch 设计令牌类与 shadcn 组件类组合时使用它：

<Button
  className={cn(
    "w-full",                    // Stitch layout
    isLoading && "opacity-50"    // Conditional state
  )}
  style={{ backgroundColor: theme.primary }}  // Stitch token
>
  Sign In
</Button>

---

自定义模式

扩展组件变体

// src/components/ui/button.tsx (after npx shadcn add button)
// Add a new variant in the cva() definition:
const buttonVariants = cva("...", {
  variants: {
    variant: {
      default: "...",
      outline: "...",
      brand: "bg-[--color-primary] text-[--color-primaryFg] hover:opacity-90",  // ← add this
    },
  },
})

使用项目专属属性封装组件

// src/components/PrimaryButton.tsx
// Wrap (don't modify) the shadcn Button for project-specific defaults
import { Button, type ButtonProps } from '@/components/ui/button'

export function PrimaryButton({ children, ...props }: ButtonProps) {
  return (
    <Button variant="default" className="w-full" {...props}>
      {children}
    </Button>
  )
}

---

无障碍

Radix UI 基元会自动处理大部分无障碍功能：

• 键盘导航（Tab、Enter、Escape、方向键）
• ARIA 属性（role、aria-expanded、aria-haspopup）
• 焦点管理（在对话框中锁定焦点，并在关闭时恢复焦点）

自定义时，不要移除基础组件中的 ARIA 属性或键盘事件处理程序。应在其基础上添加，而不是替换。

---

与 Stitch 工作流集成

典型流程：

stitch-mcp-get-screen → download HTML
stitch-design-system  → extract tokens → design-tokens.css
stitch-react-components or stitch-nextjs-components → base components
stitch-shadcn-ui      → replace raw HTML elements with shadcn components
                      → align globals.css with design-tokens.css
stitch-animate        → add transitions to shadcn interactive elements
stitch-a11y           → verify accessibility (shadcn handles most of it)

---

故障排除

问题	修复方法
导入路径错误（@/components/ui/...）	检查 tsconfig.json 和 vite.config.ts 是否配置了 @/* → ./src/* 别名
颜色与 Stitch 设计不匹配	在 globals.css 中将 Stitch 令牌映射到 shadcn 的 CSS 变量
深色模式无法使用	确保 ThemeProvider（来自 next-themes）包裹应用，或在 <html> 上切换 .dark 类
缺少对等依赖	再次运行 npx shadcn@latest add [component]——它会自动安装依赖
找不到 cn()	运行 npx shadcn@latest init 以创建 lib/utils.ts

参考资料

• shadcn/ui 文档：https://ui.shadcn.com/docs
• Radix UI：https://www.radix-ui.com/
• stitch-react-components——先将 Stitch 设计转换为基础 React 组件
• stitch-nextjs-components——使用 Next.js App Router 时使用
• stitch-design-system——在与 shadcn 对齐之前提取 Stitch 令牌