@teamix-evo/skills 0.2.0 → 0.4.0

package/src/teamix-evo-design-uni-manager/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: teamix-evo-design-uni-manager
+description: |
+  Apply Uni-Manager design system rules (philosophy, patterns, page-types, brand tone/voice, visual foundations) when AI generates or reviews a full UI screen / page in a Uni-Manager-variant project (专有云 / 混合云 / 云管平台 / hybrid cloud console).
+  TRIGGER when: user asks to "新建 / 优化 / 重构 一个页面"、"做一个列表页 / 详情页 / 表单页 / 仪表盘 / 控制台首页"、"create / review / refactor a page、screen、dashboard、console、admin template"; intent involves layout structure, page-level information density, or multi-component composition for hybrid-cloud / multi-tenant / multi-region scenarios; file write under `src/pages/**` or `src/templates/**`.
+  SKIP: single-component edits like "加个按钮"、"改 input 的 label"; pure tokens/theme overrides; pure code refactor with no visual change; teamix-evo lifecycle commands (defer to teamix-evo-manage).
+  Coordinates with: teamix-evo-code-uni-manager (run alongside when the screen also creates new files).
+---
+
+# teamix-evo-design-uni-manager
+
+> Uni-Manager 设计体系 — 面向 **专有云 / 混合云 / 多租户管控平台** 的现代设计语言。
+> 高信息密度、强一致性、可枚举可审计；视觉以 hybridcloud 蓝（B50 #0064C8）+ 锐利圆角（2px / 4px）为锚。
+>
+> 本技能是 **完整自包含** 的 Uni-Manager 设计规则（非 overlay over OpenTrek）。
+> Token 具体值请参照 `@teamix-evo/tokens/variants/uni-manager/theme.css` 中的 CSS 变量，组件详细 API 通过 MCP `get_component_meta` 按需查询。
+
+<!-- teamix-evo:managed:start id="core" -->
+
+## 意图路由
+
+收到页面相关请求时，按意图分流：
+
+| 意图     | 识别关键词                                                        | 执行路径                                    |
+| -------- | ----------------------------------------------------------------- | ------------------------------------------- |
+| **生成** | "生成" / "创建" / "新建" / "设计一个" / "做一个" / "起一个控制台" | → generation-flow.md 六步流程               |
+| **翻新** | "改造" / "升级" / "翻新" / "对齐规范" / "重新生成"                | → generation-flow.md §翻新路径              |
+| **验证** | "检查" / "验证" / "评估" / "是否符合规范"                         | → checklist.md 逐项对照                     |
+| **查询** | "token" / "色值" / "间距" / "组件尺寸" / "圆角"                   | → foundations.md(MCP `tokens_*` 工具规划中) |
+
+## 三阶段 Dispatch
+
+```
+阶段 ① 确定页面类型
+  → 读 patterns/page-types.md 决策树（含 Console Home / 一致性三件套）
+  → 读 components.md 确认组件集（含 um-topbar 实物归属）
+
+阶段 ② 匹配子类型 + 布局
+  - List / Detail / Form    → patterns/{list|detail|form}-page.md
+  - Dashboard / Console     → patterns/dashboard.md
+  - Dialog/Sheet/Drawer     → 视为复合组件(非页面);走 components.md §3.1 选型
+                              + boundaries.md F8 / F9 / S7 / C2 / FF1-FF4 + UM1-UM3
+  → 读 patterns/page-types.md §6 确认页间流转
+  → 涉及租户/项目/区域切换、跨云资源旅程时读 flows.md（A 资源查找 / B 创建 / C 异常 / D 批量 / E 上下文切换）
+
+阶段 ③ 生成代码
+  → 读 foundations.md (hybridcloud Token 约束 — 锐利圆角 / B50 / 8 档间距)
+  → 读 boundaries.md (硬规则 38 + UM1~UM3 专有云增量)
+  → MCP get_component_meta(id) 查组件 Props
+  → 对照 checklist.md 自检（含 doc 15/16/20 一致性自检）
+```
+
+## 文件索引
+
+| 文件                                                         | 职责                                                                         |
+| ------------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| [philosophy.md](./philosophy.md)                             | 设计哲学 + 四大原则 + 方法论（专有云一致性）                                 |
+| [generation-flow.md](./generation-flow.md)                   | AI 六步生成/翻新/验证流程                                                    |
+| [boundaries.md](./boundaries.md)                             | 硬约束：F/FF/S/C/I + UM 共 41+ 条规则([ERROR]/[WARN])                        |
+| [checklist.md](./checklist.md)                               | 12+ 项自检清单（含 hybridcloud 圆角 / 一致性三件套）                         |
+| [foundations.md](./foundations.md)                           | hybridcloud Token 用法 + 排版 + 8 档间距 + 色彩 + 锐利圆角 + 4 级阴影 + 动效 |
+| [components.md](./components.md)                             | 组件选型决策树 + 双层架构索引 + 组合规则（um-topbar 实物归属）               |
+| [patterns/page-types.md](./patterns/page-types.md)           | 5 种页面类型 + Console Home + 一致性三件套                                   |
+| [patterns/list-page.md](./patterns/list-page.md)             | 列表页模式（多租户 / 多区域筛选）                                            |
+| [patterns/detail-page.md](./patterns/detail-page.md)         | 详情页模式（资源详情 / 跨云资源关联）                                        |
+| [patterns/form-page.md](./patterns/form-page.md)             | 表单页模式（含 wizard / Drawer 内联表单）                                    |
+| [patterns/dashboard.md](./patterns/dashboard.md)             | Dashboard / Console Home（StatCard / Chart 标准结构）                        |
+| [flows.md](./flows.md)                                       | 5 条核心用户旅程 + 上下文切换（租户/项目/区域）                              |
+| [brand.md](./brand.md)                                       | Uni-Manager 品牌调性 + 文案语气 + 正反例（B50 + 锐利风）                     |
+| [rules/README.md](./rules/README.md)                         | boundaries.md ↔ eslint-config 元数据桥说明                                   |
+| [rules/boundaries.rules.json](./rules/boundaries.rules.json) | 41+ 条规则的结构化索引                                                       |
+
+<!-- teamix-evo:managed:end -->

