规范：确立黑金前端设计标准

2026-07-22 15:00:18 +08:00 · 2026-07-22 15:00:18 +08:00 · 5d20c18ec7
commit 5d20c18ec7
parent 488812c083
3 changed files with 603 additions and 0 deletions
--- a/.impeccable/design.json
+++ b/.impeccable/design.json
@ -0,0 +1,279 @@
+{
+  "schemaVersion": 2,
+  "generatedAt": "2026-07-22T14:59:56+08:00",
+  "title": "Design System: CaiWuXiTong",
+  "extensions": {
+    "colorMeta": {
+      "rail-black": {
+        "role": "neutral",
+        "displayName": "工具轨道黑",
+        "canonical": "#050506",
+        "tonalRamp": ["#050506", "#101011", "#1D1D1F", "#2A2927", "#424242", "#7B7B7B", "#D0D0D0", "#F6F6F6"]
+      },
+      "rail-gold": {
+        "role": "primary",
+        "displayName": "工具轨道浅金",
+        "canonical": "#F2E7C5",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#E1CF9D", "#F0E4BF", "#F2E7C5"]
+      },
+      "sidebar-black": {
+        "role": "neutral",
+        "displayName": "功能栏浅黑",
+        "canonical": "#1D1D1F",
+        "tonalRamp": ["#050506", "#101011", "#1D1D1F", "#2A2927", "#424242", "#7B7B7B", "#D0D0D0", "#F6F6F6"]
+      },
+      "sidebar-gold": {
+        "role": "primary",
+        "displayName": "功能栏米白金",
+        "canonical": "#F0E4BF",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#DDD0AA", "#F0E4BF", "#F7F0DE"]
+      },
+      "sidebar-gold-soft": {
+        "role": "primary",
+        "displayName": "功能栏柔金",
+        "canonical": "#DDD0AA",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#CDB474", "#DDD0AA", "#F7F0DE"]
+      },
+      "sidebar-active": {
+        "role": "neutral",
+        "displayName": "活动浅黑",
+        "canonical": "#2A2927",
+        "tonalRamp": ["#050506", "#101011", "#1D1D1F", "#2A2927", "#424242", "#7B7B7B", "#D0D0D0", "#F6F6F6"]
+      },
+      "content-bg": {
+        "role": "neutral",
+        "displayName": "内容浅灰",
+        "canonical": "#F8F6F1",
+        "tonalRamp": ["#171717", "#2A2927", "#595959", "#8C887F", "#BDB7AB", "#D8D2C7", "#EEE9DF", "#F8F6F1"]
+      },
+      "surface": {
+        "role": "neutral",
+        "displayName": "业务白色表面",
+        "canonical": "#FFFFFF",
+        "tonalRamp": ["#171717", "#424242", "#7D7D7D", "#AFAFAF", "#D8D2C7", "#EEE9DF", "#F8F6F1", "#FFFFFF"]
+      },
+      "content-ink": {
+        "role": "neutral",
+        "displayName": "正文墨色",
+        "canonical": "#171717",
+        "tonalRamp": ["#171717", "#2A2927", "#424242", "#595959", "#7D7D7D", "#AFAFAF", "#D8D2C7", "#F8F6F1"]
+      },
+      "content-muted": {
+        "role": "neutral",
+        "displayName": "辅助墨色",
+        "canonical": "#595959",
+        "tonalRamp": ["#171717", "#2A2927", "#424242", "#595959", "#7D7D7D", "#AFAFAF", "#D8D2C7", "#F8F6F1"]
+      },
+      "content-accent": {
+        "role": "primary",
+        "displayName": "VIP 金",
+        "canonical": "#B9954F",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#E1CF9D", "#F7F0DE", "#FBF8F1"]
+      },
+      "content-accent-soft": {
+        "role": "primary",
+        "displayName": "淡金底色",
+        "canonical": "#F7F0DE",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#E1CF9D", "#F7F0DE", "#FBF8F1"]
+      },
+      "content-accent-dark": {
+        "role": "primary",
+        "displayName": "可读深金",
+        "canonical": "#856632",
+        "tonalRamp": ["#513E21", "#6A5129", "#856632", "#A17D3E", "#B9954F", "#E1CF9D", "#F7F0DE", "#FBF8F1"]
+      },
+      "border": {
+        "role": "neutral",
+        "displayName": "暖灰边界",
+        "canonical": "#D8D2C7",
+        "tonalRamp": ["#2A2927", "#595959", "#8C887F", "#AFA99E", "#BDB7AB", "#D8D2C7", "#EEE9DF", "#F8F6F1"]
+      },
+      "success": {
+        "role": "semantic",
+        "displayName": "成功深绿",
+        "canonical": "#53793E",
+        "tonalRamp": ["#364F28", "#426131", "#53793E", "#63914A", "#6EA152", "#9ABD86", "#DBE8D4", "#F8FAF6"]
+      },
+      "danger": {
+        "role": "semantic",
+        "displayName": "危险深红",
+        "canonical": "#B80000",
+        "tonalRamp": ["#640000", "#7A0000", "#990000", "#B80000", "#CC0000", "#DB4D4D", "#F2BFBF", "#FCF2F2"]
+      },
+      "warning": {
+        "role": "semantic",
+        "displayName": "警告深橙",
+        "canonical": "#935F07",
+        "tonalRamp": ["#784D05", "#935F07", "#B87708", "#DD8E0A", "#F59E0B", "#F8BB54", "#FDE7C2", "#FFFAF3"]
+      },
+      "info": {
+        "role": "semantic",
+        "displayName": "信息深蓝",
+        "canonical": "#006395",
+        "tonalRamp": ["#003651", "#004264", "#00537D", "#006395", "#006EA6", "#4D9AC1", "#BFDBE9", "#F2F8FB"]
+      }
+    },
+    "typographyMeta": {
+      "title": {
+        "displayName": "页面与一级导航标题",
+        "purpose": "右侧页面标题和一级导航，固定 14px，不随视口流体缩放。"
+      },
+      "body": {
+        "displayName": "业务正文",
+        "purpose": "表单、说明、按钮和常规业务文字。"
+      },
+      "label": {
+        "displayName": "字段与二级导航标签",
+        "purpose": "筛选字段、状态标签和二级菜单，固定 12px。"
+      },
+      "data": {
+        "displayName": "表格与金额数据",
+        "purpose": "表格、金额、数量和比例，使用等宽数字并按数据类型对齐。"
+      }
+    },
+    "shadows": [
+      {
+        "name": "surface-low",
+        "value": "0 1px 2px rgba(16, 24, 40, 0.04)",
+        "purpose": "需要从内容底色中轻微抬起的单层面板。"
+      },
+      {
+        "name": "floating",
+        "value": "0 4px 8px rgba(23, 23, 23, 0.10)",
+        "purpose": "下拉框、悬浮菜单和模态浮层。"
+      },
+      {
+        "name": "focus-ring",
+        "value": "0 0 0 3px rgba(133, 102, 50, 0.20)",
+        "purpose": "键盘焦点和输入聚焦反馈。"
+      }
+    ],
+    "motion": [
+      {
+        "name": "state-fast",
+        "value": "150ms cubic-bezier(0.22, 1, 0.36, 1)",
+        "purpose": "标签、按钮、链接和菜单的即时状态变化。"
+      },
+      {
+        "name": "panel-standard",
+        "value": "200ms cubic-bezier(0.22, 1, 0.36, 1)",
+        "purpose": "侧栏折叠、下拉框和局部面板变化。"
+      }
+    ],
+    "breakpoints": [
+      { "name": "sm", "value": "640px" },
+      { "name": "lg", "value": "1024px" },
+      { "name": "xl", "value": "1280px" }
+    ]
+  },
+  "components": [
+    {
+      "name": "Primary Button",
+      "kind": "button",
+      "refersTo": "button-primary",
+      "description": "浅色内容区的主要操作，使用可读深金而不是亮金。",
+      "html": "<button type=\"button\" class=\"ds-btn-primary\">查询</button>",
+      "css": ".ds-btn-primary { height: 34px; padding: 0 14px; border: 1px solid #856632; border-radius: 8px; background: #856632; color: #fff; font: 500 13px/1.5 'JetBrains Mono', 'Microsoft YaHei', monospace; cursor: pointer; transition: background 150ms cubic-bezier(.22,1,.36,1), border-color 150ms cubic-bezier(.22,1,.36,1); } .ds-btn-primary:hover { background: #6A5129; border-color: #6A5129; } .ds-btn-primary:focus-visible { outline: none; box-shadow: 0 0 0 3px rgba(133,102,50,.20); } .ds-btn-primary:active { transform: translateY(1px); } .ds-btn-primary:disabled { opacity: .55; cursor: not-allowed; transform: none; }"
+    },
+    {
+      "name": "Secondary Button",
+      "kind": "button",
+      "refersTo": "button-secondary",
+      "description": "次要操作保持白底、暖灰边界和正文墨色。",
+      "html": "<button type=\"button\" class=\"ds-btn-secondary\">重置</button>",
+      "css": ".ds-btn-secondary { height: 34px; padding: 0 14px; border: 1px solid #D8D2C7; border-radius: 8px; background: #fff; color: #171717; font: 500 13px/1.5 'JetBrains Mono', 'Microsoft YaHei', monospace; cursor: pointer; transition: background 150ms cubic-bezier(.22,1,.36,1), border-color 150ms cubic-bezier(.22,1,.36,1); } .ds-btn-secondary:hover { border-color: #A17D3E; background: #FBF8F1; } .ds-btn-secondary:focus-visible { outline: none; box-shadow: 0 0 0 3px rgba(133,102,50,.20); } .ds-btn-secondary:active { background: #F7F0DE; } .ds-btn-secondary:disabled { opacity: .55; cursor: not-allowed; }"
+    },
+    {
+      "name": "Text Field",
+      "kind": "input",
+      "refersTo": "input-default",
+      "description": "紧凑、清晰、具有可见标签和深金焦点状态的业务输入框。",
+      "html": "<label class=\"ds-field\"><span class=\"ds-field-label\">订单号</span><input class=\"ds-field-input\" type=\"text\" placeholder=\"请输入订单号\"></label>",
+      "css": ".ds-field { display: inline-flex; min-width: 220px; flex-direction: column; gap: 5px; color: #171717; font-family: 'JetBrains Mono', 'Microsoft YaHei', monospace; } .ds-field-label { color: #595959; font-size: 12px; font-weight: 500; line-height: 16px; } .ds-field-input { height: 34px; padding: 0 10px; border: 1px solid #D8D2C7; border-radius: 8px; background: #fff; color: #171717; font: 400 13px/1.5 inherit; outline: none; transition: border-color 150ms cubic-bezier(.22,1,.36,1), box-shadow 150ms cubic-bezier(.22,1,.36,1); } .ds-field-input::placeholder { color: #595959; } .ds-field-input:hover { border-color: #AFA99E; } .ds-field-input:focus { border-color: #856632; box-shadow: 0 0 0 3px rgba(133,102,50,.20); } .ds-field-input:disabled { background: #EEE9DF; color: #595959; cursor: not-allowed; }"
+    },
+    {
+      "name": "Sidebar Active Item",
+      "kind": "nav",
+      "refersTo": "sidebar-item-active",
+      "description": "浅黑功能栏上的单一圆形 chevron 活动状态。",
+      "html": "<div class=\"ds-sidebar\"><a class=\"ds-sidebar-item is-active\" href=\"#\"><svg class=\"ds-sidebar-icon\" viewBox=\"0 0 24 24\" aria-hidden=\"true\"><path d=\"M4 4h16v16H4zM8 9h8M8 13h8M8 17h5\"/></svg><span>店铺收款账户账单</span><span class=\"ds-active-indicator\" aria-hidden=\"true\">›</span></a></div>",
+      "css": ".ds-sidebar { width: 240px; padding: 8px; background: #1D1D1F; } .ds-sidebar-item { display: flex; align-items: center; gap: 8px; padding: 8px 10px; border-radius: 4px; color: #F0E4BF; font: 500 14px/1.25 'JetBrains Mono', 'Microsoft YaHei', monospace; text-decoration: none; transition: background 150ms cubic-bezier(.22,1,.36,1); } .ds-sidebar-item:hover { background: rgba(240,228,191,.10); } .ds-sidebar-item.is-active { background: #2A2927; color: #F2E7C5; } .ds-sidebar-icon { width: 20px; height: 20px; fill: none; stroke: currentColor; stroke-width: 1.8; } .ds-active-indicator { display: inline-flex; width: 16px; height: 16px; margin-left: auto; align-items: center; justify-content: center; border: 1px solid rgba(246,233,194,.72); border-radius: 999px; background: rgba(246,233,194,.14); color: #F6E9C2; font-size: 14px; } .ds-sidebar-item:focus-visible { outline: 2px solid #F2E7C5; outline-offset: 2px; }"
+    },
+    {
+      "name": "Workspace Tabs",
+      "kind": "nav",
+      "refersTo": "tab-active",
+      "description": "白色工作区内使用深金活动文字和单一金色下划线的局部标签切换。",
+      "html": "<nav class=\"ds-tabs\" aria-label=\"账户类型\"><a class=\"ds-tab is-active\" aria-current=\"page\" href=\"#\">淘系支付宝账户</a><a class=\"ds-tab\" href=\"#\">淘系微信账户</a></nav>",
+      "css": ".ds-tabs { display: flex; align-items: center; gap: 36px; min-height: 80px; padding: 0 32px; overflow-x: auto; border: 1px solid #D8D2C7; border-radius: 16px; background: #fff; } .ds-tab { position: relative; display: inline-flex; min-height: 80px; align-items: center; color: #595959; font: 600 14px/1.25 'JetBrains Mono', 'Microsoft YaHei', monospace; text-decoration: none; white-space: nowrap; transition: color 150ms cubic-bezier(.22,1,.36,1); } .ds-tab:hover, .ds-tab.is-active { color: #856632; } .ds-tab.is-active::after { position: absolute; right: 0; bottom: 0; left: 0; height: 3px; border-radius: 999px 999px 0 0; background: #B9954F; content: ''; } .ds-tab:focus-visible { outline: 2px solid #856632; outline-offset: 3px; }"
+    },
+    {
+      "name": "Business Panel",
+      "kind": "card",
+      "refersTo": "panel",
+      "description": "使用白色表面、暖灰边界和有限圆角的单层业务容器。",
+      "html": "<section class=\"ds-panel\"><h2 class=\"ds-panel-title\">账单明细</h2><p class=\"ds-panel-copy\">按账户和日期范围核对交易数据。</p></section>",
+      "css": ".ds-panel { padding: 16px; border: 1px solid #D8D2C7; border-radius: 12px; background: #fff; color: #171717; font-family: 'JetBrains Mono', 'Microsoft YaHei', monospace; } .ds-panel-title { margin: 0; color: #171717; font-size: 14px; font-weight: 600; line-height: 1.25; } .ds-panel-copy { max-width: 70ch; margin: 8px 0 0; color: #595959; font-size: 13px; line-height: 1.5; } .ds-panel:focus-within { border-color: #856632; }"
+    },
+    {
+      "name": "Status Tags",
+      "kind": "chip",
+      "description": "语义颜色只表达真实业务状态，并始终带文字。",
+      "html": "<div class=\"ds-tags\"><span class=\"ds-tag ds-tag-success\">已核对</span><span class=\"ds-tag ds-tag-warning\">待处理</span><span class=\"ds-tag ds-tag-danger\">异常</span></div>",
+      "css": ".ds-tags { display: flex; gap: 8px; font-family: 'JetBrains Mono', 'Microsoft YaHei', monospace; } .ds-tag { display: inline-flex; min-height: 24px; align-items: center; padding: 2px 8px; border-radius: 999px; font-size: 12px; font-weight: 500; } .ds-tag-success { background: #F1F6EE; color: #53793E; } .ds-tag-warning { background: #FEF5E7; color: #935F07; } .ds-tag-danger { background: #FAE6E6; color: #B80000; }"
+    },
+    {
+      "name": "Finance Data Table",
+      "kind": "custom",
+      "description": "紧凑、可扫描、数字右对齐的财务数据表。",
+      "html": "<table class=\"ds-table\"><thead><tr><th>订单号</th><th class=\"ds-num\">收入</th><th class=\"ds-num\">余额</th></tr></thead><tbody><tr><td>20260722001</td><td class=\"ds-num ds-income\">¥1,280.00</td><td class=\"ds-num\">¥8,460.00</td></tr></tbody></table>",
+      "css": ".ds-table { width: 100%; border-collapse: collapse; overflow: hidden; border: 1px solid #D8D2C7; border-radius: 12px; background: #fff; color: #171717; font: 400 12.5px/1.5 'JetBrains Mono', 'Microsoft YaHei', monospace; } .ds-table th { padding: 9px 10px; border-bottom: 1px solid #D8D2C7; background: #FBF8F1; color: #595959; font-size: 12px; font-weight: 600; text-align: left; } .ds-table td { padding: 9px 10px; border-bottom: 1px solid #EEE9DF; } .ds-table tbody tr:hover { background: #F7F0DE; } .ds-table .ds-num { text-align: right; font-variant-numeric: tabular-nums; } .ds-table .ds-income { color: #B80000; font-weight: 600; }"
+    }
+  ],
+  "narrative": {
+    "northStar": "黑金财务中枢",
+    "overview": "CaiWuXiTong 是一个需要长时间、高频率使用的财务工作台。视觉设计服务于读取、核对、筛选、审批和追踪，不服务于装饰。整体气质必须克制、专业、清晰，具有 VIP 黑金的品质感，但不能变成奢侈品海报、娱乐场所或高饱和暗黑界面。\n\n应用外壳使用“深黑工具轨道 + 浅黑功能栏 + 浅色内容区”的三层结构。黑色区域承担全局导航和功能定位，浅金色提供文字与图标的高对比识别；内容区始终保持浅色，使用深色文字和有限的金色交互信号，让大量表格、金额和状态信息稳定可读。\n\n这是唯一正式视觉标准。现存页面中的紫色、靛蓝、亮蓝硬编码属于遗留偏差，不能被新页面复制，也不能被写入新的组件。语义色只用于成功、失败、警告和信息状态，不构成第二套主题色。",
+    "keyCharacteristics": [
+      "深黑工具轨道、浅黑功能栏、浅色内容区，三层边界清楚。",
+      "浅金用于深色导航，深金用于浅色内容区的文字与主要操作。",
+      "全站使用 JetBrains Mono，标题和数据采用固定字号，不使用流体放大。",
+      "页面标题位于内容区右侧，保持 14px，与侧边栏一级标题同级。",
+      "一级导航 14px，二级导航 12px；同一层级的图标、字号和交互状态必须一致。",
+      "表格、筛选器和状态反馈优先，装饰性卡片、阴影和动画受到严格限制。",
+      "标签切换是局部状态变化，不触发整页刷新；加载前后字号和布局不得跳变。"
+    ],
+    "rules": [
+      { "name": "The Task-First Rule", "body": "用户必须先看到任务和数据，再看到品牌装饰；任何视觉效果只在帮助定位、读取或确认状态时才允许存在。", "section": "overview" },
+      { "name": "The Two-Gold Rule", "body": "深色背景使用浅金，浅色背景使用深金；不得把两者交换。亮金在白色上的对比度不足，只能用于非文字强调。", "section": "colors" },
+      { "name": "The One-Accent Rule", "body": "金色是唯一交互强调色。任何新页面出现装饰性紫色、靛蓝、亮蓝或绿色，都视为视觉回归。", "section": "colors" },
+      { "name": "The Semantic Exception Rule", "body": "红、绿、橙、蓝只在状态本身有业务含义时出现，并同时提供文字或图标，不能只依赖颜色传达结果。", "section": "colors" },
+      { "name": "The Fixed-Scale Rule", "body": "产品界面使用固定 rem 字号，不使用 clamp() 放大标题；桌面与移动端通过布局重排适配，不通过夸张缩放字体适配。", "section": "typography" },
+      { "name": "The Stable-First-Paint Rule", "body": "关键字号、行高和容器尺寸必须由首屏 CSS 直接提供，不能等待 JavaScript 或异步样式后再缩小，禁止首次进入时出现巨大字体闪烁。", "section": "typography" },
+      { "name": "The One-Family Rule", "body": "按钮、标签、导航、表格和正文都使用同一字体家族；禁止在数据界面引入装饰性展示字体。", "section": "typography" },
+      { "name": "The Flat-by-Default Rule", "body": "静态业务面板默认无阴影；若已经有 1px 边框，不得再叠加 16px 以上模糊半径的宽阴影。", "section": "elevation" },
+      { "name": "The No-Nested-Cards Rule", "body": "卡片只用于真实分组；卡片内部不能再套同样外观的卡片。优先使用标题、间距、分隔线和表格分组表达层级。", "section": "elevation" }
+    ],
+    "dos": [
+      "**Do** 在所有前端任务开始前读取根目录 `DESIGN.md`，并优先复用全局 `--vip-*` 令牌和既有组件。",
+      "**Do** 保持深黑工具轨道、浅黑功能栏、浅色内容区的三层结构。",
+      "**Do** 在深色导航使用浅金，在浅色内容区使用对比度合格的深金。",
+      "**Do** 将页面标题放在右侧，使用 14px 字号和匹配业务语义的统一图标。",
+      "**Do** 让一级导航保持 14px、二级导航保持 12px，并为所有交互实现 hover、focus、active、disabled、loading 和 error 状态。",
+      "**Do** 让标签切换、筛选和分页保持局部更新，并使用 History API 维护可分享 URL。",
+      "**Do** 对正文、小号标签、按钮和占位文字检查至少 4.5:1 的对比度。",
+      "**Do** 在设计规则确需改变时，先更新 `DESIGN.md` 和 `.impeccable/design.json`，再修改页面代码。"
+    ],
+    "donts": [
+      "**Don't** 把遗留的紫色、靛蓝、亮蓝硬编码（例如 `#4F46E5`、`#4338CA`、`#2563EB`）复制到新页面；信息状态蓝色除外。",
+      "**Don't** 在白色或浅灰背景上把亮金 `colors.content-accent` 用作小号正文或白字按钮底色；改用 `colors.content-accent-dark`。",
+      "**Don't** 在内容区使用大面积黑色背景和金色正文；黑底金字只属于导航、浮层或明确的高层级控制区域。",
+      "**Don't** 同时显示竖条、圆点和圆形 chevron 等多个选中标识；每个菜单项只能有一个活动指示器。",
+      "**Don't** 在业务内容内部重复页面 H1，或让首次加载时出现远大于 14px 的标题闪烁。",
+      "**Don't** 用普通 `<a>` 默认导航实现站内标签切换，导致整个文档重新加载。",
+      "**Don't** 给有边框的卡片叠加宽而软的大阴影，也不要使用超过 16px 的卡片圆角。",
+      "**Don't** 使用渐变文字、玻璃拟态、装饰网格、斜纹背景、彩色侧边条或与任务无关的动画。",
+      "**Don't** 恢复“Akaunting 提供支持”之类的供应商页脚文字，或在业务页面加入非业务宣传信息。",
+      "**Don't** 把临时截图路径、个人电脑路径或 `design-qa.md` 当成团队视觉规范。"
+    ]
+  }
+}
--- a/AGENTS.md
+++ b/AGENTS.md
@ -9,6 +9,15 @@
 - 不确定当前环境、分支、命令作用或数据范围时，停止操作并向负责人或 Codex 说明现场，不要猜。
 - 一次只完成一个明确任务；不顺手重构、升级依赖或修改无关模块。

