Comp AI CRM 品牌设计令牌重构：把 CRM 界面对齐 Comp 品牌色的 ADR 实践与源码落地

后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载Comp AI CRM 的adrs/comp-palette.md是一份典型的架构决策记录ADR它指出当时 CRM 界面仍停留在未上妆的 shadcn默认观感并提出一套把两套主题亮/暗整体重指向 Comp 品牌视觉语言纯白 品牌绿#006B4F的令牌级改造方案同时记录了改造会破坏哪些既有组件。本文以这份 ADR 为主线结合当前仓库中 packages/ui/src/styles/globals.css 等源码讲解这份方案的完整内容、它最终在仓库中的落地形态以及做同类品牌化重构时可以照搬的排查清单。背景默认 shadcn 观感不是任何人的品牌ADR 开篇就点出核心问题CRM 当时的样子就是未加样式的 shadcn——纯中性灰、所有主操作都是近黑色、到处是直角。作者的评价很直接这是一个不错的默认值但它不属于任何人的品牌。而 Comp 的品牌是 flat white纯白与#006B4F品牌绿。CRM 是用户天天看的那个产品所以它理应看起来和 Comp 官网出自同一家公司。这引出了整份 ADR 的目标让设计令牌design token承担品牌一致性而不是让每个组件各自为政。触发场景设置页里一条过度惊悚的报错作者注意到这个问题是从设置页开始的一次失败的 Gmail 同步渲染出一条红色告警告警上挂着一个近黑色的 Resolve解决按钮。一个需要在 Google Cloud 项目里启用 API的小事被这套配色渲染得像系统崩溃一样严重。这个场景很有代表性语义色semantic color的错位会直接扭曲信息传达的轻重缓急。红色告警本身没错但近黑色按钮把用户的注意力从下一步该做什么拽到了出大事了上。问题清单五个与调色板无关的缺陷顺着这条线作者在排查过程中发现了一批无论换不换调色板都是 bug的问题圆角令牌主题不一致--radius在:root里是0.625rem在.dark里却是0.75rem。结果同一个控件在切换主题时会悄悄改变形状。焦点环宽窄不一不同组件上的 focus ring 分别是 1px、2px、3px键盘可达性的视觉语言完全没有收口。暗色模式下弹窗遮罩不可见modal scrim 用的是bg-black/1010% 黑色叠加在近黑色页面上几乎不可见暗色模式下对话框和背景之间没有任何分隔。deal-stage 图表色带与产品无关交易阶段漏斗图用的是一串琥珀到橙色的渐变和产品里任何其他元素都没有关系。--primary语义被滥用部分组件把--primary当作深色墨水色而不是强调色来用令牌一变这些组件就会未经同意跟着变色。这五条值得单独强调品牌化改造不等于换个主色它常常是一面照妖镜把原本被默认皮肤掩盖的令牌规范问题全部暴露出来。方案把两套主题整体重指向 Comp 品牌色ADR 给出了清晰的改造思路可以拆成四条原则1. 双主题同值品牌色不允许偷偷是两个颜色--primary与--destructive在亮、暗两套主题中必须持有相同的值。原因很朴素如果同一个品牌绿在暗色主题里被调暗或提亮品牌色就偷偷变成了两个颜色。在 ADR 提出的时刻这是方案的第一步——先让品牌色在主题切换时不漂移。2. 圆角收敛统一到 5px 并跨主题一致把圆角从各处飘忽不定的值0.625rem/0.75rem收敛到5px并且亮、暗两套主题完全一致。同时这也解释了为什么当时rounded-none的组件数量是改造的面之一——见下文破坏性影响。3. 填充语义收口fill 只给去和停这是一个很有设计判断力的原则实心填充fill只保留给两类操作——你想要的行动go和不可撤销的行动stop。其余的一切都用 chip浅底、描边、文本来承载。这样做的收益是销售代表的视线永远只会被两种东西吸引——绿色意味着去做红色意味着停手中间地带的次级操作不再和主操作抢注意力。4. 灰色保持真正的中性灰色不要往任何色相上靠。作者的判断是产品里没有需要往某个方向染色的场景一个无理由的偏色灰读起来就是犹豫不决indecision。中性灰 唯一强调色是最省力的品牌化路径。破坏性影响谁会在令牌变化后悄悄变绿ADR 如实记录了这次改造的破坏面——这正是一份合格 ADR 该有的样子硬编码颜色的组件任何写死颜色的地方都会与新令牌脱节。把--primary当暗色墨水用的组件它们会瞬间变绿。作者当时就命中了三处header 里的 logo左侧图标栏icon rail的激活态Gmail 失败告警上的 Resolve 按钮。rounded-none的宽 diff因为令牌变化叠加所有钉死在直角上的组件都要跟着改天然是一个大面积 diff。ADR 作者还给出了务实的分割建议如果调色板本身不被接受至少把两个真正的 bug 修复拆出去单独提交——一个是主题间圆角不一致一个是暗色模式不可见的 scrim。这个建议本身就是很好的工程实践问题修复与风格偏好是可以解耦的两件事。源码落地现状当前仓库中的设计令牌从当前仓库源码看ADR 提出的核心方案已经落地到 packages/ui/src/styles/globals.css 中。:root第 9 行起与.dark第 81 行起两套主题的关键令牌对比如下令牌:root亮.dark暗说明--background#ffffff#0f0f0f亮色为纯白对齐 Comp flat white--foreground#171717#f5f5f5中性近黑/近白无偏色--primary#006b4f#006b4f品牌绿双主题同值ADR 核心诉求--primary-foreground#ffffff#ffffff品牌绿上的前景色--secondary#f4f4f4#1f1f1f中性灰阶--muted-foreground#6b6b6b#a0a0a0次要文字--destructive#ae2e24#ae2e24双主题同值与 ADR 的fill 只给 stop对应--border/--input#e2e2e2#2a2a2a中性边框--overlayrgb(0 0 0 / 0.18)rgb(0 0 0 / 0.55)遮罩在暗色下显著加深--ring#006b4f#40be96焦点环暗色换更亮的绿保证可见--radius5px5px两主题一致回应 ADR 的半径问题--chart-1#00915f#0fa871图表首色已转为品牌绿同族几个关键点的源码印证半径双主题一致:root的--radius: 5pxglobals.css与.dark的--radius: 5pxglobals.css完全同值。同时theme inline中派生出一整套圆角阶梯--radius-sm: 4px、--radius-md: var(--radius)即 5px、--radius-lg: 8px、--radius-xl: 12px--radius-2xl/3xl/4xl则通过calc(var(--radius) * n)派生。圆角令牌的消费方也很直接例如 sonner.tsx 的 toast 会把var(--radius)直接用作边框圆角。scrim 从bg-black/10收口为--overlay令牌当前所有弹层遮罩dialog、sheet、drawer、alert-dialog都统一走bg-overlay例如 dialog.tsx 的fixed inset-0 isolate z-50 bg-overlay ...drawer.tsx 与 sheet.tsx 同款。暗色下--overlay提升到 55% 黑解决了 ADR 中暗色模式弹窗与页面融为一体的问题。焦点环的统一尝试layer base中全局*的样式统一为apply border-border outline-ring/50globals.css让默认描边与焦点环都锚定到 ring 令牌对应 ADR 对 focus ring 混乱的批评。语义色在业务层的映射仓库把语义进一步下沉到组件层。例如 status-indicator.tsx 定义StatusToneneutral/primary/info/success/warning/error到令牌的映射success → var(--color-success)、error → var(--color-destructive)、primary → var(--color-primary)等业务组件只声明语义tone不碰具体颜色值。交易阶段的表现层 apps/app/lib/deal-stage.ts 也遵循同样的模式CLOSED_WON → success、CLOSED_LOST → error、CONTRACT_SENT → warning由 apps/app/components/crm/deal-stage.tsx 交给StatusIndicator渲染。图表色带的现状ADR 批评 deal-stage 图表用的是琥珀到橙色的无关联 ramp。当前源码中dealStageColor()使用OPEN_STAGE_COLORSapps/app/lib/deal-stage.ts四个开放阶段的颜色来自--chart-1至--chart-4。其中--chart-1已改为品牌绿同族亮色#00915f、暗色#0fa871可以推断这是对 ADR 的直接回应但--chart-3仍是暖琥珀色亮色#b45309、暗色#c07e22--chart-2为蓝、--chart-4为紫整个 ramp 尚未完全收敛为单一品牌色带——图表配色依然是可继续打磨的面。rounded-none的波及面仍在ADR 预告了令牌变化 每个钉死在rounded-none的组件会形成宽 diff。当前源码里rounded-none依然广泛存在例如 drawer.tsx 的底部/侧向抽屉、calendar.tsx 的日期范围中间态单元格、input-group.tsx 的紧凑尺寸变体、tabs.tsx 的 line 变体、command.tsx、attachment.tsx 等。其中一部分如日历范围中间态、抽屉贴边是设计上合理的直角另一部分如输入框组、command item则是待收敛的历史遗留这正好印证了 ADR 对 diff 面积的判断。实操检查清单做一次品牌化令牌重构要查什么结合这份 ADR 与其落地过程可以沉淀出一份可复用的重构检查清单先统一语义令牌再谈换色检查--primary、--destructive、--radius、--ring、--overlay是否在亮/暗两套主题下同值品牌强调色在暗色下可以换更亮的 ring但主色本身不要漂移。搜硬编码颜色与滥用语义的组件用正则搜索写死的十六进制色值以及拿--primary当文字色/墨色的用法ADR 命中的三处——header logo、icon rail 激活态、Resolve 按钮——就是这类。给填充分级实心填充只留给主行动与破坏性行动其余操作改为 chip/描边/文本样式让go/stop成为界面上仅有的两个视觉重音。圆角收敛并派生阶梯定义一个基准半径本仓库为 5px其余圆角由它派生避免每个组件各自写死。遮罩、焦点环这类隐形令牌单独验证在暗色主题下逐页检查 scrim 可见性与键盘焦点环这两类问题不会被正常走查发现。把 bug 修复与风格偏好拆开提交主题半径不一致、scrim 不可见这类是 bug换色是偏好分开评审、分开回滚是 ADR 作者明确建议的工程做法。小结adrs/comp-palette.md的价值不在于换了主色而在于它演示了一次令牌级品牌化改造的完整思考链从真实的用户感知问题设置页告警过度惊悚出发顺藤摸瓜找出五个被默认皮肤掩盖的规范缺陷给出可执行的令牌取值原则同值、收敛、收口、中性并诚实评估破坏面与拆分策略。而当前仓库源码表明这份 ADR 的建议大部分已成为现实--primary/--destructive双主题同值、半径统一 5px、scrim 收口为--overlay令牌、图表首色转品牌绿、语义色在组件层StatusIndicator统一映射。对任何想在 shadcn/Tailwind 系产品上做品牌化改造的团队这份文档连同它的落地痕迹都是一份高质量的参考样本。相关延伸阅读ADR 同目录下的 i18n.md 与 README.md 记录了仓库中其他架构决策的讨论方式设计令牌的最终定义集中在 packages/ui/src/styles/globals.css组件级语义色映射可继续阅读 packages/ui/src/components/status-indicator.tsx 与 apps/app/lib/deal-stage.ts。赞分享后端前端CRM人工智能AI Agent【免费下载链接】crmComp AI CRM is an open source, CRM designed for AI agents. Agentic-first CRM.项目地址https://gitcode.com/gh_mirrors/crm48/crm点击查看免费下载相关推荐Comp AI CRM 界面色彩使用规范语义令牌、强调层级与明暗外观的落地实践Comp AI CRM 界面色彩使用规范语义令牌、强调层级与明暗外观的落地实践 色彩在界面中的价值不在好看而在可被正确解读。本指南围绕 Comp A后端前端CRM人工智能AI AgentOpenClaw 品牌身份落地指南语义色彩令牌、字体回退与设计审计在 ClawHub 中的实践OpenClaw 品牌身份落地指南语义色彩令牌、字体回退与设计审计在 ClawHub 中的实践 本文以 ClawHubOpenClaw 的 Skill 后端前端AI 技能AI 插件搜索引擎ui-ux-pro-max-skill 品牌更新实战用 /brand:update 一键同步品牌色到设计令牌ui ux pro max skill 品牌更新实战用 /brand:update 一键同步品牌色到设计令牌 本文围绕 ui ux pro max skillAI 技能前端设计系统上一篇终极指南如何用Mac轻松制作Windows安装U盘绕过TPM限制下一篇React Native for Web 开源项目指南及问题解决方案创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考