墨黑指令台 —— wanman /app 重设计方案(slug: raycast)

交付物:本文件 + tokens.css(可直接替换 web/src/styles.css 的 :root / .dark 变量块)+ preview.html(单文件预览)。 基线:worktree test@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 条)

  1. 画布唯一化:原文 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)。
  2. 单一强调色 + 严格配给:原文 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)。
  3. 暖色不作品牌色:原文 Do —— coral “is a brand mark, not a functional color”。wanman 的品牌色与 Flutter 端共用令牌,不能换色相;因此反向移植:把 Coral Pulse #ff6363 收编为 --destructive(风险/逾期/删除),暖色从此只表达危险,不表达品牌。
  4. 边界而非阴影:原文 —— “Components are defined less by shadows and more by hairline borders”;Don't —— “Don't add drop-shadows to cards or panels”。迁移为:卡片/面板用 --border 1px 发丝线定义,弹窗靠 --popover 明度台阶(深色 #191a1d ≠ 卡片 #141517)浮起,不新增阴影令牌。
  5. 圆角档位纪律 + 等宽微标签:原文 —— “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 档)。

明确舍弃的参考规则


适配判断

为什么这套语言适配「任务 + 频道消息」

  1. 长时段驻留 + 高信息密度:实测单视图字号 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)即可全局生效。
  2. 消息流与任务卡共存:任务卡是"卡片",消息气泡是"凹槽",参考的表面阶梯(canvas → card → recessed)正好对应「消息流底(canvas)→ 卡片(card)→ 输入框/引用块(recessed = --muted)」。
  3. 键盘优先:任务大厅「发布 / 接单 / 状态流转」是高频重复操作,键盘优先的指令台语言(--input 边界明确、焦点环 --ring=brand、等宽任务号)与"任务"这一核心正好同构。
  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),且深色下完全不翻转。单色相纪律是把这 253 处收敛回官方 variant 的理论依据。

舍弃项(本方案不做)


令牌映射

覆盖范围:本节表格含硬约束 §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 官方工具类

必须消除的三个现状缺陷

  1. 同一消息列表两套字号:实测他人 15px/400 #060607、自己 14px/400 #0d274a。这是 message-bubble.tsx 对自身气泡覆盖了字号 → 处置:删除该字号覆盖,两方都用 15px/1.5(这是"删除覆盖",不是新增覆盖,符合硬约束 §2.1)。
  2. 9px / 9.375px / 12.8px:来自以 15px 为基准的 em 计算(0.625em/0.85em)。处置:改为上文 6 档中的固定档位(12px 是下限,禁止 <12px)。
  3. .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 行):


深浅色与对比度

口径:正文文字 ≥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 配色)。所以:

  1. 令牌层修正是必要不充分条件;
  2. 必须补齐 --interactive/--channel-icon 的深色取值(已在本方案内,属【①】);
  3. 组件内硬编码(253 处 Tailwind 调色板 + bg-white + 头像 50/700 配对)必须按调用点替换为语义类或官方 variant(属【②】/【①】的调用点替换,不是新增变体);
  4. 若在 3 未完成时上线深色,会出现"深底 + 近黑字"的不可读区域 —— 因此本方案要求深色开关与硬编码清理同批上线,不允许先开开关。此项标为 ⚠风险(阻断项)。

shadcn 兼容性

结论:达成,且不需要新增任何官方组件、不需要新增任何自定义视觉变体。

必须显式标注的不合规处(3 条)

  1. ⚠风险 深色主题开关:需要在 web/src 里增加 .dark class 的挂载与持久化(当前无任何代码这么做)。这不属于三条途径,是方案落地的前置代码改动,实施成本与风险见下一节。
  2. ⚠风险 状态色与图标一致性:官方 Badge 只有 5 个可用 variant,无法为「待补充 / 待处理 / 进行中 / 待验收 / 已关闭 / 已逾期」六态各配一色;本方案用「variant + 文字前缀」区分(见《状态色统一口径》)。若产品坚持六态纯色区分,则必须新增 Badge variant → 不合规,需产品侧让步。同理,S8 应用中心用 emoji 作图标(与 lucide 不一致),替换图标不是令牌/variant/布局能解决的,属超出三条途径,需单独立项。
  3. ⚠风险 字号阶梯的落地口: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);缺参考背书,需设计评审

验证方式(哪些检查能证明改动生效)

  1. 令牌生效:getComputedStyle(document.documentElement).getPropertyValue('--background') 应返回 #f7f8f9(浅)与 #08090a(.dark)。
  2. 零层级对比已修:aside 的 backgroundColor ≠ body 的 backgroundColor(当前实测两者都是 #fcfcfc)。
  3. 深色泄漏归零:注入 .dark 后扫描全页 computed style,color: rgb(6,6,7) / rgb(92,94,102) / borderColor: rgb(220,222,225) 的命中数应为 0(当前基线 55 / 27 / 6)。
  4. 调色板泄漏归零: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 处)。
  5. 对比度回归:对本文"深浅色与对比度"两张表逐行用 WCAG 相对亮度公式复算,全部文字行 ≥4.5:1、图形行 ≥3:1。
  6. 圆角归一: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)。

取舍

解决了什么

  1. 零层级对比:侧栏/画布/卡片三者从"全同色 #fcfcfc"变成 1.03:1 / 1.06:1 / 1.11:1 的面差 + 发丝线,且在两套主题里方向一致(深色是「壳比内容暗」,浅色是「白卡浮在灰画布上」)。
  2. 三种蓝 → 一种蓝:--brand(浅 #2563eb/深 #5b9bff) 与 --mention(浅 #1d4ed8/深 #8ab4ff) 同族分级,硬编码 #006ce7/#3370FF 有唯一去处。
  3. 深色从"不可达且半可读"变成"可达且达标":补上 --interactive/--channel-icon 深色值、修掉 --surface-rail:#e3e5e8 浅色竖带、给 --input 3:1 边界,并把 253 处不翻转的调色板泄漏列为同批清理项。
  4. 高密度视图的噪声:单视图字号 10 档 → 6 档(消灭 9/9.375/12.8/13.125px),圆角 12 档 → 7 档,颜色从 12 个 Tailwind 色族 → 1 个色相 + 中性阶。
  5. 模态在深色下能浮起来:--popover 从与卡片同值改为 +1 档(#191a1d vs #141517)。

牺牲了什么

  1. 放弃"浅色最轻":画布从 #fcfcfc 退到 #f7f8f9,白色只留给卡片与弹窗。好处是层级,代价是整屏不再有"纸白"感。
  2. 表单框线变重:浅色 --input 从中性灰 #dcdee1 提到 #8a9099(3.22:1)。这是 WCAG 控件边界要求的直接代价,会牺牲一部分"轻"。
  3. 放弃了暖色作为品牌辅助:#ff6363 只表达风险/逾期;因此"AI 助手"这类功能入口不能用暖色点亮,只能用 secondary 徽标 + 图标区分 —— 在同屏多入口时辨识速度不如双强调色方案。
  4. 六态任务状态只能靠 5 个官方 variant + 文字:牺牲了"一眼看颜色知状态"的扫描效率,换取不新增变体(硬约束)。
  5. 不引入任何阴影:卡片边界全靠 1px 线,在低质量显示器/缩放下 1px 线的可辨性不如阴影,是"工程感"换取的风险。

什么场景下不适用