maka/docs/archive/design-refinement-roadmap-2026-07.md

Maka 质感提升路线图（2026-07）

Archived on 2026-07-13. Completed decisions remain visible for provenance; unfinished queues must be tracked in GitHub issues rather than treated as a current documentation backlog.

来源：四个设计 skill 资源的系统学习（taste-skill / superdesign / ui-skills.com 生态 / vercel-labs agent-skills），对照 maka 现状 （2026-06-24 skills 轮已 shipped 项 + 2026-07-03 三层 code review） 提炼的真增量，加上产品 owner 拍板的四个路线决策。

阅读前提：notes/ui-skills-deep-read-2026-06-24.md（已 shipped 项， 避免重做）；docs/frontend-css-governance.md（token 治理规则）。

0. 已拍板的路线决策（2026-07-03，jackwener）

#	决策	含义
D1	转向 4pt spacing 系统	所有 padding/gap 收敛到 4/8/12/16/24/32；允许偏离 QoderWork 逐像素值 1-2px。「高级感来自一致性而非对标精度」
D2	Dark mode 一等公民	dark 需要独立 elevation 体系（阴影塌缩为 border ring）、语义色 desaturate；UI PR 双主题截图验收
D3	动效人格：快而准	高频操作（切会话/发送/palette）零动画；其余全部 <300ms 且取区间下限；AI 流式输出的 typing 节奏除外（那是语义不是装饰）
D4	暂不做签名元素	先把 QoderWork 镜像的基本功（layering/圆角/阴影/状态）做精，视觉身份创新延后

1. 四源精华 × maka 适用清单

只列「真增量」——已 shipped 项见 ui-skills-deep-read 笔记。

1.1 表面层级体系（interface-design "subtle layering"，最高杠杆）

• Surface 亮度逐级只差几个百分点：shell(base) → 白卡(+1) → popover/dropdown(+2)。 dropdown 必须比它的父表面高一级。
• Input 比周围略暗（inset 隐喻「往里输入」）：composer、搜索框、 palette 输入行。当前 maka 输入面与卡面同色 → 缺一级。
• Border 四档递进：standard / softer / emphasis / focus-ring，全部 低透明度 rgba/oklch alpha 而非实色 hex。
• Depth 策略四选一并从一而终：maka 的选择 = 白卡 layered shadow + 卡内 hairline border，写死，不混用。

1.2 阴影（taste-skill + interface-design 共识配方）

• Light mode 三层：0 0 0 1px α.06 / 0 1px 2px -1px α.06 / 0 2px 4px α.04， 全部 oklch(from var(--foreground))，opacity 永不超 0.05-0.06。
• Hover 提升：0 2px 8px α.04，200ms。
• Dark mode 阴影塌缩为单 ring：0 0 0 1px oklch(1 0 0 / 0.08)（D2）。

1.3 圆角（同心圆角公式）

• 嵌套时内 radius = 外 radius − padding。审计对象：灰壳→白卡、 气泡→内嵌代码块、卡→内部输入框、modal→内部卡。
• 现有 4 档 token（control 6 / surface 8 / modal 12 / pill 999）保留， 公式约束的是嵌套关系而非档位本身。

1.4 间距（D1：4pt 网格）

• 新代码强制 4 的倍数；存量逐步迁移（每次触碰某文件时顺手收敛该文件）。
• 疏密节奏：相关项 8–12px 紧组，组间 24–32px（桌面工具档，非 landing 的 48-96px）。
• 治理方式：契约测试对新增 CSS 声明检查（存量 allowlist 冻结）。

1.5 动效（D3：快而准，Emil duration 表）

交互	时长	备注
高频操作（切会话/发送/palette 开合）	0ms	每天百次的操作不配动画
按压反馈	100–160ms	:active scale(0.97) 已 shipped
tooltip / 小 popover	125–200ms	origin-aware
dropdown / select	150–250ms
modal / drawer	200–300ms	取下限
AI 流式 / typing 指示	语义节奏	不受 300ms 上限约束