+### 1.1 前端视觉规范
+
+- 仓库根目录 `DESIGN.md` 是本项目唯一正式视觉规范；`.impeccable/design.json` 是供 Codex、设计工具和自动检查读取的同源机器规范。所有前端任务在分析或修改代码前必须先完整阅读 `DESIGN.md`。
+- 项目正式主题固定为 VIP 黑金：最左侧工具轨道使用深黑，功能导航栏使用稍浅的黑；深色区域使用浅金或米白文字，浅色内容区使用黑色正文和深金交互色。旧有紫色、靛蓝色和高饱和亮蓝色不得继续作为主题色扩散。
+- 新增或修改页面必须复用全局设计令牌和共享组件，不得另写一套黑色、金色、字号、圆角、阴影或状态样式。成功、警告、错误、信息等语义色只用于对应状态，不得代替主题色。
+- 页面标题、侧边栏层级、图标、标签页、表格、滚动条、加载状态、选中状态和局部导航行为均按 `DESIGN.md` 执行；不得用整页刷新代替标签页或局部内容切换，也不得叠加两套选中标识。
+- 截图、浏览器批注和 `design-qa.md` 只属于验收证据或临时问题记录，不能覆盖正式视觉规范。需要改变视觉方向时，必须先得到项目负责人确认，并同步更新 `DESIGN.md` 与 `.impeccable/design.json`，再修改业务页面。
+- 前端 PR 必须说明是否符合 `DESIGN.md`、是否存在经批准的偏差，并用实际页面完成最小视觉与交互验证；“AI 已修改”或单看代码不能作为验收结果。
+
 ## 2. 分支与提交

 - `main` 是稳定主线，默认禁止直接推送、禁止强推、禁止直接修改。项目负责人 `WuYongJie`，以及得到其明确授权的 Codex，可以直接合并 PR 或直接推送 `main`；任何身份仍禁止强推。
