Maka 设计质感提升路线图全解4pt 网格、OKLCH 阴影配方与动效人格的系统落地【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/makaMakaApache Incubating在 2026 年 7 月基于四个设计 skill 资源taste-skill / superdesign / ui-skills.com 生态 / vercel-labs agent-skills的系统学习对照自身渲染层现状产出并归档了一份「质感提升路线图」。本文以该路线图design-refinement-roadmap-2026-07.md为骨架逐条解读四大拍板决策D1–D4、九大实战规则与八项落地队列P 系列并结合当前仓库中的 token 源码maka-tokens.css、packages/ui/src/styles.css验证其最终落地形态。读完本文你将掌握 Maka 的间距、圆角、阴影、动效、文字层级等设计系统的精确取值与治理机制可直接迁移到自己的桌面工具类产品 UI 建设中。背景与阅读前提该路线图由四路设计 skill 资源的系统学习提炼而成对照基线是两项既有成果2026-06-24 skills 轮已 shipped 项详细清单见归档笔记 ui-skills-deep-read-2026-06-24.md原文档写作时位于notes/当前仓库归档于docs/archive/避免对已完成工作重复投入2026-07-03 三层 code review作为现状审计输入。阅读该路线图前需先掌握 token 治理规则frontend-css-governance.md另有中文版 frontend-css-governance.zh-CN.md。一、四大拍板决策D1–D4质感方向的总纲2026-07-03 由产品 ownerjackwener拍板四条路线决策构成后续所有工作的方向总纲#决策含义D1转向 4pt spacing 系统所有 padding/gap 收敛到 4/8/12/16/24/32允许偏离 QoderWork 逐像素值 1-2px。「高级感来自一致性而非对标精度」D2Dark mode 一等公民dark 需要独立 elevation 体系阴影塌缩为 border ring、语义色 desaturateUI PR 双主题截图验收D3动效人格快而准高频操作切会话/发送/palette零动画其余全部 300ms 且取区间下限AI 流式输出的 typing 节奏除外那是语义不是装饰D4暂不做签名元素先把 QoderWork 镜像的基本功layering/圆角/阴影/状态做精视觉身份创新延后这四条决策对应着设计系统的四个支柱间距网格化D1、双主题一等公民D2、动效克制D3、基本功优先D4。值得注意的是 D4 明确把「视觉身份创新」排在基本功之后说明该路线图追求的是「一致性带来的高级感」而非炫技。二、四源精华 × maka 适用清单九大实战规则路线图只保留「真增量」——已被 shipped 的内容见 ui-skills-deep-read 笔记不再重复列入。以下九条规则按杠杆排序。2.1 表面层级体系最高杠杆Surface 亮度逐级只差几个百分点shell(base) → 白卡(1) → popover/dropdown(2)。dropdown 必须比它的父表面高一级Input 比周围略暗inset 隐喻「往里输入」composer、搜索框、palette 输入行。当时的审计结论是 maka 输入面与卡面同色缺一级Border 四档递进standard / softer / emphasis / focus-ring全部用低透明度 rgba/oklch alpha 而非实色 hex。当前仓库中这组 token 已落地于 maka-tokens.css--borderoklch(from var(--foreground) l c h / 0.10)、--border-soft0.06、--border-strong0.16另有--foreground-alpha-6/12/16等 alpha 档位L358-L369全部由前景色派生、保持色相锁定Depth 策略四选一并从一而终maka 的选择是白卡 layered shadow 卡内 hairline border写死不混用。2.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.06Hover 提升0 2px 8px α.04200msDark mode 阴影塌缩为单 ring0 0 0 1px oklch(1 0 0 / 0.08)D2 的直接体现。源码验证当前 maka-tokens.css 以--elevation-raised: var(--shadow-low)、--elevation-overlay: var(--shadow-med)、--elevation-drag: var(--shadow-high)建立三层语义 elevation并将 dark 的 1px ring 配方写入 L437light-dark(oklch(from var(--foreground) l c h / 0.06), oklch(1 0 0 / 0.08)) 0 0 0 1px——light 侧用前景派生的 0.06 alphadark 侧用纯白 0.08与路线图配方逐字对应。2.3 同心圆角公式嵌套时内 radius 外 radius − padding。审计对象灰壳→白卡、气泡→内嵌代码块、卡→内部输入框、modal→内部卡现有 4 档 token 保留公式约束的是嵌套关系而非档位本身。源码验证四档 token 在 maka-tokens.css 定义为--radius-control: 6px、--radius-surface: 10px、--radius-modal: 12px、--radius-pill: 999px实际 surface 值为 10px路线图草拟时记为 8px以源码为准。文件注释L685-L701还说明了--radius-inner/-element/-container/-full是这些档位的兼容别名并要求嵌套修正统一写成calc(var(--radius-modal) - 8px)这类无空格 calc 表达式以匹配契约测试的 allowlist。2.4 4pt 间距网格D1新代码强制 4 的倍数存量逐步迁移每次触碰某文件时顺手收敛该文件疏密节奏相关项 8–12px 紧组组间 24–32px桌面工具档非 landing 的 48-96px治理方式契约测试对新增 CSS 声明检查存量 allowlist 冻结。源码验证4pt 网格的最终形态是 maka-tokens.css 的14 档--space-*scaleToken值Token值--space-0-52px--space-520px--space-14px--space-624px--space-1-56px--space-832px--space-28px--space-1040px--space-2-510px--space-1248px--space-312px--space-1664px--space-416px全部以calc(var(--spacing) * N)派生自单一基准从根上消除「Tailwind 与手写 px 两把尺」的问题详见下文 P-4PT。2.5 动效人格D3快而准Emil duration 表交互时长备注高频操作切会话/发送/palette 开合0ms每天百次的操作不配动画按压反馈100–160ms:active scale(0.97)已 shippedtooltip / 小 popover125–200msorigin-awaredropdown / select150–250msmodal / drawer200–300ms取下限AI 流式 / typing 指示语义节奏不受 300ms 上限约束四条硬性纪律永不ease-in永不从scale(0)入场0.95 起出场比入场快可中断 UI 用transition不用keyframeshover 动画包media (hover: hover) and (pointer: fine)可中断交互用 spring/transition 可重定向禁 keyframes 重播。源码验证当前 maka-tokens.css 的 duration scale 为--duration-quick: 120ms、--duration-base: 150ms、--duration-emphasized: 180ms、--duration-large: 280ms并配套--ease-out-strong: cubic-bezier(0.16, 1, 0.3, 1)L788——正是路线图 P-MOTION 审计结论「完全符合 Emil 表且取下限」的落地值。文件注释还规定「禁止transition: all需枚举属性」与治理纪律一致。2.6 文字层级收敛而非增加三档制primary--foreground100% ink/ secondary--foreground-secondary80% ink/ muted--muted-foreground50% ink。原--foreground-N十几档是「层级糊」的来源UI 新代码只从三档语义别名取值。40% 和 50% 肉眼 barely 可分桌面工具场景不需要在「不重要」内部再分一档因此从原四档制进一步收敛到三档CJK 注意Windows 中文字体缺中间字重 → color/opacity 杠杆权重高于 weight禁收紧 CJK letter-spacing拉丁负 tracking 规则不适用数字全面 tabular-numstoken 数、时间戳、计数——部分已 shipped按面补齐。源码验证当前 maka-tokens.css 的 ink ladder 注释issue #3446显示文字层级已进一步收拢为--foreground与--muted-foreground两级语义prose 场景--foreground-3/5/6等 mix stop 仅用于表面/弱化层而非正文层级--muted-foreground定义为color-mix(in oklch, var(--foreground) 68%, var(--background))L348——「收敛层级数量、用 opacity 而非字重表达主次」的治理方向在源码中持续演进。2.7 对比度硬线正文与placeholder 均 ≥4.5:1「浅灰显优雅」是中文小字的头号可读性杀手大字 ≥3:1。进 visual audit 流程。2.8 工程质量清单vercel web-interface-guidelines 摘录flex/grid 文本容器min-w-0才能截断已有多起此类 bugmodal/drawer 内overscroll-behavior: contain防滚动穿透破坏性操作永不立即执行confirm 或 undo 窗口提交中按钮转 spinner 但不提前 disable错误 inline focus 第一个错误拖拽时禁文本选择h-dvh不用h-screen。2.9 明确不采纳避免后人重提不采纳项理由Display 字体池 / serif 纪律 / hero 字号中文 system stack 无意义GSAP scrolltelling / marquee / 磁性按钮 / bentomarketing 专属em-dash 全域禁令中文破折号「——」是合法标点「禁版本号」桌面工具 About 页显示版本正当superdesign 的 AI 消息入场 600ms与 D3 冲突取 Emil 值三、落地队列八项 P 系列工作项按杠杆排序的落地队列每项独立 PR、双主题截图验收D2、契约测试锁行为#工作项状态与说明1P-SHADOW✅#457三层阴影配方升级 dark 塌缩 ring2P-INSET✅palette/搜索输入行 3% 前景 wash step-down通用 Input/Textarea 2% wash。composer 例外保持 elevated——它是主命令台不是表单字段PR-UI-LAYOUT-8 的有意设计3P-RADIUS✅首轮palette/搜索 modal 输入行按同心公式修正12−84px写法calc(var(--radius-modal)-8px)——契约的 calc allowlist 要求无空格。其余嵌套对settings modal 内卡、tool card 内 pre审计通过或留待触碰时修正4P-MOTION✅已达标无需动作duration token 120/150/180/280ms 完全符合 Emil 表且取下限装饰性入场动画已被 #406 gap 3 清除剩余 keyframes 全部是功能性流式动画D3 豁免5P-TEXT✅首轮孤儿档 -20/-30 清除8 处调用点文字并入 -40 兼修对比度、装饰内联 color-mix文字主力收敛为 40/50/60/70/80。全量四档语义别名迁移留待逐面触碰6P-4PT✅✅#448 完全体#459 的渐进 ratchet 服役半天后被 #448#430 PR3取代——它修复了--spacing 0.25rem3.75px的真 bugTailwind 与手写 px 两把尺全量 687 CSS 125 TSX 收敛到 14 档--space-*scale并用 spacing-converge-contract 硬 ban bare px。ratchet 契约已删除一个机制留强的7P-DARK✅elevation 独立化由 P-SHADOW dark-collapse 完成语义色审计通过dark 的 chroma 微调是感知补偿而非过饱和accent 0.135→0.15 配 L0.04 在暗底维持等感知强度8P-STATE✅审计轮技能/回顾/聊天 empty 构图完备发送失败 toast turn 级失败徽章双通道会话列表本地快路径合理缺席 skeleton300ms 延迟原则本地 SQLite 50ms无通用 Skeleton 组件正符合「形状对齐」原则。缺口留逐面触碰时补其中 P-4PT 的演进颇具代表性先以「渐进 ratchet 契约」起步#459发现--spacing基准存在 0.25rem3.75px 的真 bug 后用 #448 的完全体方案一次性替换——全量收敛并硬 ban bare px。契约测试仍是治理工具但只保留「一个机制留强的」。四、首轮队列完成记录与 PR 映射2026-07-03 全清首轮全部队列在 2026-07-03 完成#457 P-SHADOWroadmap 阴影配方 dark collapse#458 P-INSET P-RADIUS 首轮 P-MOTION 审计#459 P-4PT ratchet 契约 P-TEXT 孤儿档清理前置质感修复#454玻璃色板复活/token 卫生、#452blocked 语义/时间戳/i18n、#451copy-feedback 契约同步P-FOREGROUND-TIER-CONVERGEissue #430 PR45 档文字梯40/50/60/70/80收敛到 3 档语义别名——--foreground100% ink、--foreground-secondary80% ink、--muted-foreground50% ink。-90/-95 零调用直接删444 处调用点全量替换契约测试锁住文字用法不回退到裸 mix stops。下一轮候选按杠杆P-STATE 边缘面补齐、storybook Design System 页同步新阴影/层级规则。原「文字档 60/80 的逐面归并」已由 P-FOREGROUND-TIER-CONVERGE 解决落地为 3 档制而非 4 档原「module-pages 76 个 off-grid 值」已由 #448 全量收敛解决。五、第二轮全量精读增补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 全段亲读。5.1 Motion 增补300ms loading 阈值加载 300ms 什么都不显示杜绝闪烁 skeletonui-ux-pro-maxexit enter × 60–75%动画必须可中断快速触发用 transition/spring 可重定向禁 keyframes 重播context menu 只做退场动画80ms 瞬时感知阈值micro-interaction 目标「慢即真」AI 生成类复杂操作的可见工作过程传达真实感属 D3 的流式语义豁免区transitions.dev 参数表dropdown open 250/close 150ms、pre-scale 0.97modal 250/150、scale 0.96text swap 200ms8pxblur 2pxerror shake 6px4px overshoot、3s 自动回退replay 前void el.offsetWidth换字元素宽度锁定状态标签/token 计数/「已复制」按最宽态锁 min-width——chat 工具最高频 layout-shift 根治spring 决策表手势/可中断→spring(500/30)系统状态→easing时间表征→linear高频→零动画。5.2 Color/表面增补灰字禁上彩底彩底文字用同色相深一档或前景加 alphaOKLCH 三定律修对比只调 L 锁 C/Hpalette 各阶 hue 漂移 10° bug跨 hue 等鲜艳度用 max-chroma 相同百分比dark 深度 三档 surface 亮度15/20/25% L 同色相不靠阴影——与 P-SHADOW dark collapse 互证alpha 滥用是 palette 不完整的信号除 focus ring 外定义显式 overlay 色对 layer 陷阱也更友好Anti-Nested-Box卡中卡中卡硬 ban密集区用 border-t/divide-y/负空间替代套卡。5.3 排版/细节增补…不用...loading 文案以 … 结尾快捷键⌘ K用 nbspALL-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 键帽 recipe1px 边 4px radius 浅底 mono桌面快捷键提示刚需负 inset 伪元素扩热区44px 达标不改布局dialog::backdrop blur 4px 替代手写遮罩。5.4 治理增补icon 四条单 family、stroke 统一 1.5/2px、filled-outline 不同层级混用禁、尺寸 token16/20/24z-index 显式 scale 立法maka 已有语义 z token复核覆盖率即可modal scrim 40–60% blacktoast 纪律3–5s 自动消失、aria-live polite、永不作关键信息唯一渠道、低风险删除用 Undo toast文案按钮写确切动作、同意图全应用一个措辞发送/确认/提交不混用、error 原因修复路径、禁「轻松/简单/只需」、AI 腔清单段首总结过渡/datasheet 腔/碎句连发。5.5 React 性能vercel 70 rules 全读 → maka grounding现状审计全仓 0 处useTransition/useDeferredValuechat-view 仅 MessageBody 有 memo。已落地content-visibility#468。待做清单按序TurnView memo 化 props 收窄流式不重渲染旧 turn流式更新包startTransition/ 搜索过滤用useDeferredValuemarkdown parse 结果按 text 缓存面板 hover 预热void import()频繁 toggle 面板用Activity滚动三件套passive listener / 贴底判定走 ref / 读写分离barrel import 审计rollup-plugin-visualizercomposition-patternscomposer.tsx 792 行按 compound components 重构候选react19-no-forwardRef 全仓清理候选原生document.startViewTransition做 settings/panel 切换Electron 固定 Chromium零依赖。5.6 明确不采纳增补Lucide→Phosphor 全量换 icon80 调用点见 §4.3 问题 1待拍板Motion/GSAP 库编排、bento/hero/marquee 全家landing 专属声音反馈两篇超 UI-only scope规则已存档默认音量 0.3、打字禁声reactcanary的ViewTransition组件生产依赖不划算用原生 API 替代brutalist/gpt-tasteskill/brandkit/imagegen 系风格化/资产生成与 QoderWork 镜像路线冲突。六、第二轮拍板决策D5–D82026-07-03#决策含义D5保留 Lucide 治理不迁 Phosphor用治理抵消「默认感」stroke 统一 1.5px、尺寸 16/20/24 token 化、禁 filled/outline 同层级混用D6AI 等待感全谱引入taste v1 §9 五套微动效全部评估落地shimmer processing、typewriter 轮播、呼吸指示overshoot 通知、layoutId 列表重排、横向流。流式语义豁免区不违反 D3D7D7中性冷 zinchue 2862026-07-03 晚 owner 看到实际暖米观感后推翻 D7暖褐与玻璃通透语言相抵触「追求的是玻璃质感」。全局 ink/壳/dark/darwin 玻璃板换 zinc 族sage accent 与 sand 可选主题不动。参考基准冷净白侧栏截图zinc Canvas White Charcoal InkD8copy lint 做可机械化的那半check-copy.mjs 上线pressure-word / ascii-ellipsis同意图同措辞、AI 腔清单留人工 review其中 D7 的「自我推翻」过程值得注意owner 在看到实际暖米观感后判定暖褐色与「玻璃通透」的语言相抵触当场反转决策——这说明该路线图是感知驱动的迭代体系决策随真实观感修正而非一次定死。七、产品级附赠反截断体系超 UI存档来自 research/laziness 的反截断体系可迁移到 maka 自身的 agent prompt 设计skill description 具体度决定 68%→90% 触发率[PAUSED - X of Y]续写协议EmotionPrompt 量化数据。总结一条可复用的「质感工程化」路径这份路线图展示了一条完整可复用的质感工程化路径先定方向总纲D1–D4→ 再列逐条可执行的视觉规则九大清单→ 按杠杆排序拆成独立 PR 落地P 系列→ 每项用契约测试锁行为、双主题截图验收 → 第二轮全量精读继续增补规则并再次拍板D5–D8。仓库源码中 maka-tokens.css 的 14 档 spacing、4 档 radius、4 档 duration、三层 elevation 与 dark 单 ring 配方正是这条路线图从文档走向真实代码的最终证据。对于任何追求「一致性高级感」而非「炫技」的桌面工具产品这份路线图含其归档状态design-refinement-roadmap-2026-07.md、设计系统演进记录 design-system-v0.2-wave-10.md、总体设计说明 DESIGN.md都是一份可对照执行的高密度参考。归档说明本路线图于 2026-07-13 归档Archive。已完成的决策仍保留可见以作溯源provenance未完成队列需在 GitHub issues 中跟踪而非作为当前文档积压项对待。【免费下载链接】makaApache Maka (Incubating) is a high-performance agent workspace that keeps a complete record of everything it did.项目地址: https://gitcode.com/GitHub_Trending/mak/maka创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考