@szc-ft/mcp-szcd-client 0.34.2 → 0.38.0

package/opencode-extension/skills/shadcn-design-to-code/references/sketch-mapping.md

@@ -0,0 +1,247 @@
+# Sketch 节点 → shadcn 组件反查表
+
+> 把 sketch 视觉特征 → shadcn 组件候选的快速反查表
+> 避免每次都调 shadcn MCP 搜索
+> 复杂组合走 LLM 推理 + search_items
+
+## 使用方法
+
+1. 从 .sketch 解析出节点数据（步骤 2.5）
+2. 对每个节点/节点组，按下表的"Sketch 特征"列匹配
+3. 命中后，看"shadcn 组件"列选组件
+4. 看"Sketch signals" 列做二次确认
+5. 复杂组合（如 DataTable、Form、Chart）调 `mcp__shadcn__search_items` 进一步搜索
+
+---
+
+## 1. 基础原子组件
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 矩形带文字（按钮） | Button | 圆角矩形 + 单行文字 + hover/active 态 | 必装，cva variants 固定 |
+| 矩形/输入框（文本输入） | Input | 矩形 + 占位文字 + 边框 | 配 Form 使用 |
+| 矩形 + 文字标签 | Label | 与 Input 紧邻的小字 | 配 Form 使用 |
+| 矩形（多行输入） | Textarea | 高 ≥ 80px 的矩形 + 占位文字 | 配 Form 使用 |
+| 矩形（下拉选择） | Select | 矩形 + 占位文字 + 右侧 chevron | 含 Trigger/Content/Item |
+| 圆角矩形（卡片容器） | Card | 矩形 + 阴影 + Header/Content/Footer 分割 | 必有 Card |
+| 单行/多行文字 | Typography (h1-h4 / p) | text 节点 | 走 Tailwind `text-*` |
+| 单图 | img 标签 | bitmap 节点 | extractBitmaps → base64 |
+| 头像（圆形图片） | Avatar | 圆形 bitmap 或圆形 rectangle + 文字 | lucide-react User 图标兜底 |
+| 徽章（小标签） | Badge | 小圆角矩形 + 短文字 | variants: default/secondary/destructive/outline |
+| 复选框 | Checkbox | 小方框 + 文字 | 配 react-hook-form |
+| 单选框 | RadioGroup | 小圆点 + 文字 | 配 react-hook-form |
+| 开关 | Switch | 圆角矩形 + 圆点 | boolean 状态 |
+| 分隔线 | Separator | 细线（height 1-2px） | 横/竖 |
+
+## 2. 导航组件
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 顶部水平导航 | NavigationMenu | 多个文字水平排列 + 下拉 | 含 Trigger/Content/List/Item |
+| 左侧垂直菜单 | Sidebar (block sidebar-07) | 200-280px 固定宽 + 多行图标+文字 | 必装 Sidebar block |
+| 水平 Tab 切换 | Tabs | 文字带下划线/底色切换 | 配 TabsContent |
+| 垂直 Tab 切换 | Tabs (vertical orientation) | 左侧 200-240px 文字列表 | 配 TabsContent |
+| 面包屑 | Breadcrumb | `首页 / 列表 / 详情` 文字链 | 含 Item/Link/Separator |
+| 分页器 | Pagination | `< 1 2 3 ... 10 >` | 配 table |
+| 步骤条 | Stepper (自写) | 圆点 + 连接线 + 数字 | shadcn 无原生 Stepper |
+| 命令面板 | Command | 模态搜索框 | 配 ⌘K |
+
+## 3. 数据展示
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 数据表格 | DataTable (基于 @tanstack/react-table) | 多列多行矩形 + 表头 + 分页 | shadcn 官方有完整示例 |
+| 简单表格 | Table | 静态表格，无排序/筛选 | 用 Table/TableHeader/TableBody |
+| 列表（卡片网格） | Card 网格 | 多个 Card 横竖排列 | 走 grid |
+| 列表（行） | div 列表 | 多行内容 | 走 space-y-2 |
+| 折线图 | Chart (Line) | 折线 + 坐标轴 + 图例 | 基于 Recharts |
+| 柱状图 | Chart (Bar) | 竖向矩形 + 坐标轴 | 基于 Recharts |
+| 饼图 | Chart (Pie) | 圆形扇区 + 图例 | 基于 Recharts |
+| 面积图 | Chart (Area) | 折线 + 下方填充 | 基于 Recharts |
+| 雷达图 | Chart (Radar) | 多边形网格 | Recharts Radar |
+| 散点图 | Chart (Scatter) | 散点 | Recharts Scatter |
+| 数据卡片（含数字） | Card + 大字号数字 | 矩形 + 64-96px 字号数字 + 小字标签 | 配 Trend 指示器 |
+| 进度条 | Progress | 矩形 + 内部填充矩形 | 含 value 属性 |
+| 圆形进度 | 自写（基于 div） | 圆形 + 弧形 | 用 SVG 或 Conic-gradient |
+| 头像组 | AvatarGroup (自写) | 多个圆形头像横排 | 用 flex -space-x-2 |
+| 工具提示 | Tooltip | 悬停弹窗 | Radix Tooltip |
+| 弹出卡片 | Popover | 悬停/点击弹卡 | Radix Popover |
+| 折叠面板 | Accordion / Collapsible | 可展开/折叠的卡片 | 含 Item/Trigger/Content |
+| 标签页（卡片） | Tabs (type=card) | 矩形 tab 头 | TabsList |
+| 树形结构 | 自写（基于 div） | 嵌套缩进的列表 | 配 lucide ChevronRight/Down |
+
+## 4. 反馈组件
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 全局消息 | Sonner (Toast) | 浮层 + 状态色 | shadcn 官方推荐 Sonner |
+| 警告框 | Alert | 矩形 + 图标 + 文字 + 状态色 | variants: default/destructive |
+| 对话框（确认） | AlertDialog | 居中模态 + 标题 + 描述 + 按钮 | 二次确认用 |
+| 弹窗（一般） | Dialog | 居中模态 + Header + Content | 配 Form |
+| 抽屉 | Sheet | 右侧滑入面板 | 配 side="right/left/top/bottom" |
+| 加载占位 | Skeleton | 矩形 + 浅色 + 动画 | loading 状态 |
+| 加载旋转 | 自写（基于 div） | 圆圈 + 旋转动画 | 或 lucide Loader2 |
+| 空状态 | 自写 | 居中图标 + 标题 + 描述 + 按钮 | 用 Card 包裹 |
+| 错误状态 | Alert (destructive) | 矩形 + 红色 + 图标 + 文字 | |
+| 成功状态 | Alert (default) | 矩形 + 绿色 + 图标 + 文字 | |
+| 下拉菜单 | DropdownMenu | 矩形 + 多行选项 | 配 MenuItem |
+
+## 5. 表单组件
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 表单容器 | Form | FormProvider + Field 组合 | 基于 react-hook-form |
+| 表单字段包装 | FormField + FormItem | label + control + message | 必装 |
+| 表单验证错误 | FormMessage | 红色文字 | 配 zod |
+| 输入框 | Input / Textarea | 同上 | |
+| 选择器 | Select | 同上 | |
+| 多选 | 自写（基于 Checkbox） | 多个 Checkbox | |
+| 开关 | Switch | 同上 | |
+| 单选 | RadioGroup | 多个 Radio | |
+| 日期选择 | 自写（基于 Calendar） | 日期输入框 | shadcn 有 Calendar 组件 |
+| 文件上传 | 自写（基于 Input） | 上传按钮 | 或拖拽区 |
+| 标签输入 | 自写（基于 Badge） | 多个 Badge + 删除按钮 | |
+| 自动补全 | Command | 同上 | |
+
+## 6. 布局容器
+
+| Sketch 特征 | shadcn 组件 | Sketch signals | 备注 |
+|---|---|---|---|
+| 单列垂直布局 | div + space-y-* | 元素垂直堆叠 | flex flex-col |
+| 多列网格 | div + grid | 元素水平排列 | grid grid-cols-N |
+| 响应式网格 | div + grid | 上面 + 断点前缀 | md:grid-cols-2 lg:grid-cols-3 |
+| 固定侧边栏 | aside | 左侧 200-280px | 配 main flex-1 |
+| 粘性头部 | header + sticky | 顶部 56-64px | sticky top-0 z-50 |
+| 模态遮罩 | div + bg-black/50 | 全屏黑色半透明 | Dialog 内部 |
+| 响应式隐藏 | div + hidden / md:block | Sketch 中只在某断点出现 | |
+| 滚动区域 | ScrollArea | 内容超出滚动 | shadcn ScrollArea |
+| 响应式容器 | div + container | 居中 + 最大宽度 | container mx-auto |
+
+## 7. 业务组件（基于 block）
+
+shadcn 官方提供完整 block，覆盖常见业务场景。**优先看 block 再组合**：
+
+| Sketch 特征 | shadcn block | 内容 |
+|---|---|---|
+| Dashboard 完整布局 | `dashboard-01` | sidebar + 4 stat + 2 chart + 1 table |
+| 登录页 | `login-01` ~ `login-05` | 居中表单 + 背景 |
+| 注册页 | `signup-01` ~ `signup-05` | 居中表单 + 背景 |
+| 定价页 | `pricing-01` ~ `pricing-04` | 3-4 列定价卡片 |
+| 用户主页 | `profile-01` ~ `profile-05` | Cover + 头像 + 信息 |
+| 团队成员 | `team-01` ~ `team-04` | 成员卡片列表 |
+| 任务管理 | `tasks-01` ~ `tasks-04` | 看板 / 列表 |
+| 日历 | `calendar-01` | 月视图 |
+| 邮件 | `mail-01` ~ `mail-06` | 左右分栏 + 列表 + 详情 |
+| 聊天 | `chat-01` | 联系人 + 对话窗口 |
+| 设置 | `settings-01` ~ `settings-05` | 垂直 Tab + 表单 |
+| 404 | `not-found-01` | 居中插图 + 文字 + 按钮 |
+
+**block 命名规律**：`{category}-{NN}` 格式。
+
+**调用方式**：
+```
+mcp__shadcn__search_items_in_registries(registries=["@shadcn"], query="dashboard")
+mcp__shadcn__view_items_in_registries(items=["@shadcn/dashboard-01"])
+mcp__shadcn__get_add_command_for_items(items=["@shadcn/dashboard-01"])
+→ npx shadcn@latest add @shadcn/dashboard-01
+```
+
+## 8. 缺失能力（必须自写）
+
+| Sketch 特征 | 解决方案 | 备注 |
+|---|---|---|
+| Stepper（步骤条） | 自写 | shadcn 无原生 |
+| DatePicker | 基于 Calendar 包装 | 选完日期填到 Input |
+| TimePicker | 自写（基于 Input） | 配 lucide Clock |
+| Cascader 级联选择 | 自写 | shadcn 无 |
+| Tree 树形控件 | 自写 | Radix Accordion 改造 |
+| Transfer 穿梭框 | 自写 | |
+| Upload 上传 | 自写 | 配合 react-dropzone |
+| RichText 富文本 | 集成 Tiptap | |
+| Mention @ 提及 | 自写 | 基于 Tiptap 扩展 |
+| Cropper 图片裁剪 | 集成 react-image-crop | |
+| Signature 签名 | 集成 react-signature-canvas | |
+| ColorPicker | 集成 react-colorful | |
+| Slider 数值滑块 | Slider (shadcn 有) | 但 range 要 Slider.Range |
+| Rating 评分 | 自写（基于 lucide Star） | |
+| Carousel 轮播 | Carousel (基于 embla-carousel) | shadcn 有 |
+| Code 代码块 | SyntaxHighlighter | |
+| Diff 代码差异 | react-diff-viewer-continued | |
+| Sticky 吸顶 | 自写（基于 div + sticky） | |
+| Floating 悬浮 | 自写（基于 div + fixed） | |
+| Print 打印 | window.print() | |
+| Fullscreen 全屏 | 自写 | |
+| Resizable 可拖拽 | Resizable (基于 react-resizable-panels) | shadcn 有 |
+| Masonry 瀑布流 | 自写 | CSS columns 或 react-masonry-css |
+| VirtualList 虚拟列表 | 基于 @tanstack/react-virtual | |
+| Dock（macOS 风格） | 自写 | |
+| Command Palette | Command (shadcn 有) | 配 ⌘K |
+| Context Menu | ContextMenu (shadcn 有) | 右键菜单 |
+
+## 9. 反查决策树（快速定位）
+
+```
+Sketch 节点是什么？
+├── 文字 → h1-h4 / p / span (Typography)
+├── 矩形（无文字）→ 容器 / 卡片 / 装饰
+│   ├── 阴影 + 圆角 + 内部有内容 → Card
+│   ├── 圆角 + 单色填充 + 小尺寸 → Badge
+│   ├── 进度条形状 → Progress
+│   └── 装饰几何 → div + bg-*
+├── 矩形（带文字）→ Button / Label / Tab / MenuItem
+├── 圆形/椭圆形 → Avatar / Switch / Radio / 装饰
+├── 输入框形状 → Input / Textarea / Select
+├── 复选框形状 → Checkbox
+├── 列表/菜单 → 走 NavigationMenu 或 Sidebar
+├── 树形 → 自写 Tree
+├── 图表 → Chart (Recharts)
+├── 表格 → Table / DataTable
+├── 模态 → Dialog / Sheet / AlertDialog / Popover
+├── 弹窗消息 → Sonner
+├── 折叠面板 → Accordion / Collapsible
+├── 标签页 → Tabs
+├── 进度条 → Progress
+├── 滑块 → Slider
+├── 评分 → 自写（Star）
+├── 头像 → Avatar
+├── 工具提示 → Tooltip
+├── 弹出菜单 → DropdownMenu / ContextMenu
+└── 完整页面 → 搜 block（dashboard-01 等）
+```
+
+## 10. 缺失时如何扩列
+
+如果 Sketch 有上表未覆盖的视觉特征：
+1. 先调 `mcp__shadcn__search_items_in_registries(query="<中文描述>")` 看是否有匹配
+2. 搜不到 → 调 `mcp__shadcn__list_items_in_registries(types=["block"])` 看所有 block
+3. 还找不到 → 可能是 Radix primitive，需要 `mcp__shadcn__view_items_in_registries(items=["@radix-ui/react-xxx"])`（**注意：Radix 组件不在 shadcn registry，需要另外装**）
+4. 都没有 → 自写（参考 lucide-react 图标 + Tailwind utility）
+
+## 11. 必备 shadcn 组件清单
+
+任何中等复杂度的页面都建议装：
+
+```
+npx shadcn@latest add button card input label form textarea select
+npx shadcn@latest add checkbox radio-group switch slider
+npx shadcn@latest add dialog sheet alert-dialog dropdown-menu
+npx shadcn@latest add tabs accordion collapsible separator
+npx shadcn@latest add table tooltip popover avatar badge
+npx shadcn@latest add navigation-menu sidebar breadcrumb pagination
+npx shadcn@latest add alert sonner progress skeleton
+npx shadcn@latest add chart         # 图表（基于 Recharts）
+npx shadcn@latest add data-table    # 高级表格（基于 @tanstack/react-table）
+npx shadcn@latest add calendar      # 日期选择
+npx shadcn@latest add command       # 命令面板
+npx shadcn@latest add resizable     # 可拖拽面板
+npx shadcn@latest add carousel      # 轮播
+npx shadcn@latest add drawer        # 抽屉（与 sheet 类似但从底部）
+```
+
+**精简版**（小型页面）：
+```
+npx shadcn@latest add button card input label form textarea select
+npx shadcn@latest add dialog sheet dropdown-menu
+npx shadcn@latest add tabs table tooltip avatar badge
+npx shadcn@latest add alert sonner skeleton
+```