diff --git a/.impeccable/design.json b/.impeccable/design.json new file mode 100644 index 00000000..95595d70 --- /dev/null +++ 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": "", + "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": "", + "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": "", + "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": "
店铺收款账户账单›
", + "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": "", + "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": "

账单明细

按账户和日期范围核对交易数据。

", + "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": "
已核对待处理异常
", + "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": "
订单号收入余额
20260722001¥1,280.00¥8,460.00
", + "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** 用普通 `` 默认导航实现站内标签切换，导致整个文档重新加载。", + "**Don't** 给有边框的卡片叠加宽而软的大阴影，也不要使用超过 16px 的卡片圆角。", + "**Don't** 使用渐变文字、玻璃拟态、装饰网格、斜纹背景、彩色侧边条或与任务无关的动画。", + "**Don't** 恢复“Akaunting 提供支持”之类的供应商页脚文字，或在业务页面加入非业务宣传信息。", + "**Don't** 把临时截图路径、个人电脑路径或 `design-qa.md` 当成团队视觉规范。" + ] + } +} diff --git a/AGENTS.md b/AGENTS.md index aa5197ab..074f6a93 100644 --- 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`；任何身份仍禁止强推。 diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 00000000..047b9ed4 --- /dev/null +++ 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** 用普通 `` 默认导航实现站内标签切换，导致整个文档重新加载。 +- **Don't** 给有边框的卡片叠加宽而软的大阴影，也不要使用超过 16px 的卡片圆角。 +- **Don't** 使用渐变文字、玻璃拟态、装饰网格、斜纹背景、彩色侧边条或与任务无关的动画。 +- **Don't** 恢复“Akaunting 提供支持”之类的供应商页脚文字，或在业务页面加入非业务宣传信息。 +- **Don't** 把临时截图路径、个人电脑路径或 `design-qa.md` 当成团队视觉规范。