暖钢工坊 · Ember Shopfloor — wanman /app 重设计方案
参考设计:Retool(
retool)。对象:https://wanman-test.example.com/app,代码web/(React + TanStack Router + Tailwind + shadcn/ui,components.json的base-nova)。 基线:test@3d35969f;实测环境 1440×900,真实数据(580 用户 / 148 频道 / 30 空间 / 1554 消息 / 457 任务)。 交付:docs/design-proposals/retool/{proposal.md,tokens.css,preview.html}。本方案不改动web/下任何文件。
方案名与主张
中文名:暖钢工坊(Ember Shopfloor)
一句话主张: 把目前从飞书采样出来的「蓝灰画布 + 单一品牌蓝 + 同色层级」换成 Retool 式黑曜石三步面层(#0e0e0e 衬底 → #151515 画布 → #242424 面层)+ 单一暖橙强调,用亮度步进而非阴影表达层级;浅色是同一套语言的暖砂版本(#e2dcd2 衬底 → #f7f5f1 画布 → #ffffff 面层)。
三条不可妥协的立意:
- 层级靠面层,不靠描边。 现状
--background与--sidebar同为#fcfcfc(实测 1.00:1),会话侧栏与右侧主面板逐像素同色;Retool 的解法是连续三步亮度阶梯。本方案在浅色给出 1.15:1 → 1.09:1 两步,深色给出 1.06:1 → 1.18:1 两步,全部由令牌驱动。 - 全站只有一个彩色。 现状界面 chrome 里蓝(品牌)、绿/琥珀/玫瑰(6 个业务 tone)、emoji 图标并列,注意力被摊平。本方案把彩色预算收成 ember 橙一族(
--brand/--brand-ink/--brand-soft/--mention/--chart-*),其余一切退到暖中性灰(Parchment#e9ebdf/ Charcoal#3f403d),彩色只出现在「当前状态」上。 - 深色是一等公民。 现状
.dark(styles.css:163-211)只声明了 39 个变量(:root有 48 个),漏掉了--interactive和--channel-icon;注入.dark后--interactive继承浅色的#4e5058,在#0a0a0a上只有 2.46:1。本方案让深浅两套逐变量对齐、逐项给出实测比值。
主色: 浅色 --brand: #c2410c(ember 700 档,白字 5.18:1)/深色 --brand: #f97316(亮度型 CTA,近黑字 #1a1206 6.61:1)。
圆角: --radius: 0.625rem → 0.5rem(Retool cards-default 8px),实测 10px / 18px 两档随之消失。
覆盖样例面: S1、S2、S3、S4、S5、S7、S8(7 个),另附 S6 的代码级说明(§6 末)。
参考提炼
从 Retool 的界面语言里提炼出 6 条可直接翻译成令牌的规则,以及 4 条主动舍弃的规则。
继承并翻译成令牌的 6 条:
| # | Retool 规则 | 本方案的令牌落点 |
|---|---|---|
| 1 | 三步面层纯亮度分层、零阴影:#0e0e0e(退后)/ #151515(画布)/ #242424(抬起),相邻步进约 3% 亮度 |
--surface-rail / --workspace-background / --background / --card / --sidebar;浅色对应 #e2dcd2 / #f7f5f1 / #ffffff |
| 2 | 明令不用纯黑 #000、不用纯白 #ffffff,所有「白」是暖 Parchment #e9ebdf |
深色 --foreground: #e9ebdf、--background: #151515(原文 #0a0a0a 已近纯黑);浅色 --background: #f7f5f1、--foreground: #1c1a17 |
| 3 | Charcoal Rim #3f403d:边框是实体暖灰,不是 alpha 白 |
深色 --border: #3f403d(原文 oklch(1 0 0 / 10%),合成后 #222222 且随底层漂移) |
| 4 | 唯一彩色是低饱和大面积水洗,饱和色不得进入界面 chrome | 彩色收缩为 ember 一族;业务 tone(tone.ts 的 emerald/teal/amber/blue/rose/slate)改走官方 Badge variant 的中性档 |
| 5 | 间距基准 4px;卡片默认圆角 8px、大卡 12px、徽标 4px | --radius: 0.5rem(8px)为唯一卡片档;--radius-2xl 1.8×0.5rem = 14.4px 承担弹窗;4px 栅格与现有 64px 会话行、52px 频道头一致,不动 |
| 6 | 小字号标签 +0.01em 字距、大字号轻字重 −0.02em,用字距区分「界面语」与「内容语」 | 字号体系见 §5;字距作为风险 R1 登记(tracking 是 className,不在三条途径内) |
主动舍弃的 4 条(企业协作工具不适用):
- 0px / 9999px 二元圆角语法 —— Retool 的锋利语法在消息气泡、任务卡、头像上会变成标签墙;本方案保留 shadcn 自带的柔和圆角阶梯(
--radius-sm..4xl),只把基准从 10px 收到 8px。 - pill CTA 与 hero 径向渐变、营销式大标题 —— S3 群聊大厅现在正是「营销式 hero + 品牌蓝 20 处」;本方案不搬 Retool 那套,反其道把大厅降级到与任务大厅同构的容器布局(§6-S3)。
- em dash 风格装饰与超大 display 字号 —— 企业工具没有 display 层级,最大字号止于 26px(登录页),且是既有值。
- 深色独有的「唯一亮色」特权 —— Retool 深色下 teal 大面积水洗只在深色出现;本方案的 ember 在深浅两套里同位对等(浅
#c2410c/ 深#f97316),避免浅色用户拿到一个「没有品牌色」的产品。
适配判断
结论:适配,且改造几乎全部落在「语义令牌取值」一条途径上(不需要新增任何组件变体)。
有利条件(已逐条核实到代码):
web/components.json是cssVariables: true,styles.css:31-106(@theme inline)把每个--color-*都写成var(--令牌);因此改:root/.dark即改全站,ui/下 34 个组件(+ui/chat/子目录 11 个,共 45 个)一行都不用动(清单见 §8)。- 圆角全部由
--radius推导:实测档位 14px =--radius-xl(0.625rem×1.4,im-sidebar.tsx:226的md:rounded-xl)、18px =--radius-2xl(×1.8,channel-settings-dialog.tsx:477与space-manage-dialog.tsx:183的rounded-2xl)、10px =--radius-lg(=--radius)、8px =--radius-md(×0.8)。把--radius改成0.5rem后档位变为 4.8 / 6.4 / 8 / 11.2 / 14.4 / 17.6px——10px 与 18px 两档消失,卡片与控件统一落在 8px。零 className 改动,纯途径①。 - 消息气泡配色 100% 令牌驱动:
web/src/components/app/message-bubble.tsx(23 行)把--primary/--primary-foreground就地在气泡作用域内重映射为--message-self/--message-self-foreground;本人消息渲染Bubble variant="default"(=--primary),他人消息Bubble variant="secondary"(=--secondary)。所以「自己/他人气泡」两色是纯令牌(途径①)。 - 登录页样式全部走令牌:
styles.css:1091-1290(209 行)的.login-glass-*/.login-primary-btn里除:1114一处投影色#000 40%外零硬编码,其余全是color-mix(in oklab, var(--brand) 7~32%, …)/var(--card)/var(--foreground)/var(--background)/var(--muted)/var(--destructive);主按钮渐变是linear-gradient(135deg, var(--brand), var(--brand-ink))。令牌改值,登录页就从蓝玻璃变 ember 玻璃,零代码(途径①)。 - 外壳衬底本身是令牌:
styles.css:977-979的.workspace-shell { background: var(--workspace-background) },app-shell.tsx:12070挂在 shell 根节点上——这是全站唯一一块「可以彻底变色的底」。
不利条件(写在 §8、§10,并编号为 R1–R5):
--sidebar族在web/src中零引用(grep 'bg-sidebar|sidebar-accent'= 0 命中)。会话侧栏真正用的是components/app/chrome.ts:55的imListAside = "relative flex h-full w-full flex-col bg-background",即和右侧主面板同一个--background(全仓bg-background103 处)。同一令牌无法拆成两个值 ⇒ 侧栏与主面板之间的层级只能靠容器沟槽(途径③)让--workspace-background透出来,见 §6-S1。- 硬编码 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);源头是
components/app/tone.ts的 6 个 tone 与 5 张 class 映射表。令牌改不动它们(R2)。 - 深色主题在运行环境中不可达:
web/src内没有任何代码给<html>加.dark(<html class>恒为空),declarations.css里 104 条.dark\:*规则查不到命中元素。深色只能人工注入验证(R4)。 - 正文里 55 处硬编码
--foreground等价色rgb(6,6,7)(注入.dark后不翻转),另有rgb(92,94,102)27 处、rgb(220,222,225)6 处、头像底rgb(255,251,235)3 处(R2)。
令牌映射
tokens.css 就是可直接替换 styles.css:108-211 的成品:变量名与 styles.css 现有名字逐一对应(无新增令牌、无语义角色变更),改动写在该文件里每一行上方的中文注释里。@theme inline(styles.css:31-106)逐字沿用原文,无改动。
4.1 浅色 :root
| 变量 | 当前值 | 建议值 | 意图(途径①) |
|---|---|---|---|
--background |
#fcfcfc |
#f7f5f1 |
暖砂画布;给 --card/--sidebar 让出 1.09:1 的立足点 |
--foreground |
#060607 |
#1c1a17 |
暖近黑正文,15.95:1 |
--card |
#ffffff |
#ffffff |
不动(面层最上一步) |
--card-foreground |
#060607 |
#1c1a17 |
随正文转暖 |
--popover |
#ffffff |
#ffffff |
不动 |
--popover-foreground |
#060607 |
#1c1a17 |
随正文转暖 |
--primary |
var(--brand) |
var(--brand) |
引用不动 |
--primary-foreground |
var(--brand-foreground) |
var(--brand-foreground) |
引用不动 |
--secondary |
#ebedef |
#eeebe4 |
他人气泡底,去冷转暖;与本人气泡拉开 1.11:1 |
--secondary-foreground |
#060607 |
#1c1a17 |
随正文 |
--muted |
#f2f3f5 |
#f1eee8 |
弱面(骨架、输入框外框) |
--muted-foreground |
#5c5e66 |
#6a655d |
次级文字:卡片 5.78:1、画布 5.31:1 |
--accent |
#ebedef |
#ece8e0 |
hover 面 |
--accent-foreground |
#060607 |
#1c1a17 |
随正文 |
--destructive |
#da373c |
#c0341d |
原值在画布上 4.46:1(不达 AA)→ 5.14:1 |
--border |
#dcdee1 |
#e0dbd2 |
装饰性分隔线转暖(1.27:1,见 §7 说明) |
--input |
#dcdee1 |
#8f887c |
表单控件边界提到 3:1(白卡 3.51:1),满足 WCAG 1.4.11 |
--ring |
var(--brand) |
var(--brand) |
焦点环随笔触变 ember |
--brand |
#2563eb |
#c2410c |
飞书蓝 → ember 橙;白字 5.18:1 |
--brand-foreground |
#ffffff |
#ffffff |
不动(ember 700 上白字 5.18:1) |
--brand-soft |
rgb(37 99 235 / 0.12) |
rgb(194 65 12 / 0.10) |
选中块柔底;白卡上合成 #f9ece7,压 --brand-ink 得 6.33:1 |
--brand-ink |
#1d4ed8 |
#9a3412 |
柔底文字 + 登录按钮渐变暗端(白字 7.31:1) |
--message-self |
#e8f3fe |
#f7dcba |
本人气泡:与次色 1.11:1、与卡片 1.37:1(现状对次色仅 1.02:1) |
--message-self-foreground |
#0d274a |
#43220d |
气泡文字 10.79:1 |
--surface-chat-soft |
#e8f2ff |
#fbeadd |
引用/回复底,对画布 1.08:1 |
--surface-chat-selected |
#e5ecfc |
#f5dfc9 |
会话选中底,对侧栏白底 1.29:1 |
--mention |
#3370ff |
#a83c0c |
@提及:原值画布上 4.18:1(不达 AA)→ 5.81:1 |
--ink |
#060607 |
#1c1a17 |
深色文字语义位,随正文 |
--surface-rail |
#e1e8f2 |
#eae5dd |
空间 rail 由蓝灰转暖,对画布 1.15:1 |
--sidebar |
#fcfcfc |
#ffffff |
与画布拉开 1.09:1(本仓零引用,见 R6) |
--sidebar-foreground |
#060607 |
#1c1a17 |
随正文 |
--sidebar-accent |
#ebedef |
#ece8e0 |
与 --accent 同源 |
--sidebar-accent-foreground |
#060607 |
#1c1a17 |
随正文 |
--sidebar-border |
#dcdee1 |
#e0dbd2 |
与 --border 同源 |
--chart-1..5 |
oklch(0.87/0.556/0.439/0.371/0.269 0 0)(灰阶) |
#c76f2a / #a5571c / #844113 / #63300f / #8a857d |
ember 单色阶 + 一档暖中性;在 #ffffff 上 3.66 / 5.28 / 7.65 / 10.71 / 3.66:1 |
--radius |
0.625rem |
0.5rem |
8px 基准,收敛实测 10px/18px 两档 |
4.2 深色 .dark
原 .dark 只声明 39 个变量(:root 为 48 个);下表是完整的对齐结果(含补齐项)。当前值中的 oklch 已在换算为 sRGB hex 后列入。
| 变量 | 当前值 | 建议值 | 意图(途径①) |
|---|---|---|---|
--background |
oklch(0.145 0 0) = #0a0a0a |
#151515 |
Retool 明令不用纯黑;抬到画布步进,ember 光晕才有落点 |
--foreground |
oklch(0.985 0 0) = #fafafa |
#e9ebdf |
冷白 → 暖 Parchment;15.14:1 |
--card |
oklch(0.205 0 0) = #171717 |
#242424 |
面层抬起一步(对画布 1.18:1,零阴影) |
--card-foreground |
oklch(0.985 0 0) |
#e9ebdf |
随正文 |
--popover |
oklch(0.205 0 0) = #171717 |
#242424 |
同 --card |
--popover-foreground |
oklch(0.985 0 0) |
#e9ebdf |
随正文 |
--primary |
var(--brand) |
var(--brand) |
引用不动 |
--primary-foreground |
var(--brand-foreground) |
var(--brand-foreground) |
引用不动 |
--secondary |
oklch(0.269 0 0) = #262626 |
#262626 |
值不变;此处显式声明以保持与浅色逐变量对齐 |
--secondary-foreground |
oklch(0.985 0 0) |
#e9ebdf |
他人气泡文字 12.55:1 |
--muted |
oklch(0.269 0 0) = #262626 |
#1f1f1f |
与 --card/--accent 分离,避免弱面与卡片同色(原文三者同值) |
--muted-foreground |
oklch(0.708 0 0) = #a1a1a1 |
#a8a69c |
暖中性灰;卡片 6.36:1、弱面 6.75:1 |
--accent |
oklch(0.269 0 0) = #262626 |
#2a2a2a |
hover 面比卡片再亮一档(对画布 1.27:1) |
--accent-foreground |
oklch(0.985 0 0) |
#e9ebdf |
随正文 |
--destructive |
oklch(0.704 0.191 22.216) = #ff6467 |
#ff8578 |
冷红 → 暖瓷红;在自身 20% 柔底上 4.58:1(原值 3.96:1 不达 AA),画布上 7.72:1 |
--border |
oklch(1 0 0 / 10%) ≈ #222222 |
#3f403d |
去 alpha 改实体暖灰(Retool Charcoal Rim),不再随底层漂移 |
--input |
oklch(1 0 0 / 15%) ≈ #3a3a3a |
#76766f |
控件边界 3.39:1(卡片)/ 3.99:1(画布),满足 1.4.11 |
--ring |
未声明(继承 var(--brand)) |
var(--brand) |
深色下解析为 #f97316 |
--brand |
oklch(0.68 0.15 256) = #5599f3 |
#f97316 |
深色下 ember 是唯一亮色;近黑字压其上 6.61:1 |
--brand-foreground |
oklch(0.16 0.02 258) = #080d16 |
#1a1206 |
暖近黑(亮度型 CTA 的文字端) |
--brand-soft |
oklch(0.28 0.05 256) = #182941 |
rgb(249 115 22 / 0.16) |
卡片上合成 #463122,压 --brand-ink 得 7.23:1 |
--brand-ink |
oklch(0.84 0.09 256) = #a4cdff |
#fdba74 |
柔底文字 + 登录按钮渐变亮端(10.99:1) |
--message-self |
#203b59 |
#442a14 |
本人气泡深 ember:对次色气泡 1.14:1、对卡片 1.17:1 |
--message-self-foreground |
#e7f3ff |
#fbe3cd |
气泡文字 10.69:1 |
--surface-chat-soft |
oklch(0.32 0.06 250) = #193550 |
#2b1c10 |
引用/回复底转暖,对画布 1.11:1 |
--surface-chat-selected |
oklch(0.28 0.04 250) = #192a3c |
#3a2614 |
会话选中底:对画布 1.28:1、对侧栏 1.19:1 |
--mention |
oklch(0.72 0.14 254) = #62a7fa |
#ffab70 |
@提及 9.84:1 |
--ink |
oklch(0.16 0.02 258) = #080d16 |
#17120e |
深色文字语义位转暖 |
--surface-rail |
#e3e5e8 |
#0e0e0e |
原文是深色下的一根浅色竖带(对画布 15.69:1);改为退后一步的凹槽(1.06:1) |
--sidebar |
oklch(0.205 0 0) = #171717 |
#1c1c1c |
抬起弱于卡片:对画布 1.07:1(本仓零引用,见 R6) |
--sidebar-foreground |
oklch(0.985 0 0) |
#e9ebdf |
随正文 |
--sidebar-accent |
oklch(0.269 0 0) = #262626 |
#2a2a2a |
与 --accent 同源 |
--sidebar-accent-foreground |
oklch(0.985 0 0) |
#e9ebdf |
随正文 |
--sidebar-border |
oklch(1 0 0 / 10%) |
#3f403d |
与 --border 同源 |
--chart-1..5 |
同浅色灰阶 | #f7bd90 / #ef9560 / #dd6f31 / #b8551d / #a8a69c |
在 #242424 上 9.34 / 6.75 / 4.73 / 3.22 / 6.36:1 |
--radius |
未声明(继承 :root) |
不重声明 | 继承 0.5rem 即可 |
--interactive |
未声明 → 继承浅色 #4e5058 |
#94958e |
补齐。原值在 #0a0a0a 上 2.46:1(不可读),新值 6.04:1 |
--channel-icon |
未声明 → 继承浅色 #80848e |
#8b867f |
补齐,5.06:1 |
--workspace-background(深色)另有一处方向性修正:原文 radial-gradient(ellipse at 8% 0%, color-mix(oklab, var(--brand) 10%, var(--muted)), var(--muted) 64%) 以 --muted(#1f1f1f)收尾,导致衬底比面板更亮(衬底浮在画布之上),层级方向反了;改用 --surface-rail 作底后是「黑曜石底 + 左上角 ember 光晕」,衬底↔面板 1.06:1、面板↔卡片 1.18:1。浅色 --workspace-background 同步取暖端(#eae5dd → #e2dcd2),与画布相距 1.15:1 ~ 1.25:1。
字体与排版
字体族不动,且是「有意的非改动」: --font-sans(styles.css:32-38)以 "Geist Variable", "gg sans" 打头,两者都没有 CJK 字形,中文按字形回退到 "Noto Sans SC", "PingFang SC", ui-sans-serif——正合硬约束 4(中文回退必须落到 Noto Sans SC / PingFang SC)。--font-mono(ui-monospace, "SF Mono")用于任务 ID、数字统计、tabular-nums。
排版主张:不新增任何字号,只把「非刻度字号」收回到官方组件的官方档与 12px 中文下限。 实测字号档位为 9 / 9.375 / 11 / 11.25 / 12 / 12.8 / 13.125 / 14 / 15 / 26px——其中 9.375、11.25、12.8、13.125 是 text-[0.8em] / em 计算 / 任意值写法产生的非刻度值。
| 语义角色 | 现状实测 | 目标 | 途径 |
|---|---|---|---|
| 消息正文 | 他人 15px/400、自己 14px/400(§3.3 文本运行块:同一列表两套字号;S2-main-geometry 全部气泡上报 14px —— 两处证据不一致,可确认的是「同一列表里 14/15 混合」) |
统一 15px / 行高 1.375(20.63px) | 超出三途径 → R1(需删 message-bubble 内的字号覆写) |
| 空间头计数行 vs 频道头成员数 | 空间头 15px/400(「12 个频道 · 5 位成员」),S2 频道头成员数 12px/500 —— 同类信息两套字号 | 13px 单一档 | 超出三途径 → R1 |
| 会话行主文本 | 14px | 14px(官方 Item 默认 text-sm) |
① + ②(换官方 Item,字号自然回落官方档) |
| 作者名 / 频道头标题 | 13px / 16px 600 | 13px / 16px 600 | 不动 |
| 时间戳 / 成员数 / 元信息 | 12px 500 / 12px | 12px(= 官方 text-xs,也已到中文 12px 下限) |
②(徽标换官方 Badge 后即 12px) |
| 业务状态 chip(手写 span) | 12.8px(px-1.5 py-0.5 的 em 计算产物) |
12px(官方 Badge 的 text-xs) |
②——这是本方案唯一能真正消灭非刻度字号的地方 |
| 任务卡标题 | 14px 500 | 14px 500 | 不动 |
| 消息预览(会话列表第二行) | 11.25px | 12px | 超出三途径 → R1 |
| 登录页页脚 | 11px | 12px | 超出三途径 → R1(且 11px 低于中文 12px 下限) |
| 登录页主标题 | 26px(52px 行高按钮同级) | 保留 26px | 既有值,超出官方 size → R5 |
| 表格 / 数字统计 | 12–13px,混用 | 12px + --font-mono + tabular-nums |
② + ①(--font-mono 已是令牌) |
字距(tracking-tight / tracking-wide)与字重(300/400/500/600)不在三条途径内,本方案不做主张;Retool 的「标签 +0.01em / 大标题 −0.02em」若要落实,须走 R1 的同一豁免。
关键界面改造
每条改造都标注了落在哪条途径:①语义令牌取值 / ②官方 variant/size / ③容器布局与间距。凡不在三条途径内的一律标为风险。
6.1 S1 外壳与空间/频道侧栏(app-shell.tsx、channel-sidebar.tsx、im-sidebar.tsx、chrome.ts)
现状(实测)
- 空间 rail:
nav72×900,background透明,右侧边框rgba(220,222,225,0.55)——不是--border,是硬编码半透明值。 - 会话侧栏:
aside256×715 @ x=76(与 rail 之间 4px 沟槽),border-radius 14px,background #fcfcfc;因为chrome.ts:55的imListAside用的是bg-background,它与右侧主面板逐像素同色(1.00:1),层级为零。 - 侧栏头 52px;搜索框高 30px、圆角 10px、背景
rgba(235,238,239,0.75);会话行 240×64;body15px / 1.375。
改后
- ①
--surface-rail:浅#e1e8f2 → #eae5dd、深#e3e5e8 → #0e0e0e。深色那一处是缺陷修复:原值让 rail 变成深色下的一根浅色竖带(对画布 15.69:1);改后是退后一步的凹槽(1.06:1)。--workspace-background同步暖端(浅#eae5dd→#e2dcd2,深「#0e0e0e+ ember 光晕」),使.workspace-shell(styles.css:977)成为一块真正退后的衬底。 - ③ 侧栏与主面板之间的沟槽由 4px 提到 8px(
gap,容器层)。这一步是唯一能造出「侧栏浮在衬底上」观感的做法,因为两者共用--background(见 §3 不利条件 1)。侧栏自身已有md:rounded-xl,令牌改0.5rem后圆角自动从 14px 收到 11.2px,与衬底之间的圆角-沟槽关系更清楚——零 className 改动。 - ①
--interactive(浅#5a554d/ 深#94958e)与--channel-icon(浅#8b857c/ 深#8b867f)整体转暖,并在深色补上声明(原.dark缺失,继承浅色值#4e5058在#0a0a0a上仅 2.46:1)。 - ② 会话行改用官方
Item(选中variant="muted"、size="sm"),未读点用官方Badge variant="default"的 pill;头像从硬编码 Tailwind 色对换成官方Avatar+AvatarFallback(其内建bg-muted text-muted-foreground正好吃到本方案的暖中性色)。现状硬编码的 5 组头像色对实测为 amberrgb(255,251,235)/rgb(187,77,0)、rosergb(255,241,242)/rgb(199,0,54)、bluergb(239,246,255)/rgb(20,71,230)、emeraldrgb(236,253,245)/rgb(0,122,85)、tealrgb(240,253,250)/rgb(0,120,111)——注入.dark后这些浅色底依然是浅色块,属 R2。 - ③ rail 72px、侧栏 256px、行高 64px、侧栏头 52px 全部保持:密度层面实测已是好的,本方案只改面层级。
6.2 S2 频道消息流(message-list.tsx、channel-thread.tsx、channel-header.tsx、message-bubble.tsx)
现状(实测)
- 频道头 860×52,标题 16px/600
#060607,成员数 12px/500#5c5e66。 - 气泡圆角 14px;他人气泡
rgb(235,237,239)(=--secondary=--accent)、本人气泡rgb(232,243,254)配rgb(13,39,74)——两者亮度差仅 1.02:1,靠色相区分,深色下还会一起翻成近黑的#203b59。 - 正文:他人 15px/400
#060607、自己 14px/400#0d274a(§3.3 文本运行块);S2-main-geometry里全部气泡上报 14px——两条证据不一致,保守结论是「同一列表 14/15 混排」。 - 输入区:
textarea628×33 无边框,外层只有一条上边框rgb(220,222,225)(硬编码);工具按钮 28×28(= 官方size="icon-sm"h-7)。
改后
- ① 气泡配色 100% 靠
--message-self/--message-self-foreground/--secondary:本人浅#f7dcba+#43220d(10.79:1)、深#442a14+#fbe3cd(10.69:1);他人浅#eeebe4、深#262626。自己/他人区分度由 1.02:1 提到 1.11:1(浅)/ 1.14:1(深),且色相从「蓝 vs 灰」变成「暖砂 vs 暖灰」,在深色下不会塌成一个黑块。message-bubble.tsx的--primary → --message-self重映射不用改一行。 - ② 消息触发的工具条与频道头动作统一走官方
Button variant="ghost" size="icon-sm"(h-7 = 28px,与实测一致),hover 面自动落到--accent。 - ① @提及色
--mention#3370ff → #a83c0c:现状在画布上 4.18:1(不达 AA),改后 5.81:1(--surface-chat-selected上 4.91:1)。引用/回复底用--surface-chat-soft(浅#fbeadd/ 深#2b1c10)。 - ③ 消息流本身是
MessageScroller(官方组件已在ui/中)+ 容器max-width与行间距,不改组件内部。 - 风险 R1:「同一列表两套字号」的修复必须删掉
message-bubble.tsx里对正文字号的覆写,属超出三途径的 className 删除,单列。
6.3 S3 任务大厅 + 任务卡(task-hall.tsx、group-hall.tsx、create-task-dialog.tsx、channel-work-items.tsx、tone.ts)
现状(实测)
- 列头「待补充 0 / 待处理 5」、筛选条「全部频道 / 5 项任务」;卡片标题 14px/500 + 频道 chip +
AI 助手chip +查看任务+ 负责人。 - 圆角双档混用:10px × 48 个、8px × 37 个(两者都是
--radius推导,所以令牌一改就收敛)。 - 状态 chip 是手写
<span className={cn("rounded-full border px-1.5 py-0.5 font-medium", ...)}>,取自toneChipClasses,实测量到border-amber-200 bg-amber-50 text-amber-800、border-rose-200 bg-rose-50 text-rose-700,slate档为border-border bg-muted text-interactive。tone.ts共 6 个 tone(brand / emerald / teal / amber / blue / rose / slate)与 5 张映射表(toneTileClasses/toneTextClasses/toneChipClasses/toneBarClasses/toneBorderClasses)。 - 群聊大厅:营销式 hero + 品牌蓝
rgb(37,99,235)出现 20 处。 - AI 助手空间:395 项任务,字号 12.8 / 12 / 14px 混用,圆角 8px × 1591、10px × 844。
改后
- ② 状态 chip 换成官方
Badge,6 个业务状态映射到官方 variant:
| 业务状态 | 官方 Badge variant |
视觉 |
|---|---|---|
| 待补充 | outline |
描边中性 |
| 待处理 | secondary |
次色实底 |
| 进行中 | default |
全站唯一 ember 实心(近黑/白字,浅 5.18:1 / 深 6.61:1) |
| 待验收 | destructive |
暖瓷红(语义借用 → R3) |
| 已完成 | ghost |
文字型 |
| 已关闭 | ghost |
与已完成同 treatment,靠文字区分(→ R3) |
| 风险 / 发布失败 | destructive |
暖瓷红 |
同时 tone.ts 的 6 个 tone 收束到官方档:brand → default、emerald/teal → secondary、amber/blue → outline、rose → destructive、slate → ghost。这一步顺带消灭了 12.8px 这个非刻度字号(官方 Badge = h-5 px-2 text-xs = 12px)。
2. ① --radius: 0.5rem 让实测的 10px/8px 两档收敛到 8px(--radius-lg)与 6.4px(--radius-md),任务卡成组地看起来「一套圆角」。状态色全部落到令牌(--brand-soft / --brand-ink / --destructive / --muted / --border)后,ember 柔底 rgb(194 65 12 / 0.10) 取代蓝柔底。
3. ② 进度条目前靠 toneBarClasses(bg-emerald-500 等硬编码)——ui/ 下没有官方 progress,建议引入官方 progress 组件承接(见 §8)。
4. ③ 任务卡网格与列宽属容器布局;卡片内部间距用官方 Card(--card-spacing,默认 16px / size="sm" 12px),列头与筛选条保持在一条 52px 高的 header 里(与频道头同高,形成跨页面的横向节律)。
5. ③ + ② 群聊大厅去掉营销式 hero:把 hero 降级成与任务大厅同构的容器(一行标题 + 一行统计 + 筛选行),品牌蓝 20 处全部由令牌接管或换成官方 Badge/Button variant。
6.4 S4 AI 助手频道(agent-chat-panel.tsx、agent-channel.tsx、agent-channel-results.tsx、channel-summary-panel.tsx)
现状:agent-chat-panel.tsx:350 用 <Bubble align="end" variant="muted"> 渲染本人的提问、:325 用 <EmptyMedia variant="icon"> 做空态;回答是流式文本 + 来源引用 + 结果卡片,右侧 280px(17.5rem)历史栏 hidden md:flex + border-r border-border/45 bg-background。
改后
- ② 本人消息统一走
message-bubble.tsx的MessageBubble(own →--message-self),助手消息用Bubble variant="secondary"。关键收益:AI 频道不再是独立配色孤岛——现状它在 S2 之外另开了一套variant="muted",于是「自己说的话」在频道里是 ember、在 AI 频道里是中性灰;统一后同一句「我」在两种上下文里同色。 - ① 备选档
Bubble variant="tinted"(其实现是oklch(from var(--primary) …),从--primary推导),令牌一改即 ember 着色——若产品希望助手回答也带一点暖色,只需换 variant,不动令牌。 - ② 空态用官方
Empty*三件套;来源引用与结果卡片改官方Card+Badge variant="outline";流式等待用官方Skeleton(--muted承载,浅#f1eee8/ 深#1f1f1f)。 - ③ 右侧历史栏宽 17.5rem 与左边框
border-border/45属既有容器取值;本方案只让它的底色吃--background、边界吃--border。
6.5 S5 管理设置弹窗(space-manage-dialog.tsx、channel-settings-dialog.tsx、group-members.tsx、channel-permission-picker.tsx)
现状(实测)
[role=dialog]704×512,圆角 18px(=--radius-2xl),背景#ffffff。- 左侧导航项 135×36,圆角 8px(=
--radius-md);选中态--brand-soft rgb(37 99 235 / 0.12)+--brand-ink #1d4ed8;危险项--destructive #da373c。 - 输入框 488×32,圆角 10px(=
--radius-lg,官方Input就是 h-8),边框#dcdee1(白卡上仅 1.31:1);表单标签 14px。 channel-settings-dialog.tsx:71有一处 TabsTrigger 的 className 旁路:data-active:bg-brand-soft data-active:text-brand-ink。
改后
- ①
--brand-soft/--brand-ink/--destructive/--input换值即完成整体换色;--input: #8f887c让 488×32 输入框的边界从 1.31:1 提到 3.51:1,达标 WCAG 1.4.11。 - ② 删除
channel-settings-dialog.tsx:71的覆写,回到官方Tabs orientation="vertical" variant="line":选中态由--foreground的 2px 指示条承担(浅#1c1a17对白底 17.36:1、深#e9ebdf对#1c1c1c14.13:1)。代价是失去「选中块整块 ember 柔底」,写入 §10。 - ② 表单用官方
Field/FieldLabel/FieldSelect;成员列表用官方Item+Avatar+Badge;危险操作用官方Button variant="destructive"(--destructive换值后即暖瓷红)。 - ③ 704×512、36px 行高、135px 导航宽度保持;圆角由
--radius-2xl自动从 18px 收到 14.4px——这是本方案唯一会让弹窗「变紧」的改动,且是零代码的。
6.6 S6 语音频道(依据代码,不依据截图)
本栈不可见,理由全部来自代码与库内数据,没有任何截图作为依据:
- 组件存在:
web/src/components/app/rtc-group-call-ui.tsx(以及rtc-live-transcript-panel.tsx、personal-call-sidebar.tsx)。 - 数据存在:库内
wanman3_rtc_voice_channels30 行(空间 395/396/398/399 各有active频道)、wanman3_rtc_calls183 行、会议纪要 20 行。 - 但本机
TRTC_ENABLED=false,/api/v1/rtc/*一律返回RTC_DISABLED;DOM 内aria-label匹配「语音|通话|加入」命中 0,正文不含「语音」。 ⇒ 界面一个语音元素都不渲染,本方案不对 S6 做视觉主张。唯一可写的是:若开启 TRTC,语音面板会用到--card/--border/--muted-foreground,即天然继承本方案的暖中性面层,不需要为它单独配色。
6.7 S7 登录页(routes/login.tsx、sign-in.$.tsx、styles.css:1091-1290)
现状(实测):居中卡片;主标题 26px;「邮箱验证码 / 短信验证码」切换块 173×42(选中态背景 --background + 品牌蓝文字);主按钮 356×52,白字压 #2563eb(5.17:1);页脚 11px(低于中文 12px 下限)。文案:「登录 WanChat」「使用企业邮箱验证码继续」「企业邮箱 @example.com」「获取验证码」。样式全在 .login-glass-* / .login-primary-btn,主按钮渐变 = linear-gradient(135deg, var(--brand), var(--brand-ink))。
改后
- ①(本方案最干净的一处) 只改令牌:
--brand#2563eb → #c2410c、--brand-ink#1d4ed8 → #9a3412、--card#ffffff(不动)、--foreground → #1c1a17、--background → #f7f5f1。蓝玻璃因此变成 ember 玻璃:白字在渐变浅端 5.18:1、深端 7.31:1;深色下--brand #f97316+--brand-ink #fdba74,深字 6.61:1 / 10.99:1。零代码,判定为纯途径①。 - ③ 卡片留白与居中容器属布局,不动。
- R5:26px 主标题与 52px 按钮超出官方
Button size上限(lg= h-9 = 36px)。两条路:(a) 保留自定义尺寸(登录页是产品「门面」,52px 触摸目标合理,代价是继续持有非官方尺寸类);(b) 改官方Button size="lg"并删掉.login-primary-btn的渐变/阴影(代价是失去 ember 渐变,按钮变成纯色--brand)。本方案不替产品决定,默认取 (a),因为 52px 的可点击面积是可用性收益。
6.8 S8 应用中心(app-center.tsx、assistant-board.tsx)
现状(实测):8 个分类(全部 / Agent / 人事行政 / 数据与报表 / 项目管理 / 行业模板 / 研发协作 / 智能办公)+「共 14 个应用」+ 卡片(运行中 / 开发中 徽标、emoji 图标、Agent · 第三方 · chat 元信息)。同文件里已有 8 处 variant="ghost"、7 处 size="icon"、3 处 variant="custom"、2 处 secondary、2 处 outline。
改后
- ②
运行中→ 官方Badge variant="default"(实心 = 唯一 ember,与 S3 的「进行中」共享同一语义:活的就发光);开发中→variant="secondary"。3 处variant="custom"与toneChipClasses旁路全部换成官方 variant——custom是官方提供的旁路(Button的variant里就有custom),意味着现在的实现允许任意视觉,本方案主动取消这个自由度。 - ② 分类筛选用官方
Tabs variant="line"(与 S5 的纵向 Tabs 同一套语言);卡片用官方Card(rounded-xl bg-card ring-1 ring-foreground/10)。 - ②(需组件级改动,标注) 图标现状是 emoji,而
components.json的iconLibrary是lucide——同一页面同时出现 emoji 与 lucide 线性图标是明显的一致性缺口。emoji 本身没有官方 variant 可调,替换为 lucide 图标属组件替换(不新增视觉变体,但确实是代码改动),登记为 R2 的一类。 - ③ 8 个分类横向排布的容器与卡片网格属布局;建议固定为「一行放得下、超出一行则横向滚动」,避免分类行温度随数据增长而换行抖动。
深浅色与对比度
比值全部用 WCAG 2.x 相对亮度公式自算(线性化 sRGB → (L1+0.05)/(L2+0.05),保留两位小数);.dark 中的 oklch 值先换算成 sRGB hex 再参与计算。
7.1 正文与语义色(改后)
| 组合 | 浅色 | 比值 | 深色 | 比值 | AA 正文 4.5:1 |
|---|---|---|---|---|---|
| 正文 / 画布 | #1c1a17 on #f7f5f1 |
15.95 | #e9ebdf on #151515 |
15.14 | ✅ |
| 正文 / 卡片 | #1c1a17 on #ffffff |
17.36 | #e9ebdf on #242424 |
12.87 | ✅ |
| 次级文字 / 画布 | #6a655d on #f7f5f1 |
5.31 | #a8a69c on #151515 |
7.48 | ✅ |
| 次级文字 / 卡片 | #6a655d on #ffffff |
5.78 | #a8a69c on #242424 |
6.36 | ✅ |
| 次级文字 / 弱面 | #6a655d on #f1eee8 |
4.99 | #a8a69c on #1f1f1f |
6.75 | ✅ |
| 本人气泡文字 / 气泡 | #43220d on #f7dcba |
10.79 | #fbe3cd on #442a14 |
10.69 | ✅ |
| 他人气泡文字 / 气泡 | #1c1a17 on #eeebe4 |
14.58 | #e9ebdf on #262626 |
12.55 | ✅ |
| 品牌按钮文字 / 品牌底 | #ffffff on #c2410c |
5.18 | #1a1206 on #f97316 |
6.61 | ✅ |
| 品牌墨 / 品牌柔底 | #9a3412 on #f9ece7 |
6.33 | #fdba74 on #463122 |
7.23 | ✅ |
| 品牌墨 / 画布 | #9a3412 on #f7f5f1 |
6.71 | #fdba74 on #151515 |
10.83 | ✅ |
| 品牌色文字 / 画布 | #c2410c on #f7f5f1 |
4.76 | #f97316 on #151515 |
6.51 | ✅ |
| 危险 / 画布 | #c0341d on #f7f5f1 |
5.14 | #ff8578 on #151515 |
7.72 | ✅ |
| 危险 / 卡片 | #c0341d on #ffffff |
5.60 | #ff8578 on #242424 |
6.56 | ✅ |
| 危险徽标文字 / 柔底(10% / 20%) | #c0341d on #f9ebe8 |
4.82 | #ff8578 on #4d332f |
4.58 | ✅(柔底压在 --card 上;官方 bg-destructive/10 是透明混合,若压在 --background #f7f5f1 上为 4.45,略低于 AA —— 徽标实际都长在卡片/列表里,登记为已知边界) |
| @提及 / 画布 | #a83c0c on #f7f5f1 |
5.81 | #ffab70 on #151515 |
9.84 | ✅ |
| @提及 / 选中底 | #a83c0c on #f5dfc9 |
4.91 | #ffab70 on #3a2614 |
7.71 | ✅ |
| Tabs line 指示条 | #1c1a17 on #ffffff |
17.36 | #e9ebdf on #1c1c1c |
14.13 | ✅ |
--interactive 图标 / 画布 |
#5a554d on #f7f5f1 |
6.79 | #94958e on #151515 |
6.04 | ✅ |
--channel-icon / 画布 |
#8b857c on #f7f5f1 |
3.36 | #8b867f on #151515 |
5.06 | ✅(图形 3:1) |
7.2 面层阶梯与控件边界(非文本,按 1.4.11 的 3:1 判)
| 组合 | 浅色 | 比值 | 深色 | 比值 |
|---|---|---|---|---|
| 衬底 / 画布 | #eae5dd(渐变起) on #f7f5f1 |
1.15 | #0e0e0e on #151515 |
1.06 |
| 衬底 / 画布(渐变止点) | #e2dcd2 on #f7f5f1 |
1.25 | —(深色为径向光晕) | — |
| 画布 / 卡片 | #f7f5f1 on #ffffff |
1.09 | #151515 on #242424 |
1.18 |
| 卡片 / 衬底 | #ffffff on #e2dcd2 |
1.37 | #242424 on #0e0e0e |
1.24 |
| 会话选中底 / 侧栏 | #f5dfc9 on #ffffff |
1.29 | #3a2614 on #1c1c1c |
1.19 |
| 自己气泡 / 他人气泡 | #f7dcba on #eeebe4 |
1.11 | #442a14 on #262626 |
1.14 |
| 引用底 / 画布 | #fbeadd on #f7f5f1 |
1.08 | #2b1c10 on #151515 |
1.11 |
控件边框 --input / 卡片 |
#8f887c on #ffffff |
3.51 | #76766f on #242424 |
3.39 |
控件边框 --input / 画布 |
#8f887c on #f7f5f1 |
3.22 | #76766f on #151515 |
3.99 |
分隔线 --border / 画布 |
#e0dbd2 on #f7f5f1 |
1.27 | #3f403d on #151515 |
1.75 |
| 图表五档 / 卡片(最暗一档) | #8a857d on #ffffff |
3.66 | #b8551d on #242424 |
3.22 |
| 图表五档 / 卡片(最亮一档) | #63300f on #ffffff |
10.71 | #f7bd90 on #242424 |
9.34 |
7.3 现状缺陷清单(改前,实测)
| 问题 | 浅色 | 深色 |
|---|---|---|
| 品牌/危险/提及色不达 AA | @提及 #3370ff on #fcfcfc = 4.18;危险 #da373c on #fcfcfc = 4.46 |
—(品牌 #5599f3 6.70 达标) |
| 侧栏/画布零层级 | #fcfcfc / #fcfcfc = 1.00 |
卡片 #171717 / 画布 #0a0a0a = 1.10(过弱) |
| 控件边界远低于 3:1 | #dcdee1 / #ffffff = 1.31 |
oklch(1 0 0 / 15%) 合成 #3a3a3a / #171717 = 1.58 |
| 深色下的浅色带 | — | --surface-rail #e3e5e8 on #0a0a0a = 15.69(一根白竖带) |
| 深色漏声明 | — | --interactive 继承浅色 #4e5058 on #0a0a0a = 2.46(不可读) |
| 自/他气泡几乎同亮度 | #e8f3fe / #ebedef = 1.02 |
#203b59 / #262626 = 1.13 |
已记录的偏离(--border): --border 在浅色下只给到 1.27:1、深色 1.75:1。这是有意的——它承担的是装饰性分隔线(会话行之间、卡片之间的细线),WCAG 1.4.11 针对的是「理解 UI 控件与状态所必需的视觉边界」,装饰性线条不适用;真正需要 3:1 的表单控件边界由独立的 --input(3.51:1 / 3.39:1)承担。把两者混成一个令牌会在视觉上把界面切成网格纸。
与之配套的一条硬规则(必须写进验收清单):凡是「可点区域本身要靠边框才能被看见」的位置,不得依赖 --border。 实测三类真实冲突与处理:
| 冲突点 | 现状实现 | 实测 | 处理 |
|---|---|---|---|
Input / Textarea / Select 触发器的边界 |
组件自带 border-input,深色另有 dark:bg-input/30 |
3.51 / 3.39:1 | ✅ 天然达标,只靠 --input 取值(途径①) |
深色下 Button variant="outline" 的边界 |
dark:border-input dark:bg-input/30 |
3.39:1 | ✅ 达标 |
浅色下 Button variant="outline" 的边界 |
border-border bg-background |
边框与白卡 1.38:1、填充底 #f7f5f1 与白卡 1.09:1 |
⚠️ 低于 1.4.11;缓解手段在三条途径内:把「图标工具栏 / 弹窗次级动作」的 outline 换成 ghost(靠 --muted 悬停底提示,不承担常驻边界职责),把「唯一决定性动作」留给 default(ember 实心 5.18:1),把「浅色 outline」限定在主区与卡片之外、底色差异更大的面上。若产品不接受,则唯一合规解是把 --border 提到 3:1(浅色 #8f887c=与 --input 同值),代价见 §10 第 3 条。 |
同理,浅色 Button variant="secondary"(bg-secondary #eeebe4 与白卡 1.19:1)与 Item variant="outline" 的边界也属于「靠面层步进而非边界」的同一族;这类「安静的次级动作」正是本方案的既定语言(全区只有一个 ember 热点),在 §10 登记为主动取舍。
shadcn 兼容性
结论:ui/ 下全部 45 个官方组件一行不改;需要新增的官方组件只有 1 个(progress)。
已核实存在的组件(web/src/components/ui/,34 个 .tsx + 3 个 .test.tsx,另加 chat/ 子目录 11 个,共 45 个)——
本方案用到的 button、badge、bubble、card、input、textarea、tabs、avatar、separator、item、field、field-select、dialog、alert-dialog、popover、dropdown-menu、tooltip、select、collapsible、checkbox、radio-group、accordion、context-menu、calendar、table、skeleton、scroll-area、scroll-region、scroll-surface、floating-layer、button-group、input-group、badge、以及 chat/ 下的 bubble、button、input、input-group、textarea、message、message-scroller、empty、attachment、trace、collapsible —— 全部存在、全部到位。
(不存在且本方案不需要的:switch、slider、sonner、sheet、command、hover-card、label、menubar、toggle、toggle-group、resizable、alert、顶层 empty(官方形态在 ui/chat/empty.tsx)。)
已核实的官方 variant/size 清单(本方案只用这些):
Button:variant = default | outline | secondary | ghost | destructive | link(+ 类型级旁路"custom",见下);size = default(h-8) | xs(h-6) | sm(h-7) | lg(h-9) | icon(size-8) | icon-xs(size-6) | icon-sm(size-7) | icon-lg(size-9)。Button variant="destructive"与Badge variant="destructive"都是官方柔底(bg-destructive/10 text-destructive,深色bg-destructive/20),不是实心红 —— §7.1 的 4.82 / 4.58 就是按这个柔底实测的。Badge:variant = default | secondary | destructive | outline | ghost | link;几何h-5 px-2 rounded-4xl text-xs。Bubble:variant = default | secondary | muted | tinted | outline | ghost | destructive(tinted用oklch(from var(--primary) …)从--primary推导 → 令牌改值即换色)。Tabs:variant = default | line、orientation = horizontal | vertical(line选中态 =after:h-0.52pxafter:bg-foreground指示条)。Avatar:size = default(size-8) | sm(size-6) | lg(size-10);AvatarFallback内建bg-muted text-muted-foreground。Item:variant = default | muted(bg-muted/50)| outline(border-border)、size = default | sm | xs。Card:rounded-xl bg-card ring-1 ring-foreground/10,内部间距吃--card-spacing(default 4×spacing、data-size=sm3×spacing)。Input:h-8 rounded-lg border-input text-base md:text-sm dark:bg-input/30。
⚠️ 必须登记的一处旁路:variant="custom" 共 215 处、分布在 65 个文件。 它是一个类型级逃生口(button.tsx:50 把 union 扩成 … | "custom",:56 命中时不施加任何 variant 类),颜色与尺寸全由调用方 className 接管 —— 登录页 auth/sign-in-form.tsx / auth/login-code-form.tsx、agent-lab.tsx、agent-developer-platform.tsx 等大量使用。它们是不受本方案令牌变化影响的(除非其 className 自己就吃令牌;实测登录页那几个 variant="custom" 是 text-muted-foreground hover:text-foreground 的文本按钮,仍随令牌走)。计入 §10 的 R2。
需要新增的官方组件(缺 1 个):
| 组件 | 用途 | 替换掉什么 |
|---|---|---|
progress |
任务完成率 / 进度条 | tone.ts 的 toneBarClasses(bg-emerald-500 / bg-amber-500 等硬编码色条) |
明确不需要新增的: switch(全仓无开关控件)、slider、sonner/toast(channel-work-items.tsx 自己用 useState 渲染了一条 inline toast,若要规范化可换官方 sonner,但那是行为改动,本方案不动)。
与组件的语义契约(改令牌不会破坏的部分):
- 焦点环:
Button/Input/Tabs的 focus-visible 都吃--ring;--ring: var(--brand)保持不变 ⇒ 焦点环顺带变 ember,无需改组件。深色下--ring未声明时自动继承:root的var(--brand),解析成#f97316✓。 - 无效态:
aria-invalid:border-destructive吃--destructive⇒ 暖瓷红自动生效。 - 卡片描边:
Card的ring-1 ring-foreground/10是从--foreground推导的 10% 透明环,不随--border走;深色下#e9ebdf10% 落在#242424上合成#37372f(1.30:1),与--border #3f403d(1.49:1)接近,视觉不冲突。
不兼容 / 必须豁免的 6 项(R1–R6,见 §10): 字号与行高的统一(R1)、253 处硬编码调色板与 55 处硬编码前景(R2)、待验收 → destructive 的语义借用与 已完成/已关闭 合并(R3)、深色主题在本栈不可达(R4)、登录页 26px 标题 / 52px 按钮与 .login-primary-btn 渐变(R5)、--sidebar 族零引用(R6,本方案仍给值,但不产生本仓视觉变化)。
实施成本
改动面(共 1 个令牌文件 + 6 个组件文件):
| 文件 | 改动 | 途径 | 量级 |
|---|---|---|---|
web/src/styles.css(:root 108-161、.dark 163-211) |
用 tokens.css 的 B / C 段整块替换 |
① | ~54 + ~45 行变量,纯值替换 |
web/src/components/app/tone.ts |
6 个 tone 的 class 映射表收束到官方 variant 语义(brand→default、emerald/teal→secondary、amber/blue→outline、rose→destructive、slate→ghost) |
② | 5 张表,~40 行 |
web/src/components/app/task-hall.tsx |
手写 <span className="rounded-full border px-1.5 py-0.5 ..."> 状态 chip 换成官方 Badge(6 状态映射见 §6.3) |
② | ~30 行 |
web/src/components/app/channel-settings-dialog.tsx |
删除 :71 的 TabsTrigger 覆写 |
②(删) | 1 行 |
web/src/components/app/message-bubble.tsx |
删掉正文字号覆写(R1) | 风险 R1 | ~2 行 |
web/src/components/app/channel-sidebar.tsx + im-sidebar.tsx |
会话行换官方 Item / Badge / Avatar(R2 的一类) |
② | ~40 行 |
web/src/components/app/app-center.tsx |
运行中/开发中 徽标与分类筛选换官方 Badge/Tabs,去掉 3 处 variant="custom" |
② | ~20 行 |
预估 diff: 只做「令牌 + 上述 6 个文件」约为 +150 / −180 行;若把 R2 的全部 253 处硬编码调色板一起清理,量级升到 ~44 个文件、600+ 行——建议分两步:先落令牌(本方案主体,视觉收益最大、风险最低),再按 §6 逐面清理旁路。
验证方式(不需要构建,全部可在浏览器控制台完成):
getComputedStyle(document.documentElement).getPropertyValue('--background')→#f7f5f1;--brand→#c2410c;--radius→0.5rem。document.documentElement.classList.add('dark')后复读 →#151515/#f97316;并检查前景色是否翻转(现状 55 处硬编码rgb(6,6,7)不会翻转——这是 R2 的已知残留,需按文件清单逐个替换)。- 在目标元素上
getComputedStyle(el).backgroundColor/borderColor抽样若干处,核对是否等于令牌值(用于验证「令牌真的生效、没有被 className 旁路覆盖」)。现状已知会被旁路覆盖的位置:channel-settings-dialog.tsx:71(Tabs 选中态)、task-hall.tsx:181的flagBadge、tone.ts全部映射表、app-shell.tsx的rgba(220,222,225,0.55)侧栏边框。 - 对比度用 WCAG 公式复算:
(max(L1,L2)+0.05)/(min(L1,L2)+0.05),L = 0.2126R+0.7152G+0.0722B(线性化后)。
不做的事(成本上的取舍): 不引入自定义 CSS 变量之外的新令牌、不改 @theme inline、不动阴影与动效令牌、不新增组件、不做响应式重构(1440×900 是唯一实测断点,max-xl 抽屉行为保持原样)。
取舍
1. 不动 --shadow-e1..pop 与 --animate-*。 Retool 的核心是零阴影纯亮度分层,理论上可以删掉四步阴影阶梯;但深色下阴影不可见、浅色下弹窗与抽屉仍靠阴影做浮层分离,删除是无视觉收益的行为变更,因此保留原文四步梯度不动。代价:浅色下卡片会同时有「亮度步进」和「1px 阴影」,轻微冗余——接受。
2. 不动 --font-sans / --font-mono。 前已述:Geist 无 CJK 字形,中文回退链正好是硬约束 4 要求的 Noto Sans SC / PingFang SC;动它反而是风险。
3. --border 保持低对比,另立 --input 承担 3:1。 见 §7 的「已记录偏离」。若统一提到 3:1,界面上会出现大量 3:1 的细线,把暖砂面层切成网格纸——这与本方案「层级靠面层」的立意直接冲突。代价:浅色下 Button variant="outline"(border-border bg-background)的可点区域边界只有 1.38:1,低于 1.4.11;缓解办法是用官方 variant 换语义(需要常驻边界的地方用 ghost + 悬停 --muted,唯一决定性动作给 default ember 实心),而不是动 --border。
4. 深色 .dark 不重声明 --radius。 圆角是形态而不是主题,两套主题共享 0.5rem 基准;重声明会让深色单独漂移。
5. 状态色语义借用(R3)。 「待验收 → destructive」是把危险色借给「需要人介入的等待态」。理由:卡片状态列表里没有任何官方 variant 能表达「等你做事」(outline 太弱、secondary 与待处理撞、default 已被进行中占用)。代价是「待验收」与「发布失败」同色,靠文字区分。同理「已完成」与「已关闭」都落到 ghost——官方 6 个 variant 里没有第 7 个中性档,而新增语义令牌或自定义 variant 都超出三条途径。这是本方案唯一主动接受的语义损失。
6. S5 设置弹窗回官方 Tabs variant="line",放弃 ember 选中块。 现状的 data-active:bg-brand-soft 覆写视觉上其实很好看,但它是 className 旁路;回官方后选中态是 2px --foreground 指示条(14.13:1 / 17.36:1,清晰度更高,但少了「品牌色存在感」)。若产品更看重品牌存在感,则需保留旁路并登记为豁免——本方案选合规。
7. S7 登录页保留 26px 标题与 52px 按钮(取 (a))。 理由:52px 是触摸目标,26px 是「门面」字号;换成官方 lg(h-9 = 36px) 会让登录页从产品门面退化成表单页。代价:继续持有非官方尺寸类(R5)。若选 (b),请一并删除 .login-primary-btn 的渐变与阴影(否则会得到一个「小巧但仍然渐变」的按钮,比现在更不协调)。
8. 应用中心的 emoji 图标:本方案建议换 lucide,但把它单列为组件级改动而不混在令牌改造里。 理由是 emoji 的渲染(彩色位图、字体依赖)无法通过任何令牌或官方 variant 影响,它与「线性图标」并置是 S8 最刺眼的一致性问题;但替换它需要逐项挑选图标,属内容决策。本方案不擅自决定 14 个应用各自用哪个图标。
9. 不修复「深色主题不可用」(R4)。 本方案保证令牌层两套完备且逐变量对等(.dark 声明数从 39 补齐到 41,与 :root 的 48 个在语义角色上一一对应),但把 .dark 挂到 <html> 上(或跟随系统 prefers-color-scheme)是产品决策 + 代码改动,不在重设计范围内;本方案只交付「打开开关即成立」的令牌。
10. 主动舍弃 Retool 的 4 条语言规则(§2 末):0px/9999px 二元圆角、pill CTA + hero 径向渐变 + 营销排版、em dash 装饰、深色专属彩色水洗。企业协作工具的信息密度(148 频道 / 457 任务 / 1554 消息)决定了它需要「安静的面层 + 一个热点」,而不是一套展示型设计语言。
11. 一处可接受的形态下沉: --radius-md 从 8px 变 6.4px(0.8 × 0.5rem)。实测中 8px 档(37 个元素)多为小控件与徽标,收到 6.4px 后与 8px 主档仍有 1.6px 差异,肉眼几乎不可辨;若要严格「只有 8px 与 14.4px 两档」,需要新增一个 --radius-md: 0.5rem 的显式声明(仍是令牌层,可行但属额外改动),本方案默认不动。
风险登记(R1–R6)
| 编号 | 风险 | 影响面 | 是否超出三条途径 |
|---|---|---|---|
| R1 | 字号 / 行高统一(消息正文 14 → 15px、空间头计数 15px → 13px、11.25px → 12px、11px → 12px)需删改组件 className | S1 / S2 / S7 会话与登录 | 是(超出,需豁免) |
| R2 | 253 处硬编码 Tailwind 调色板(44 文件)+ 55 处硬编码 rgb(6,6,7) 前景(深色不翻转)+ 头像 5 组硬编码色对 + emoji 图标 + Button variant="custom" 215 处 / 65 文件(类型级逃生口,:56 不施加任何 variant 类,颜色全由调用方 className 决定) |
全站 | 是(需组件级替换,建议分两步) |
| R3 | 待验收 → destructive 语义借用;已完成/已关闭 合并到同一 ghost treatment |
S3 / S8 | 是(官方 6 个 variant 不够用) |
| R4 | 深色主题在运行环境中不可达(web/src 无任何代码给 <html> 加 .dark,<html class> 恒为空) |
全局 | 是(需产品决策 + 代码开关) |
| R5 | 登录页 26px 标题 / 52px 按钮 / .login-primary-btn 渐变超出官方 Button size 上限 |
S7 | 是(保留自定义尺寸,或改官方 lg 并删渐变) |
| R6 | --sidebar 族在 web/src 零引用(grep 'bg-sidebar|sidebar-accent' = 0 命中),本方案给值但不产生本仓视觉变化 |
S1 | 否(仅说明,不构成改动) |
一句话总结: 本方案的视觉改观 90% 来自一个令牌文件(styles.css 的 :root / .dark),改完后浅色是「暖砂纸 + ember」,深色是「黑曜石 + ember 微光」,实测对比度全部达标(正文 15.95 / 15.14:1,品牌按钮 5.18 / 6.61:1,控件边界 3.51 / 3.39:1);剩下 10% 是把状态色与前缀旁路收回到官方 Badge / Tabs / Item variant,代价是 §10 里登记的 6 条风险,其中 R2 与 R4 需要产品决策,其余 4 条本方案已给出可执行的选择。