黑丝绒终端 —— wanman /app 重设计方案(slug: resend)

目标:web/(Vite + React + TanStack Router + Tailwind v4 + shadcn/ui base-nova) 基线:test@3d35969f;交付目录:docs/design-proposals/resend/ 证据:简报 §3.3 实测(1440×900 真实登录态 + 真实数据)+ localtmp/design-render/*.json 本方案不改 web/ 任何文件,三条途径:①语义令牌取值 ②shadcn 官方 variant/size ③容器布局/尺寸/间距/滚动。

方案名与主张

方案名:黑丝绒终端

一句话主张: 把 /app 的「蓝灰渐变画布 + 白色卡片 + 四步投影 + 浮动圆角面板」,整体换成一块不间断的纯黑丝绒——画布 #000000,层级只由 1px 石墨描边 #292d30 与三档白字(#f0f0f0 / #a1a4a5 / #6e727a)切分;蓝色只做动作(#3b9eff),紫色只做标识(#baa7ff),一个像素的品牌色都不许浪费在装饰上。

适用基调:深色优先、双主题对等。 深浅两套令牌都给全值(tokens.css 同时含 :root 与 .dark),但深色是本方案的主场景——因为参考本身是 dark-first(见 §2),且当前 /app 在 1440×900 下的实测层级问题(rgb(6,6,7) 55 处、边框只存在于浅色)在深色下暴露得最彻底。

三条记忆点(评审时可直接核对):

# 记忆点 可验证判据
1 底色只有一个 深色下 --background、--card、--sidebar、--surface-rail 全为 #000000;全仓 rgb(6,6,7)(含硬编码)应为 0
2 层级靠线不靠影 .shadow-e1 变为 0 0 0 1px 细环;--shadow-e1..pop 不再含 rgb(15 23 42 / …) 这类投影
3 圆角只有两档 --radius: 0.5rem → 控件 6.4–8px、表面 11.2px,无第三种

参考提炼

参考体系 = Resend(black velvet with violet neon)。只提炼可移植的规则,不做风格抒情:

四条骨架规则(本方案逐条落地)

  1. 纯黑画布:#000000 本身即是画布,参考明确禁止「偏黑的深灰」(off-black)。本方案把 --background/--card/--sidebar 全部收归 #000000,并把 --popover 定为 #0b0e14(参考的 Surface Lift)作为唯一抬升面。
  2. 1px 石墨描边代替投影:层级 = #292d30 的 1px 线(参考的 Graphite),而非 4 级阴影。本方案把 --shadow-* 改写成基于 var(--foreground) 的 color-mix 细环(.shadow-e1 退化为 0 0 0 1px),并把 --border/--sidebar-border 定为 #292d30。
  3. 两色纪律:蓝 #3b9eff(Signal Blue)= 动作(主按钮、链接、焦点环、进度);紫 #baa7ff(Iris Violet Glow)= 标识(@提及、agent、代码标识)。参考原文是“Iris Violet 只用于代码与标识”,本方案把它扩到「一切标识」,并把品牌蓝从装饰位赶回动作位。
  4. 文字三档:#f0f0f0(Bone White,正文)/ #a1a4a5(Ash Gray,次级)/ #6e727a(更弱,图标与占位)。参考的 14px 正文 + -0.01em 负字距在中文场景不可照搬,但「一个屏幕三种文字亮度、不许第四种」可照搬。

两条组织规则

  1. 等宽字体只做「机器数据」:编号、时间戳、计数、连接态。参考用 Commit Mono;本方案不新增字体依赖,改为在 --font-mono 前置本地字体并规定用途(真正的改观来自用途,不来自字体本身)。
  2. @theme inline 的坑:@theme inline 会把值内联进工具类,所以 .shadow-e1 拿到的是字面量而不是 var(--shadow-e1)——这就是为什么本方案的阴影必须写回 @theme inline(用 var(--foreground) 让它随主题解析),而不是塞进 :root/.dark。这是本方案与常规 shadcn 改色流程唯一不同的机械细节,实施时最容易做错。

参考的 Don't(本方案逐条对照)

参考禁止项 wanman 现状(实测) 本方案处置
渐变 / 光晕 / 彩色洗色 工作区带品牌色径向渐变;登录页三处光晕 + 流光按钮 + 网格 工作区渐变 → 平涂(§6);登录页光晕只能减弱不能移除 → §8 标注为不合规风险
彩色填充式主 CTA 登录主按钮是 --brand → --brand-ink 渐变 改为纯 var(--brand) 填充(§6-S7,需改非令牌规则 → 风险)
用投影表达层级 四步投影 + shadow-e1 用了 26 次 全部改写为 1px 细环(route ①)
彩色卡片底 task-hall.tsx 用 border-l-amber-400 等彩色脊线 + bg-white 卡 卡片归 #000000 + 1px 描边;状态进 Badge 官方 variant(§6-S3)
每屏多于两处强调色 一屏内并存 3 种蓝 + 7 组 Tailwind 色 蓝收敛为 1 个令牌,状态收敛为 4 个通道(§6)

适配判断

3.1 覆盖的样例面(7 个)与逐面判定

面 实测现状(简报 §3.3) 判定 主要途径
S1 应用外壳 72px 导轨(图标钮 71×48)+ 侧栏 256×715 @x=76(与导轨留 4px 缝、圆角 14px)+ 频道头 256×52 + 会话行 240×64;画布是 linear-gradient(180deg, #e1e8f2, #e1e5f1) 结构保留、外观重构 ①半径/底色 ③去缝与尺寸
S2 频道消息 区域 1200×731、消息头 860×52;气泡 r=14px;他人气泡 rgb(235,237,239)/14px;自己气泡 rgb(255,255,255)/15px;同屏字号档位过多(全量普查 12 档) 适配(改观主要来自本面) ①令牌 ②Bubble/Message variant
S3 任务大厅 + 任务卡 bg-white 卡 + 彩色脊线(border-l-amber-400/400/300)+ 6 状态 chip + 营销式 hero 段;shadow-e1 需改造 ①②③ + 清漏
S7 登录 430px 玻璃卡 + 三处光晕 + 网格 + 流光主按钮 356×52(--brand → --brand-ink 渐变);分段控件 173×42 部分适配 ①②③;光晕无解 → 风险
S4 AI 助手频道 员工智能助手会话;等待态呼吸灯动效(--animate-breathe);只有 tool/trace 消息,无彩色装饰 适配 ①令牌(紫做 agent 标识)
S5 管理/设置弹窗 弹窗 704×512 r=18px;标题 18px/600;导航项 135×36 r=8px,选中 rgba(37,99,235,0.12) + rgb(29,78,216);输入 488×32 r=10px;标签 14px 适配 ①②(Input h-8、圆角、选中态)
S8 应用中心 emoji 图标块 + 分类筛选 + 运行中/开发中徽标 需改造 ②③(官方 Tabs/Badge/容器),emoji 本身 → 风险
S6 语音频道 TRTC_ENABLED=false,/api/v1/rtc/* 返回 RTC_DISABLED,界面不渲染,只在 rtc-group-call-ui.tsx 有代码与 DB 行 不纳入(无渲染证据可依据,仅代码可读) —

覆盖 7 面(≥6),其中 S4 / S5 / S8 为必选 2 个之外的第 3–5 个。

3.2 参考元素逐条裁断

参考元素 裁断 落地方式与代价
纯黑画布 #000000(禁 off-black) 采纳 --background/--card/--sidebar/--surface-rail = #000000;深色原值 oklch(0.145 0 0)=#0a0a0a、--card=#171717 全部作废
Surface Lift #0b0e14 采纳但收缩 只给 --popover 与 --muted;不再让卡片比画布亮
Graphite #292d30 采纳 --border/--secondary/--accent/--sidebar-accent 一色四用
Signal Blue #3b9eff 采纳但改用途 只做 --brand/--ring/Badge default/进度条;不再做装饰
Iris Violet Glow #baa7ff 采纳并扩用途 --mention:@提及、agent、代码/标识;替代当前与蓝同族的 #3370ff/#62a7fa
等宽字体(Commit Mono) 降级采纳 不新增字体依赖:--font-mono 前置本地字体 + 规定用途(编号/时间戳/计数/连接态)。没装即无视觉变化,改观靠"用途"而非"字体"
「1px 细环」表达层级 采纳 @theme inline 里把 4 档投影改写成基于 var(--foreground) 的 color-mix 细环
6px 控件 / 16px 表面 双圆角 部分采纳 单标量 --radius: 0.5rem → 控件 6.4–8px、表面 11.2px;无法同时给出 6px 与 16px(@theme inline 用固定倍率 1.4 派生),取舍见 §10
徽标方角 6px 拒绝 官方 Badge 固定 rounded-4xl(=20.8px 胶囊),改圆角必须覆盖 className → 违反 §2.2,记为舍弃项
Hero 字距 -0.05em / 56px 拒绝 /app 无营销 hero;页标题用官方 text-2xl(24px)+ -0.01em
渐变、光晕、彩色洗色 拒绝 工作区渐变改平涂(①);登录页三处光晕无法通过令牌移除 → §8 风险

3.3 明确不适配的四处(连同量化代价)

  1. 信息密度不同。 参考是营销页(一屏一个主张、body 16px、大留白);/app 是驻留 8 小时的协作台。本方案不照搬参考的留白与 16px 正文,正文保持 14–15px、元信息 12px、会话行 56px(见 §5、§6-S1)。代价:与参考"呼吸感"相比更紧,属有意偏离。
  2. 状态语义 6 态撑不住 2 色纪律。 /app 有 待补充/待处理/进行中/待验收/已完成/已关闭 6 态,参考只有"动作色 + 标识色"。本方案压缩为 4 个通道(吃掉 6 态)+ 文字标签承载剩余语义(§6-S3)。代价:状态辨识从"颜色差"转为"文字 + 4 通道差",需产品确认。
  3. 彩色识别度必然损失。 /app 用 8 色头像首字底与 emoji 应用图标做快速识别;参考体系里没有彩色头像/彩色图标。本方案把头像转单色(官方 Avatar)、应用图标容器化(§6-S8)。代价:扫视识别速度下降,是本次最实在的体验牺牲(§10)。
  4. 浅色是反相推导,不是参考原生。 参考没有浅色规范。tokens.css 里的 :root 是按深色阶梯镜像推导并逐对验算过的(§7),气质上浅色弱于深色——这是"双主题对等"的诚实边界。

3.4 硬约束对照

硬约束 本方案的满足方式
只用 shadcn 官方组件与官方 variant/size 全文不改任何组件文件;组件侧改动只有 variant/size 取值(§6 每处标注 route ②)。颜色一律由令牌落地
视觉改观只来自令牌/variant/布局 §4 令牌表逐行标注 route ①;§6 每处标明 ②/③;越界项集中列在 §8
深浅两套 + 实测对比度 tokens.css 同时给 :root 与 .dark 全量值;§7 给出全部前景/背景组合的实测比值(含 4 处不达标项)
中文 body 14–15px、行高 ≥1.375、最小 12px §5 刻度表;现状实测存在 9/9.375/10/11/11.25px 共 5 档违规,全部上收到 12px(属删除既有违规,见 §8 边界声明)
数字/代码用 --font-mono §5 规定用途清单(任务编号、时间戳、计数、连接态、快捷键)
不改 web/、不构建/不测试 本方案只交付目录下三个文件

令牌映射

三张表的每一行都是 route ①(语义令牌取值);tokens.css 就是这三张表的可执行版本。所有建议值均已按 WCAG 公式实测(§7 给前景/背景组合比值)。

4.1 深色 .dark(主场景,全部为替换值)

变量 当前值 建议值 意图
--background oklch(0.145 0 0) = #0a0a0a #000000 参考要求纯黑画布、禁用 off-black;#0a0a0a 属于"偏黑的深灰"
--foreground oklch(0.985 0 0) = #fafafa #f0f0f0 Bone White:18.43:1,比 #fafafa 在纯黑上柔和一档,仍是最高档文字
--card oklch(0.205 0 0) = #171717 #000000 卡片与画布同色,层级交给 1px 描边(参考 Section Card 做法)
--card-foreground #fafafa #f0f0f0 跟随 --foreground
--popover #171717 #0b0e14 Surface Lift:唯一抬升面,且与 --card 不再同值(当前 card=popover 导致弹窗无区分)
--popover-foreground #fafafa #f0f0f0 16.95:1
--primary / --primary-foreground var(--brand) / var(--brand-foreground) 不变 保持原文件结构,颜色由 --brand 承接
--secondary oklch(0.269 0 0) = #262626 #292d30 Graphite:他人消息气泡主填充(实测他人气泡 = --secondary,见 §6-S2),12.18:1
--secondary-foreground #fafafa #f0f0f0 跟随
--muted #262626 #0b0e14 原 muted/accent/secondary 三值同色;muted 应是更弱一档,改为 Lift
--muted-foreground oklch(0.708 0 0) = #a1a1a1 #a1a4a5 Ash Gray 次级文字 8.37:1,色相与 Graphite 同族(原值是纯灰,与蓝系填充不咬合)
--accent #262626 #292d30 菜单/幽灵按钮 hover 填充与 --secondary 对齐
--accent-foreground #fafafa #f0f0f0 跟随
--destructive oklch(0.704 0.191 22.216) = #ff6467 #ff9592 Alarm Red 9.97:1;颜色更淡更冷,减少满屏红点噪音
--border oklch(1 0 0 / 10%) = rgba(255,255,255,.10) #292d30 改为不透明:半透明白边叠在 #0a0a0a/#171717 上亮度不可控(实测 1.38:1 与更亮两种结果)
--input oklch(1 0 0 / 15%) #565a61 同上改不透明,并把输入框边界提到 3.03:1(满足 1.4.11)
--ring var(--brand) = #5599f3 #3b9eff 焦点环跟着新品牌蓝;显式字面量与其它主题解耦
--chart-1..5 oklch(0.87/0.556/0.439/0.371/0.269) = #d4d4d4/#737373/#525252/#404040/#262626 #f0f0f0 / #c9ccd1 / #a1a4a5 / #6e727a / #4b4f57 原阶梯在纯黑上 chart-5 仅 1.39:1(不可见)且"第 1 档最浅";改为由亮到暗、chart-1 恒为主序列
--radius 继承 :root 的 0.625rem 0.5rem(在 .dark 显式写出) 两套主题圆角一致,避免主题切换时圆角跳变
--brand oklch(0.68 0.15 256) = #5599f3 #3b9eff Signal Blue:唯一动作色 7.52:1
--brand-foreground oklch(0.16 0.02 258) = #080d16 #000000 按钮上的字 = 该主题的画布色 7.52:1;比 #06121f 更稳——官方 hover:bg-primary/80 也会把填充往画布混,#06121f 在悬停态只剩 4.47:1,纯黑仍有 4.98:1
--brand-soft oklch(0.28 0.05 256) = #182941 rgb(59 158 255 / 0.16) 改为品牌色派生(同浅色写法),选中轻底更"薄"
--brand-ink oklch(0.84 0.09 256) = #a4cdff #9ecbff 轻底上的选中文字 10.52:1
--mention oklch(0.72 0.14 254) = #62a7fa(与品牌蓝同族,紫缺失) #baa7ff Iris Violet Glow 10.06:1;@提及/agent 与动作蓝一眼可分
--ink oklch(0.16 0.02 258) = #080d16 #05060a 与纯黑画布同族的反相墨色
--message-self #203b59 #1c2c40 自己气泡:石墨掺 12% 品牌蓝(1.48:1 vs 画布),与 --secondary 气泡 1.02:1 的差靠色调区分
--message-self-foreground #e7f3ff #f0f0f0 12.42:1;全文只保留三档文字亮度
--surface-chat-soft oklch(0.32 0.06 250) = #193550 #0f1a29 引用/回复底:比气泡更淡一档(1.20:1),不再比气泡还亮
--surface-chat-selected oklch(0.28 0.04 250) = #192a3c #2a3a4c 会话选中 1.81:1 vs 画布,与中性 hover #292d30 靠色相区分
--surface-rail #e3e5e8(浅色值泄漏) #000000 修掉暗色下 72px 导轨变成一条近白竖带(15.69:1 的亮带);导轨即画布,靠 1px 描边分层
--workspace-background radial-gradient(... var(--brand) 10% ...) #000000 删除参考明确禁止的彩色洗色,画布平涂
--workspace-rail-background color-mix(in oklab, var(--background) 45%, transparent) transparent 导轨底色即画布,不再叠混色
--workspace-header-background linear-gradient(180deg, color-mix(..., var(--brand) 3%), var(--background)) var(--background) 顶栏去渐变(参考禁 gradient)
--interactive 缺失(继承 :root 的 #4e5058) #a1a4a5 补齐:继承值在纯黑上仅 2.46:1,不可读
--channel-icon 缺失(继承 :root 的 #80848e) #6e727a 补齐并与浅色统一一个值(深 4.35:1 / 浅 4.83:1)
--sidebar oklch(0.205 0 0) = #171717 #000000 侧栏与消息区同色,两栏之间只用 1px 描边
--sidebar-foreground #fafafa #f0f0f0 跟随
--sidebar-primary / --sidebar-primary-foreground 缺失 var(--brand) / var(--brand-foreground) 补齐,避免回落到浅色定义
--sidebar-accent oklch(0.269 0 0) = #262626 #292d30 会话行 hover 与 --accent 统一
--sidebar-accent-foreground #fafafa #f0f0f0 跟随
--sidebar-border oklch(1 0 0 / 10%) #292d30 与 --border 同值同性质(不透明,1px 竖线分隔两栏)
--sidebar-ring 缺失 var(--ring) 补齐

4.2 浅色 :root(黑丝绒的日间反相)

变量 当前值 建议值 意图
--background #fcfcfc #ffffff 画布反相为纯白,与深色 #000000 同构(当前是"近白画布 + 纯白卡片",层级靠 1.01:1 的色差)
--foreground #060607 #0a0a0b 19.79:1;与深色 #f0f0f0(18.43:1) 同档
--card #ffffff #ffffff 与画布同色,层级交给 1px --border
--card-foreground #060607 #0a0a0b 跟随
--popover #ffffff #ffffff 与当前一致;浅色下弹层靠遮罩 + ring-foreground/10 分离
--popover-foreground #060607 #0a0a0b 跟随
--primary / --primary-foreground var(--brand) / var(--brand-foreground) 不变 结构保持
--secondary #ebedef #eff1f3 他人气泡/次要填充:纯中性(去掉轻微偏冷),1.13:1 vs 白底
--secondary-foreground #060607 #0a0a0b 跟随
--muted #f2f3f5 #f4f5f6 与 --secondary 分开档次(当前 #f2f3f5 与 #ebedef 过近)
--muted-foreground #5c5e66 #4d5159 6.30:1 → 7.96:1;次级文字在纯白底上再深一档
--accent #ebedef #eff1f3 与 --secondary 同值(当前二者已同值,保持一致语义)
--accent-foreground #060607 #0a0a0b 跟随
--destructive #da373c #b01922 4.46:1 → 6.98:1;比 #c2202a 再深一档,是为了让官方悬停底 destructive/20 仍保住 4.90:1
--border #dcdee1 #d4d5d8 1.31:1 → 1.47:1,与深色 1.51:1 镜像;仍是装饰性细线(见 §7)
--input #dcdee1 #909399 1.35:1 → 3.08:1:输入框边界是"必要边界",必须过 1.4.11
--ring var(--brand) var(--brand) 不变(跟随新品牌蓝,7.27:1)
--chart-1..5 oklch(0.87/0.556/0.439/0.371/0.269) #0a0a0b / #4a4d55 / #767b83 / #8f939a / #b3b6bb 原 chart-1 = #d4d4d4(白底 1.48:1,主序列最弱);改为由深到浅、chart-1 恒为主序列
--radius 0.625rem 0.5rem 控件 6.4–8px / 表面 11.2px(见 §10 取舍)
--brand #2563eb #0e57a0 Signal Blue 浅色档 7.27:1;色相与深色 #3b9eff 同族(≈210°),去掉"审批蓝"的紫味。没有再亮一档的余地:官方 hover:bg-primary/80 会把填充推向白底,更亮的 #0f6ad0 悬停态只有 3.60:1
--brand-foreground #ffffff #ffffff 按钮上的字 = 该主题的画布色 7.27:1(悬停 4.57:1)
--brand-soft rgb(37 99 235 / 0.12) rgb(14 87 160 / 0.12) 跟随新品牌色(叠白底 ≈ #e2ebf4)
--brand-ink #1d4ed8 #073a6e 轻底上的选中文字 9.47:1
--mention #3370ff(4.18:1,不达标,且与品牌蓝同族) #5b46c8 Iris Violet 浅色档 6.66:1:既满足 AA,又让"标识色"与"动作色"分离
--ink #060607 #0a0a0b 与 --foreground 同值(当前已同值,保留)
--message-self #e8f3fe #eaf3ff 极淡品牌蓝(1.12:1 vs 白底)
--message-self-foreground #0d274a #0b2545 13.75:1
--surface-chat-soft #e8f2ff #f2f7ff 引用/回复底比气泡更淡一档(当前与 --message-self 几乎同色)
--surface-chat-selected #e5ecfc #e4edfa 会话选中(≈1.18:1 vs 白底),与中性 hover #f4f5f6 靠色相区分
--surface-rail #e1e8f2(蓝灰) #f5f6f7(中性) 全仓唯一的"下沉一档"面;去掉蓝灰即去掉飞书味
--workspace-background linear-gradient(180deg, var(--surface-rail), #e1e5f1) #f5f6f7 删除渐变洗色,平涂
--workspace-rail-background transparent transparent 不变
--workspace-header-background var(--background) var(--background) 不变
--interactive #4e5058 #4a4d55 8.45:1,与深色 #a1a4a5(8.37:1) 同档镜像
--channel-icon #80848e #6e727a 4.83:1,与深色统一为一个值
--sidebar #fcfcfc #ffffff 侧栏与画布同色(层级靠 --sidebar-border)
--sidebar-foreground #060607 #0a0a0b 跟随
--sidebar-primary / --sidebar-primary-foreground var(--brand) / var(--brand-foreground) 不变 结构保持
--sidebar-accent #ebedef #f4f5f6 会话行 hover 与 --muted 对齐(当前 sidebar-accent 与 secondary 同值,hover 过重)
--sidebar-accent-foreground #060607 #0a0a0b 跟随
--sidebar-border #dcdee1 #d4d5d8 与 --border 同值:两栏之间就是这条 1px 线
--sidebar-ring var(--ring) var(--ring) 不变

4.3 非颜色令牌

令牌 位置 当前值 建议值 意图
--radius :root + .dark 0.625rem 0.5rem 一个标量派生全部圆角:sm 4.8 / md 6.4 / lg 8 / xl 11.2 / 2xl 14.4 / 4xl 20.8px。控件落 6.4–8px(参考 6px 档),表面落 11.2px(参考 16px 档的收敛值)
--shadow-e1 @theme inline 0 1px 0 rgb(4 4 5 / .08), 0 1.5px 0 rgb(4 4 5 / .02) 0 0 0 1px color-mix(in oklab, var(--foreground) 5%, transparent) 退化为纯 1px 细环(参考的"用线不用影");.shadow-e1 用了 26 次,是最主要的观感来源之一
--shadow-e2 @theme inline 0 2px 4px -1px rgb(15 23 42 / .07), 0 6px 16px -4px rgb(15 23 42 / .1) 0 1px 2px -1px color-mix(... 6% ...), 0 0 0 1px color-mix(... 7% ...) 保留一丝投影,但主体是细环
--shadow-e3 @theme inline 0 10px 28px -8px rgb(15 23 42 / .16), 0 2px 6px -2px rgb(15 23 42 / .06) 0 8px 20px -12px color-mix(... 14% ...), 0 0 0 1px color-mix(... 8% ...) 面积不变、浓度减半,避免"浮起来"的 SaaS 感
--shadow-pop @theme inline 0 16px 40px -12px rgb(15 23 42 / .24), 0 4px 10px -4px rgb(15 23 42 / .1) 0 18px 44px -16px color-mix(... 20% ...), 0 0 0 1px color-mix(... 10% ...) 弹层是唯一保留"面积感"的一档
--font-mono @theme inline ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, ... 前置 "Commit Mono", "JetBrains Mono" 未安装即逐级回落,不新增字体依赖;真正的改观在用途(§5)

为什么阴影必须写在 @theme inline: @theme inline 会把值内联进工具类,.shadow-e1 拿到的是字面量而不是 var(--shadow-e1)。因此把阴影写进 :root/.dark 是无效的;把值写成引用 var(--foreground) 的 color-mix,才能一次书写、随主题解析(深色下自动变成极淡的白晕,浅色下是中性灰影)。

字体与排版

5.1 字体族:三族不动,只做两处用途收口

角色 栈 处置
界面/正文 "Geist Variable", "gg sans", "Noto Sans SC", "PingFang SC", ui-sans-serif, system-ui, "Segoe UI", "Microsoft YaHei", Roboto, Helvetica, Arial, sans-serif 不变。参考的 Inter 与 Geist 同属几何无衬线;Geist Variable 已随前端打包,不引入任何新字体包(同时满足"西文优先、中文兜底"的回退要求)
中文 "Noto Sans SC" → "PingFang SC" → "Microsoft YaHei" 不变(顺序保持:西文字形优先、中文按平台回落)
等宽 前置 "Commit Mono", "JetBrains Mono",其后 ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas, ... 只加本地偏好;未安装逐级回落,无网络请求。真正的改观在"用途"(§5.4)
数字 font-variant-numeric: tabular-nums 从当前仅任务大厅使用,扩到时间戳/计数(§5.4)

中文不用等宽:项目内等宽栈没有 CJK 字形,中文走会是系统回退导致混排——所以"数字用等宽"这条纪律只覆盖 ASCII 内容,中文标签(如"连接中")保持常规字重。

5.2 字号刻度:12 档 → 5 档

按简报 §3.3 的字体普查,单视图出现 12 个不同字号值:9 / 9.375 / 10 / 11 / 11.25 / 12 / 12.8 / 13.125 / 14 / 15 / 17 / 26px。本方案把它们全部映射到 5 档(全部落在官方 Tailwind 刻度上,不新增任意值):

档 字号/行高 官方工具类 承担角色 现状映射(→ 本档)
元信息 12px / 16px text-xs 时间戳、成员数、计数、状态徽标、快捷键、卡片脚注 9 9.375 10 11 11.25 12 12.8 13.125 全部上收到本档
控件/消息 14px / 20px text-sm 消息正文、按钮、输入框、菜单项、卡片正文、标签 14(保持)
文档正文 15px / 20.6px(1.375) @layer base 的 body(既有值) 长文本消息、任务描述、说明段 15(保持,不改基础层)
区块标题 18px / 26px text-lg 弹窗标题、区块标题(实测弹窗标题 = 18px/600,保留字重) 17 18 → 本档
页面标题 24px / 32px text-2xl 页面标题、登录主标题(字距 -0.01em) 26 → 本档

5.3 行高与字距

项 规定 说明
正文行高 15px/20.6px(1.375) 保持 @layer base 现有值,满足"行高 ≥1.375"
消息正文 14px/20px(text-sm 官方 1.43) 一屏更多行;比正文档更紧但不低于 1.375
12px 元信息 text-xs 官方 12/16(1.333) 边界说明:这些是单行短文本(时间戳/计数/徽标),不是正文段落。若评审要求 12px 也满足 1.375,则须加 leading-relaxed——记为待决策项(§8)
标题字距 24px 档 -0.01em 参考的负字距在 56px/-0.05em 上成立,中文 24px 只取 -0.01em
元信息字距 12px 档 +0.01em(可选) ASCII 数字/英文更清晰;中文可省
正文宽度 消息/描述文本容器 max-width: 720px 实测消息区宽 860px 时一行可到 57 个汉字;720px 收敛到 ≈48 汉字/行(route ③ 容器尺寸)

5.4 --font-mono 的用途清单(route ①,需要 className 收口)

场景 现状 建议
任务编号 / 任务卡 ID / 空间 ID 部分已用 font-mono tabular-nums,12px
时间戳(消息时间、更新时间) 11.25px 常规字 12px + font-mono tabular-nums
计数(成员数、未读数、任务数) 混用 font-mono tabular-nums
快捷键提示(kbd-chip) 已是 mono 保持
代码/接口片段(composer-markdown) 已是 mono 保持,并统一用 --muted 底 + 1px --border
连接态(已连接/连接中/重连中/已断开/连接失败) 彩色文字 不改成 mono(中文),改为「圆点 + 12px 文字」:--brand / --mention / --destructive 三个通道(§6-S1)

关键界面改造

每条都标了途径:① 令牌取值 · ② shadcn 官方 variant/size · ③ 容器布局/尺寸/间距/滚动。凡是需要改组件 className 的项目,统一在 §8 汇总为「去定制化」清单。

S1 应用外壳(1440×900:导轨 72px + 侧栏 256×715 + 频道头 256×52 + 会话行 240×64)

# 现状(实测) 改造 途径
1 画布 = linear-gradient(180deg, #e1e8f2, #e1e5f1);导轨 --surface-rail = #e1e8f2(蓝灰) 画布与导轨同时归 #000000(浅色 #f5f6f7 中性面);渐变删除 ①
2 侧栏容器 256×715、圆角 14px、与导轨留 4px 缝(md:ml-1),是"浮在画布上的白卡" 去掉 4px 缝与面板自绘描边,两栏全高贯通、由 1px --sidebar-border 分隔;圆角由令牌派生为 11.2px ① + ③
3 会话行 240×64,行内预览文字 11.25px 行高收到 240×56(同视口多约 1.6 行;64px 行装 11.25px 预览本来就过高);预览文字 → 12px --muted-foreground ③ + ①
4 选中/悬停行底色相近(--surface-chat-selected 与 --accent 都在同一灰阶) 悬停 = --sidebar-accent(中性石墨 #292d30);选中 = --surface-chat-selected(石墨叠加品牌蓝偏色 #2a3a4c):靠色相区分,不靠亮度叠加 ①
5 未读计数、成员数 font-mono tabular-nums 12px;未读用 16px --brand 圆点 + 白字数字(唯一允许的小色块) ①
6 连接态靠彩色文字 圆点 + 12px 文字:已连接 --brand / 连接中·重连中 --mention / 已断开·连接失败 --destructive ①
7 导轨图标钮 71×48(几乎顶满 72px 轨道) 轨道宽度保持 72px;图标钮改 48×48 居中(左右各留 12px 呼吸),圆角随 --radius 收为 8px;选中态只用 --secondary 填充 + 白色图标,不做彩色 ③ + ①
8 空间/频道分组标题 12px --muted-foreground + 字距 +0.01em;分组之间只用 1px --border(不再用底色块) ①

S2 频道消息(区域 1200×731、消息头 860×52、气泡 r=14px)

# 现状(实测) 改造 途径
1 他人气泡 rgb(235,237,239)/14px;自己气泡 rgb(255,255,255)/15px("自己 = 更亮更大") 他人 = --secondary(深 #292d30 / 浅 #eff1f3);自己 = --message-self(深 #1c2c40 / 浅 #eaf3ff)。字号统一 14px,自己靠色调而非亮度/字号表达 ①
2 气泡圆角 r=14px --radius-xl = 11.2px(深色 1.02:1 的自他气泡差靠色调 + 11.2px 圆角 + 头像位置区分) ①
3 频道头 860×52 保持 52px;底部分隔只用 1px --border(深 #292d30);标题 14px + 成员数 12px mono ①
4 @提及 --mention = 浅色 #3370ff(4.18:1,不达标)且与链接蓝同族;全仓 --mention 使用 124 处 一次令牌改动:#5b46c8(浅)/ #baa7ff(深,10.06:1)。全文只有"@提及 / agent / 标识"用紫,链接与按钮用蓝 ①
5 引用/回复底与气泡几乎同色 --surface-chat-soft(深 #0f1a29):比气泡更淡一档 + 1px --border 左脊线 ①
6 消息 hover 工具条(表情/回复/更多) 官方 Button variant="ghost" size="icon-xs";悬停底色 --accent(#292d30) ②
7 输入区:textarea 628×33 无边框 保持无边框;容器只加上边 1px --border;发送键 = 官方 Button size="icon-sm" variant="default" ③ + ②
8 消息正文可撑满 860px(≈57 汉字/行) 文本容器 max-width: 720px(≈48 汉字/行);长消息行高 1.375 ③
9 附件/图片/文件 官方 chat/attachment 组件;容器 1px --border + --radius-lg;不覆盖任何组件颜色 ②
10 空态「这里还没有消息 / 在下方输入框发送第一条消息,把话题开起来。」 保持文案;图标 20px --channel-icon,标题 14px --foreground、说明 12px --muted-foreground ①

S3 任务大厅 + 任务卡

# 现状(实测) 改造 途径
1 顶部有"营销式 hero"段落(大标题 + 说明块) 压成一行工具条:页标题 text-2xl(24px)+ 一行 14px --muted-foreground 说明;该区域高度从约 120px 收到 44px ③
2 筛选/排序是自绘彩色 chip 官方 Tabs variant="line" 做状态筛选(无底色、仅 2px 下划线 --foreground);排序用官方 Select;搜索用官方 Input(h-8) ②
3 卡片 bg-white + border-l-amber-400/-rose-400/-slate-300 彩色脊线 + shadow-e1 卡片 = bg-card(#000000)+ 官方 Card 既有 ring-1 ring-foreground/10;删除彩色脊线;紧迫度改用文字/序号(--mention 数字),不用色块 ① + ②
4 6 状态用 tailwind 色 + 混色 状态一律走官方 Badge,压缩到 4 个通道(下表) ②
5 头像首字底色在 tone.ts 里是 7 组 Tailwind 50/700 配对 官方 Avatar(sm/default/lg)+ --muted 底 + --muted-foreground 首字(单色);靠姓名识别 ② + ①
6 卡片宽度/间距不齐(同一行卡片宽度不一致) 容器改为等宽网格:grid 三列、间距 12px、卡片内边距 12px、高度由内容决定;滚动只发生在列表容器内(overflow-y-auto) ③
7 卡片脚注(负责人、时间、编号)11.25px 12px;负责人 = Avatar size="sm" + 姓名;时间/编号 = font-mono tabular-nums ①

6 状态 → 4 通道映射(只用官方 Badge variant)

状态 Badge variant 视觉 说明
待补充 outline 1px --border 空心 最弱,尚未成任务
待处理 secondary 石墨填充 有归属、未开工
进行中 default 品牌蓝填充 全站唯一"活跃"信号
待验收 destructive Alarm Red 淡底 + 红字(深 destructive/20 = #331e1d/7.41:1;浅 /10 = #f7e8e9/5.88:1) 需要人做决定
已完成 secondary 石墨填充 与待处理同通道,靠文字标签区分
已关闭 outline 空心 最弱
(逾期标记,若存在) 不加颜色通道 --destructive 文字 + mono 时间 逾期是时间属性不是状态

代价明说:待处理 与 已完成 共用 secondary、待补充 与 已关闭 共用 outline,颜色不足以区分,必须读文字。这是"2 色纪律 vs 6 状态"的正面取舍(§10)。

S7 登录(430px 玻璃卡 · 主按钮 356×52 · 分段控件 173×42)

# 现状(实测) 改造 途径
1 430px 玻璃卡(半透明 + 模糊 login-glass-card) 卡面 = --card(深 #000000 / 浅 #ffffff),边界改为 1px --border;宽度保持 430px ①
2 主按钮 356×52、rounded-2xl、--brand → --brand-ink 渐变 官方 Button size="lg" + w-full(高 36px);填充改纯 var(--brand):深 #3b9eff + 黑字(7.52:1)/ 浅 #0e57a0 + 白字(7.27:1)——两套主题的按钮字色都等于该主题的画布色。渐变写在 .login-primary-btn 里,属非令牌规则 → §8 越界项 ② + 越界
3 分段控件 173×42(自绘 login-segment + login-segment-pill) 官方 Tabs + TabsList(h-8 / rounded-lg / p-[3px] / bg-muted),选中档 data-active:bg-background(深色下即纯黑) ② + ①
4 login-glass-input / login-otp-cell 玻璃态输入 官方 Input(h-8 / rounded-lg)+ 官方 OTP 输入;边界 --input(深 3.03:1 / 浅 3.08:1,当前浅色 #dcdee1 仅 1.35:1) ② + ①
5 三处光晕(login-orb-blue / login-orb-indigo / login-orb-center)+ 网格 login-glass-grid + 流光 login-btn-shimmer 令牌只能减弱:--background 变纯黑后蓝晕的对比更弱;无法移除(alpha 与 stop 位置硬编码在 .login-* 规则)→ §8 风险 1 越界
6 文案「登录 WanChat / 使用企业邮箱验证码继续 / WanChat Enterprise」 保留;主标题 26px → text-2xl(24px),副标题 14px --muted-foreground,验证码说明 12px ①

S4 AI 助手频道(员工智能助手)

# 现状 改造 途径
1 助手等待态呼吸灯(--animate-breathe)+ 助手气泡 动效保持不变(不在本方案范围);助手与 agent 标识统一用 --mention 紫:紫 = 非人类身份,蓝 = 动作 ①
2 tool 调用 / trace 折叠块 折叠用官方 Collapsible;tool 名用 font-mono 12px;块底 = --muted + 1px --border ② + ①
3 结构化结果(本地命令、文件变更、引用卡片) 用官方 Card / Item 分层,层级只用 1px 描边,不用彩色底块 ②
4 @agent 提及 --mention 紫;同 S2-4 ①

S5 管理/设置弹窗(704×512 r=18px · 导航项 135×36 r=8px · 输入 488×32 r=10px)

# 现状(实测) 改造 途径
1 弹窗 r=18px --radius-xl = 11.2px ①
2 导航项 135×36,选中 = rgba(37,99,235,0.12) 底 + rgb(29,78,216) 字 换新令牌:--brand-soft + --brand-ink(深 10.52:1 / 浅 9.47:1);高度 36 → 32px(对齐官方控件高) ① + ③
3 输入框 488×32 r=10px 官方 Input h-8(高度不变)+ rounded-lg(8px);边界 --input ② + ①
4 表单标签 14px 保持 14px;帮助文字 12px --muted-foreground ①
5 弹窗内分区/分隔 只用 1px --border;深色下 --popover(#0b0e14) 是全局唯一抬升面,弹窗内不得再叠第二层底色 ①
6 危险操作 官方 Button variant="destructive"(淡红底 + 红字):深 #ff9592 于 destructive/20 = 7.41:1 / 浅 #b01922 于 /10 = 5.88:1;当前 #da373c 单色文字只有 4.46:1 ② + ①
7 深色遮罩不压暗(dialog.tsx 硬编码 bg-black/10) 令牌无解 → §8 风险 1,建议改 bg-background/60 越界

S8 应用中心

# 现状 改造 途径
1 emoji 作为应用图标块 容器统一 32×32 rounded-lg + 1px --border + --muted 底,emoji 居中;emoji 本身无法替换(数据源) → §8 风险 4 ③ + ①
2 分类筛选条 官方 Tabs variant="line";搜索 = 官方 Input ②
3 运行中 / 开发中 徽标 官方 Badge:运行中 = default(蓝,全站唯一"活跃"信号);开发中 = outline ②
4 应用卡片网格 与任务卡同一网格规范:等宽三列、12px 间距、12px 内边距、内容定高 ③
5 应用名 / 作者 / 说明 / 版本 名称 14px;说明 12px --muted-foreground;版本与编号 font-mono tabular-nums ①

6.5 令牌泄漏清理(三条途径之外的前置项)

这是本方案能否成立的前提:深色主题的每一处视觉收益都建立在"颜色真的来自令牌"之上,而实测显示大量颜色绕过了令牌。

泄漏 规模 映射 主要位置
Tailwind 调色板直用(text-amber-800、bg-rose-50、border-slate-100、bg-slate-400 …) 253 处 / 44 文件(amber 69 / rose 68 / slate 44 为主) amber → --muted 底 + --destructive 文字;rose → --destructive;slate → --secondary 或 --muted;emerald/teal/blue → --brand 或中性 task-hall.tsx、message-list.tsx、im-sidebar.tsx、group-hall.tsx、agent-metrics.tsx、rtc-*.tsx、voice-channel-section.tsx …
tone.ts 的 7 组 *-50 / *-700 配对 + presenceDotClasses 硬编码 #23a55a / #f0b232 1 文件 5 张映射表(已被多数组件复用) tone 收敛为 3 个语义:brand(--brand-soft/--brand-ink)、neutral(--muted/--muted-foreground/--interactive)、danger(--destructive);在线/忙碌/离线改 --brand/--mention/--channel-icon components/app/tone.ts:17-70
三种蓝并存:--brand(浅 #2563eb)、硬编码 #006ce7、硬编码 #3370FF 4 文件 全部 → var(--brand) message-list.tsx、composer-markdown.ts、voice-channel-history-dialog.tsx、chat-mention.ts
硬编码 bg-white 卡片 / border-slate-900/[0.04] 多处 bg-card / --border task-hall.tsx 等
color-mix / 选择器里写死的品牌色(#f06f66) 2 处 → var(--destructive) components/app/chrome.ts:163-164
.dark 缺令牌 5 个(--interactive、--channel-icon、--sidebar-primary、--sidebar-primary-foreground、--sidebar-ring) 按 §4.1 补齐 web/src/styles.css 的 .dark
深色主题开关 全仓无任何代码写入 .dark 类(color-scheme: normal),即深色当前不可达 建议:<html class="dark"> 由主题模块写入 + 声明 color-scheme → §8 风险 2 web/index.html / 主题模块

tone.ts 的注释写着「每个彩色面都经由这里解析」,但普查显示 44 个文件绕过了它——令牌纪律只对愿意遵守的文件有效。清理属"删除既有违规",不是新增自定义样式;但它确实要碰 web/ 下的文件,因此单列为 §8 的边界声明。

深浅色与对比度

全部比值为 WCAG 2.x 相对亮度公式实测(同一函数算出,可复算)。判定阈值:正文/标签/图标文字 ≥4.5:1,构件边界/焦点 ≥3:1,纯装饰细线不受 1.4.11 约束(下面单列)。

7.1 深色 .dark(画布 #000000 与各填充面)

用途 前景 背景 比值 判定
正文(Bone White) #f0f0f0 #000000 18.43:1 ✅
次级文字(Ash Gray) #a1a4a5 #000000 8.37:1 ✅
图标/占位 #6e727a #000000 4.35:1 ✅
可交互图标 --interactive #a1a4a5 #000000 8.37:1 ✅(原继承浅色 #4e5058 = 2.46:1 ❌)
动作蓝 --brand #3b9eff #000000 7.52:1 ✅
轻底文字 --brand-ink #9ecbff #000000 12.44:1 ✅
标识紫 --mention #baa7ff #000000 10.06:1 ✅
危险 --destructive #ff9592 #000000 9.97:1 ✅
输入框边界 --input #565a61 #000000 3.03:1 ✅(1.4.11)
正文 on 弹层 #f0f0f0 #0b0e14 16.95:1 ✅
次级字 on 弹层 #a1a4a5 #0b0e14 7.70:1 ✅
正文 on 他人气泡/石墨填充 #f0f0f0 #292d30 12.18:1 ✅
次级字 on 石墨填充 #a1a4a5 #292d30 5.53:1 ✅
蓝底上的按钮字(= 画布色) #000000 #3b9eff 7.52:1 ✅
蓝 on 石墨填充(次级按钮内的蓝字) #3b9eff #292d30 4.97:1 ✅
正文 on 自己气泡 #f0f0f0 #1c2c40 12.42:1 ✅
次级字 on 自己气泡 #a1a4a5 #1c2c40 5.64:1 ✅
轻底文字 on --brand-soft(画布上 #091929) #9ecbff #091929 10.52:1 ✅
轻底文字 on --brand-soft(弹层上 #13253a) #9ecbff #13253a 9.19:1 ✅
危险字 on destructive/10(#1a0f0f) #ff9592 #1a0f0f 8.91:1 ✅
Tabs 未选中档(text-foreground/60 → #909090) #909090 #000000 6.58:1 ✅(官方组件未覆盖色即达标)

7.2 浅色 :root(画布 #ffffff)

用途 前景 背景 比值 判定
正文 #0a0a0b #ffffff 19.79:1 ✅
次级文字 #4d5159 #ffffff 7.96:1 ✅(原 #5c5e66 = 6.30:1)
次级文字 on --muted #4d5159 #f4f5f6 7.30:1 ✅
次级文字 on 他人气泡 #4d5159 #eff1f3 7.03:1 ✅
图标 #6e727a #ffffff 4.83:1 ✅
可交互图标 #4a4d55 #ffffff 8.45:1 ✅
动作蓝 #0e57a0 #ffffff 7.27:1 ✅
动作蓝 on --muted #0e57a0 #f4f5f6 6.66:1 ✅
标识紫 #5b46c8 #ffffff 6.66:1 ✅(原 #3370ff = 4.18:1 ❌)
危险 #b01922 #ffffff 6.98:1 ✅(原 #da373c = 4.46:1 ❌)
危险字 on destructive/10(#f7e8e9) #b01922 #f7e8e9 5.88:1 ✅
白字 on 品牌蓝按钮(= 画布色) #ffffff #0e57a0 7.27:1 ✅
轻底文字 on --brand-soft(#e2ebf4) #073a6e #e2ebf4 9.47:1 ✅
正文 on 自己气泡 #0a0a0b #eaf3ff 17.68:1 ✅
自己气泡自带前景 #0b2545 #eaf3ff 13.75:1 ✅
正文 on 他人气泡 #0a0a0b #eff1f3 17.48:1 ✅
输入框边界 #909399 #ffffff 3.08:1 ✅(原 #dcdee1 = 1.35:1 ❌)

7.3 面与面(非文本)对比

关系 深色 浅色 备注
抬升面 --popover / 画布 1.09:1 1.00:1 深色靠 ring-foreground/10(≈#181818,1.18:1);风险 1
石墨填充(他人气泡、hover)/ 画布 1.51:1 1.13:1 深色更清楚:为深色优先的又一理由
自己气泡 / 画布 1.48:1 1.12:1 —
自己气泡 / 他人气泡 1.02:1 1.01:1 只靠色相(蓝 vs 中性)+ 圆角 + 头像位区分;浅色若需更强,把 --secondary 降到 #e9ebee(→1.07:1,代价是与 --muted 层次逼近)
会话选中行 / 画布 1.81:1 1.18:1 深色用"石墨 + 蓝偏色",与中性 hover(1.51:1)靠色相区分
引用底 / 画布 1.20:1 1.08:1 引用块另有 1px 左脊线
下沉面 --surface-rail / 画布 1.00:1 1.08:1 深色下导轨即画布,靠 1px 竖线分层
图表 chart-3 / 画布 8.37:1 4.26:1 中间档
图表 chart-5 / 画布 2.56:1 2.03:1 仅作最浅/最深一档填充(原深色 chart-5 = 1.39:1 ❌)
装饰细线 --border / 画布 1.51:1 1.47:1 见风险 3

7.4 悬停态:官方 variant 的联动(浅色蓝取值偏深的唯一原因)

官方 Button default 的悬停是 hover:bg-primary/80——按 alpha 与画布背景混合,所以填充在悬停时总朝画布色移动:深色下变暗、浅色下变亮。于是"品牌蓝能取多亮"不是审美题,而是悬停态对比度决定的:

状态 深色 浅色 判定
default 静置(bg-primary) #3b9eff + 黑字 7.52:1 #0e57a0 + 白字 7.27:1 ✅
default 悬停(bg-primary/80 混画布) #2f7ecc + 黑字 4.98:1 #3e79b3 + 白字 4.57:1 ✅
destructive 静置(深 /20、浅 /10) #331e1d + #ff9592 7.41:1 #f7e8e9 + #b01922 5.88:1 ✅
destructive 悬停(深 /30、浅 /20) #4c2d2c + #ff9592 5.80:1 #efd1d3 + #b01922 4.90:1 ✅

被这两个数字否掉的取值:浅色若用观感更亮的 #0f6ad0,静置 5.26:1 很好看,但悬停只剩 3.60:1;深色若把按钮字写成 #06121f,悬停只剩 4.47:1。这就是 §4.2 取 #0e57a0、§4.1 取 #000000 的全部理由——本方案不接受"静置达标、悬停掉档"。

7.5 面与面的判定口径

面与面不做 3:1 要求(WCAG 1.4.11 只约束"识别构件所需的视觉信息")。本方案的判据是:任何一个"面"的边界都必须能被 1px 细线或明确的内容(文字/图标)识别,而不是靠底色差。§7.3 那些 1.0x–1.8x 的数字正是这个设计的代价与证据。

7.6 不达标 / 未达标的诚实记录(4 处)

# 项 数值 原因与处置
1 深色弹窗与画布几乎同色 + 遮罩不压暗 popover/画布 1.09:1;dialog.tsx 遮罩硬编码 bg-black/10(纯黑上等于无压暗) 令牌无法解决。建议把遮罩改为 token 驱动(bg-background/60 + 1px 亮边)——超出三条途径,列为 §8 风险 1。若不改,用户仍能靠 18px 圆角、--popover 底色与环线定位弹窗,但"模态感"弱
2 12px 元信息行高 1.333 text-xs = 12/16 单行短文本,非正文段落。若评审要求 1.375,加 leading-relaxed(记入待决策)
3 装饰细线低于 1.4.11 的 3:1 深 1.51:1 / 浅 1.47:1 有意保留:细线是层级语言本体,加深会破坏"黑丝绒"质感,且 1.4.11 不约束纯装饰。所有"构件识别"边界一律走 --input(3.03/3.08)、--ring、--brand、图标(4.35/4.83)
4 浅色自他气泡亮度差 1.01:1 仅色相区分 见 7.3 的替代值(#e9ebee)

shadcn 兼容性

配置:web/components.json → base-nova、图标 lucide、样式入口 src/styles.css;web/src/components/ui/ 共 38 个官方组件。本方案不新增、不 fork、不改任何组件文件,只使用官方 variant/size;颜色一律由令牌承接。

8.1 组件 × variant/size 使用清单(route ②)

组件 用到的官方变体 本方案中的位置
Button default / outline / secondary / ghost / destructive / link;xs / sm / default / lg / icon-sm / icon-xs S1 图标钮、S2 消息工具条与发送键、S3 筛选、S5 危险操作、S7 主按钮、S8 卡片动作
Badge default / secondary / destructive / outline S3 6 态映射、S8 运行中/开发中
Tabs / TabsList / TabsTrigger `variant="default" "line",h-8、p-[3px]`
Input h-8 + rounded-lg + border-input + dark:bg-input/30 S3 搜索、S5 设置项、S7 登录输入
Card rounded-xl bg-card ring-1 ring-foreground/10 S3 任务卡、S8 应用卡、S4 结果卡
Avatar size="sm" / "default" / "lg" S1 会话行、S3/S8 负责人、S5 成员列表
Separator bg-border 分组、弹窗内分区
Dialog / AlertDialog bg-popover ring-1 ring-foreground/10;遮罩 bg-black/10(见 8.3-1) S5 管理/设置、确认删除
DropdownMenu / Select / Popover bg-popover shadow-md S3 排序、S1 空间菜单
Collapsible / Item 官方 S4 trace/工具调用折叠
ScrollArea(或现有 scroll-region) 官方 侧栏与消息区滚动收敛(route ③:滚动只发生在列表容器内)
chat/*(bubble / message / message-scroller / attachment / input / textarea) 官方 S2 频道消息主结构
Skeleton / Tooltip 官方 加载态与提示

注意:web/src/components/ui/ 没有 sidebar.tsx。侧栏是 app-shell.tsx 里自绘的容器(实测 h-full w-64 shrink-0 overflow-visible),因此 S1 的布局改造走 route ③(容器类),不需要引入 shadcn 的 Sidebar 组件——引入它会带来一套新的令牌(--sidebar-* 已有,但结构与滚动模型要重做),属范围外。

8.2 为什么这套配色不需要覆盖任何组件颜色

官方默认 在纯黑画布上的结果 收益
Card: bg-card ring-1 ring-foreground/10 #000000 卡片 + #181818(1.18:1) 细环 正是参考的 Section Card(黑卡 + 细线),零覆盖
Badge: rounded-4xl + 4 色 官方 4 通道即覆盖 6 状态的语义(§6-S3) 不需要新配色
TabsList: bg-muted + TabsTrigger data-active:bg-background dark:data-active:bg-input/30 深色下 = --muted 底 + #1a1b1d 选中胶囊(--input 30% 叠纯黑) 深色下自动成立,且未选中档 text-foreground/60 = 6.58:1
Button default: bg-primary #3b9eff 填充 + #000000 字(7.52:1,官方悬停态 4.98:1) 蓝只出现在动作上
Input: border-input dark:bg-input/30 边界 3.03:1(深)/3.08:1(浅)+ 深色自动补一层 #1a1b1d 底 当前"玻璃输入框"边界不可见的问题一并解决
Dialog/Popover: bg-popover 唯一抬升面 #0b0e14 全局只有一个"第二层"
Separator: bg-border 1px #292d30 层级语言本体

这正是本方案能"零组件覆盖"的原因:参考的层级语言(黑底 + 细环 + 单一抬升面)与 base-nova 的官方类名结构天然同构——原体系之所以要靠覆盖色、渐变、投影,是因为它试图在浅色采样上仿飞书的"浮卡"。

8.3 无法用三条途径表达的项(逐条标注)

# 项 事实(可核) 影响 建议补丁(需评审授权)
1 深色模态感不足 dialog.tsx 遮罩硬编码 bg-black/10;--popover 与画布 1.09:1 深色下弹窗缺少压暗 遮罩改 bg-background/60(1 行,ui/dialog.tsx)
2 深色主题当前不可达 全仓无任何代码给 <html> 加 .dark;color-scheme: normal 深色优先方案在生产看不到 加主题模块写 <html class="dark"> + color-scheme: dark(功能缺口,不属三条途径)
3 令牌在 44 个文件里不生效 253 处调色板直用;tone.ts 7 组 50/700;bg-white;三种蓝 route ① 在这些面上等于没落地 §6.5 映射表(属删除既有违规)
4 emoji 应用图标 图标内容来自数据 无法用令牌/布局统一观感 只统一容器(32×32 + 1px + --muted);彻底解决需产品侧换 lucide 图标
5 登录页光晕/流光/网格 .login-orb-blue / -indigo / -center、login-glass-grid、login-btn-shimmer、.login-primary-btn 渐变均写死在 styles.css 的非令牌规则里 令牌只能减弱,不能移除(参考明确禁止 glow/wash) 删 login-orb-* 的 background、按钮渐变改纯 var(--brand)(共 4–6 行)
6 任意值字号与圆角 实测字号 12 档、圆角 12 档(含 9px…13.125px、17px、26px) 需要改组件 className 才能收口 §5.2 / §4.3 的映射表(属删除既有违规)
7 Badge 达不到参考的 6px 方角 官方固定 rounded-4xl(=20.8px 胶囊) 与参考的方角徽标不一致 不修(覆盖会违反 §2.2),列为 §10 舍弃项

边界声明(重要):第 3、5、6 项与"删除既有任意值"这类动作,严格说不在①令牌取值/②官方 variant/③容器布局三条之内——它们是"移除既有违规",不产生任何新的自定义样式。本方案把它们单列而非混入三条途径,正是为了让评审一眼看到:本方案的令牌部分(§4)可以零代码直接落地,其余收益依赖一次性清漏。

实施成本

9.1 分期、工量与风险

期 内容 改动面 人日 风险
P0 令牌落地 @theme inline 的 4 行阴影 + 等宽栈;:root / .dark 全量替换;补齐 .dark 缺失的 5 个令牌 tokens.css 可直接替换(1 文件) 0.5 低。改完即出观感,且不碰任何组件文件
P1 深色可用性(前置) 主题开关写 <html class="dark"> + color-scheme: dark;dialog.tsx 遮罩改 bg-background/60 3 处小改 0.5 中。涉及入口文件,需产品确认"深色优先"
P2 清漏 tone.ts 7 组色板收敛为 3 语义;253 处调色板回收;三种蓝归一;bg-white→bg-card;头像单色;在线/忙碌点改令牌 44 文件 3.5 高。量大、需逐面回归;不做则 route ① 在多数面上不生效
P3 版式收口 字号 12 档→5 档(含 5 档 <12px 必删);圆角任意值回收;tabular-nums;正文 max-width: 720px 约 300 处 className 1.5 中。纯删除型改动,但触碰面广
P4 布局改造 S1 去缝/行高 56px;S2 气泡与输入区;S3 hero 压缩与卡片网格;S5 尺寸对齐;S7 官方控件替换;S8 图标容器 7 面 2.0 中。逐面可独立验收
P5 登录页补丁 移除光晕/网格/流光,按钮渐变改纯 --brand 4–6 行 CSS 0.25 低
合计 ≈8.25 人日

可独立上线的最小闭环 = P0 + P1(1 人日):立刻得到"纯黑画布 + 石墨细线 + 单色刻度"的深色界面,且不引入任何组件风险。P2 是深色真正成立的门槛,P3–P5 是观感与可达性的收尾。

9.2 回归面

9.3 验收断言(客观、可用工具跑)

断言 方法 期望
底色唯一 读 --background 计算值 深色 rgb(0, 0, 0) / 浅色 rgb(255, 255, 255)
调色板泄漏归零 正则 `\b(bg text
硬编码底归零 正则 bg-white\b 0 命中
字号下限 提取 text-\[(\d+(\.\d+)?)px\],数值 < 12 0 命中
字号档位收敛 收集全页 font-size 仅出现 12 / 14 / 15 / 18 / 24px
圆角档位收敛 收集全页 border-radius 仅出现 0 / 4.8 / 6.4 / 8 / 11.2 / 14.4 / 17.6 / 20.8 / 9999px
对比度 对 §7 表逐对跑 WCAG 公式 全部达阈值(§7.6 已声明的 4 处例外除外)
主题可达 切换主题后检查 <html class="dark"> 与 color-scheme 存在

取舍

10.1 得到什么(可量化)

  1. 层级语言单一化:深色下每个面都有确定位置——画布 #000000(0 层)→ 唯一抬升面 #0b0e14(1 层)→ 石墨填充 #292d30(2 层),其余全靠 1px 描边。原来的"色差 + 4 级投影 + 浮动圆角卡"三套语言并存的局面消失。
  2. 令牌纪律可被工具校验(§9.3),253 处泄漏 / 12 档字号 / 12 档圆角这三类顽疾有客观归零点。
  3. 状态语义收敛:7 组 Tailwind 色 + 6 态散落 → 4 个官方 Badge 通道 + 文字标签。
  4. 一批真实可达性缺陷被顺带修正:输入框边界 1.35:1 → 3.08:1、@提及 4.18:1 → 6.66:1、危险色 4.46:1 → 6.98:1、动作蓝 5.26:1 → 7.27:1(浅色)、深色 --interactive 2.46:1 → 8.37:1、深色 chart-5 1.39:1 → 2.56:1、中文最小字号 9px → 12px;并修掉 .dark 的 --surface-rail: #e3e5e8(暗色下导航条会变成 15.69:1 的亮带)这类"令牌级 bug"。
  5. 深浅两套都可交付:两张全量表 + 实测比值,没有"深色先做、浅色以后再说"的欠账。

10.2 牺牲什么(明确的代价)

牺牲 量化 为什么接受
飞书辨识度 蓝灰画布、白色浮动卡、4px 缝、渐变全部删除 这正是本方案的目的
彩色识别度 头像 8 色 → 单色;应用 emoji 只统一容器 参考体系无彩色头像;色彩预算留给"动作"与"标识"
状态色辨识 6 态 → 4 通道(待处理/已完成同色,待补充/已关闭同色) 颜色不够时读文字,符合"2 色纪律";需产品确认
与参考的密度差 正文 14–15px(参考 16px)、留白更紧、会话行 56px 企业协作台的信息密度优先
浅色气质 浅色是深色的反相推导,不如深色"黑丝绒" 参考没有浅色规范,只能推理
徽标形状 官方 Badge 固定 20.8px 胶囊(参考是 6px 方角) 改圆角需覆盖组件 className → 违反 §2.2
浅色主色偏深 #0e57a0(白底 7.27:1),而不是观感更亮的 #0f6ad0(5.26:1) 官方 hover:bg-primary/80 会把填充推向白底;只有压深才能让悬停态保住 4.57:1。代价是浅色下蓝色更"企业"、少一点活泼
弹窗模态感(深色) popover/画布 1.09:1 + 遮罩不压暗 令牌无解,列为 §8-1 待授权补丁

10.3 一处必须明示的机械限制(横向对比口径)

@theme inline 用固定倍率 calc(var(--radius) * 1.4) 从单一 --radius 派生全部圆角,"控件 6px + 卡片 16px"不可能同时成立(比值锁死 1.4)。本方案取 --radius: 0.5rem:控件档 6.4–8px(贴近参考的 6px),卡片 11.2px(参考 16px 的收敛值)。若评审更看重卡片,改 --radius: 0.75rem 即反向取舍(控件 9.6–12px、卡片 16.8px)。对比其它方案时请统一按此口径:本方案选择"优先控件"。

10.4 明确不适用的场景