package/src/teamix-evo-design-uni-manager/boundaries.md

@@ -0,0 +1,564 @@
+# 硬约束 · Boundaries
+
+> 本文件列出所有"AI 生成页面 / 组件代码时**不能做什么**"的硬规则。共 41 条规则分 6 组：
+>
+> - **F1-F10**：禁止项（视觉与 token 层面）
+> - **FF1-FF4**：表单专属硬约束（错误信息、必填、状态色块、Card 嵌套）
+> - **S1-S8**：样式规则（className 写法）
+> - **C1-C12**：组件结构规则（shadcn/ui 复合组件用法）
+> - **I1-I4**：图标规则
+> - **UM1-UM3**：Uni-Manager 专有云一致性硬约束（v0.1+，见 ADR 0030）
+>
+> 严重等级：`ERROR` 必须修复，`WARN` 建议修复。
+>
+> **本文件是硬规则的唯一真值**。其他 skill 文件（patterns / components / brand / philosophy）遇到规则引用一律 `[boundaries.md X#]` inline 链接，不复述。
+
+---
+
+## F1-F10 · 禁止项
+
+### [ERROR] F1 · 禁止硬编码色值
+
+```diff
+- <div style={{ color: '#0064C8' }}>...</div>
+- <div className="text-[#0064C8]">...</div>
++ <div className="text-primary">...</div>
+```
+
+使用 CSS 变量引用，参照 [foundations.md](./foundations.md) §色彩。
+
+> 检查: eslint `teamix-evo/no-color-literal` (JSX/TSX 字符串) · stylelint `teamix-evo/no-color-literal` (CSS 声明)
+
+### [ERROR] F2 · 禁止硬编码尺寸
+
+```diff
+- <input className="h-8 text-xs" />
++ <Input />  {/* 组件已封装 token */}
+```
+
+不要绕过组件用 Tailwind 任意值（`h-[32px]` / `text-[12px]`）覆盖默认尺寸。
+
+> 例外：`*-[var(--xxx)]` 形式（CSS 变量包裹的任意值）允许使用，因为变量本身就是 token。详见 [F7]。
+>
+> 检查: eslint `teamix-evo/no-arbitrary-tw-value` (Tailwind className) · stylelint `teamix-evo/no-hardcoded-dimension` (CSS gap/padding/margin/width/height/font-size 等)
+
+### [ERROR] F3 · 禁止按组件新增重复语义变量
+
+新增 CSS 变量前**必须**先检索 `tokens/variants/uni-manager/theme.css`：
+
+- 已有语义匹配的变量 → 直接复用
+- 完全没有可对应变量 → 才允许新增（提交前过 architect subagent 评审）
+
+> 检查: 无 lint (人工评审 / architect subagent)
+
+### [ERROR] F4 · 禁止页头添加底色或下边框 · scope: PageHeader
+
+```diff
+- <PageHeader className="bg-card border-b">
++ <PageHeader>  {/* 透明无底色 */}
+```
+
+> 检查: 无 lint (人工评审 / Storybook visual diff)
+
+### [ERROR] F5 · outline 按钮禁止使用 border-input · scope: Button
+
+```diff
+- <Button variant="outline" className="border-input">
++ <Button variant="outline">  {/* 默认已使用 border-gray-line */}
+```
+
+> 检查: 无 lint (人工评审 / Button.stories visual diff)
+
+### [ERROR] F6 · 禁止直接写 `font-size: 12px`
+
+使用 token：`text-xs` / `text-sm` / `text-base`，或 CSS 变量 `var(--input-font-size)`。
+
+> 检查: stylelint `teamix-evo/no-hardcoded-dimension` (CSS `font-size`) · eslint `teamix-evo/no-arbitrary-tw-value` (Tailwind `text-[12px]`)
+
+### [ERROR] F7 · 语义间距必须走 CSS 变量
+
+```diff
+- <div className="grid gap-4">
++ <div className="grid gap-[var(--card-gap)]">
+```
+
+适用范围：
+
+- **必须用变量**：Card、Tabs、Form、Section 等"具备语义间距"的容器 —— 用 `gap-[var(--card-gap)]` / `gap-[var(--form-gap)]`。
+- **允许用 token 类**：列表、网格、表单内一般行间距等通用容器允许 8 档刻度（`gap-2/4/6` 等已映射 token 的预设类）。
+- **禁止用裸数字任意值**：`gap-[16px]` / `gap-[1rem]` 是 [F2] 禁止的硬编码，永远不允许。
+
+判定关键：`*-[var(--xxx)]` 形态走 token、合规；`*-[16px]` 形态硬编码、违规。
+
+> 检查: eslint `teamix-evo/no-arbitrary-tw-value` · stylelint `teamix-evo/no-hardcoded-dimension`
+
+### [ERROR] F8 · 禁止在 DialogTitle 中加图标 · scope: Dialog
+
+```diff
+- <DialogTitle><AlertIcon /> 永久删除</DialogTitle>
++ <DialogTitle>永久删除</DialogTitle>
+```
+
+标题区只放纯文字。如需视觉提醒，用 `variant="destructive"` 或 DialogDescription 表达。
+
+> 检查: 无 lint (人工评审,可由 reviewer subagent 抽检 Dialog 用法)
+
+### [ERROR] F9 · 弹窗确定按钮禁止加 disabled 禁用态 · scope: Dialog
+
+```diff
+- <Button type="submit" disabled={!isValid}>提交</Button>
++ <Button type="submit">提交</Button>
+{/* 始终可点击，校验后通过 inline error / Toast 反馈 */}
+```
+
+理由：禁用态切断了"为什么不能提交"的反馈链路，改用 inline error 显式说明。
+
+> 检查: 无 lint (UX 评审 / scenario-instantiator subagent)
+
+### [WARN] F10 · hover 时禁止将 boxShadow 设为 undefined · scope: HoverCard
+
+切换 box-shadow 必须保留初始值 + 通过 animation 过渡，否则会引发布局抖动。
+
+> 检查: 无 lint (Storybook hover 交互验证)
+
+---
+
+## FF1-FF4 · 表单专属硬约束
+
+> 来自源仓 `teamix-evo-design/src/form-page.json` 的表单反模式。
+> 注：DialogTitle 不加图标 与 提交按钮不可 disabled 已分别由 [F8] / [F9] 覆盖，本节只收录无重叠的 4 条。
+
+### [ERROR] FF1 · 禁止用色块表达表单状态 · scope: Form
+
+```diff
+- <div className="bg-red-50 border-red-300 p-3">用户名已存在</div>
++ <div className="text-destructive text-sm">用户名已存在</div>
++ {/* 或 */}
++ <Alert variant="destructive">...</Alert>
+```
+
+表单字段错误用 `text-destructive` 文字 + 图标前缀；页面级错误用 `<Alert>`；不要为单字段错误造彩色块。
+
+> 检查: eslint `teamix-evo/no-raw-color-scale` (拦截 `bg-red-50`) · 模式识别需评审
+
+### [WARN] FF2 · Card 不嵌套 Card · scope: Form
+
+```diff
+- <Card>
+-   <Card>
+-     <FieldGroup>...</FieldGroup>
+-   </Card>
+- </Card>
++ <Card>
++   <FieldGroup>...</FieldGroup>
++   <Separator />
++   <FieldGroup>...</FieldGroup>
++ </Card>
+```
+
+白卡是表单页的**单例容器**。分区表单确需嵌入子 Card 时，子 Card 必须有明确边框/阴影差异，且仅限**分区表单**用例（form-page.md §2.3）。
+
+> 检查: 无 lint (人工评审 / reviewer subagent)
+
+### [ERROR] FF3 · 错误信息禁止暴露技术栈痕迹 · scope: Form
+
+```diff
+- <FormMessage>POST /api/users failed: 500 Internal Server Error (stacktrace: ...)</FormMessage>
+- <FormMessage>ERR_DUPLICATE_KEY: violates unique constraint "users_email_key"</FormMessage>
++ <FormMessage>该邮箱已被注册，请换一个或<a>登录</a></FormMessage>
+```
+
+不允许：HTTP status code、stack trace、SQL 错误片段、ORM 异常名。要给的是**用户能采取的下一步行动**。
+
+> 检查: 无 lint (评审 / scenario-instantiator subagent)
+
+### [WARN] FF4 · 必填用红色 `*` 星号，放标签后空格 · scope: Form
+
+```diff
+- <FormLabel>用户名 (required)</FormLabel>
+- <FormLabel>用户名*</FormLabel>
++ <FormLabel required>用户名</FormLabel>
++ {/* 由组件内置渲染 `<span className="text-destructive ml-1">*</span>` */}
+```
+
+不要 "(required)" / "(必填)" 文本；不要把 `*` 紧贴标签。
+
+> 检查: 无 lint (代码评审)
+
+---
+
+## S1-S8 · 样式规则
+
+### [ERROR] S1 · className 仅用于布局，不用于覆盖组件颜色 / 字体
+
+```diff
+- <Button className="bg-blue-100 text-blue-900 font-bold">提交</Button>
++ <Button>提交</Button>
+- <Card className="text-red-500">...</Card>
++ <Card><CardContent className="max-w-md mx-auto">...</CardContent></Card>
+```
+
+className 只允许写**布局相关**类（`flex` / `grid` / `gap-*` / `max-w-*` / `mx-auto`）。
+
+> 检查: eslint `teamix-evo/no-color-literal` + `no-raw-color-scale` 拦截显式颜色覆盖；其余命名覆盖需评审。
+
+### [ERROR] S2 · 不用 `space-x-*` / `space-y-*`，改用 `flex + gap-*`
+
+```diff
+- <div className="space-y-4">
++ <div className="flex flex-col gap-4">
+```
+
+> 检查: eslint `teamix-evo/prefer-gap-over-space`
+
+### [WARN] S3 · 等宽高用 `size-*`，不用 `w-* h-*`
+
+```diff
+- <div className="w-10 h-10">
++ <div className="size-10">
+```
+
+> 检查: 无 lint (代码风格评审)
+
+### [WARN] S4 · 用 `truncate` 简写文本截断
+
+```diff
+- <span className="overflow-hidden text-ellipsis whitespace-nowrap">
++ <span className="truncate">
+```
+
+> 检查: 无 lint (代码风格评审)
+
+### [ERROR] S5 · 不用手动 `dark:` 颜色覆盖，用语义 token
+
+```diff
+- <div className="bg-white dark:bg-gray-950 text-black dark:text-white">
++ <div className="bg-background text-foreground">
+```
+
+CSS 变量已在 dark 模式下自动切换（uni-manager `theme.css` 内置）。
+
+> 检查: eslint `teamix-evo/no-manual-dark-classnames`
+
+### [ERROR] S6 · 用 `cn()` 处理条件类名，不用模板字符串三元
+
+```diff
+- className={`flex ${isActive ? 'bg-primary' : 'bg-muted'}`}
++ className={cn('flex', isActive ? 'bg-primary text-primary-foreground' : 'bg-muted')}
+```
+
+> 检查: 无 lint (代码评审 / 后续可加 ESLint 规则)
+
+### [ERROR] S7 · overlay 组件不手动设置 z-index
+
+```diff
+- <Dialog><DialogContent className="z-50">
++ <Dialog><DialogContent>
+```
+
+适用：`Dialog / Sheet / Drawer / Popover / Tooltip / DropdownMenu / HoverCard`。
+
+> 检查: 无 lint (运行时 / 评审)
+
+### [ERROR] S8 · 不用原始色值表示状态
+
+```diff
+- <span className="text-emerald-600">运行中</span>
++ <Badge variant="success">运行中</Badge>
+
+- <span className="text-red-500">异常</span>
++ <Badge variant="destructive">异常</Badge>
+```
+
+> 检查: eslint `teamix-evo/no-raw-color-scale`
+
+---
+
+## C1-C12 · 组件结构规则
+
+### [ERROR] C1 · Item 必须在 Group 内
+
+适用：`SelectItem / DropdownMenuItem / CommandItem / MenubarItem / ContextMenuItem`
+
+```diff
+- <SelectContent>
+-   <SelectItem value="a">Apple</SelectItem>
+- </SelectContent>
++ <SelectContent>
++   <SelectGroup>
++     <SelectItem value="a">Apple</SelectItem>
++   </SelectGroup>
++ </SelectContent>
+```
+
+| Item                                     | Group               |
+| ---------------------------------------- | ------------------- |
+| `SelectItem` / `SelectLabel`             | `SelectGroup`       |
+| `DropdownMenuItem` / `DropdownMenuLabel` | `DropdownMenuGroup` |
+| `CommandItem`                            | `CommandGroup`      |
+| `MenubarItem`                            | `MenubarGroup`      |
+| `ContextMenuItem`                        | `ContextMenuGroup`  |
+
+> 检查: 无 lint (后续可加 ESLint JSX 结构规则)
+
+### [ERROR] C2 · Dialog / Sheet / Drawer 必须有 Title
+
+```diff
+- <DialogContent>...</DialogContent>
++ <DialogContent>
++   <DialogHeader>
++     <DialogTitle>编辑配置</DialogTitle>
++     <DialogDescription>修改资源参数</DialogDescription>
++   </DialogHeader>
++   ...
++ </DialogContent>
+```
+
+无障碍要求。如视觉上不需要标题，用 `<VisuallyHidden>` 或 sr-only 包裹但保留语义。
+
+> 检查: eslint `teamix-evo/dialog-must-have-title`
+
+### [WARN] C3 · Card 用完整结构
+
+```diff
+- <Card><CardContent>标题 + 内容 + 操作</CardContent></Card>
++ <Card>
++   <CardHeader>
++     <CardTitle>团队成员</CardTitle>
++     <CardDescription>管理团队访问权限</CardDescription>
++   </CardHeader>
++   <CardContent>...</CardContent>
++   <CardFooter><Button>邀请</Button></CardFooter>
++ </Card>
+```
+
+### [ERROR] C4 · Button 用 Spinner + disabled 组合表达 loading
+
+```diff
+- <Button isPending>保存中...</Button>
++ <Button disabled><Spinner data-icon="inline-start" /> 保存中...</Button>
+```
+
+或直接用 `<Button loading>`。
+
+### [ERROR] C5 · TabsTrigger 必须在 TabsList 内
+
+```diff
+- <Tabs><TabsTrigger value="a">账户</TabsTrigger></Tabs>
++ <Tabs defaultValue="account">
++   <TabsList>
++     <TabsTrigger value="account">账户</TabsTrigger>
++   </TabsList>
++   <TabsContent value="account">...</TabsContent>
++ </Tabs>
+```
+
+### [WARN] C6 · Avatar 必须有 AvatarFallback
+
+```diff
+- <Avatar><AvatarImage src="/avatar.png" /></Avatar>
++ <Avatar>
++   <AvatarImage src="/avatar.png" alt="User" />
++   <AvatarFallback>JD</AvatarFallback>
++ </Avatar>
+```
+
+### [WARN] C7 · 提示用 Alert，不用自定义 div
+
+```diff
+- <div className="border border-red-500 p-4">Warning...</div>
++ <Alert variant="destructive">
++   <AlertTitle>警告</AlertTitle>
++   <AlertDescription>需要关注的内容</AlertDescription>
++ </Alert>
+```
+
+### [WARN] C8 · 空状态用 Empty 组件
+
+```diff
+- <div className="flex flex-col items-center p-8">
+-   <p>暂无数据</p>
+-   <Button>创建</Button>
+- </div>
++ <Empty>
++   <EmptyHeader>
++     <EmptyTitle>暂无实例</EmptyTitle>
++     <EmptyDescription>创建第一个实例以开始</EmptyDescription>
++   </EmptyHeader>
++   <EmptyContent><Button>创建实例</Button></EmptyContent>
++ </Empty>
+```
+
+### [WARN] C9 · Toast 用 sonner
+
+```diff
+- alert("Changes saved");
++ import { toast } from "sonner";
++ toast.success("已保存修改");
+```
+
+### [WARN] C10 · 分隔线用 Separator
+
+```diff
+- <hr />
+- <div className="border-t" />
++ <Separator />
+```
+
+### [WARN] C11 · 加载占位用 Skeleton
+
+```diff
+- <div className="animate-pulse bg-gray-200 h-4 w-3/4" />
++ <Skeleton className="h-4 w-3/4" />
+```
+
+### [WARN] C12 · 标签 / 状态用 Badge
+
+```diff
+- <span className="rounded-full bg-green-100 text-green-800">运行中</span>
++ <Badge variant="success">运行中</Badge>
+```
+
+---
+
+## I1-I4 · 图标规则
+
+### [ERROR] I1 · 按钮内图标用 data-icon 属性定位
+
+```diff
+- <Button><SearchIcon className="mr-2 size-4" /> 搜索</Button>
++ <Button><SearchIcon data-icon="inline-start" /> 搜索</Button>
++ <Button>下一步 <ArrowRightIcon data-icon="inline-end" /></Button>
+```
+
+### [ERROR] I2 · 组件内图标不设尺寸类
+
+适用：`Button` / `DropdownMenuItem` / `Alert` / `Sidebar*`
+
+```diff
+- <Button><SettingsIcon className="mr-2 size-4" /></Button>
++ <Button><SettingsIcon /></Button>
+```
+
+### [ERROR] I3 · 图标作为组件对象传递
+
+```diff
+- const iconMap = { check: CheckIcon };
+- <StatusBadge icon="check" />
++ function StatusBadge({ icon: Icon }) { return <Icon /> }
++ <StatusBadge icon={CheckIcon} />
+```
+
+### [ERROR] I4 · 按项目配置的 iconLibrary 导入
+
+`@teamix-evo/ui` Uni-Manager 变体默认使用 `lucide-react`。如项目切换图标库，遵循 `tokens.overrides.css` 中的 `--icon-library` 配置。
+
+> 检查: eslint `teamix-evo/icon-from-lucide`
+
+---
+
+## UM1-UM3 · Uni-Manager 专有云一致性硬约束
+
+> 来自 ADR 0030 / Teamix-UI 规范 doc 15-16-20。这三条是 uni-manager 区别于 opentrek 的核心硬约束，与"一致性是云管平台生命线"的哲学主张呼应（philosophy.md §1）。
+
+### [ERROR] UM1 · 全局 topbar 必须使用 um-topbar 实物 · scope: uni-manager
+
+```diff
+- export default function Layout() {
+-   return (
+-     <>
+-       <header className="flex justify-between p-4 border-b">
+-         <Logo /> <UserMenu />
+-       </header>
+-       <main>{children}</main>
+-     </>
+-   );
+- }
++ import { UmTopbar } from '@teamix-evo/biz-ui/uni-manager';
++ export default function Layout() {
++   return (
++     <>
++       <UmTopbar />
++       <main>{children}</main>
++     </>
++   );
++ }
+```
+
+理由：um-topbar 内置 ContextSwitcher（租户/项目/区域）+ Logo + 用户菜单 + 全局通知，是 uni-manager "一致性三件套"之一（brand.md §3.2）。自建 topbar 会破坏跨页面一致性，并丢失 ContextSwitcher 全局可达性（违反 flows.md §1.E 上下文切换旅程）。
+
+> 检查: 无 lint (代码评审 / reviewer subagent 抽检 Layout 组件)
+
+### [ERROR] UM2 · PageHeader 必须保持一致性结构 · scope: uni-manager
+
+```diff
+- <div className="flex justify-between mb-4">
+-   <h1 className="text-3xl font-bold">实例列表</h1>
+-   <div><Button>新建</Button></div>
+- </div>
++ <PageHeader
++   title="实例列表"
++   breadcrumb={[{ label: '云资源' }, { label: '实例' }]}
++   actions={<Button>创建实例</Button>}
++ />
+```
+
+铁律（与 OpenTrek 共享，但 uni-manager 强化）：
+
+- 标题字号统一 `text-2xl`（24px），不允许业务页用 `text-3xl` 自我突出
+- 面包屑紧贴标题左侧，操作按钮组统一靠右
+- L1 页面用 `title` 模式（仅标题）；L2 页面用 `breadcrumb` 模式
+- 不允许在 PageHeader 内部添加底色 / 下边框（与 F4 一致）
+
+> 检查: 无 lint (代码评审 / Storybook visual diff)
+
+### [ERROR] UM3 · 跨云资源列表必须标注 cloud-provider · scope: uni-manager
+
+```diff
+- <DataTable
+-   columns={[
+-     { key: 'id', title: '实例 ID' },
+-     { key: 'region', title: '区域' },
+-     { key: 'status', title: '状态' },
+-   ]}
+- />
++ <DataTable
++   columns={[
++     { key: 'id', title: '实例 ID', render: (v) => <Mono copyable>{v}</Mono> },
++     { key: 'cloud', title: '所属云', render: (v) => <CloudBadge provider={v} /> },
++     { key: 'region', title: '区域' },
++     { key: 'status', title: '状态', render: (v) => <Badge variant={v} /> },
++   ]}
++ />
+```
+
+理由：uni-manager 默认场景就是多云，列表中混合阿里云 / 腾讯云 / AWS / 私有 IDC 资源是常态。不标注归属会让用户产生"这是哪朵云的实例"的认知断裂。
+
+例外：明确单云场景（如 `tenant.cloudProviders.length === 1`）可去除该列，但 FilterBar 中仍需保留 cloud 筛选项。
+
+> 检查: 无 lint (人工评审 / scenario-instantiator subagent)
+
+---
+
+## Overlay 组件选型表
+
+| 场景                   | 组件                                |
+| ---------------------- | ----------------------------------- |
+| 需要输入的任务         | `Dialog`                            |
+| 危险操作确认           | `AlertDialog variant="destructive"` |
+| 侧面板（详情 / 筛选）  | `Sheet`                             |
+| 移动端底部面板         | `Drawer`                            |
+| 悬浮信息（hover 触发） | `HoverCard`                         |
+| 点击弹出小内容         | `Popover`                           |
+
+---
+
+## 自定义优先级
+
+需要差异化样式时按以下优先级：
+
+1. **优先**：内置 `variant`（如 `variant="outline"` / `variant="destructive"`）
+2. **其次**：语义 token（如 `bg-primary` / `text-muted-foreground`）
+3. **最后**：CSS 变量覆盖（在 `tokens.overrides.css` 中定义）
+
+**严禁**：直接 className 覆盖颜色 / 字号 / 尺寸（违反 S1）。