墨黑指令台 —— wanman /app 重设计方案(slug: raycast)
交付物:本文件 +
tokens.css(可直接替换web/src/styles.css的:root/.dark变量块)+preview.html(单文件预览)。 基线:worktreetest@3d35969f;实测环境 1440×900、真实登录态(用户 17 张三)、真实数据(580 用户 / 148 频道 / 30 空间 / 1554 消息 / 457 任务)。 三条实现途径全程只用这三条:【①】语义令牌取值(web/src/styles.css)·【②】shadcn 官方variant/size·【③】容器 flex/grid 布局、区域尺寸、间距与滚动。凡超出三条之处,一律显式标注为⚠风险。
方案名与主张
方案名:墨黑指令台
主张:把 /app 从「飞书本机浅色采样的通用 IM 皮」改造成一台近黑画布 + 单一蓝强调 + 发丝边界 + 键盘优先的高密度指令台 —— 深色是主身份(--background:#08090a,侧栏 #0d0e10 比画布更暗),浅色是同一套规则的反相实现(画布 #f7f8f9、卡片纯白、侧栏 #f4f5f7)。
适用基调:深色优先,双主题对等。两套令牌都给出完整取值与实测对比度;浅色不是深色的降级备份,而是同一层级规则的镜像(见「深浅色与对比度」)。
核心命题(可直接对照验收):界面 98% 无彩色,彩色只出现在四个位置 —— ① 主按钮/--primary;② 当前频道与被选中项(--brand-soft + --brand-ink);③ @提及(--mention);④ 风险/逾期(--destructive:#ff6363,暖色被降级为语义色)。其余全部靠表面明度阶梯 + 1px 发丝线建立层级,不靠阴影、不靠十六种 Tailwind 调色板。
参考提炼
| 项 | 值 |
|---|---|
| 参考风格名 | Raycast — Style Reference |
| slug | raycast |
| 主题(theme) | dark |
| 来源站点 | raycast.com |
| 参考文件 | /Users/waw/Documents/code/wanman/localtmp/gradientdeck/raycast.design.md、raycast.design-extended.md |
可迁移规则(引用原文要点,共 5 条)
- 画布唯一化:原文 Do —— “Use #040506 as the only page background — never introduce lighter or grayer canvas colors”。当前
/app是--background:#fcfcfc与--sidebar:#fcfcfc同色(实测aside背景#fcfcfc,与 body 底色完全相同),等于没有画布概念。迁移为:画布只有一个值,所有面板靠相对画布的明度偏移表达(深色#08090a→ 侧栏#0d0e10→ 卡片#141517→ 弹窗#191a1d)。 - 单一强调色 + 严格配给:原文 Don't —— “Don't use multiple accent colors in the same surface… the system is monochromatic with one coral accent”。迁移为把实测的三种蓝(令牌
--brand #2563eb、硬编码#006ce7于message-list.tsx/composer-markdown.ts/voice-channel-history-dialog.tsx、#3370FF于chat-mention.ts)收敛为--brand与--mention两个同族不同明度的值(浅色#2563eb/#1d4ed8)。 - 暖色不作品牌色:原文 Do —— coral “is a brand mark, not a functional color”。wanman 的品牌色与 Flutter 端共用令牌,不能换色相;因此反向移植:把 Coral Pulse
#ff6363收编为--destructive(风险/逾期/删除),暖色从此只表达危险,不表达品牌。 - 边界而非阴影:原文 —— “Components are defined less by shadows and more by hairline borders”;Don't —— “Don't add drop-shadows to cards or panels”。迁移为:卡片/面板用
--border1px 发丝线定义,弹窗靠--popover明度台阶(深色#191a1d≠ 卡片#141517)浮起,不新增阴影令牌。 - 圆角档位纪律 + 等宽微标签:原文 —— “Use 8px radius for buttons, inputs, and badges; 16–20px radius for cards”,mono 用于版本号/技术微标签。迁移为:
--radius从0.625rem(10px) 收到0.5rem(8px)、档位从实测 12 档收到 7 档;任务号/计数/连接态时长用--font-mono(实测当前 9px/9.375px 数字没有等宽处理,12.8px/500 ×2765这类小数字号应改为 mono 档)。
明确舍弃的参考规则
- 舍弃「无彩色 CTA」(Don't: “Don't use chromatic action buttons — the CTA system is deliberately neutral (Mist on dark)”)。理由:wanman 有真实品牌蓝且与 Flutter 端共用语义令牌,主按钮必须是
bg-primary。保留其配给精神(全书只有主按钮、当前项、@提及、风险四处上色),不保留其「无色相按钮」结论。 - 舍弃 hero 大图 / 玻璃导航 pill / 滚动叙事 / max-width 1200px 居中:本产品是消息 + 任务双核心的高密度工具,不是营销站;对应规则在
web/src/components/app/无落点。 - 舍弃正文行高 1.15:中文正文行高不得低于 1.375(硬约束 §2.4),参考的 0.91–1.15 只适用于单行拉丁 UI 标签。
- 舍弃「dark-only,不引入浅色段」:本产品必须双主题对等。
适配判断
为什么这套语言适配「任务 + 频道消息」
- 长时段驻留 + 高信息密度:实测单视图字号 9 / 9.375 / 11 / 11.25 / 12 / 12.8 / 13.125 / 14 / 15 / 26 px 共 10 档(AI 助手空间一次渲染内
12.8px/500 ×2765、12px/500 ×2381)。深色近黑底能把「主信息亮、元信息灰」的对比直接映射为可读性层级,且不动任何组件样式 —— 只改 3 个令牌(--background/--foreground/--muted-foreground)即可全局生效。 - 消息流与任务卡共存:任务卡是"卡片",消息气泡是"凹槽",参考的表面阶梯(canvas → card → recessed)正好对应「消息流底(canvas)→ 卡片(card)→ 输入框/引用块(recessed =
--muted)」。 - 键盘优先:任务大厅「发布 / 接单 / 状态流转」是高频重复操作,键盘优先的指令台语言(
--input边界明确、焦点环--ring=brand、等宽任务号)与"任务"这一核心正好同构。 - 配色纪律解决已有的泄漏:实测 Tailwind 原始调色板泄漏 253 处、44 个非测试文件(amber 69 / rose 68 / slate 44 / emerald 42 / teal 12 / blue 7 / red 3 / violet 2 / purple 2 / neutral 2 / sky 1 / cyan 1),且深色下完全不翻转。单色相纪律是把这 253 处收敛回官方 variant 的理论依据。
舍弃项(本方案不做)
- 不做深色之外的第二强调色(不许出现 logo 紫、AI 青、成功绿并列);成功/普通态一律走中性
secondary/outline。 - 不做渐变、发光、玻璃拟态背景(
--workspace-background由「径向品牌色晕染」改为纯表面梯度,避免整屏蓝色调污染消息区,见令牌表)。 - 不做图标重绘:但明确点出 S8 应用中心图标是 emoji(实测元信息
Agent · 第三方 · chat+ emoji 图标)与其余 lucide 线性图标不一致 —— 该一致性缺口只能靠换图标组件解决,不在三条途径内,标为⚠风险(见「shadcn 兼容性」)。
令牌映射
覆盖范围:本节表格含硬约束 §5.1 第 4 条列出的全部变量名(浅色、深色各一套),并补充必须同步修正的三个遗漏令牌(--interactive、--channel-icon、--workspace-*)。所有改动均为**【①】**。
浅色(:root,web/src/styles.css:108 起)
| 变量名 | 当前值 | 建议值 | 意图 |
|---|---|---|---|
--background |
#fcfcfc |
#f7f8f9 |
画布退一级,让纯白卡片成为唯一抬升面;原值与侧栏/卡片同色导致零层级 |
--foreground |
#060607 |
#16181c |
近黑压到 16.7:1 仍足够,留出冷灰中性调,与深色的蓝灰系一致 |
--card |
#ffffff |
#ffffff |
保持纯白:画布变灰后,白卡自动获得 1.06:1 可感抬升 |
--card-foreground |
#060607 |
#16181c |
与 --foreground 同步 |
--popover |
#ffffff |
#ffffff |
弹窗与卡片同白,靠 18px 圆角 + 遮罩层区分 |
--popover-foreground |
#060607 |
#16181c |
同上 |
--primary |
var(--brand) |
var(--brand) |
保留间接引用,不引入品牌色旁路 |
--primary-foreground |
var(--brand-foreground) |
var(--brand-foreground) |
同上 |
--secondary |
#ebedef |
#eff1f3 |
与 --accent 拉开:次级填充(徽标/次级按钮)比悬停底浅 |
--secondary-foreground |
#060607 |
#16181c |
同步前景 |
--muted |
#f2f3f5 |
#f2f3f5 |
保留:凹槽/弱底(输入区、引用块、进度槽) |
--muted-foreground |
#5c5e66 |
#62656d |
5.48:1(原 4.83:1),为 12px 元信息留余量 |
--accent |
#ebedef |
#e9ebee |
悬停/选中底,比 --secondary 深一档,交互反馈可辨(原 secondary=accent 同值) |
--accent-foreground |
#060607 |
#16181c |
同步前景 |
--destructive |
#da373c |
#d92d20 |
4.83:1(原 4.54:1,边缘值),统一风险/逾期/删除 |
--border |
#dcdee1 |
#dde0e5 |
发丝线 1.32:1,仅作装饰性分隔,不承担控件识别 |
--input |
#dcdee1 |
#8a9099 |
输入框描边就是控件边界,必须 ≥3:1(白底 3.22:1、画布 3.02:1) |
--ring |
var(--brand) |
var(--brand) |
焦点环沿用品牌蓝,不改组件默认行为 |
--brand |
#2563eb |
#2563eb |
品牌蓝不动:与 Flutter 端共用语义令牌 |
--brand-foreground |
#ffffff |
#ffffff |
白字在 #2563eb 上 5.17:1 |
--brand-soft |
rgb(37 99 235 / 0.12) |
rgb(37 99 235 / 0.1) |
选中项底色,10% 叠白合成 #e9effd,配 --brand-ink 5.82:1 |
--brand-ink |
#1d4ed8 |
#1d4ed8 |
选中项前景 6.70:1,与 --mention 同族 |
--message-self |
#e8f3fe |
#e7f0fe |
自己气泡底色,与 --accent 灰底的他人气泡用色相区分 |
--message-self-foreground |
#0d274a |
#10305c |
11.44:1;与正文同字号后仍稳定可读 |
--surface-chat-soft |
#e8f2ff |
#eef4ff |
引用/回复块底,比自己气泡更淡,避免与气泡抢层级 |
--surface-chat-selected |
#e5ecfc |
#dfe8fb |
会话行选中底:从近白改为蓝调填充,与 hover(--accent)分属色相/明度两个通道 |
--mention |
#3370ff |
#1d4ed8 |
三种蓝收敛为一种:@提及 6.70:1(卡片)/5.84:1(自己气泡内) |
--ink |
#060607 |
#0f1115 |
深墨面(视频信箱底、深色条带),两套主题都必须近黑 |
--surface-rail |
#e1e8f2 |
#e9ecf0 |
空间 rail 去掉蓝味,成为中性第三面板色 |
--sidebar |
#fcfcfc |
#f4f5f7 |
修零层级对比:侧栏与画布 1.03:1,可辨识(实测原 aside 背景与 body 同为 #fcfcfc) |
--sidebar-foreground |
#060607 |
#16181c |
同步前景 |
--sidebar-accent |
#ebedef |
#e9ebee |
侧栏行悬停底,与全局 --accent 对齐 |
--sidebar-accent-foreground |
#060607 |
#16181c |
同步前景 |
--sidebar-border |
#dcdee1 |
#dde0e5 |
与 --border 对齐 |
--chart-1 |
oklch(0.87 0 0) |
#1d4ed8 |
图表改单色相蓝阶梯(原为灰阶,深色下不可分、无法承载趋势) |
--chart-2 |
oklch(0.556 0 0) |
#2563eb |
阶梯第 2 档(品牌主明度) |
--chart-3 |
oklch(0.439 0 0) |
#60a5fa |
阶梯第 3 档 |
--chart-4 |
oklch(0.371 0 0) |
#93c5fd |
阶梯第 4 档 |
--chart-5 |
oklch(0.269 0 0) |
#c7dbfe |
阶梯第 5 档(最浅,用于网格/参考线) |
--radius |
0.625rem(10px) |
0.5rem(8px) |
圆角档位从实测 12 档收敛为 7 档(4.8/6.4/8/11.2/14.4/17.6/20.8),8px 是最高频实测档(单视图 1591 处) |
浅色补充修正(同一文件内既有变量)
| 变量名 | 当前值 | 建议值 | 意图 |
|---|---|---|---|
--workspace-background |
linear-gradient(180deg, var(--surface-rail), #e1e5f1) |
linear-gradient(180deg, var(--surface-rail), var(--muted)) |
删掉值内硬编码 #e1e5f1(绕过令牌),渐变的第二停点回到 --muted |
--workspace-rail-background |
transparent |
transparent |
不变 |
--workspace-header-background |
var(--background) |
var(--background) |
不变 |
--interactive |
#4e5058 |
#5b6069 |
控制图标色 6.32:1 |
--channel-icon |
#80848e |
#767a83 |
频道/占位图标 4.30:1(当前偏亮,反而是"未选中"抢戏) |
--sidebar-primary / --sidebar-primary-foreground / --sidebar-ring |
var(--brand) / var(--brand-foreground) / var(--ring) |
不变 | 间接引用,自动跟随 |
深色(.dark)
| 变量名 | 当前值 | 建议值 | 意图 |
|---|---|---|---|
--background |
oklch(0.145 0 0) |
#08090a |
近黑但非纯黑:高密度中文长时段驻留时纯黑产生光晕感(相对参考 #040506 整体上抬 4 个明度级) |
--foreground |
oklch(0.985 0 0) |
#f2f3f5 |
17.95:1;不用纯白,降低暗底上的眩光 |
--card |
oklch(0.205 0 0) |
#141517 |
画布 +1 档(1.09:1),卡片全靠发丝线 + 明度 |
--card-foreground |
oklch(0.985 0 0) |
#f2f3f5 |
16.46:1 |
--popover |
oklch(0.205 0 0) |
#191a1d |
弹窗必须比卡片再亮一档:原值与卡片同色,模态在深色下会丢失层级 |
--popover-foreground |
oklch(0.985 0 0) |
#f2f3f5 |
同步前景 |
--primary |
var(--brand) |
var(--brand) |
不变(解析到深色 brand) |
--primary-foreground |
var(--brand-foreground) |
var(--brand-foreground) |
不变 |
--secondary |
oklch(0.269 0 0) |
#1e2023 |
三档分层第 1 层(徽标/次级按钮),比 --muted 亮 |
--secondary-foreground |
oklch(0.985 0 0) |
#e8eaed |
同步前景 |
--muted |
oklch(0.269 0 0) |
#161719 |
三档分层第 2 层(凹槽/弱底);原 secondary=muted=accent 三者完全相同 |
--muted-foreground |
oklch(0.708 0 0) |
#9c9ea6 |
7.45:1(画布)/6.83:1(卡片),冷灰与品牌蓝同温 |
--accent |
oklch(0.269 0 0) |
#232529 |
三档分层第 3 层(悬停),比卡片亮 1.19:1,交互反馈可见 |
--accent-foreground |
oklch(0.985 0 0) |
#f2f3f5 |
同步前景 |
--destructive |
oklch(0.704 0.191 22.216) |
#ff6363 |
承接参考唯一强调色角色,但降级为风险/逾期语义;卡片上 6.28:1 |
--border |
oklch(1 0 0 / 10%) |
rgb(255 255 255 / 0.12) |
合成 #262727(1.33:1),发丝线;比原 10% 略亮以便 1px 在近黑底上稳定可见 |
--input |
oklch(1 0 0 / 15%) |
#6b6f77 |
输入框边界 ≥3:1:画布 3.95:1 / 卡片 3.62:1 / 侧栏 3.83:1(原合成仅 1.51:1) |
--ring |
var(--brand) |
var(--brand) |
不变 |
--brand |
oklch(0.68 0.15 256) |
#5b9bff |
品牌蓝提亮到 7.19:1,成为深色下唯一高亮面 |
--brand-foreground |
oklch(0.16 0.02 258) |
#0a1626 |
深海军蓝前景,在 #5b9bff 上 6.56:1(反向对比,非白字) |
--brand-soft |
oklch(0.28 0.05 256) |
rgb(91 155 255 / 0.16) |
叠在弹窗 #191a1d 上合成 #242f41,配 --brand-ink 7.82:1 |
--brand-ink |
oklch(0.84 0.09 256) |
#a8c6ff |
选中项前景,画布上 11.56:1 |
--message-self |
#203b59 |
#16304f |
深蓝凹底,与 --accent 灰底明确区分 |
--message-self-foreground |
#e7f3ff |
#eaf3ff |
11.95:1 |
--surface-chat-soft |
oklch(0.32 0.06 250) |
#121b29 |
引用块底:低明度蓝相,比气泡更暗(凹槽方向) |
--surface-chat-selected |
oklch(0.28 0.04 250) |
rgb(91 155 255 / 0.14) |
用 alpha 叠色:在任何侧栏底色上合成(在 #0d0e10 上为 #182231),不写死某个侧栏色 |
--mention |
oklch(0.72 0.14 254) |
#8ab4ff |
卡片 8.75:1 / 自己气泡内 6.40:1 |
--ink |
oklch(0.16 0.02 258) |
#0b0c0e |
视频信箱底/深色条带,两套主题一致近黑 |
--surface-rail |
#e3e5e8 |
#16181b |
修 bug:原值在深色下是浅色,rail 会变成一条浅色竖带 |
--sidebar |
oklch(0.205 0 0) |
#0d0e10 |
比画布更暗(1.03:1):壳比内容暗,形成指令台纵深;且与卡片 #141517 反向 |
--sidebar-foreground |
oklch(0.985 0 0) |
#d7d9de |
13.67:1,侧栏不必用最亮白,把最亮留给消息正文 |
--sidebar-accent |
oklch(0.269 0 0) |
#1c1e21 |
侧栏行悬停,介于画布与卡片之间 |
--sidebar-accent-foreground |
oklch(0.985 0 0) |
#f2f3f5 |
同步前景 |
--sidebar-border |
oklch(1 0 0 / 10%) |
rgb(255 255 255 / 0.1) |
合成 #1e1f21,比全局 --border 更轻(侧栏内分隔已由间距承担) |
--chart-1 |
oklch(0.87 0 0) |
#8ab4ff |
单色相蓝阶梯深色版,明度单调递减(9.54→2.24:1) |
--chart-2 |
oklch(0.556 0 0) |
#5b9bff |
第 2 档 |
--chart-3 |
oklch(0.439 0 0) |
#3b7ff0 |
第 3 档 |
--chart-4 |
oklch(0.371 0 0) |
#2a5fc4 |
第 4 档 |
--chart-5 |
oklch(0.269 0 0) |
#1e4694 |
第 5 档 |
--radius |
未覆盖(继承 :root 值) |
未覆盖(继承 :root: 0.5rem) |
两套主题共用同一半径基准,不新增声明 |
深色补充修正
| 变量名 | 当前值 | 建议值 | 意图 |
|---|---|---|---|
--surface-rail |
#e3e5e8 |
#16181b |
见上(rail 浅色竖带 bug) |
--workspace-background |
radial-gradient(ellipse at 8% 0%, color-mix(... brand 10% ...), var(--muted) 64%) |
linear-gradient(180deg, #0d0e10, var(--background)) |
删除径向品牌色晕染:整屏蓝色调会污染消息区与任务卡的语义色 |
--workspace-rail-background |
color-mix(in oklab, var(--background) 45%, transparent) |
transparent |
半透明叠色会让 rail 随下层内容变色,取消叠加 |
--workspace-header-background |
linear-gradient(180deg, color-mix(... brand 3% ...), var(--background)) |
var(--background) |
顶部不再做品牌渐变(同第 2 条理由) |
--interactive |
未在 .dark 声明(继承 #4e5058) |
#9a9da6 |
修漏:实测注入 .dark 后仍有 27 处 rgb(92,94,102);补齐后 7.35:1 |
--channel-icon |
未在 .dark 声明(继承 #80848e) |
#8f939d |
修漏:补齐后 6.48:1 |
--sidebar-primary / --sidebar-primary-foreground / --sidebar-ring |
未覆盖 | 未覆盖 | 间接引用 var(--brand)/var(--brand-foreground)/var(--ring),自动跟随,无需重复声明 |
完整可替换代码见同目录
tokens.css(每处改动一行中文注释)。
字体与排版
字体栈:不改动(顺序已正确:西文在前、中文回退在后,西文字形不会挤掉中文)。
--font-sans: "Geist Variable", "gg sans", "Noto Sans SC", "PingFang SC",
ui-sans-serif, system-ui, "Segoe UI", "Microsoft YaHei", Roboto,
Helvetica, Arial, sans-serif;
--font-mono: ui-monospace, "SF Mono", SFMono-Regular, Menlo, Consolas,
"Liberation Mono", monospace;
--font-heading: var(--font-sans);
Risks/knowledge: Geist Variable 无中文字形 → 中文实际落到 Noto Sans SC / PingFang SC,与拉丁混排时基线存在 1px 级差异;处理办法是不对正文加任何 letter-spacing(中文加正字距会降低密度可读性,参考稿的 +0.014em at 14px 只适用于拉丁 UI 标签,本方案不迁移),并让数字走 --font-mono 消掉字宽抖动。
字号阶梯(6 档,替代实测 10 档 9/9.375/11/11.25/12/12.8/13.125/14/15/26px)
| 角色 | 字号 | 行高 | 字重 | 字体 | 落地位置(现文件) | 途径 |
|---|---|---|---|---|---|---|
| 页面标题 | 20px | 1.4 | 600 | sans | task-hall.tsx 页头、app-center.tsx 页头 |
【①】基准 + 删除调用点字号类 |
| 区块标题 | 16px | 1.4 | 600 | sans | 频道头 channel-header.tsx(实测 860×52,标题 16px/600)、看板列头、弹窗标题 |
保持现状值,仅统一 |
| 消息正文 / 表单值 | 15px | 1.5 | 400 | sans | message-list.tsx、channel-thread.tsx;styles.css 的 body { @apply text-[15px] leading-[1.375] } |
【①】行高 1.375 → 1.5(中文长句需要) |
| 卡片标题 / 行标 | 14px | 1.4 | 500 | sans | 任务卡标题(实测 14px/500)、设置弹窗表单标签(实测 14px) | 【②】回归组件默认 text-sm |
| 作者 / 行内次级 | 13px | 1.4 | 400 | sans | 作者名(实测 13px/400) | 保持 |
| 元信息 / 标签 | 12px | 1.4 | 500 | sans | 频道头成员数(实测 12px/500 #5c5e66)、看板计数 |
保持(12px 即下限) |
| 编号 / 计数 / 连接态 | 12px | 1.4 | 400 | --font-mono + tabular-nums |
任务号 TASK-1554、待处理 5、0 人已读 / 4 人未读、已连接/重连中 |
【②】用 font-mono 官方工具类 |
必须消除的三个现状缺陷
- 同一消息列表两套字号:实测他人 15px/400
#060607、自己 14px/400#0d274a。这是message-bubble.tsx对自身气泡覆盖了字号 → 处置:删除该字号覆盖,两方都用 15px/1.5(这是"删除覆盖",不是新增覆盖,符合硬约束 §2.1)。 - 9px / 9.375px / 12.8px:来自以 15px 为基准的 em 计算(
0.625em/0.85em)。处置:改为上文 6 档中的固定档位(12px 是下限,禁止 <12px)。 .dark下--interactive/--channel-icon未声明 → 已并入令牌表修正。
途径合规声明:本节的"落点"主要是删除调用点上的临时字号/行高/间距类,回到组件默认,属硬约束允许的"不新增覆盖";唯一新增的取值是 styles.css @layer base 里 body 的基准行高(1.375 → 1.5),它是全局排版基准、不是任何 shadcn 组件的样式覆盖。若评审认为连 body 基准也不得动,则该行保留 1.375,代价是 15px 中文正文行高 20.63px 偏紧、长消息(实测最长一条 40+ 字)阅读吃力 —— 标为 ⚠风险(可回退项)。
关键界面改造
覆盖样例面:S1 外壳/侧栏、S2 频道消息流、S3 任务大厅+任务卡、S7 登录页、S4 AI 助手频道、S5 管理设置弹窗、S8 应用中心(7 个,≥6);另附 S6 语音频道的代码依据说明。每条标注途径与所用官方组件。
状态色统一口径(全部 7 个面共用,先声明一次)
任务/连接状态只能用 shadcn 官方 Badge 的 5 个 variant 表达,不新增变体:【②】
| 状态 | 官方 variant | 令牌落点 | 依据 |
|---|---|---|---|
| 待补充 / 已关闭 | outline |
--border + --foreground |
中性,不抢注意力 |
| 待处理 | secondary |
--secondary |
填充但不强调 |
| 进行中 | default |
--primary(=--brand) |
唯一彩色徽标 |
| 待验收 | ghost + 前缀文字「待验收」 |
--muted-foreground |
用文字而非颜色区分 |
| 已逾期 / 风险 | destructive |
--destructive |
暖色只表达危险 |
| 已连接 / 重连中 / 已断开 | 见各面条目 | --chart-2 / --secondary / --destructive 语义化后由文字承载 |
连接态以文字为主、颜色为辅 |
S1 应用外壳 + 空间/频道侧栏(app-shell.tsx、channel-sidebar.tsx、workspace-rail.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
会话侧栏 aside 256×715,background #fcfcfc 与页面底色相同,零层级对比 |
侧栏 --sidebar 浅 #f4f5f7 / 深 #0d0e10;画布浅 #f7f8f9 / 深 #08090a;三面板(rail → 侧栏 → 内容)明度单调 |
【①】 |
空间 rail nav 72×900 背景 transparent,右边框 rgba(220,222,225,0.55)(≠ --border #dcdee1,值不同源) |
rail 用 --surface-rail(浅 #e9ecf0/深 #16181b)填充,右边框改 --border:不再依赖手写 alpha |
【①】 |
深色下 --surface-rail:#e3e5e8 → rail 是浅色竖带 |
深色 --surface-rail:#16181b,位于画布(更暗侧栏)与卡片之间 |
【①】(bug 修复) |
侧栏头部 52px、搜索框 30px/圆角 10px/背景 rgba(235,238,239,0.75)(三处硬编码) |
头部 48px(h-12)、搜索框 Input 官方 h-8(32px),底色用 --sidebar-accent,圆角随 --radius(8px) |
【③】 容器尺寸 + 【②】 用官方 Input |
| 会话行 240×64、未读点、预览 11.25px | 行高 60px(h-15),预览字号回 12px 档;未读点用 --destructive,选中行用 --surface-chat-selected(浅 #dfe8fb/深 14% 蓝) |
【③】+【①】 |
空间图标按钮 71×48、分隔线 rgba(5,5,9,0.22) |
图标容器 40×40 圆角随 --radius-2xl(14.4px),分隔用 Separator 官方组件 |
【②】 官方 Separator+【③】 |
频道行激活态 chrome.ts:19 用 bg-surface-chat-selected font-semibold text-brand-ink |
保留该组合(正好符合"唯一彩色 = 当前项"),仅令牌值更新 | 【①】 |
补充:侧栏分区(频道 / 语音 / 应用)之间用 Separator + 12px 间距,取消手写 <div class="h-px bg-…">。
S2 频道消息流(message-list.tsx、channel-thread.tsx、channel-header.tsx、channel-tabs.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
他人 15px/400 #060607,自己 14px/400 #0d274a(同一列表两套字号) |
两方统一 15px/1.5;删除自身气泡的字号覆盖;靠底色(--accent 灰 vs --message-self 蓝)区分发送方 |
【②】 删除调用点覆盖 + 【①】 |
他人气泡 rgb(235,237,239)=--accent,与悬停底色同值(消息底与交互反馈撞色) |
--accent 改为浅 #e9ebee(且与 --secondary #eff1f3 分离);气泡底改走 --muted #f2f3f5,悬停走 --accent,两者分离 |
【①】 |
自己气泡 --message-self #e8f3fe / 前景 #0d274a |
浅 #e7f0fe/#10305c(11.44:1),深 #16304f/#eaf3ff(11.95:1) |
【①】 |
气泡圆角 14px(与 --radius 派生的 8/11.2 不同源) |
圆角归 --radius-lg/--radius-xl 两档(10px 档位被删除) |
【①】 |
硬编码 #006ce7(message-list.tsx)与 #3370FF(chat-mention.ts)并存 |
统一到 --mention(浅 #1d4ed8/深 #8ab4ff)与 --brand;chat-mention.ts 的字符串常量不再需要独立色值 |
【①】 |
频道头 860×52,标题 16px/600 #060607、成员数 12px/500 #5c5e66 |
头部高 48px(对齐侧栏头),标题 16px/600(不变),成员数走 --muted-foreground + --font-mono 数字 |
【③】+【①】 |
输入区:textarea 628×33 无边框,外层只有上边框 rgb(220,222,225);工具按钮 28×28 |
外层 --border 上边框保留;输入框改官方 Input/Textarea(h-8、--input 描边 ≥3:1),工具按钮用 Button variant="ghost" size="icon-sm"(28px) |
【②】+【①】 |
| 悬停动作(点赞/回复/更多/图片预览/已读 0 人) | 一律 Button variant="ghost" + size="icon-xs"(24px);已读计数 0 人已读 / 4 人未读 用 mono |
【②】 |
| 引用块(回复) | 用 --surface-chat-soft(浅 #eef4ff/深 #121b29)+ 3px 左侧 --brand 竖线;不用自定义背景 |
【①】+【③】 |
S3 任务大厅与任务卡(task-hall.tsx、group-hall.tsx、create-task-dialog.tsx、channel-work-items.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
| 卡片圆角两套混用:10px×48 / 8px×37 | 全部 --radius-2xl = 14.4px;--radius 收敛后不再有 10px 档 |
【①】 |
卡片内容:标题 14px/500 + 频道 chip + AI 助手 chip + 查看任务 + 负责人 |
结构不变;chips 改用官方 Badge(频道 chip → outline,AI chip → secondary),查看任务 改 Button variant="link" size="xs" |
【②】 |
| 状态色分散在 Tailwind 原始调色板(amber 69 / rose 68 / emerald 42 处) | 按上文《状态色统一口径》全量替换为 5 个官方 variant;删除所有 text-amber-700/bg-emerald-50 类 |
【②】(风险见后) |
| 列头「待补充 0 / 待处理 5」与筛选「全部频道 / 5 项任务」 | 列头计数走 mono + --muted-foreground;筛选条用官方 Tabs(variant="line" 用于看板切换、默认 variant 用于视图切换) |
【②】 |
| 群聊大厅 hero 段(营销式)+ 品牌蓝出现 20 处 | hero 段压缩为一行标题 20px/600 + 一行说明 14px/--muted-foreground(【③】 容器),品牌蓝只保留在「新建/加入」主按钮与当前筛选 |
【③】+【①】 |
| 卡片 = 平面白块,无抬升 | 卡片 --card + 1px --border 定义边界,不加阴影(对应参考 Don't:不用投影) |
【①】 |
| 进度/流转可视 | 进度条槽 --muted、填充 --brand;逾期卡计数徽标 destructive |
【①】 |
S7 登录页(web/src/routes/login.tsx、sign-in.$.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
| 居中卡片,主标题 26px | 主标题 20px/600(并入 6 档阶梯;26px 是阶梯外的孤值),页脚 11px → 12px(12px 为下限) | 【①】 阶梯 + 【②】 删除临时字号 |
「邮箱验证码 / 短信验证码」切换块 173×42,选中态背景 --background #fcfcfc + 品牌蓝文字 |
改用官方 Tabs;选中态由 --card(纯白)承载而不是画布色,与"画布退灰"一起生效,选中差异从 1.0:1 提升到 1.06:1 且另有字色差 |
【②】 |
主按钮 356×52、白字、#2563eb |
Button size="lg"(h-9=36px) 全宽;颜色走 --primary/--primary-foreground;深色下自动变 #5b9bff + #0a1626 字 |
【②】+【①】 |
| 文案「登录 WanChat」「使用企业邮箱验证码继续」「企业邮箱 @example.com」「获取验证码」 | 保留文案;「企业邮箱 @example.com」走 mono(域名是标识符不是散文) | 【②】 |
| 页面背景 | 深色下登录页是唯一一个全屏强调面的合适场景;但默认仍走 --background,不做渐变/插图(避免营销化) |
【①】 |
S4 AI 助手频道(agent-chat-panel.tsx、agent-channel.tsx、agent-channel-results.tsx、channel-summary-panel.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
AI 助手空间一次渲染内 12.8px/500 ×2765、12px/500 ×2381、12px/400 ×1994、14px/400 ×1724;圆角 8px ×1591、10px ×844 |
字号收敛到 12/13/14/15 四档;圆角全部落到 --radius-* 派生档(8px 档保留即 --radius-lg,删掉 10px 档) |
【①】+【②】 删除临时字号 |
| 流式回答无"进行中"语义 | 等待态用既有 --animate-breathe 三点(不动效);结果卡片状态用 Badge variant="default"(进行中)/secondary(已完成) |
【①】+【②】 |
| 来源引用块 | 用 --surface-chat-soft 引用底 + Button variant="link" size="xs" 承载来源链接 |
【①】+【②】 |
| 结果卡片列表密度 | 结果列表用 flex 列 + 8px gap(【③】),卡片用 --card/--border;每卡 1 个语义徽标,不叠加多色 |
【②】+【①】 |
S5 管理与设置弹窗(space-manage-dialog.tsx、channel-settings-dialog.tsx、group-members.tsx、channel-permission-picker.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
[role=dialog] 704×512、圆角 18px、背景 #ffffff |
尺寸不变;圆角归 --radius-2xl(14.4px);背景 --popover(深色 #191a1d,比卡片亮一档,模态才浮得起来,原来是 oklch(0.205 0 0) 与卡片同值) |
【①】 |
左侧导航项 135×36、圆角 8px,选中态 --brand-soft + --brand-ink,危险项 --destructive |
保留该组合(正好是"唯一彩色 = 当前位置 + 风险"),仅令牌取值更新(浅 rgb(37 99 235/0.1)+#1d4ed8 5.82:1;深 16% 蓝+#a8c6ff 7.82:1) |
【①】 |
输入框 488×32 圆角 10px(bg-white 硬编码,见 space-manage-dialog.tsx:117 等 5 处 bg-white) |
改用官方 Input(h-8、--input 描边),删除 bg-white/rounded-lg 硬编码;字段组用官方 Field |
【②】 |
| 表单标签 14px,成员列表 | 标签 14px(保持);成员列表用 Item + Avatar size="sm" + Badge variant="outline"(角色 群主/管理员/研发/产品/pmo) |
【②】 |
| 权限选择器 | 官方 Checkbox/Switch? 现有 38 组件含 checkbox.tsx/radio-group.tsx,权限项用 Checkbox + Separator 分组,不新增视觉变体 |
【②】 |
S8 应用中心(app-center.tsx、assistant-board.tsx)
| 现状(实测) | 改后 | 途径 |
|---|---|---|
| 分类筛选(全部/Agent/人事行政/数据与报表/项目管理/行业模板/研发协作/智能办公)+「共 14 个应用」 | 筛选用官方 Tabs(8 项横向滚动,【③】 容器 overflow-x-auto 处理溢出);「共 14 个应用」走 mono + --muted-foreground |
【②】+【③】 |
卡片:运行中/开发中 徽标 + emoji 图标 + Agent · 第三方 · chat 元信息 |
徽标改官方 Badge(运行中→default,开发中→secondary);元信息 12px --muted-foreground;emoji 图标与 lucide 线性图标不一致 → 需替换图标组件(不在三条途径内) |
【②】;图标替换 ⚠风险 |
| 卡片网格间距 | 网格 grid-cols-[repeat(auto-fill,minmax(260px,1fr))] + 12px gap(【③】),卡片 --card+--border |
【③】 |
S6 语音频道 / 通话 —— 依据代码,非截图(rtc-group-call-ui.tsx)
本栈 TRTC_ENABLED=false,实测 DOM 内 aria-label 匹配「语音|通话|加入」命中 0、正文不含「语音」、/api/v1/rtc/* 返回 RTC_DISABLED → 界面不渲染,本方案没有也无法引用该页截图。以下依据代码与库内数据(wanman3_rtc_voice_channels 30 行、wanman3_rtc_calls 183 行、会议纪要 20 行):
- 【①】
rtc-video-frame.tsx:48与rtc-mini-window.tsx:36用bg-ink:--ink在浅深两套都必须是近黑(浅#0f1115/深#0b0c0e),视频信箱底才不会在浅色主题里发灰。 - 【②】
rtc-mini-window.tsx:174的aria-pressed:bg-white aria-pressed:text-ink:bg-white是绕过令牌的硬编码,改为官方Button variant="secondary"(--secondary/--secondary-foreground)。 - 【①】通话成员状态(
已连接 / 连接中 / 重连中 / 已断开 / 连接失败)在深色下必须有可读前景:--foreground(17.95:1)/--muted-foreground(7.45:1)/--destructive(6.85:1) 三档足够;不引入新色。 - 结论:该面不做结构性重设计,只保证令牌层正确;其完整视觉验证需在开启 TRTC 的部署环境进行,标为
⚠待验证。
深浅色与对比度
口径:正文文字 ≥4.5:1;控件边界与图标(图形)≥3:1;装饰性发丝线(--border/--sidebar-border)与表面层级差(面 vs 面)不适用 3:1,因为它们不承载"识别控件所需信息",层级由明度 + 1px 线 + 间距三者共同承担 —— 这与参考稿"edges do the work"的做法一致。
浅色
| 组合 | hex | 对比度 | 达标 |
|---|---|---|---|
| 正文 / 画布 | #16181c on #f7f8f9 |
16.72:1 | ✅ |
| 正文 / 卡片 | #16181c on #ffffff |
17.77:1 | ✅ |
| 次级文字 / 画布 | #62656d on #f7f8f9 |
5.48:1 | ✅ |
| 次级文字 / 卡片 | #62656d on #ffffff |
5.83:1 | ✅ |
| 次级文字 / 弱底 | #62656d on #f2f3f5 |
5.25:1 | ✅ |
| 次级文字 / 次级填充 | #62656d on #eff1f3 |
5.15:1 | ✅ |
| 链接/品牌文字 / 卡片 | #2563eb on #ffffff |
5.17:1 | ✅ |
| 主按钮字 / 主按钮底 | #ffffff on #2563eb |
5.17:1 | ✅ |
| 选中项文字 / 卡片 | #1d4ed8 on #ffffff |
6.70:1 | ✅ |
| 选中项文字 / 选中底 | #1d4ed8 on #e9effd(brand-soft 合成) |
5.82:1 | ✅ |
| @提及 / 卡片 | #1d4ed8 on #ffffff |
6.70:1 | ✅ |
| @提及 / 自己气泡 | #1d4ed8 on #e7f0fe |
5.84:1 | ✅ |
| 自己气泡文字 / 气泡底 | #10305c on #e7f0fe |
11.44:1 | ✅ |
| 风险文字 / 卡片 | #d92d20 on #ffffff |
4.83:1 | ✅ |
| 风险文字 / 画布 | #d92d20 on #f7f8f9 |
4.54:1 | ✅(余量小,仅用于徽标/短标签,禁止长段) |
| 侧栏文字 / 侧栏 | #16181c on #f4f5f7 |
16.29:1 | ✅ |
| 输入框边界 / 卡片 | #8a9099 on #ffffff |
3.22:1 | ✅(图形线) |
| 输入框边界 / 画布 | #8a9099 on #f7f8f9 |
3.02:1 | ✅(图形线) |
| 控制图标 / 卡片 | #5b6069 on #ffffff |
6.32:1 | ✅ |
| 频道图标 / 卡片 | #767a83 on #ffffff |
4.30:1 | ✅ |
| 发丝线 / 卡片 | #dde0e5 on #ffffff |
1.32:1 | — 装饰,不设门槛 |
| 卡片 / 画布(层级) | #ffffff vs #f7f8f9 |
1.06:1 | — 面差 + 发丝线共同定义 |
| 侧栏 / 画布(层级) | #f4f5f7 vs #f7f8f9 |
1.03:1 | — 侧栏另有 --sidebar-border 分隔 |
| rail / 画布(层级) | #e9ecf0 vs #f7f8f9 |
1.11:1 | — 面差 |
| 会话选中底 / 侧栏 | #dfe8fb vs #f4f5f7 |
1.13:1 | ⚠ 单靠底色不达 3:1 → 选中态由「底色 + --brand-ink 字色(6.7:1) + 字重 600」三重承载 |
深色
| 组合 | hex | 对比度 | 达标 |
|---|---|---|---|
| 正文 / 画布 | #f2f3f5 on #08090a |
17.95:1 | ✅ |
| 正文 / 卡片 | #f2f3f5 on #141517 |
16.46:1 | ✅ |
| 次级文字 / 画布 | #9c9ea6 on #08090a |
7.45:1 | ✅ |
| 次级文字 / 卡片 | #9c9ea6 on #141517 |
6.83:1 | ✅ |
| 次级文字 / 弱底 | #9c9ea6 on #161719 |
6.71:1 | ✅ |
| 次级文字 / 次级填充 | #9c9ea6 on #1e2023 |
6.11:1 | ✅ |
| 品牌色作文字 / 画布 | #5b9bff on #08090a |
7.19:1 | ✅ |
| 主按钮字 / 主按钮底 | #0a1626 on #5b9bff |
6.56:1 | ✅ |
| 选中项文字 / 弹窗 | #a8c6ff on #191a1d |
10.10:1 | ✅ |
| 选中项文字 / 选中底 | #a8c6ff on #242f41(brand-soft 合成) |
7.82:1 | ✅ |
| @提及 / 卡片 | #8ab4ff on #141517 |
8.75:1 | ✅ |
| @提及 / 自己气泡 | #8ab4ff on #16304f |
6.40:1 | ✅ |
| 自己气泡文字 / 气泡底 | #eaf3ff on #16304f |
11.95:1 | ✅ |
| 风险文字 / 卡片 | #ff6363 on #141517 |
6.28:1 | ✅ |
| 风险文字 / 画布 | #ff6363 on #08090a |
6.85:1 | ✅ |
| 侧栏文字 / 侧栏 | #d7d9de on #0d0e10 |
13.67:1 | ✅ |
| 输入框边界 / 画布 | #6b6f77 on #08090a |
3.95:1 | ✅(图形线) |
| 输入框边界 / 卡片 | #6b6f77 on #141517 |
3.62:1 | ✅(图形线) |
| 输入框边界 / 侧栏 | #6b6f77 on #0d0e10 |
3.83:1 | ✅(图形线) |
| 控制图标 / 画布 | #9a9da6 on #08090a |
7.35:1 | ✅ |
| 频道图标 / 画布 | #8f939d on #08090a |
6.48:1 | ✅ |
| 发丝线 / 画布 | #262727(12% 白合成) on #08090a |
1.33:1 | — 装饰 |
| 发丝线 / 卡片 | #292a2c on #141517 |
1.27:1 | — 装饰 |
| 卡片 / 画布(层级) | #141517 vs #08090a |
1.09:1 | — 面差 |
| 悬停底 / 卡片(层级) | #232529 vs #141517 |
1.19:1 | — 面差 + 交互反馈 |
| 弹窗 / 卡片(层级) | #191a1d vs #141517 |
1.19:1 | — 弹窗另有遮罩层 |
| 侧栏 / 画布(层级) | #0d0e10 vs #08090a |
1.03:1 | — 侧栏另有 --sidebar-border |
| rail / 画布(层级) | #16181b vs #08090a |
1.12:1 | — 面差 |
| 会话选中底 / 侧栏 | #182231 vs #0d0e10 |
1.21:1 | ⚠ 同浅色:由底色 + --brand-ink(10.1:1) + 字重共同承载 |
深色可达性前提(必读,属本方案的最大风险源)
实测:全仓 web/src 无任何代码添加 .dark,localStorage 无主题键,<html> class 恒为空,color-scheme: normal → 深色主题在生产不可达;注入 .dark 后仍有 rgb(6,6,7) 前景 55 处、rgb(92,94,102) 27 处、rgb(220,222,225) 边框 6 处、浅色头像底 3 处(amber/rose/blue/emerald/teal 的 50 配色)。所以:
- 令牌层修正是必要不充分条件;
- 必须补齐
--interactive/--channel-icon的深色取值(已在本方案内,属【①】); - 组件内硬编码(253 处 Tailwind 调色板 +
bg-white+ 头像 50/700 配对)必须按调用点替换为语义类或官方 variant(属【②】/【①】的调用点替换,不是新增变体); - 若在 3 未完成时上线深色,会出现"深底 + 近黑字"的不可读区域 —— 因此本方案要求深色开关与硬编码清理同批上线,不允许先开开关。此项标为
⚠风险(阻断项)。
shadcn 兼容性
结论:达成,且不需要新增任何官方组件、不需要新增任何自定义视觉变体。
- 组件库现状:
web/src/components/ui/共 38 个组件(accordion / alert-dialog / avatar / badge / bubble / button / button-group / calendar / card / chat / checkbox / collapsible / context-menu / dialog / dropdown-menu / field / field-select / floating-layer / input / input-group / item / message / message-scroller / popover / radio-group / scroll-area / scroll-region / scroll-surface / select / separator / skeleton / table / tabs / textarea / tooltip / …),web/components.json为style: base-nova、baseColor: neutral、iconLibrary: lucide、cssVariables: true。 - 本方案用到的官方组件全部已在库内:
Button(variant: default/outline/secondary/ghost/destructive/link;size: xs/sm/default/lg/icon-xs/icon-sm/icon/icon-lg)、Badge(6 variant)、Input、Textarea、Tabs(variant: default/line)、Avatar(size: sm/default/lg)、Separator、Card、Item、Field、Dialog、Select、Checkbox、RadioGroup、ScrollArea、Table、Tooltip、Popover、DropdownMenu。无"需引入但未安装"的官方组件。 - 令牌面:所有色值改动都写在
styles.css既有变量名上,@theme inline映射与--radius-*派生阶梯沿用原文,因此bg-background/text-foreground/border-border/bg-primary这类语义工具类自动跟随,无需触碰任何组件文件。
必须显式标注的不合规处(3 条)
⚠风险深色主题开关:需要在web/src里增加.darkclass 的挂载与持久化(当前无任何代码这么做)。这不属于三条途径,是方案落地的前置代码改动,实施成本与风险见下一节。⚠风险状态色与图标一致性:官方Badge只有 5 个可用 variant,无法为「待补充 / 待处理 / 进行中 / 待验收 / 已关闭 / 已逾期」六态各配一色;本方案用「variant + 文字前缀」区分(见《状态色统一口径》)。若产品坚持六态纯色区分,则必须新增 Badge variant → 不合规,需产品侧让步。同理,S8 应用中心用 emoji 作图标(与 lucide 不一致),替换图标不是令牌/variant/布局能解决的,属超出三条途径,需单独立项。⚠风险字号阶梯的落地口:6 档阶梯主要靠删除调用点上的临时字号/行高类(合规),但body基准行高 1.375 → 1.5 写在styles.css的@layer base,严格说是全局样式而非令牌。若评审判定不可动,则保留 1.375 并接受 15px 中文正文 20.63px 行高的阅读代价。
实施成本
改动面
| # | 改动 | 文件 | 途径 | 人时 |
|---|---|---|---|---|
| 1 | :root 令牌块整体替换(39 条声明) |
web/src/styles.css |
【①】 | 0.5 |
| 2 | .dark 令牌块整体替换(含补 3 条缺失声明:--interactive/--channel-icon/--surface-rail) |
web/src/styles.css |
【①】 | 0.5 |
| 3 | @layer base 的 body 行高 1.375 → 1.5(可选,见风险 3) |
web/src/styles.css |
全局排版 | 0.1 |
| 4 | 硬编码色清理:Tailwind 原始调色板 253 处 / 44 个非测试文件(amber 69、rose 68、slate 44、emerald 42、teal 12、blue 7、red 3、violet 2、purple 2、neutral 2、sky 1、cyan 1)→ 语义类或官方 variant | 以 avatar/tone.ts/chrome.ts/message-list.tsx/file-preview/*/spreadsheet/SpreadsheetPreview.tsx 为热点,共 44 文件 |
【①】调用点替换 + 【②】variant | 8–12 |
| 5 | 硬编码 bg-white / #006ce7 / #3370FF / #f06f66 / #23a55a / #f0b232 / #f2f3f5 统一到令牌 |
create-space-dialog.tsx:172、create-group-dialog.tsx:216、create-agent-dialog.tsx:56、space-manage-dialog.tsx:117、agent-developer-platform.tsx:37、user-picker.tsx:409/436、chat-mention.ts:2/5、chrome.ts:19、tone.ts:20/30/41、message-list.tsx、voice-channel-history-dialog.tsx、image-preview-dialog.tsx |
【①】 | 3–4 |
| 6 | 字号档位收敛(删除调用点上 9/9.375/11/11.25/12.8/13.125 等档,收敛到 6 档;统一自己/他人消息字号) | message-list.tsx、agent-channel.tsx、agent-channel-results.tsx、create-task-dialog.tsx、user-picker.tsx 等约 20 文件 |
【②】删除覆盖 | 4 |
| 7 | 深色接入:<html> class 挂载 + 持久化 + 用户偏好读取(阻断项,必须先于深色上线) |
新建 theme provider 挂载点 + app-shell.tsx 入口 |
⚠非三条途径 | 3 |
| 8 | 圆角归一:删除 6/7/10/12/14/18/26/32px 等散值,落到 --radius-* 派生档 |
任务卡、弹窗、会话行、频道头等约 15 文件 | 【①】 | 2 |
| 9 | 验收脚本(对比度复算 + 令牌泄漏扫描 + computed style 断言) | 新增 scripts/design-check.mjs(不入 web/) |
— | 2 |
| 合计 | 23–28 人时 |
风险清单
| 风险 | 等级 | 说明与缓解 |
|---|---|---|
| 深色不可达 / 半可读 | 高(阻断) | 现状 <html> class 恒空;注入 .dark 后仍有 55 处近黑前景。缓解:第 4/5/7 项必须同批上线;先做令牌 + 硬编码清理,最后才开开关 |
--input 提亮后观感变化 |
中 | 浅色 #dcdee1→#8a9099、深色合成 1.51:1→#6b6f77(3.95:1) 会让表单框线明显变重。这是达成 ≥3:1 控件边界的代价;若评审接受"输入框另有填充底即视为可识别",可回退到 --border 同值,但需在方案里标注不达标 |
| 253 处调用点替换的面 | 中 | 44 文件、含 file-preview/* 整套自研预览色板;建议按目录分批,先做 components/app/* |
| 状态色只有 5 个 variant | 中 | 六态区分退化为"variant + 文字",需产品确认;如产品不同意,则该处不合规(新增 variant) |
| 参考语言在浅色下的适配 | 低 | Raycast 无浅色版,浅色取值由本方案推导(画布 #f7f8f9 / 卡片纯白 / 侧栏 #f4f5f7);缺参考背书,需设计评审 |
验证方式(哪些检查能证明改动生效)
- 令牌生效:
getComputedStyle(document.documentElement).getPropertyValue('--background')应返回#f7f8f9(浅)与#08090a(.dark)。 - 零层级对比已修:
aside的backgroundColor≠body的backgroundColor(当前实测两者都是#fcfcfc)。 - 深色泄漏归零:注入
.dark后扫描全页 computed style,color: rgb(6,6,7)/rgb(92,94,102)/borderColor: rgb(220,222,225)的命中数应为 0(当前基线 55 / 27 / 6)。 - 调色板泄漏归零:
grep -rE "(text|bg|border)-(amber|rose|slate|emerald|teal|violet|purple|sky|cyan|red)-[0-9]{2,3}" web/src --include=*.tsx命中数应为 0(当前 253 处)。 - 对比度回归:对本文"深浅色与对比度"两张表逐行用 WCAG 相对亮度公式复算,全部文字行 ≥4.5:1、图形行 ≥3:1。
- 圆角归一:
document.querySelectorAll('*')去重后的borderRadius集合应只含{4.8, 6.4, 8, 11.2, 14.4, 17.6, 20.8, 999px}与 0(当前基线 12 档:2/6/7/8/10/12/14/18/24/26/32/9999px)。
取舍
解决了什么
- 零层级对比:侧栏/画布/卡片三者从"全同色
#fcfcfc"变成 1.03:1 / 1.06:1 / 1.11:1 的面差 + 发丝线,且在两套主题里方向一致(深色是「壳比内容暗」,浅色是「白卡浮在灰画布上」)。 - 三种蓝 → 一种蓝:
--brand(浅#2563eb/深#5b9bff) 与--mention(浅#1d4ed8/深#8ab4ff) 同族分级,硬编码#006ce7/#3370FF有唯一去处。 - 深色从"不可达且半可读"变成"可达且达标":补上
--interactive/--channel-icon深色值、修掉--surface-rail:#e3e5e8浅色竖带、给--input3:1 边界,并把 253 处不翻转的调色板泄漏列为同批清理项。 - 高密度视图的噪声:单视图字号 10 档 → 6 档(消灭 9/9.375/12.8/13.125px),圆角 12 档 → 7 档,颜色从 12 个 Tailwind 色族 → 1 个色相 + 中性阶。
- 模态在深色下能浮起来:
--popover从与卡片同值改为 +1 档(#191a1dvs#141517)。
牺牲了什么
- 放弃"浅色最轻":画布从
#fcfcfc退到#f7f8f9,白色只留给卡片与弹窗。好处是层级,代价是整屏不再有"纸白"感。 - 表单框线变重:浅色
--input从中性灰#dcdee1提到#8a9099(3.22:1)。这是 WCAG 控件边界要求的直接代价,会牺牲一部分"轻"。 - 放弃了暖色作为品牌辅助:
#ff6363只表达风险/逾期;因此"AI 助手"这类功能入口不能用暖色点亮,只能用secondary徽标 + 图标区分 —— 在同屏多入口时辨识速度不如双强调色方案。 - 六态任务状态只能靠 5 个官方 variant + 文字:牺牲了"一眼看颜色知状态"的扫描效率,换取不新增变体(硬约束)。
- 不引入任何阴影:卡片边界全靠 1px 线,在低质量显示器/缩放下 1px 线的可辨性不如阴影,是"工程感"换取的风险。
什么场景下不适用
- 投影/录屏/大屏看板场景:近黑画布 + 发丝边界在投影仪低对比度环境下会明显吃亏,此时浅色主题更合适(浅色是完整对等实现,可直接切)。
- 需要超过 2 个强调色并存的产品形态(例如同时要在同屏区分"AI 生成 / 人工确认 / 系统事件"三类来源):单色相纪律会强制改用文字标签,信息扫描效率下降。
- 营销页/落地页(
components/landing/*):本方案不含 hero、渐变、插图规则;那些页面只跟随令牌(背景/前景/边框)翻转,不做结构重设计。 - 移动端单手场景:8px 圆角 + 40px 图标容器与参考的 9999px pill 相比更"硬",触屏上缺少 pill 的点击暗示;现有
tap-target工具类(44px 命中区)可缓解,但不在本方案的观感目标内。