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

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

@@ -0,0 +1,551 @@
+# shadcn 布局模式库
+
+> 15 种常见设计稿布局模式 → Tailwind 落地代码片段
+> 按"区块分布特征"反查，按 layouts 排序
+
+## 推理流程
+
+1. 看 .sketch 画板的 x 分布（大区分列）
+2. 看 y 分布（大区内纵序）
+3. 看主区内部的"卡片栅格"
+4. 命中下面的 15 种之一 → 直接用对应 Tailwind 模板
+
+---
+
+## L01: sidebar-main（侧边栏 + 主内容）
+
+**Sketch 特征**：
+- 左侧 200-280px 固定宽度，1 列深色/浅色导航，含 logo + 菜单项 + 底部用户
+- 右侧剩余宽度，主内容上下排列
+
+**典型场景**：SaaS 后台、Admin Panel、文档站
+
+```tsx
+<div className="flex h-screen bg-background">
+  <aside className="w-64 border-r bg-slate-50 dark:bg-slate-900 flex flex-col">
+    <div className="h-16 border-b flex items-center px-6">{/* logo */}</div>
+    <nav className="flex-1 p-4 space-y-1">{/* 菜单项 */}</nav>
+    <div className="p-4 border-t">{/* user */}</div>
+  </aside>
+  <main className="flex-1 overflow-auto">
+    <div className="container mx-auto p-6 space-y-6">{/* 主内容 */}</div>
+  </main>
+</div>
+```
+
+**shadcn 组件**：Sidebar (sidebar-07 block) + Sheet（移动端抽屉）
+
+---
+
+## L02: topbar-content（顶部栏 + 内容）
+
+**Sketch 特征**：
+- 顶部 56-64px 高度，含 logo + 水平导航 + 搜索 + 头像
+- 下方全宽内容区
+
+**典型场景**：营销页、文档首页
+
+```tsx
+<div className="min-h-screen bg-background">
+  <header className="sticky top-0 z-50 h-16 border-b bg-background/95 backdrop-blur">
+    <div className="container mx-auto h-full flex items-center justify-between px-4">
+      <div className="flex items-center gap-8">{/* logo + nav */}</div>
+      <div className="flex items-center gap-4">{/* 搜索 + 头像 */}</div>
+    </div>
+  </header>
+  <main className="container mx-auto px-4 py-8">{/* content */}</main>
+</div>
+```
+
+**shadcn 组件**：NavigationMenu + Input + Avatar + Button
+
+---
+
+## L03: dashboard-grid（多卡片仪表盘）
+
+**Sketch 特征**：
+- 顶部 4 个统计卡片（Stat）
+- 中部 1-2 个大图表卡片
+- 底部表格 + 活动 feed
+
+**典型场景**：运营 Dashboard、监控大屏
+
+```tsx
+<div className="flex-1 space-y-6 p-6">
+  {/* 4 个 Stat 卡片 */}
+  <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-4">
+    {stats.map((s) => <StatCard key={s.title} {...s} />)}
+  </div>
+  {/* 2 个图表卡片 */}
+  <div className="grid grid-cols-1 gap-4 lg:grid-cols-7">
+    <Card className="lg:col-span-4"><ChartContainer config={chartConfig}>
+      <LineChart data={data} /></ChartContainer></Card>
+    <Card className="lg:col-span-3"><ChartContainer config={chartConfig2}>
+      <BarChart data={data2} /></ChartContainer></Card>
+  </div>
+  {/* 表格 + 活动 */}
+  <div className="grid grid-cols-1 gap-4 lg:grid-cols-7">
+    <Card className="lg:col-span-4">{/* 表格 */}</Card>
+    <Card className="lg:col-span-3">{/* 活动 feed */}</Card>
+  </div>
+</div>
+```
+
+**shadcn 组件**：Card + Chart（基于 Recharts）+ Table + Avatar
+
+---
+
+## L04: left-right（左内容 + 右详情）
+
+**Sketch 特征**：
+- 左侧 35-45% 宽，列表/卡片网格
+- 右侧 55-65% 宽，单条详情/大图
+- 移动端垂直堆叠
+
+**典型场景**：邮件客户端、文件管理、电商详情
+
+```tsx
+<div className="grid grid-cols-1 gap-6 lg:grid-cols-3">
+  <div className="lg:col-span-1 space-y-2">
+    {items.map((item) => (
+      <Card key={item.id} className={cn("cursor-pointer", selected === item.id && "border-primary")}>
+        {/* item summary */}
+      </Card>
+    ))}
+  </div>
+  <div className="lg:col-span-2">
+    <Card>{/* 详情 */}</Card>
+  </div>
+</div>
+```
+
+**shadcn 组件**：Card + ScrollArea + Separator
+
+---
+
+## L05: form-page（表单页）
+
+**Sketch 特征**：
+- 顶部标题 + 描述
+- 居中卡片（max-width 800-1000px）
+- 表单字段 1-2 列
+- 底部固定操作栏（保存/取消）
+
+**典型场景**：设置页、新建/编辑表单
+
+```tsx
+<div className="container max-w-3xl py-8 space-y-6">
+  <div>
+    <h1 className="text-2xl font-semibold">页面标题</h1>
+    <p className="text-muted-foreground">页面描述</p>
+  </div>
+  <Card>
+    <CardContent className="pt-6">
+      <Form {...form}>
+        <form onSubmit={form.handleSubmit(onSubmit)} className="space-y-6">
+          <div className="grid grid-cols-1 gap-4 md:grid-cols-2">
+            <FormField control={form.control} name="name" render={({ field }) => (
+              <FormItem><FormLabel>名称</FormLabel>
+                <FormControl><Input {...field} /></FormControl>
+                <FormMessage />
+              </FormItem>
+            )} />
+            {/* 其他字段 */}
+          </div>
+          <div className="flex justify-end gap-2">
+            <Button type="button" variant="outline" onClick={onCancel}>取消</Button>
+            <Button type="submit">保存</Button>
+          </div>
+        </form>
+      </Form>
+    </CardContent>
+  </Card>
+</div>
+```
+
+**shadcn 组件**：Form + Input + Select + Textarea + Checkbox + Button
+
+---
+
+## L06: list-card-switch（列表/卡片切换）
+
+**Sketch 特征**：
+- 顶部筛选/搜索 + 切换按钮（grid / list）
+- 下方卡片网格或列表
+
+**典型场景**：商品列表、数据浏览
+
+```tsx
+<div className="space-y-4">
+  <div className="flex items-center justify-between">
+    <div className="flex items-center gap-2">{/* 筛选 */}</div>
+    <div className="flex items-center gap-2">
+      <Button variant={view === 'grid' ? 'secondary' : 'ghost'} size="icon" onClick={() => setView('grid')}>
+        <LayoutGrid />
+      </Button>
+      <Button variant={view === 'list' ? 'secondary' : 'ghost'} size="icon" onClick={() => setView('list')}>
+        <List />
+      </Button>
+    </div>
+  </div>
+  {view === 'grid' ? (
+    <div className="grid grid-cols-1 gap-4 md:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4">
+      {items.map((item) => <ItemCard key={item.id} {...item} />)}
+    </div>
+  ) : (
+    <div className="space-y-2">{items.map((item) => <ItemRow key={item.id} {...item} />)}</div>
+  )}
+</div>
+```
+
+**shadcn 组件**：Button + ToggleGroup + Card + lucide-react 图标
+
+---
+
+## L07: tabs-vertical（左侧 Tab + 右侧内容）
+
+**Sketch 特征**：
+- 左侧 200-240px 垂直 Tab 列表（含图标）
+- 右侧 Tab 对应内容
+
+**典型场景**：设置页（账户/通知/隐私）、个人中心
+
+```tsx
+<div className="grid grid-cols-1 gap-6 md:grid-cols-[200px_1fr] lg:grid-cols-[240px_1fr]">
+  <nav className="flex flex-col gap-1">
+    {tabs.map((tab) => (
+      <button key={tab.value} onClick={() => setActive(tab.value)}
+        className={cn("flex items-center gap-2 rounded-md px-3 py-2 text-sm",
+          active === tab.value ? "bg-muted font-medium" : "hover:bg-muted/50")}>
+        <tab.icon className="h-4 w-4" />{tab.label}
+      </button>
+    ))}
+  </nav>
+  <div>{/* tab content */}</div>
+</div>
+```
+
+**shadcn 组件**：Tabs（也可用 vertical orientation 的 Radix Tabs）
+
+---
+
+## L08: wizard-steps（步骤向导）
+
+**Sketch 特征**：
+- 顶部 Stepper（3-5 步）
+- 中部当前步骤表单
+- 底部 上一步/下一步 按钮
+
+**典型场景**：注册流程、配置向导
+
+```tsx
+<div className="container max-w-3xl py-8">
+  <ol className="flex items-center w-full mb-8">
+    {steps.map((step, i) => (
+      <li key={step} className={cn("flex items-center", i < steps.length - 1 && "w-full")}>
+        <span className={cn("flex items-center justify-center w-8 h-8 rounded-full",
+          i <= current ? "bg-primary text-primary-foreground" : "bg-muted text-muted-foreground")}>
+          {i < current ? <Check /> : i + 1}
+        </span>
+        {i < steps.length - 1 && <span className={cn("flex-1 h-0.5 mx-2", i < current ? "bg-primary" : "bg-muted")} />}
+      </li>
+    ))}
+  </ol>
+  <Card>
+    <CardContent className="pt-6">
+      {/* current step form */}
+    </CardContent>
+    <CardFooter className="flex justify-between">
+      <Button variant="outline" onClick={prev} disabled={current === 0}>上一步</Button>
+      <Button onClick={next}>{current === steps.length - 1 ? '完成' : '下一步'}</Button>
+    </CardFooter>
+  </Card>
+</div>
+```
+
+**shadcn 组件**：Button + Card + lucide-react Check 图标
+
+---
+
+## L09: modal-form（弹窗表单）
+
+**Sketch 特征**：
+- 背景遮罩
+- 居中 480-640px 模态框
+- 标题 + 描述 + 表单 + 底部按钮
+
+**典型场景**：新建/编辑操作
+
+```tsx
+<Dialog open={open} onOpenChange={setOpen}>
+  <DialogContent className="sm:max-w-[540px]">
+    <DialogHeader>
+      <DialogTitle>新建项目</DialogTitle>
+      <DialogDescription>填写项目信息</DialogDescription>
+    </DialogHeader>
+    <Form {...form}>
+      <form onSubmit={form.handleSubmit(onSubmit)}>
+        <div className="space-y-4 py-4">
+          <FormField control={form.control} name="name" render={({ field }) => (
+            <FormItem><FormLabel>名称</FormLabel>
+              <FormControl><Input {...field} /></FormControl>
+              <FormMessage />
+            </FormItem>
+          )} />
+        </div>
+        <DialogFooter>
+          <Button type="button" variant="outline" onClick={() => setOpen(false)}>取消</Button>
+          <Button type="submit">确认</Button>
+        </DialogFooter>
+      </form>
+    </Form>
+  </DialogContent>
+</Dialog>
+```
+
+**shadcn 组件**：Dialog + Form + Input + Button
+
+---
+
+## L10: data-table-page（数据表页）
+
+**Sketch 特征**：
+- 顶部筛选条 + 操作按钮
+- 列头含排序 + 过滤 + 列选择
+- 行支持选择（checkbox）
+- 分页器在底部
+
+**典型场景**：管理后台表格
+
+```tsx
+<div className="space-y-4">
+  <div className="flex items-center justify-between">
+    <Input placeholder="搜索..." className="max-w-sm" />
+    <div className="flex items-center gap-2">
+      <Button variant="outline" size="sm">导出</Button>
+      <Button size="sm"><Plus />新建</Button>
+    </div>
+  </div>
+  <div className="rounded-md border">
+    <Table>
+      <TableHeader>
+        {table.getHeaderGroups().map((hg) => (
+          <TableRow key={hg.id}>{hg.headers.map((h) => <TableHead key={h.id}>{flexRender(h.column.columnDef.header, h.getContext())}</TableHead>)}</TableRow>
+        ))}
+      </TableHeader>
+      <TableBody>
+        {table.getRowModel().rows.map((row) => (
+          <TableRow key={row.id}>{row.getVisibleCells().map((cell) => <TableCell key={cell.id}>{flexRender(cell.column.columnDef.cell, cell.getContext())}</TableCell>)}</TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  </div>
+  <DataTablePagination table={table} />
+</div>
+```
+
+**shadcn 组件**：Table + Checkbox + Button + DropdownMenu（基于 @tanstack/react-table）
+
+---
+
+## L11: empty-state（空状态）
+
+**Sketch 特征**：
+- 居中 360-480px 区域
+- 顶部插图/图标（60-120px）
+- 中部标题 + 描述
+- 底部主操作按钮
+
+**典型场景**：空列表、404、首次使用引导
+
+```tsx
+<div className="flex flex-col items-center justify-center py-16 text-center">
+  <div className="rounded-full bg-muted p-4 mb-4">
+    <Inbox className="h-8 w-8 text-muted-foreground" />
+  </div>
+  <h3 className="text-lg font-semibold">暂无数据</h3>
+  <p className="text-sm text-muted-foreground mt-1 max-w-sm">开始创建你的第一个项目</p>
+  <Button className="mt-6"><Plus />新建项目</Button>
+</div>
+```
+
+**shadcn 组件**：Button + lucide-react 图标
+
+---
+
+## L12: profile-header（用户主页头部）
+
+**Sketch 特征**：
+- 顶部 Cover 图（200-320px）
+- 头像悬浮在 Cover 底部边缘
+- 用户名 + 简介 + 操作按钮
+
+**典型场景**：用户主页、团队介绍
+
+```tsx
+<div>
+  <div className="h-48 md:h-64 bg-gradient-to-r from-slate-200 to-slate-300 dark:from-slate-800 dark:to-slate-900" />
+  <div className="container mx-auto px-4">
+    <div className="flex flex-col sm:flex-row sm:items-end sm:gap-6 -mt-12 sm:-mt-16">
+      <Avatar className="h-24 w-24 sm:h-32 sm:w-32 border-4 border-background">
+        <AvatarImage src={user.avatar} />
+        <AvatarFallback>{user.name[0]}</AvatarFallback>
+      </Avatar>
+      <div className="flex-1 mt-4 sm:mt-0 sm:mb-2">
+        <h1 className="text-2xl font-semibold">{user.name}</h1>
+        <p className="text-muted-foreground">{user.bio}</p>
+      </div>
+      <div className="flex gap-2 sm:mb-2">
+        <Button variant="outline">编辑</Button>
+        <Button>关注</Button>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+**shadcn 组件**：Avatar + Button
+
+---
+
+## L13: kanban-board（看板）
+
+**Sketch 特征**：
+- 横向多列（待办 / 进行中 / 已完成）
+- 每列含卡片堆叠
+- 卡片可拖拽
+
+**典型场景**：项目管理、Trello 风格
+
+```tsx
+<div className="flex gap-4 overflow-x-auto p-4">
+  {columns.map((col) => (
+    <div key={col.id} className="w-72 shrink-0 rounded-lg bg-muted/40 p-3">
+      <div className="flex items-center justify-between mb-3">
+        <h3 className="font-medium">{col.title}</h3>
+        <Badge variant="secondary">{col.cards.length}</Badge>
+      </div>
+      <div className="space-y-2">
+        {col.cards.map((card) => (
+          <Card key={card.id} className="cursor-grab active:cursor-grabbing">
+            <CardContent className="p-3">
+              <p className="text-sm">{card.title}</p>
+              {card.tags && <div className="flex gap-1 mt-2">{card.tags.map((t) => <Badge key={t} variant="outline">{t}</Badge>)}</div>}
+            </CardContent>
+          </Card>
+        ))}
+      </div>
+    </div>
+  ))}
+</div>
+```
+
+**shadcn 组件**：Card + Badge + dnd-kit（拖拽）
+
+---
+
+## L14: timeline（时间线）
+
+**Sketch 特征**：
+- 垂直轴 + 时间点
+- 每点配内容卡片
+
+**典型场景**：活动日志、订单历史
+
+```tsx
+<div className="space-y-6">
+  {events.map((event, i) => (
+    <div key={event.id} className="flex gap-4">
+      <div className="flex flex-col items-center">
+        <div className={cn("h-2 w-2 rounded-full", i === 0 ? "bg-primary" : "bg-muted-foreground")} />
+        {i < events.length - 1 && <div className="w-px flex-1 bg-border mt-2" />}
+      </div>
+      <Card className="flex-1">
+        <CardContent className="p-4">
+          <div className="flex items-center justify-between">
+            <p className="font-medium">{event.title}</p>
+            <time className="text-xs text-muted-foreground">{event.time}</time>
+          </div>
+          <p className="text-sm text-muted-foreground mt-1">{event.description}</p>
+        </CardContent>
+      </Card>
+    </div>
+  ))}
+</div>
+```
+
+**shadcn 组件**：Card
+
+---
+
+## L15: pricing-cards（价格卡片）
+
+**Sketch 特征**：
+- 3-4 列响应式
+- 中间一列"推荐"（高亮边框 + 徽章）
+- 每列：标题 + 价格 + 特性列表 + CTA 按钮
+
+**典型场景**：SaaS 定价页
+
+```tsx
+<div className="grid grid-cols-1 gap-6 md:grid-cols-3">
+  {plans.map((plan) => (
+    <Card key={plan.id} className={cn("relative", plan.featured && "border-primary shadow-lg")}>
+      {plan.featured && <Badge className="absolute -top-3 left-1/2 -translate-x-1/2">推荐</Badge>}
+      <CardHeader>
+        <CardTitle>{plan.name}</CardTitle>
+        <CardDescription>{plan.description}</CardDescription>
+        <div className="mt-4">
+          <span className="text-4xl font-bold">¥{plan.price}</span>
+          <span className="text-muted-foreground">/月</span>
+        </div>
+      </CardHeader>
+      <CardContent>
+        <ul className="space-y-2">
+          {plan.features.map((f) => (
+            <li key={f} className="flex items-center gap-2 text-sm">
+              <Check className="h-4 w-4 text-primary" />{f}
+            </li>
+          ))}
+        </ul>
+      </CardContent>
+      <CardFooter>
+        <Button className="w-full" variant={plan.featured ? 'default' : 'outline'}>
+          {plan.cta}
+        </Button>
+      </CardFooter>
+    </Card>
+  ))}
+</div>
+```
+
+**shadcn 组件**：Card + Badge + Button + lucide-react Check
+
+---
+
+## 反查决策树
+
+```
+画板 1 列      → L02 topbar-content
+画板 2 列      → x<300 侧栏 L01 sidebar-main | x>700 主区单独
+画板 2 列 35/65 → L04 left-right
+画板 3+ 列    → 顶部 grid（d-grid-cols-3/4）
+画板 卡片栅格  → L03 dashboard-grid
+画板 表单     → L05 form-page
+画板 弹窗     → L09 modal-form
+画板 步骤     → L08 wizard-steps
+画板 表格     → L10 data-table-page
+画板 价格     → L15 pricing-cards
+画板 时间线   → L14 timeline
+画板 看板     → L13 kanban-board
+画板 列表/卡片切换 → L06 list-card-switch
+画板 垂直 Tab  → L07 tabs-vertical
+画板 空状态   → L11 empty-state
+画板 用户主页 → L12 profile-header
+```
+
+**多种模式可叠加**（常见组合）：
+- L01 + L03：侧边栏 + 仪表盘
+- L02 + L10：顶部栏 + 表格
+- L01 + L05：侧边栏 + 设置表单
+- L01 + L07：侧边栏 + 垂直 Tab 设置