• 永不 ease-in；永不从 scale(0) 入场（0.95 起）；出场比入场快。
• 可中断 UI 用 transition 不用 keyframes。
• hover 动画包 @media (hover: hover) and (pointer: fine)。

1.6 文字层级（收敛，而非增加）

• 三档制：primary（--foreground，100% ink）/ secondary （--foreground-secondary，80% ink）/ muted （--muted-foreground，50% ink）。--foreground-N 十几档是 层级糊的来源，UI 新代码只从三档语义别名取值。40% 和 50% 肉眼 barely 可分，桌面工具场景不需要在"不重要"内部再分一档，所以 从原四档制进一步收敛到三档。
• CJK 注意：Windows 中文字体缺中间字重 → color/opacity 杠杆权重高于 weight；禁收紧 CJK letter-spacing（拉丁负 tracking 规则不适用）。
• 数字全面 tabular-nums（token 数、时间戳、计数）——部分已 shipped， 按面补齐。

1.7 对比度硬线

• 正文与 placeholder 均 ≥4.5:1（「浅灰显优雅」是中文小字的头号 可读性杀手）；大字 ≥3:1。进 visual audit 流程。

1.8 工程质量清单（vercel web-interface-guidelines 摘录）

• flex/grid 文本容器 min-w-0 才能截断（已有多起此类 bug）。
• modal/drawer 内 overscroll-behavior: contain 防滚动穿透。
• 破坏性操作永不立即执行（confirm 或 undo 窗口）。
• 提交中按钮转 spinner 但不提前 disable；错误 inline + focus 第一个错误。
• 拖拽时禁文本选择；h-dvh 不用 h-screen。

1.9 明确不采纳（避免后人重提）

• Display 字体池 / serif 纪律 / hero 字号 —— 中文 + system stack 无意义
• GSAP scrolltelling / marquee / 磁性按钮 / bento —— marketing 专属
• em-dash 全域禁令 —— 中文破折号「——」是合法标点
• 「禁版本号」—— 桌面工具 About 页显示版本正当
• superdesign 的 AI 消息入场 600ms —— 与 D3 冲突，取 Emil 值

2. 落地队列（按杠杆排序）

