platform-ui

版本假设

• Tailwind CSS v4。
• shadcn CLI 3.x。
• registry item schema 以 https://ui.shadcn.com/schema/registry-item.json 当前版本为准。
• 所有命令以 npx shadcn --help 实测结果为准。

输入契约

追问只针对必填项，顺序固定为：页面清单 → SSR 与否。可选项缺失一律直接取默认值，不追问。"两轮"按同一必填项计数：对同一必填项累计两轮追问仍无有效回应时，立即进入 P0，交付文档后终止，不得继续 P1（SSR 项按上表规则默认 CSR，不计入该门槛）。

执行顺序约定：只读适用性检测（P1 检测程序）先于输入契约追问——若目标目录已可判定不适用（如存量 antd 项目），直接进入 P0 退出，不浪费用户的追问轮次。目标目录以用户指定为准，未指定时取当前工作目录；检测与生成均以该目录为根。

P0 方案分支

• 进入：连续两轮拿不到输入契约必填项，或用户确认需要 SSR/SEO，或 P1 检测判定不适用。
• 必读：本文件的输入契约、适用性矩阵、P1 检测程序。
• 产出（按进入原因分场景）：
  • 必填项缺失 → 基于已知信息的《页面结构与选型建议》文档。
  • 需要 SSR/SEO → 不适用说明 + Next.js 方向迁移建议。
  • 存量 antd / 其他 UI 库项目 → 不适用说明 + 分流建议：确有需要时可在新目录另起独立 greenfield 项目继续使用本 skill，不建议在存量仓库内混用。
• 完成判定：文档交付完成后立即终止流程。
• 降级：无。P0 本身就是显式退出路径，不得从 P0 续跑工程。

适用性矩阵

P1 检测程序

1. 读取 package.json；若依赖包含 antd、antd-mobile、@ant-design/*，判定不适用，进入 P0 产出"不适用说明 + 另起独立项目分流建议"后终止；@mui/*、@chakra-ui/* 同理。不适用的统一出口是 P0，不做无产出的裸退出。
2. 若无 package.json 且目录为空，或仅存在配置文件，则判定为 greenfield。
3. 若存在 tailwindcss 依赖，则走“已有 Tailwind”分支；若存在 pnpm-workspace.yaml 或 turbo.json，则走 monorepo 分支。
4. 兜底：存在 package.json 但前 3 步均不命中时，不得静默继续。先提示混用风险，再询问用户是否确认引入 shadcn；空壳脚手架仅在 src/ 只含模板文件时才按适用处理，含业务代码的存量项目默认走询问分支。

六阶段工序

P1 初始化

• 进入：输入契约必填项齐全，且未落入 P0。
• 必读：本文件的适用性矩阵与 P1 检测程序。

• 产出：适用性结论；脚手架 pnpm create vite <app> --template react-ts；Tailwind v4；npx shadcn init；TypeScript strict；补齐 package.json scripts（Vite 模板默认没有 typecheck/lint，必须显式补齐）：

  {
    "typecheck": "tsc --noEmit",
    "lint": "eslint .",
    "build": "tsc -b && vite build"
  }

• 完成判定：pnpm install && pnpm build 成功；components.json 存在；pnpm typecheck 与 pnpm lint 可运行。
• 降级：shadcn init 失败时，输出 Tailwind 兼容排查与手动初始化步骤；安装失败或依赖缺失时，检查 .npmrc registry 指向（公司私有源可能拿不到公共依赖），参见 references/registry-guide.md 的项目级 .npmrc 覆盖节；不适用项目直接退出。

P2 设计 Token

• 进入：P1 完成判定通过。
• 必读：references/design-tokens.md。
• 产出：src/styles/tokens.css 或 Tailwind v4 @theme 块，包含 --background、--foreground、--primary、--primary-foreground、--secondary、--secondary-foreground、--muted、--muted-foreground、--accent、--accent-foreground、--border、--input、--ring、--card、--card-foreground、--popover、--popover-foreground、--radius 等变量，并补全 .dark 映射。
• 完成判定：shadcn 约定变量在亮色与暗色两套中全部赋值完成。
• 降级：无品牌色时，使用 Radix Blue + Slate。

P3 组件安装

• 进入：P2 完成。
• 必读：references/component-map.md；涉及第三方源时额外读取 references/registry-guide.md。
• 产出：基础组件与按页面清单反推的场景组件；lucide-react；必要时完成 registry 拉取或手动复制源码。
• 完成判定：pnpm typecheck 通过；components/ui/ 中的组件与页面清单需要一致。
• 降级：registry 网络失败时，按 registry-guide.md 的手动复制源码方案处理。

P4 应用骨架

• 进入：P3 完成。
• 必读：references/component-map.md 的布局与数据层约定。
• 产出：App Shell；侧边导航、顶栏、内容区；按需接入 react-resizable-panels；React Router 或文件路由骨架；TanStack Query Provider；Vite 开发环境下的 MSW 初始化。
• 完成判定：pnpm dev 下所有导航项可达占位页；MSW 能拦截至少一条示例请求。
• 降级：无多栏需求时跳过 react-resizable-panels。

P5 页面组装

• 进入：P4 完成。
• 必读：references/component-map.md 中匹配当前页面类型的章节。
• 产出：列表页、表单页、详情页、看板页按固定顺序组装；每页配齐成功、空、错误三类 MSW handler；必要时接入可选的 AI 对话模块。
• 完成判定：每页三态都能通过切换 MSW handler 复现；pnpm typecheck && pnpm lint 通过。
• 降级：页面类型超出四类范式时，按最接近范式实现，并在注释或交付说明中标注偏离点。

P6 质量关卡

• 进入：全部页面完成 P5。
• 必读：assets/quality-checklist.md。
• 产出：可直接粘贴到 PR 描述的核验记录。
• 完成判定：删除 node_modules 后 pnpm install 可干净复装，pnpm typecheck、pnpm lint、pnpm build 全部通过；暗色模式、375/768/1280 三断点、键盘可达与焦点环、对比度、空/加载/错误三态、console 无错误全部核验完成。
• 降级：任何单项不过都必须列入问题清单，禁止静默放行。

轻量路径

• 仅加组件：直接执行 P3，并按需读取 references/component-map.md 与 references/registry-guide.md。
• 仅调主题：直接执行 P2，并只读取 references/design-tokens.md。
• 仅补三态 mock：执行 P4 的数据层初始化与 P5 的 MSW handler 范式。
• 轻量路径不强制补跑全流程，但必须满足当前阶段的完成判定。

必读资源导航

• 设计变量、字体、间距、圆角、暗色模式：references/design-tokens.md
• 场景到组件的安装与代码范式：references/component-map.md
• 多 registry 配置、拉取命令、失败降级：references/registry-guide.md
• 最终工程与视觉验收：assets/quality-checklist.md