--- a/DESIGN.md
+++ b/DESIGN.md
@ -0,0 +1,315 @@
+---
+name: CaiWuXiTong
+description: 面向多角色财务协作的克制型 VIP 黑金财务管理系统
+colors:
+  rail-black: "#050506"
+  rail-gold: "#F2E7C5"
+  sidebar-black: "#1D1D1F"
+  sidebar-gold: "#F0E4BF"
+  sidebar-gold-soft: "#DDD0AA"
+  sidebar-active: "#2A2927"
+  content-bg: "#F8F6F1"
+  surface: "#FFFFFF"
+  content-ink: "#171717"
+  content-muted: "#595959"
+  content-accent: "#B9954F"
+  content-accent-soft: "#F7F0DE"
+  content-accent-dark: "#856632"
+  border: "#D8D2C7"
+  success: "#53793E"
+  danger: "#B80000"
+  warning: "#935F07"
+  info: "#006395"
+typography:
+  title:
+    fontFamily: "JetBrains Mono, Microsoft YaHei, PingFang SC, monospace"
+    fontSize: "0.875rem"
+    fontWeight: 600
+    lineHeight: 1.25
+  body:
+    fontFamily: "JetBrains Mono, Microsoft YaHei, PingFang SC, monospace"
+    fontSize: "0.8125rem"
+    fontWeight: 400
+    lineHeight: 1.5
+  label:
+    fontFamily: "JetBrains Mono, Microsoft YaHei, PingFang SC, monospace"
+    fontSize: "0.75rem"
+    fontWeight: 500
+    lineHeight: 1.333
+  data:
+    fontFamily: "JetBrains Mono, Microsoft YaHei, PingFang SC, monospace"
+    fontSize: "0.78125rem"
+    fontWeight: 400
+    lineHeight: 1.5
+    fontFeature: "tnum"
+rounded:
+  sm: "4px"
+  md: "8px"
+  lg: "12px"
+  panel: "16px"
+  pill: "999px"
+spacing:
+  xs: "4px"
+  sm: "8px"
+  md: "16px"
+  lg: "24px"
+  xl: "40px"
+components:
+  button-primary:
+    backgroundColor: "{colors.content-accent-dark}"
+    textColor: "{colors.surface}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "0 14px"
+    height: "34px"
+  button-primary-hover:
+    backgroundColor: "#6A5129"
+    textColor: "{colors.surface}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "0 14px"
+    height: "34px"
+  button-secondary:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.content-ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "0 14px"
+    height: "34px"
+  input-default:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.content-ink}"
+    typography: "{typography.body}"
+    rounded: "{rounded.md}"
+    padding: "0 10px"
+    height: "34px"
+  sidebar-item:
+    backgroundColor: "{colors.sidebar-black}"
+    textColor: "{colors.sidebar-gold}"
+    typography: "{typography.title}"
+    rounded: "{rounded.sm}"
+    padding: "8px 10px"
+  sidebar-item-active:
+    backgroundColor: "{colors.sidebar-active}"
+    textColor: "{colors.rail-gold}"
+    typography: "{typography.title}"
+    rounded: "{rounded.sm}"
+    padding: "8px 10px"
+  tab-default:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.content-muted}"
+    typography: "{typography.title}"
+    padding: "0 4px"
+    height: "80px"
+  tab-active:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.content-accent-dark}"
+    typography: "{typography.title}"
+    padding: "0 4px"
+    height: "80px"
+  panel:
+    backgroundColor: "{colors.surface}"
+    textColor: "{colors.content-ink}"
+    rounded: "{rounded.lg}"
+    padding: "16px"
+---
+
+# Design System: CaiWuXiTong
+
+## 1. Overview
+
+**Creative North Star: "黑金财务中枢"**
+
+CaiWuXiTong 是一个需要长时间、高频率使用的财务工作台。视觉设计服务于读取、核对、筛选、审批和追踪，不服务于装饰。整体气质必须克制、专业、清晰，具有 VIP 黑金的品质感，但不能变成奢侈品海报、娱乐场所或高饱和暗黑界面。
+
+应用外壳使用“深黑工具轨道 + 浅黑功能栏 + 浅色内容区”的三层结构。黑色区域承担全局导航和功能定位，浅金色提供文字与图标的高对比识别；内容区始终保持浅色，使用深色文字和有限的金色交互信号，让大量表格、金额和状态信息稳定可读。
+
+这是唯一正式视觉标准。现存页面中的紫色、靛蓝、亮蓝硬编码属于遗留偏差，不能被新页面复制，也不能被写入新的组件。语义色只用于成功、失败、警告和信息状态，不构成第二套主题色。
+
+**Key Characteristics:**
+
+- 深黑工具轨道、浅黑功能栏、浅色内容区，三层边界清楚。
+- 浅金用于深色导航，深金用于浅色内容区的文字与主要操作。
+- 全站使用 JetBrains Mono，标题和数据采用固定字号，不使用流体放大。
+- 页面标题位于内容区右侧，保持 14px，与侧边栏一级标题同级。
+- 一级导航 14px，二级导航 12px；同一层级的图标、字号和交互状态必须一致。
+- 表格、筛选器和状态反馈优先，装饰性卡片、阴影和动画受到严格限制。
+- 标签切换是局部状态变化，不触发整页刷新；加载前后字号和布局不得跳变。
+
+**The Task-First Rule.** 用户必须先看到任务和数据，再看到品牌装饰；任何视觉效果只在帮助定位、读取或确认状态时才允许存在。
+
+## 2. Colors
+
+配色采用受控的黑金体系：深色导航使用高明度浅金，浅色内容区使用对比度合格的深金。亮金是强调材料，不是正文颜色。
+
+### Primary
+
+- **VIP 金** (#B9954F): 用于活动下划线、细边框、图标点缀、进度和非文字强调；禁止作为浅色背景上的小号正文或白字按钮背景。
+- **可读深金** (#856632): 用于浅色内容区的活动文字、链接、焦点边框和主要按钮。它在内容底色上的对比度约为 4.93:1，满足普通文字要求。
+- **淡金底色** (#F7F0DE): 用于标签、选中行和弱提示背景，必须搭配深金或深色文字。
+
+### Semantic States
+
+- 本系统没有第二装饰主题色。紫色、靛蓝和亮蓝不得承担品牌、导航、按钮或选中状态。
+- **成功绿** (#53793E): 只表达已完成、已通过或正向业务结果。
+- **危险红** (#B80000): 只表达错误、拒绝、删除或高风险结果。
+- **警告棕橙** (#935F07): 只表达待处理、需注意或可能产生影响的状态。
+- **信息蓝** (#006395): 只表达中性信息或帮助提示，不得作为主题色。
+
+### Neutral
+
+- **工具轨道黑** (#050506): 最左侧固定工具栏，是全站最深背景。
+- **功能栏黑** (#1D1D1F): 功能列表区域，比工具轨道略浅，保持两层黑色结构。
+- **活动浅黑** (#2A2927): 深色导航的悬停和选中底色。
+- **工具轨道浅金** (#F2E7C5): 最深工具轨道上的文字和图标。
+- **功能栏浅金** (#F0E4BF): 功能栏一级文字和图标；深色背景上的对比度超过 13:1。
+- **功能栏柔金** (#DDD0AA): 功能栏二级文字和弱提示，不再通过透明度继续降对比度。
+- **内容底色** (#F8F6F1): 页面工作区的浅灰暖白底色。
+- **内容表面** (#FFFFFF): 表格、筛选区和业务面板表面。
+- **正文墨色** (#171717): 标题、正文和关键数据。
+- **辅助墨色** (#595959): 说明、占位和次要数据；不得再降低透明度导致对比不足。
+- **边界色** (#D8D2C7): 面板、输入框、表格分隔和结构边界。
+
+### Named Rules
+
+**The Two-Gold Rule.** 深色背景使用浅金，浅色背景使用深金；不得把两者交换。亮金在白色上的对比度不足，只能用于非文字强调。
+
+**The One-Accent Rule.** 金色是唯一交互强调色。任何新页面出现装饰性紫色、靛蓝、亮蓝或绿色，都视为视觉回归。
+
+**The Semantic Exception Rule.** 红、绿、橙、蓝只在状态本身有业务含义时出现，并同时提供文字或图标，不能只依赖颜色传达结果。
+
+## 3. Typography
+
+**Display Font:** JetBrains Mono (with Microsoft YaHei, PingFang SC, monospace)
+
+**Body Font:** JetBrains Mono (with Microsoft YaHei, PingFang SC, monospace)
+
+**Label/Mono Font:** JetBrains Mono
+
+**Character:** 单一字体家族带来稳定、技术化和可核对的财务工具气质。中文回退字体只在字形缺失时接管；不要增加相似但不同的第二套无衬线字体。
+
+### Hierarchy
+
+- **页面标题** (600, 14px, 1.25): 固定在内容头部右侧，与配套图标同行；禁止在业务内容内部重复放置大号 H1。
+- **侧边栏一级标题** (500–600, 14px, 1.25): 模块和一级功能名称。
+- **侧边栏二级标题** (400–500, 12px, 16px): 比一级标题小一档，保持单行和稳定缩进。
+- **正文** (400, 13px, 1.5): 表单说明、面板正文和常规业务文字。
+- **标签** (500, 12px, 16px): 筛选条件、字段名、状态标签和辅助说明。
+- **表格与金额** (400–600, 12.5px, 1.5): 启用等宽数字 `tabular-nums`，金额和数量右对齐。
+- **关键汇总值** (700, 22px, 1.2): 只用于真实汇总数字，不能充当页面标题。
+
+### Named Rules
+
+**The Fixed-Scale Rule.** 产品界面使用固定 rem 字号，不使用 `clamp()` 放大标题；桌面与移动端通过布局重排适配，不通过夸张缩放字体适配。
+
+**The Stable-First-Paint Rule.** 关键字号、行高和容器尺寸必须由首屏 CSS 直接提供，不能等待 JavaScript 或异步样式后再缩小，禁止首次进入时出现巨大字体闪烁。
+
+**The One-Family Rule.** 按钮、标签、导航、表格和正文都使用同一字体家族；禁止在数据界面引入装饰性展示字体。
+
+## 4. Elevation
+
+界面默认采用“色调分层 + 细边界”，不是依赖大阴影堆叠。工具轨道、功能栏和内容区通过背景明度形成第一层深度；内容面板通过白色表面与细边界形成第二层。阴影只用于浮层或短暂交互反馈。
+
+### Shadow Vocabulary
+
+- **Surface Low** (`box-shadow: 0 1px 2px rgba(16, 24, 40, 0.04)`): 只用于需要从内容底色中轻微抬起的单层面板。
+- **Floating** (`box-shadow: 0 4px 8px rgba(23, 23, 23, 0.10)`): 只用于下拉框、悬浮菜单和模态浮层。
+- **Focus Ring** (`box-shadow: 0 0 0 3px rgba(133, 102, 50, 0.20)`): 键盘焦点和输入聚焦反馈，不承担常驻装饰。
+
+### Named Rules
+
+**The Flat-by-Default Rule.** 静态业务面板默认无阴影；若已经有 1px 边框，不得再叠加 16px 以上模糊半径的宽阴影。
+
+**The No-Nested-Cards Rule.** 卡片只用于真实分组；卡片内部不能再套同样外观的卡片。优先使用标题、间距、分隔线和表格分组表达层级。
+
+## 5. Components
+
+### App Shell
+
+- 最左工具轨道固定为 56px，使用 `colors.rail-black`。
+- 功能列表桌面宽度为 224px，使用 `colors.sidebar-black`；收起后不残留透明占位。
+- 内容区使用 `colors.content-bg`，业务表面使用 `colors.surface`。
+- 小屏幕折叠导航，内容保持完整宽度；表格允许局部横向滚动，页面本身不得横向漂移。
+
+### Navigation
+
+- 一级导航 14px，二级导航 12px；文字和对应 Material 图标使用同一浅金色。
+- 图标统一采用 Material Icons Outlined/Round，常规尺寸 20–24px；同一业务语义不得在不同页面更换图标体系。
+- 当前二级菜单只显示一个 16px 圆形浅金 chevron 指示器；禁止同时保留竖条、圆点或第二个箭头。
+- 悬停使用轻微浅金透明底，选中使用 `colors.sidebar-active`；状态变化为 150–200ms。
+
+### Page Header
+
+- 页面标题始终位于内容头部右侧，14px/600，文字前配一个与业务匹配的 18–20px 图标。
+- 标题文字使用 `colors.content-ink`，图标使用可读深金；禁止左侧大号标题或内容面板内的重复 H1。
+- 标题区域必须在首屏 CSS 中获得最终字号和位置，不能依赖加载完成后的脚本纠正。
+
+### Tabs
+
+- 桌面标签栏高度 80px，白色表面，标签间距以可点击性和单行展示为准。
+- 默认文字使用辅助墨色；活动文字使用 `colors.content-accent-dark`，底部使用 3px `colors.content-accent` 下划线。
+- 标签图标与文字同色；切换只更新内容、URL History 和活动状态，不触发 document 级刷新。
+- 标签变化使用 150ms 状态过渡；`prefers-reduced-motion` 下立即切换。
+
+### Buttons
+
+- 标准高度 34px，8px 圆角，13px/500；同一操作在所有页面保持相同高度、圆角和状态。
+- 主按钮使用可读深金底和白字；悬停使用更深一档金色，焦点显示 3px 深金焦点环。
+- 次按钮使用白底、边界色和正文墨色；悬停只改变边界或浅底，不变成第二主题色。
+- 禁用状态保留可读标签，降低整体强调并移除点击反馈；加载状态保持原宽度。
+
+### Inputs / Fields
+
+- 标准高度 34px，8px 圆角，白底、1px 边界；标签位于字段上方，12px/500。
+- 聚焦使用深金边框和半透明焦点环；占位文字至少使用辅助墨色，不允许低对比浅灰。
+- 错误状态使用语义危险色、明确文字和错误图标；不能只把边框染红。
+
+### Cards / Containers
+
+- 常规业务面板使用 12px 圆角、16px 内边距；大型工作区容器最多使用 16px 圆角、24px 内边距。
+- 表面为白色，边界为 `colors.border`；默认不加宽阴影。
+- 筛选、汇总和数据表属于同一业务流程时，用间距和分隔线组织，不生成无意义的多层卡片。
+
+### Data Tables
+
+- 表格正文 12.5px，表头 12px/600；表头可使用极浅金背景，不能使用蓝紫背景。
+- 金额、数量、比例右对齐并启用等宽数字；文本左对齐，状态居中或按列契约统一。
+- 行悬停使用极浅金/中性背景；选中状态同时提供图标、文字或边界，不只改变底色。
+- 收入、支出、错误和成功色遵循业务语义；不得为了“好看”交换红绿含义。
+
+### Scrollbars
+
+- 内容滚动条为 8px，轨道使用浅中性色，滑块使用 VIP 金；悬停使用更深金色。
+- 深色导航的滚动条轨道透明、滑块浅金，不能出现系统紫色或亮蓝色。
+
+### Loading, Empty and Error States
+
+- 首次加载使用与最终布局同尺寸的骨架或稳定占位，避免标题、标签和表格跳动。
+- 空状态说明“为什么没有数据”和“下一步能做什么”，不能只写“暂无数据”。
+- 错误状态保留重试入口和明确原因；局部失败不能清空整个页面或触发整页刷新。
+
+## 6. Do's and Don'ts
+
+### Do:
+
+- **Do** 在所有前端任务开始前读取根目录 `DESIGN.md`，并优先复用全局 `--vip-*` 令牌和既有组件。
+- **Do** 保持深黑工具轨道、浅黑功能栏、浅色内容区的三层结构。
+- **Do** 在深色导航使用浅金，在浅色内容区使用对比度合格的深金。
+- **Do** 将页面标题放在右侧，使用 14px 字号和匹配业务语义的统一图标。
+- **Do** 让一级导航保持 14px、二级导航保持 12px，并为所有交互实现 hover、focus、active、disabled、loading 和 error 状态。
+- **Do** 让标签切换、筛选和分页保持局部更新，并使用 History API 维护可分享 URL。
+- **Do** 对正文、小号标签、按钮和占位文字检查至少 4.5:1 的对比度。
+- **Do** 在设计规则确需改变时，先更新 `DESIGN.md` 和 `.impeccable/design.json`，再修改页面代码。
+
+### Don't:
+
+- **Don't** 把遗留的紫色、靛蓝、亮蓝硬编码（例如 `#4F46E5`、`#4338CA`、`#2563EB`）复制到新页面；信息状态蓝色除外。
+- **Don't** 在白色或浅灰背景上把亮金 `colors.content-accent` 用作小号正文或白字按钮底色；改用 `colors.content-accent-dark`。
+- **Don't** 在内容区使用大面积黑色背景和金色正文；黑底金字只属于导航、浮层或明确的高层级控制区域。
+- **Don't** 同时显示竖条、圆点和圆形 chevron 等多个选中标识；每个菜单项只能有一个活动指示器。
+- **Don't** 在业务内容内部重复页面 H1，或让首次加载时出现远大于 14px 的标题闪烁。
+- **Don't** 用普通 `<a>` 默认导航实现站内标签切换，导致整个文档重新加载。
+- **Don't** 给有边框的卡片叠加宽而软的大阴影，也不要使用超过 16px 的卡片圆角。
+- **Don't** 使用渐变文字、玻璃拟态、装饰网格、斜纹背景、彩色侧边条或与任务无关的动画。
+- **Don't** 恢复“Akaunting 提供支持”之类的供应商页脚文字，或在业务页面加入非业务宣传信息。
+- **Don't** 把临时截图路径、个人电脑路径或 `design-qa.md` 当成团队视觉规范。