1. P-SHADOW ✅ (#457)：三层阴影配方升级 + dark 塌缩 ring
2. P-INSET ✅：palette/搜索输入行 3% 前景 wash step-down；通用 Input/Textarea 2% wash。composer 例外保持 elevated —— 它是主命令台 不是表单字段（PR-UI-LAYOUT-8 的有意设计）。
3. P-RADIUS ✅（首轮）：palette/搜索 modal 输入行按同心公式修正 （12−8=4px，写法 calc(var(--radius-modal)-8px) —— 契约的 calc allowlist 要求无空格）。其余嵌套对（settings modal 内卡、tool card 内 pre）审计通过或留待触碰时修正。
4. P-MOTION ✅（已达标，无需动作）：duration token 120/150/180/280ms 完全符合 Emil 表且取下限；装饰性入场动画已被 #406 gap 3 清除；剩余 keyframes 全部是功能性流式动画（D3 豁免）
5. P-TEXT ✅（首轮）：孤儿档 -20/-30 清除（8 处调用点：文字并入 -40 兼修对比度、装饰内联 color-mix）；文字主力收敛为 40/50/60/70/80。全量四档语义别名迁移留待逐面触碰。
6. P-4PT ✅✅（#448 完全体）：#459 的渐进 ratchet 服役半天后被 #448（#430 PR3）取代 —— 它修复了 --spacing 0.25rem=3.75px 的真 bug （Tailwind 与手写 px 两把尺），全量 687 CSS + 125 TSX 收敛到 14 档 --space-* scale，并用 spacing-converge-contract 硬 ban bare px。 ratchet 契约已删除（一个机制，留强的）
7. P-DARK ✅：elevation 独立化由 P-SHADOW dark-collapse 完成； 语义色审计通过（dark 的 chroma 微调是感知补偿而非过饱和， accent 0.135→0.15 配 L+0.04 在暗底维持等感知强度）
8. P-STATE ✅（审计轮）：技能/回顾/聊天 empty 构图完备；发送失败 = toast + turn 级失败徽章双通道；会话列表本地快路径合理缺席 skeleton（300ms 延迟原则，本地 SQLite <50ms）；无通用 Skeleton 组件正符合「形状对齐」原则。缺口留逐面触碰时补。

每项独立 PR，双主题截图验收（D2），契约测试锁行为。

3. 队列完成记录（2026-07-03 首轮全清）

• #457 P-SHADOW（roadmap + 阴影配方 + dark collapse）
• #458 P-INSET + P-RADIUS 首轮 + P-MOTION 审计
• #459 P-4PT ratchet 契约 + P-TEXT 孤儿档清理
• 前置质感修复：#454（玻璃色板复活/token 卫生）、#452（blocked 语义/时间戳/i18n）、#451（copy-feedback 契约同步）
• P-FOREGROUND-TIER-CONVERGE（issue #430 PR4）：5 档文字梯 （40/50/60/70/80）收敛到 3 档语义别名 — --foreground （100% ink）、--foreground-secondary（80% ink）、 --muted-foreground（50% ink）。-90/-95 零调用直接删。 444 处调用点全量替换，契约测试锁住文字用法不回退到裸 mix stops。

下一轮候选（按杠杆）：P-STATE 边缘面补齐、storybook Design System 页同步新阴影/层级规则。 （原「文字档 60/80 的逐面归并」已由 P-FOREGROUND-TIER-CONVERGE 解决，落地为 3 档制而非 4 档 — 50% 和 40% 肉眼 barely 可分， 桌面工具场景不需要在"不重要"内部再分一档。） （原「module-pages 76 个 off-grid 值」已由 #448 全量收敛解决。）

4. 第二轮全量精读增补（2026-07-03，四源全覆盖）

覆盖：taste-skill 全部 26 文件（含 v2 遗漏章节、v1 §9、research/laziness）、 ui-skills registry 全部 126 条目（~110 份独立文档）、vercel-labs 88 文件 （react-best-practices 70 rules 全读）、superdesign 全段亲读。 原文缓存：session scratchpad skills2/ 与 agent-skills/。

4.1 新增可落地规则（相对 §1 的真增量）

Motion 增补

• 300ms loading 阈值：加载 <300ms 什么都不显示，杜绝闪烁 skeleton（ui-ux-pro-max）
• exit = enter × 60–75%；动画必须可中断（快速触发用 transition/spring 可重定向，禁 keyframes 重播）；context menu 只做退场动画（Emil review-animations / transitions.dev）
• 80ms 瞬时感知阈值（micro-interaction 目标）；「慢即真」：AI 生成类复杂操作的可见工作过程传达真实感（pbakaus animate — 属 D3 的流式语义豁免区）
• transitions.dev 参数表：dropdown open 250/close 150ms、pre-scale 0.97；modal 250/150、scale 0.96；text swap 200ms+8px+blur 2px；error shake 6px+4px overshoot、3s 自动回退；replay 前 void el.offsetWidth
• 换字元素宽度锁定：状态标签/token 计数/「已复制」按最宽态锁 min-width —— chat 工具最高频 layout-shift 根治（compact-landing）
• spring 决策表：手势/可中断→spring(500/30)；系统状态→easing；时间表征→linear；高频→零动画

Color/表面增补

• 灰字禁上彩底：彩底文字用同色相深一档或前景加 alpha（pbakaus 三处反复强调）
• OKLCH 三定律：修对比只调 L 锁 C/H；palette 各阶 hue 漂移 >10° = bug；跨 hue 等鲜艳度用 max-chroma 相同百分比（oklch-skill）
• dark 深度 = 三档 surface 亮度（15/20/25% L 同色相），不靠阴影 —— 与 P-SHADOW dark collapse 互证
• alpha 滥用是 palette 不完整的信号：除 focus ring 外定义显式 overlay 色（对 @layer 陷阱也更友好）
• Anti-Nested-Box：卡中卡中卡硬 ban；密集区用 border-t/divide-y/负空间替代套卡

排版/细节增补

• … 不用 ...（loading 文案以 … 结尾）；快捷键 ⌘ K 用 nbsp；ALL-CAPS 短标签 +5–12% tracking
• 暗底亮字三轴补偿：line-height +0.05–0.1、letter-spacing +0.01–0.02em、字重调档
• italic 含降部字符（y g j p q）最低 leading-[1.1]
• kbd 键帽 recipe：1px 边 + 4px radius + 浅底 + mono（桌面快捷键提示刚需）
• 负 inset 伪元素扩热区（44px 达标不改布局）；dialog::backdrop + blur 4px 替代手写遮罩

治理增补

• icon 四条：单 family、stroke 统一 1.5/2px、filled-outline 不同层级混用禁、尺寸 token（16/20/24）
• z-index 显式 scale 立法（maka 已有语义 z token ✓ 复核覆盖率即可）；modal scrim 40–60% black
• toast 纪律：3–5s 自动消失、aria-live polite、永不作关键信息唯一渠道、低风险删除用 Undo toast
• 文案：按钮写确切动作、同意图全应用一个措辞（发送/确认/提交不混用）、error = 原因+修复路径、禁「轻松/简单/只需」、AI 腔清单（段首总结过渡/datasheet 腔/碎句连发）

React 性能（vercel 70 rules 全读 → maka grounding） 现状：全仓 0 处 useTransition/useDeferredValue；chat-view 仅 MessageBody 有 memo。

• ✅ content-visibility 已落地（#468）
• 待做（按序）：TurnView memo 化 + props 收窄（流式不重渲染旧 turn）→ 流式更新包 startTransition / 搜索过滤用 useDeferredValue → markdown parse 结果按 text 缓存 → 面板 hover 预热 void import() → 频繁 toggle 面板用 → 滚动三件套（passive listener / 贴底判定走 ref / 读写分离）→ barrel import 审计（rollup-plugin-visualizer）
• composition-patterns：composer.tsx 792 行按 compound components 重构候选；react19-no-forwardRef 全仓清理候选
• 原生 document.startViewTransition 做 settings/panel 切换（Electron 固定 Chromium，零依赖）

4.2 明确不采纳增补

• Lucide→Phosphor 全量换 icon（80+ 调用点，见 §4.3 问题 1，待拍板）
• Motion/GSAP 库编排、bento/hero/marquee 全家（landing 专属）
• 声音反馈两篇（超 UI-only scope，规则已存档：默认音量 0.3、打字禁声）
• react@canary 的 组件（生产依赖不划算，用原生 API 替代）
• brutalist/gpt-tasteskill/brandkit/imagegen 系（风格化/资产生成，与 QoderWork 镜像路线冲突）

4.3 已拍板决策（2026-07-03 第二轮，jackwener）

#	决策	含义
D5	保留 Lucide + 治理	不迁 Phosphor；用治理抵消「默认感」：stroke 统一 1.5px、尺寸 16/20/24 token 化、禁 filled/outline 同层级混用
D6	AI 等待感全谱引入	taste v1 §9 五套微动效全部评估落地：shimmer processing、typewriter 轮播、呼吸指示+overshoot 通知、layoutId 列表重排、横向流。流式语义豁免区，不违反 D3
D7 D7'	中性冷 zinc（hue 286）	2026-07-03 晚 owner 看到实际暖米观感后推翻 D7：暖褐与玻璃通透语言相抵触（「追求的是玻璃质感」）。全局 ink/壳/dark/darwin 玻璃板换 zinc 族；sage accent 与 sand 可选主题不动。参考基准：冷净白侧栏截图（zinc Canvas White + Charcoal Ink）
D8	copy lint 做可机械化的那半	check-copy.mjs 上线（pressure-word / ascii-ellipsis）；同意图同措辞、AI 腔清单留人工 review

产品级附赠（超 UI，存档）：research/laziness 的反截断体系 —— skill description 具体度决定 68%→90% 触发率、[PAUSED - X of Y] 续写协议、EmotionPrompt 量化数据，可用于 maka 自身的 agent prompt 设计。