@teamix-evo/skills 0.3.0 → 0.4.0

package/src/teamix-evo-design-opentrek/boundaries.md

@@ -0,0 +1,513 @@
+# 硬约束 · Boundaries
+
+> 本文件列出所有"AI 生成页面 / 组件代码时**不能做什么**"的硬规则。共 38 条规则分 5 组：
+>
+> - **F1-F10**：禁止项（视觉与 token 层面）
+> - **FF1-FF4**：表单专属硬约束（错误信息、必填、状态色块、Card 嵌套）
+> - **S1-S8**：样式规则（className 写法）
+> - **C1-C12**：组件结构规则（shadcn/ui 复合组件用法）
+> - **I1-I4**：图标规则
+>
+> 严重等级：`ERROR` 必须修复，`WARN` 建议修复。
+>
+> **本文件是硬规则的唯一真值**。其他 skill 文件（patterns / components / brand / philosophy）遇到规则引用一律 `[boundaries.md X#]` inline 链接,不复述。
+
+---
+
+## F1-F10 · 禁止项
+
+### [ERROR] F1 · 禁止硬编码色值
+
+```diff
+- <div style={{ color: '#333333' }}>...</div>
+- <div className="text-[#333333]">...</div>
++ <div className="text-foreground">...</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/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 类**：列表、网格、表单内一般行间距等通用容器允许 `gap-2/4/6`（这些是 Tailwind 已映射 token 的预设类，不是任意值）。
+- **禁止用裸数字任意值**：`gap-[16px]` / `gap-[1rem]` 是 [F2] 禁止的硬编码，永远不允许。
+
+判定关键：`*-[var(--xxx)]` 形态走 token、合规；`*-[16px]` 形态硬编码、违规。
+
+> 检查: eslint `teamix-evo/no-arbitrary-tw-value` (Tailwind `gap-[16px]`,`*-[var(--…)]` 是允许的例外) · stylelint `teamix-evo/no-hardcoded-dimension` (CSS `gap`/`row-gap`/`column-gap`)
+
+### [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 不加图标(源仓 F6) 与 提交按钮不可 disabled(源仓 F2) 已分别由 [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>`;不要为单字段错误造彩色块,会与 Dialog 内主色冲突且增加视觉噪音。
+
+> 检查: 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>
+```
+
+白卡是表单页的**单例容器**(参 [list-page.md §9 嵌套约束](./patterns/list-page.md#9-嵌套约束) / [form-page.md §9](./patterns/form-page.md#9-嵌套约束))。分区表单确需嵌入子 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: at UserService.create...)</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>用户名 <span className="text-destructive">*</span></FormLabel>
++ {/* 推荐用项目封装的 <RequiredMark /> 或 FormLabel required={true} */}
+```
+
+不要 "(required)" / "(必填)" 文本,会增加阅读宽度;不要把 `*` 紧贴标签(影响 OCR / 截屏识别)。
+
+> 检查: 无 lint (代码评审)
+
+---
+
+## S1-S8 · 样式规则
+
+### [ERROR] S1 · className 仅用于布局，不用于覆盖组件颜色 / 字体
+
+```diff
+- <Button className="bg-blue-100 text-blue-900 font-bold">提交</Button>
++ <Button>提交</Button>  {/* 用 variant，不用 className 强改色 */}
+- <Card className="text-red-500">...</Card>
++ <Card><CardContent className="max-w-md mx-auto">...</CardContent></Card>
+```
+
+className 只允许写**布局相关**类（`flex` / `grid` / `gap-*` / `max-w-*` / `mx-auto` / `space-*`）。
+
+> 检查: 部分覆盖 — eslint `teamix-evo/no-color-literal` (色值字面量) + `teamix-evo/no-raw-color-scale` (Tailwind 色阶) 拦截显式颜色覆盖;字号/尺寸覆盖由 `no-arbitrary-tw-value` 处理。其余命名覆盖需评审。
+
+### [ERROR] S2 · 不用 `space-x-*` / `space-y-*`，改用 `flex + gap-*`
+
+```diff
+- <div className="space-y-4">
++ <div className="flex flex-col gap-4">
+```
+
+理由：space-_ 通过 margin 实现，会与第一项的外边距产生冲突；gap-_ 在 flex / grid 容器内统一管理。
+
+> 检查: 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 模式下自动切换。手动 `dark:` 会绕过主题系统，破坏一致性。
+
+> 检查: 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')}
+```
+
+`cn()` 来自 `@teamix-evo/ui` 工具函数，自动处理 tailwind-merge 冲突。
+
+> 检查: 无 lint (代码评审 / 后续可加 ESLint 规则)
+
+### [ERROR] S7 · overlay 组件不手动设置 z-index
+
+```diff
+- <Dialog><DialogContent className="z-50">
++ <Dialog><DialogContent>
+```
+
+适用：`Dialog / Sheet / Drawer / Popover / Tooltip / DropdownMenu / HoverCard`。组件自带层级管理。
+
+> 检查: 无 lint (运行时 / 评审,可由 reviewer subagent 抽检)
+
+### [ERROR] S8 · 不用原始色值表示状态
+
+```diff
+- <span className="text-emerald-600">+20.1%</span>
++ <Badge variant="secondary">+20.1%</Badge>
+
+- <span className="text-red-500">-3.2%</span>
++ <span className="text-destructive">-3.2%</span>
+```
+
+状态信息一律走语义 token / Badge variant。
+
+> 检查: eslint `teamix-evo/no-raw-color-scale` (拦截 `text-emerald-600` 等原始色阶)
+
+---
+
+## 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 结构规则,目前由 reviewer subagent 抽检)
+
+### [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>
+```
+
+> 检查: 无 lint (人工评审)
+
+### [ERROR] C4 · Button 用 Spinner + disabled 组合表达 loading
+
+```diff
+- <Button isPending>保存中...</Button>
++ <Button disabled><Spinner data-icon="inline-start" /> 保存中...</Button>
+```
+
+或直接用 `<Button loading>` —— `@teamix-evo/ui` Button 已封装 loading prop。
+
+> 检查: 无 lint (代码评审 / Storybook 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>
+```
+
+> 检查: 无 lint (后续可加 JSX 结构规则)
+
+### [WARN] C6 · Avatar 必须有 AvatarFallback
+
+```diff
+- <Avatar><AvatarImage src="/avatar.png" /></Avatar>
++ <Avatar>
++   <AvatarImage src="/avatar.png" alt="User" />
++   <AvatarFallback>JD</AvatarFallback>
++ </Avatar>
+```
+
+> 检查: 无 lint (代码评审)
+
+### [WARN] C7 · 提示用 Alert，不用自定义 div
+
+```diff
+- <div className="border border-red-500 p-4">Warning...</div>
++ <Alert variant="destructive">
++   <AlertTitle>警告</AlertTitle>
++   <AlertDescription>需要关注的内容</AlertDescription>
++ </Alert>
+```
+
+> 检查: eslint `teamix-evo/no-color-literal` + `no-raw-color-scale` 拦截"自定义警示框"的色值,但容器结构需评审
+
+### [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>
+```
+
+> 检查: 无 lint (代码评审)
+
+### [WARN] C9 · Toast 用 sonner
+
+```diff
+- alert("Changes saved");
+- 自定义 toast 组件
++ import { toast } from "sonner";
++ toast.success("已保存修改");
+```
+
+> 检查: 无 lint (依赖审计 / 代码评审)
+
+### [WARN] C10 · 分隔线用 Separator
+
+```diff
+- <hr />
+- <div className="border-t" />
++ <Separator />
+```
+
+> 检查: 无 lint (代码评审)
+
+### [WARN] C11 · 加载占位用 Skeleton
+
+```diff
+- <div className="animate-pulse bg-gray-200 h-4 w-3/4" />
++ <Skeleton className="h-4 w-3/4" />
+```
+
+> 检查: eslint `teamix-evo/no-raw-color-scale` 部分覆盖 (拦截 `bg-gray-200`),但模式识别仍需评审
+
+### [WARN] C12 · 标签 / 状态用 Badge
+
+```diff
+- <span className="rounded-full bg-green-100 text-green-800">Active</span>
++ <Badge variant="secondary">Active</Badge>
+```
+
+> 检查: eslint `teamix-evo/no-raw-color-scale` (拦截 `bg-green-100` / `text-green-800`)
+
+---
+
+## 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>
+```
+
+> 检查: 无 lint (代码评审,可由 reviewer subagent 抽检 Button 内图标)
+
+### [ERROR] I2 · 组件内图标不设尺寸类
+
+适用：`Button` / `DropdownMenuItem` / `Alert` / `Sidebar*`
+
+```diff
+- <Button><SettingsIcon className="mr-2 size-4" /></Button>
++ <Button><SettingsIcon /></Button>  {/* 组件 CSS 控制尺寸 */}
+```
+
+> 检查: 无 lint (Button/Item 容器内 icon 尺寸由 component CSS 强制,代码评审)
+
+### [ERROR] I3 · 图标作为组件对象传递
+
+```diff
+- const iconMap = { check: CheckIcon };
+- <StatusBadge icon="check" />
++ function StatusBadge({ icon: Icon }) { return <Icon /> }
++ <StatusBadge icon={CheckIcon} />
+```
+
+> 检查: 无 lint (API 设计评审)
+
+### [ERROR] I4 · 按项目配置的 iconLibrary 导入
+
+`@teamix-evo/ui` OpenTrek 变体默认使用 `lucide-react`。如项目切换图标库，遵循 `tokens.overrides.css` 中的 `--icon-library` 配置。
+
+> 检查: eslint `teamix-evo/icon-from-lucide` (拦截 import 自非配置图标库)
+
+---
+
+## 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）。

package/src/teamix-evo-design-opentrek/brand.md

@@ -0,0 +1,154 @@
+# Brand — OpenTrek 视觉调性 + 文案语气 + 正反例
+
+> OpenTrek 服务于运维与平台管理场景。本文是品牌定标尺：所有视觉、文案决策不应越过这里定义的边界。
+
+---
+
+## 1. 视觉风格五维
+
+| 维度         | 定位     | 具体表现                                | 对立面（禁止）       |
+| ------------ | -------- | --------------------------------------- | -------------------- |
+| **色彩情绪** | 沉稳专业 | 深色底色为主基调 + 高对比度信息层级     | 花哨多彩、渐变堆叠   |
+| **信息密度** | 高效紧凑 | 单屏承载核心操作，减少翻页              | 大面积留白、装饰占位 |
+| **视觉层次** | 克制有序 | 间距、字重、色彩建立 3 级层级           | 多重强调、全部高亮   |
+| **交互反馈** | 即时确定 | 操作后 200ms 内明确反馈                 | 模糊状态、静默       |
+| **圆角风格** | 轻圆角   | `rounded-md` (6px) / `rounded-lg` (8px) | 全直角、超大圆角     |
+
+---
+
+## 2. 情感矩阵
+
+```
+可信赖 ████████████████████ 95%   ← 不可让步
+高效率 ███████████████████░ 90%   ← 不可让步
+专业感 ██████████████████░░ 85%
+现代感 ████████████████░░░░ 75%
+亲和力 ███████████░░░░░░░░░ 55%   ← 次要，不刻意追求
+趣味性 ████░░░░░░░░░░░░░░░░ 20%   ← 极度克制
+```
+
+> "可信赖" 与 "高效率" 是不能让步的两根支柱。"亲和力" 与 "趣味性" 刻意低，避免在严肃场景产生轻浮感。
+
+---
+
+## 3. 品牌个性
+
+| 特征     | 描述                           | 设计映射                       |
+| -------- | ------------------------------ | ------------------------------ |
+| **稳定** | 云基础设施核心诉求是"不出问题" | 一致的布局骨架、可预期的交互   |
+| **透明** | 用户需要知道系统正在做什么     | 状态指示器、进度反馈、操作确认 |
+| **掌控** | 管理员需要"全局在握"的感觉     | 数据概览、筛选能力、批量操作   |
+| **专注** | 运维操作容错率低               | 清晰的信息层级、防误操作确认   |
+
+### Moodboard 参考
+
+- 开发者控制台：Vercel、Linear、Datadog、PlanetScale
+- 现代企业 SaaS：Notion Admin、Stripe Dashboard
+- 工程化文档：Tailwind / shadcn / Radix UI Docs
+
+---
+
+## 4. 文案语气总体风格
+
+> **精确 > 友好。简短 > 完整。可执行 > 可理解。**
+>
+> 不卖萌、不感叹、不"恭喜你"。所有文案以**"是否帮助用户做下一步决策"**为唯一评价标准。
+
+### 4.1 语气矩阵
+
+| 场景        | 语气             | ✅ 正例                            | ❌ 反例                |
+| ----------- | ---------------- | ---------------------------------- | ---------------------- |
+| 标题 / 导航 | 名词、定语短句   | "实例列表" / "安全组规则"          | "你的实例们"           |
+| 引导说明    | 简洁、可执行     | "选择资源后，可执行批量操作"       | "快来选个资源试试吧～" |
+| 主操作按钮  | 动宾结构、≤ 5 字 | "创建实例" / "释放资源"            | "去创建一个新的实例"   |
+| 危险按钮    | 名词 + 动作      | "永久删除" / "立即停机"            | "确认" / "OK"          |
+| 错误提示    | 具体原因 + 建议  | "实例正在运行中，请先停止后再删除" | "操作失败，请重试"     |
+| 成功反馈    | 已完成的事实     | "已释放 3 个实例"                  | "操作成功！🎉"         |
+| 空状态      | 解释 + 入口      | "暂无实例。创建第一个实例以开始"   | "这里空空如也～"       |
+| 加载提示    | 进行时           | "正在加载实例…"                    | "马上就好~"            |
+
+### 4.2 写作规范
+
+1. **动词在前** — 按钮以动词开头：「创建项目」非「项目创建」
+2. **避免歧义** — 「删除」与「释放」严格区分（删除不可恢复 / 释放进入回收站）
+3. **不省略主语** — 错误信息指出"什么"出错：「实例 i-xxx 启动失败」非「启动失败」
+4. **量词精确** — "已删除 3 项" 而非 "已删除几项"
+5. **主动语态** — "系统已保存配置" 而非 "配置已被系统保存"
+
+### 4.3 标点与排版
+
+- 按钮文字 / 表头标签：**不加**句号
+- 描述、提示、说明：**完整句子** + 句号
+- 列表项格式统一（全加句号 或 全不加）
+- 中英文 / 中数字之间加 1 空格：`已选 3 项 / 共 128 项`
+- 数字使用半角；区间用 `~`（中文）/ `–`（英文）
+- 时间格式统一：`2026-05-14 10:23:45`（ISO-like）
+
+---
+
+## 5. 危险操作专用文案（硬约束）
+
+破坏性操作（删除、释放、强制重启）必须满足：
+
+| 元素                 | 规则             | 示例                                                                      |
+| -------------------- | ---------------- | ------------------------------------------------------------------------- |
+| **AlertDialog 标题** | 陈述句而非疑问句 | ✅「永久删除实例 i-xxx」 ❌「确定要删除吗？」                             |
+| **正文**             | 列出具体后果     | ✅「该实例的数据盘将被释放且不可恢复。关联的快照（共 2 个）将一并删除。」 |
+| **确认按钮**         | 重复动作动词     | ✅「永久删除」 ❌「确认」                                                 |
+| **取消按钮**         | 用「取消」       | ❌「不」/「再想想」                                                       |
+
+---
+
+## 6. AI 场景文案规则
+
+AI 助手在生成回复时遵循：
+
+- **不使用**第一人称「我」（避免拟人化）→ 用「OpenTrek AI」或省略主语
+- 操作建议必须给出**确定性** + **量化影响**：「建议将实例规格升级至 ecs.g7.large（预计成本 +¥120/月）」
+- 不确定时**明确表达**：「此问题可能由 A、B 两个原因引起，建议先排查 A」
+- 拒绝执行不可逆操作时给出明确原因 + 替代路径
+
+---
+
+## 7. 视觉正反例对照
+
+### 7.1 布局
+
+| ✅ 正例                                                          | ❌ 反例                                  |
+| ---------------------------------------------------------------- | ---------------------------------------- |
+| ListPage 搜索/筛选固定顶部，表格自适应高度，分页固定底部         | 同一页面同时使用左右两套 Sidebar         |
+| 表单左对齐标签，字段按"必填 → 可选"排序，主操作右下角            | 主操作按钮放在一屏之外（需滚动才能看到） |
+| 详情页 Tab 顺序：基本信息 → 监控 → 配置 → 操作日志（按使用频率） | 表单字段按字母顺序排序（忽略业务优先级） |
+
+### 7.2 色彩
+
+| ✅ 正确                                                              | ❌ 错误                              |
+| -------------------------------------------------------------------- | ------------------------------------ |
+| 主色仅用于主行动点（CTA 按钮、当前选中项、品牌标识）                 | 用主色表示"错误"状态                 |
+| 状态色：`destructive` = 错误/删除；绿/黄按业务语义；图表用 `chart-*` | 把 `destructive` 红色用在 Tab 选中态 |
+| 暗色模式直接切换 CSS 变量，不重写组件                                | 同一页面 4 种以上"重要"按钮颜色      |
+
+### 7.3 动效
+
+| ✅ 正确                                                  | ❌ 错误                                                |
+| -------------------------------------------------------- | ------------------------------------------------------ |
+| Hover 色彩切换 `transition-colors duration-150 ease-out` | 给 width / height / margin 加过渡（性能差 + 布局抖动） |
+| 弹窗入场 `zoom-in-95 + fade-in` 300ms                    | 整页加载用复杂 Loader + 进度条（用 Skeleton 即可）     |
+| Skeleton 占位 → 数据到达后 `fade-in`                     | 微交互动效超过 200ms（hover 不应让用户等待）           |
+
+### 7.4 圆角与阴影对应表
+
+> **完整对应表见 [foundations.md §6.3 圆角 × 阴影对应表](./foundations.md#63-圆角--阴影对应表)** — 圆角与阴影必须同档对应,这是 foundations 层的语义归一规则,brand 层不再重复。
+
+---
+
+## 8. 品牌自检
+
+- [ ] 文案动词在前，按钮 ≤ 5 字
+- [ ] 错误提示含主语 + 原因 + 建议
+- [ ] 危险操作 AlertDialog 标题用陈述句、按钮用动作动词
+- [ ] 不出现 emoji 表情、感叹号过多、拟人化主语「我」
+- [ ] 主色仅用于 CTA 与当前选中态，不滥用
+- [ ] 圆角阴影同档对应（rounded-md ↔ shadow-sm ↔ rounded-lg ↔ shadow-md/xl）
+- [ ] 动效仅 transition-colors / opacity / transform，禁 width/height/margin
+- [ ] 中英文之间有空格，时间格式统一 ISO-like