小程序界面做久了你会发现一个挺尴尬的现象功能逻辑写得再顺只要视觉上差一口气用户第一眼的信任感就建立不起来。很多人以为界面美化是设计师的事开发只管把组件拼上去就行结果做出来的页面能用但不好看配色发灰、间距拥挤、圆角生硬上线后自己都不太愿意截图分享。ColorUI 这类视觉组件库之所以在小程序圈子里被反复提起本质上就是它把好看这件事拆成了可以直接调用的样式资产——一套配色体系、一批现成的组件样式、一套间距与圆角的规范开发者不用从零调色也能把页面拉到及格线以上。这篇内容我想聊的不是复制粘贴就能用那种浅层教程而是把 ColorUI 放进一条完整的视觉开发链路里从项目初始化、样式体系怎么接入、组件怎么按需改造、主题色怎么统一管理到实际开发中最容易翻车的几个细节。适合已经能写小程序页面、但对视觉规范没什么系统概念的朋友也适合接过别人半成品项目、需要快速把界面收拾干净的同学。下面这些内容里有不少是我自己在几个模拟项目里反复试出来的踩过的坑会直接标出来能抄的部分我会给到具体做法。1. 先想清楚 ColorUI 到底解决的是哪一层问题很多人第一次接触这类组件库会误以为它是UI 框架跟那些带完整交互逻辑的组件库混为一谈。这个认知偏差会直接导致后面用得很别扭。ColorUI 的定位更接近一套视觉样式层它提供的是颜色、间距、圆角、阴影、字体层级这些皮肤层面的东西以及一批基于这些样式拼出来的静态组件结构。它不负责帮你处理数据绑定、事件流转、状态管理这些逻辑层的事。1.1 样式层与逻辑层的边界在哪理解这条边界特别重要。举个具体例子ColorUI 里有一个卡片样式类你把它加到 view 上立刻就有了白底、圆角、轻阴影的效果。但这个卡片里放什么内容、点击后跳哪里、数据从哪来全都得你自己写。它给你的是长什么样不是怎么动。这个边界带来的直接好处是侵入性极低。你不需要为了用它去改项目的目录结构不需要引入额外的运行时依赖甚至不需要动已有的业务代码。它本质上就是一堆 CSS 类你愿意用哪个就用哪个不想用的部分完全不影响项目。对比那些需要注册组件、配置编译参数的方案这种轻量接入对老项目改造特别友好。但边界也意味着责任划分视觉一致性得你自己守。组件库不会强制你用它的间距体系你完全可以在一个页面里混用 8px 和 13px 的边距它不会报错但页面看起来就会乱。所以用这类库的正确姿势是先把它提供的设计变量当成项目规范来遵守而不是当成可选的美化插件。1.2 为什么小程序的视觉开发特别需要这类工具小程序有个绕不开的限制包体积。主包和分包都有大小约束视觉资源如果全靠图片切图几张高清背景图就能把预算吃掉一大半。ColorUI 这类方案的核心思路是用样式代替图片——渐变用 CSS 写、阴影用 box-shadow、图标用字体或 SVG这样视觉丰富度和包体积之间就能取得一个不错的平衡。另一个原因是小程序的样式隔离机制。页面和组件之间的样式作用域有它自己的规则跨组件复用样式不像 Web 那么随意。一套提前定义好的全局样式类配合小程序的样式引入机制能省掉大量重复定义的工作。我在一个模拟项目里统计过同一个列表卡片样式如果每个页面各写一遍光重复的 CSS 就有两百多行抽成全局类之后每个页面只需要加一个 class 名。还有一点是团队协作。视觉规范如果只存在于设计稿里不同开发者实现出来的效果一定会有偏差。把颜色、间距、字号固化成一套可引用的类名相当于把设计规范变成了代码资产新人接手时照着类名用就行不用再去猜这个灰色到底是 #999 还是 #666。2. 项目接入从拿到样式文件到第一个页面跑起来接入这一步看起来简单但顺序和方式选错后面会一直别扭。我见过有人把整个样式文件直接塞进 app.wxss结果所有页面都被全局污染改一个类名影响一大片也见过有人每个页面单独引入导致样式重复打包。下面这套流程是我试下来比较稳的。2.1 样式文件的组织方式与引入位置拿到 ColorUI 的源码后核心文件通常是一个主样式文件和若干辅助文件图标字体、动画等。我的建议是不要直接改源文件而是建一个独立的样式目录来存放比如styles/colorui/把原始文件放进去然后在app.wxss里统一引入。/* app.wxss */ import styles/colorui/main.wxss; import styles/colorui/icon.wxss; import styles/colorui/animation.wxss;这样做的理由是源文件保持干净将来库更新时可以直接替换整个目录不用担心自己的定制被覆盖。你自己的定制样式单独放在另一个文件里比如styles/custom.wxss在引入顺序上放在 ColorUI 之后这样同优先级下你的覆盖规则能生效。注意小程序的import是编译期行为引入的文件会被合并进最终产物。所以引入顺序直接影响样式优先级后引入的同权重规则会覆盖前面的。这个特性既是定制的手段也是踩坑的来源。2.2 全局变量与主题色的落地方式ColorUI 自带一套配色但项目往往有自己的品牌色。直接改源文件里的颜色值是最省事的做法但也是最难维护的。更稳的方式是用 CSS 变量做一层中间层。小程序的 WXSS 对 CSS 变量的支持已经比较完善可以在app.wxss的 page 选择器上定义变量page { --brand-primary: #3d7eff; --brand-success: #2ecc71; --brand-warning: #f39c12; --brand-danger: #e74c3c; --text-main: #2c3e50; --text-sub: #7f8c8d; --bg-page: #f5f6fa; }然后在自定义样式里引用这些变量而不是写死色值。这样将来换主题只需要改变量定义不用全局搜索替换。ColorUI 的原始类名里如果写死了颜色可以在 custom 文件里用变量重新声明一遍覆盖掉。这里有个细节值得说变量定义在 page 上而不是 :root。小程序的根选择器是 page:root在部分基础库版本下行为不一致用 page 更稳妥。另外变量定义在 page 上之后所有页面和自定义组件都能继承到但自定义组件如果开启了样式隔离可能需要额外处理这个后面会讲。2.3 图标字体的加载与体积控制ColorUI 的图标方案通常是字体图标。字体文件体积相对可控但也不是没有代价。接入时要注意两点一是字体文件放在项目里用本地路径引用避免网络请求带来的首屏闪烁二是按需裁剪如果项目只用到几十个图标没必要把整套几百个图标的字体都打进去。裁剪字体图标需要一点工具配合思路是把用到的图标码点整理出来用字体编辑工具重新生成一个子集。如果嫌麻烦也可以退一步保留完整字体但确认它的体积在可接受范围内通常几百 KB 以内并且放在主包里只加载一次。我在一个模拟项目里对比过完整图标字体大约 200KB 出头对大多数项目来说可以接受但如果包体积已经很紧张裁剪就是必要动作。3. 组件改造把现成样式变成项目自己的东西直接套用组件库的默认样式做出来的页面会有很强的模板感——一看就知道用了哪个库。真正有价值的做法是在它的基础上做二次设计保留它的结构合理性替换掉视觉上的通用感。这一节讲几个改造的具体切入点。3.1 卡片与列表从默认样式到品牌化ColorUI 的卡片默认是白底、圆角、轻阴影。这个基础结构没问题但直接用会显得平淡。改造可以从三个维度入手圆角大小、阴影层次、边框处理。圆角方面默认值通常偏小如果项目调性偏柔和可以把圆角调大但要注意一致性——卡片、按钮、输入框的圆角应该属于同一个体系不能卡片是 16px 按钮是 4px那样看起来会割裂。我的做法是定义三档圆角变量小圆角用于标签和徽章中圆角用于按钮和输入框大圆角用于卡片和弹层。阴影方面默认的单层阴影容易显得脏。更好的做法是用双层阴影模拟真实光照一层近距离的浅阴影负责边缘轮廓一层远距离的扩散阴影负责层次感。.card-elevated { border-radius: var(--radius-lg); box-shadow: 0 2px 4px rgba(44, 62, 80, 0.06), 0 8px 24px rgba(44, 62, 80, 0.08); }边框处理上如果页面背景本身有颜色卡片可以去掉边框只留阴影如果背景是白色卡片就需要一条极浅的边框来区分层次否则边界会糊在一起。这个判断依据是背景与卡片的明度差差值小的时候靠边框差值大的时候靠阴影。3.2 按钮与交互态别忽略按下和禁用按钮是最容易被做糙的组件。很多人只做了默认态按下态和禁用态要么没有要么就是简单改个透明度。实际上按钮的交互反馈直接影响用户对产品质感的判断。ColorUI 的按钮类通常带了基础的按下效果但默认的反馈往往偏弱。我一般会强化三点按下时的缩放比例0.97 左右比较自然太小没感觉太大像在抖、阴影收缩按下时阴影变小模拟被按下去、颜色加深主色按钮按下时颜色深一档。.btn-primary { background: var(--brand-primary); transition: transform 0.12s ease, box-shadow 0.12s ease, background 0.12s ease; } .btn-primary:active { transform: scale(0.97); box-shadow: 0 1px 2px rgba(61, 126, 255, 0.2); background: #2f6ae0; }禁用态则要明确区分于不可点击和加载中两种语义。不可点击用降低饱和度和透明度加载中保留颜色但加一个转圈指示。这两种状态混用会让用户困惑——他不知道自己点不了是因为条件不满足还是因为正在处理。3.3 表单控件的视觉统一表单是最考验视觉一致性的地方。输入框、选择器、开关、滑块这些控件如果来自不同来源风格很容易打架。用 ColorUI 的好处是它们的基础样式是统一的但改造时要注意高度对齐。一个常见问题是输入框高度和按钮高度不一致放在同一行里高低不齐。解决办法是定义一组高度变量小号控件 32px、中号 40px、大号 48px所有控件都从这三档里取值。这样无论怎么组合同一行的元素高度都是对齐的。另一个细节是聚焦态。输入框获得焦点时边框颜色应该变成品牌色同时可以加一圈很淡的外发光。这个反馈告诉用户当前正在这里输入比单纯的光标闪烁更明确。但外发光要克制扩散范围太大反而显得廉价。4. 主题与暗色模式一套样式怎么撑起两种外观暗色模式现在几乎是标配需求但很多项目做暗色模式的方式是再写一套样式维护成本翻倍。用 CSS 变量的话这件事可以做得优雅很多。4.1 用变量切换实现主题切换核心思路是把所有颜色都抽成变量暗色模式只改变量值不改任何类名。小程序的暗色模式可以通过媒体查询prefers-color-scheme自动适配也可以提供手动切换开关。page { --bg-page: #f5f6fa; --bg-card: #ffffff; --text-main: #2c3e50; --border-color: rgba(44, 62, 80, 0.08); } media (prefers-color-scheme: dark) { page { --bg-page: #12141a; --bg-card: #1c1f27; --text-main: #e8eaed; --border-color: rgba(255, 255, 255, 0.08); } }这样所有引用变量的样式会自动跟着变。关键在于变量要覆盖完整——背景、文字、边框、阴影、分割线任何一个漏掉都会在暗色下露馅。我踩过的坑是阴影颜色写死成黑色暗色模式下阴影完全看不见卡片层次全丢了。暗色下的阴影应该用更深的黑加更高的透明度或者干脆改用边框来区分层次。4.2 暗色模式下的对比度陷阱暗色模式不是简单地把白底黑字反过来。纯黑背景配纯白文字对比度过高长时间看会累。比较舒服的组合是深灰背景比如 #12141a配略暗的白比如 #e8eaed对比度控制在 12:1 左右。还有一个容易忽略的点是品牌色在暗色下的表现。同一个蓝色在白色背景上很精神放到深色背景上可能显得刺眼或者发灰。解决办法是为暗色模式单独定义一档品牌色通常是把明度提高、饱和度略降。场景背景色文字主色品牌色调整亮色模式#f5f6fa#2c3e50原始品牌色暗色模式#12141a#e8eaed明度 15%饱和度 -10%这个调整没有绝对标准得对着实际页面看效果。我的经验是暗色下的品牌色要亮而不艳太艳会在深色背景上跳出来抢注意力。5. 实战中最容易翻车的几个细节前面讲的都是怎么做对这一节讲哪里容易做错。这些坑基本都是我在模拟项目里真实踩过的有些排查起来还挺费劲。5.1 自定义组件的样式隔离问题小程序的自定义组件默认开启样式隔离这意味着 app.wxss 里的全局类在组件内部不一定生效。ColorUI 的类如果定义在全局组件里用的时候可能完全没效果页面看起来就像样式丢了。解决办法有两个一是在组件的 json 配置里设置styleIsolation: apply-shared让外部样式能作用进来二是把需要的样式在组件内部再引入一次。前者更省事但有污染风险后者更干净但会增加重复。我的选择是基础样式颜色、间距变量用 apply-shared 共享组件特有的样式在组件内部定义。注意apply-shared 是单向的外部样式能进来组件内样式出不去。这个方向性要记清楚否则会疑惑为什么组件里定义的类在页面上用不了。5.2 字体图标不显示的三类原因图标突然变成方块或者空白排查顺序应该是字体文件是否加载成功、码点是否正确、样式是否被覆盖。第一类字体文件路径错误或者文件损坏控制台会有网络请求失败或者解析错误。第二类码点写错比如把\e600写成\e60图标就找不到对应字形。第三类最隐蔽图标的 font-family 被其他样式覆盖了尤其是引入了多个字体图标库的时候后引入的会覆盖前面的。排查方法很直接在开发者工具里选中那个图标元素看计算后的 font-family 是什么是不是你期望的那个字体名。如果不是往上找是哪条规则覆盖的。5.3 样式优先级打架的排查链路用组件库最常见的冲突是我写的样式不生效。排查链路我总结成三步看计算样式在开发者工具里选中元素看最终生效的是哪条规则来自哪个文件。比权重类选择器权重相同的情况下后定义的赢。如果你的样式文件在 ColorUI 之前引入同权重下就会被覆盖。查内联与 important内联样式优先级高于类选择器带!important的规则又高于内联。如果组件库某处用了 important你得用更高权重或者同样 important 去覆盖。大多数不生效问题到第二步就能定位。真正难查的是样式隔离导致的规则存在但不作用这种情况计算样式里根本看不到你的规则得回到 5.1 去检查组件配置。5.4 真机与开发者工具的渲染差异开发者工具用的是模拟渲染真机是真实渲染两者在阴影、渐变、字体渲染上会有细微差异。我遇到过阴影在工具里很柔和真机上偏硬也遇到过渐变在工具里过渡平滑真机上出现色带。应对方式是以真机为准做视觉验收工具只用来快速迭代。阴影参数可以适当调柔和一点给真机留余量渐变如果出现色带增加中间色标或者改用更接近的色相过渡。这些差异不影响功能但影响观感做视觉相关的工作时不能只信工具里的效果。6. 把视觉资产沉淀成可复用的规范做到这一步页面已经能看了。但如果项目要继续迭代、要多人协作光有能看的页面不够得有可复用的规范。这一节讲怎么把前面做的东西沉淀下来。6.1 建立项目自己的样式清单把用到的颜色、间距、圆角、字号、阴影整理成一份清单每个值对应一个变量名。这份清单就是项目的视觉契约新页面开发时只从清单里取值不临时拍脑袋定数值。类别变量名值用途颜色--brand-primary#3d7eff主按钮、链接、强调颜色--text-sub#7f8c8d次要文字、说明间距--space-sm8px元素内边距、图标与文字间距间距--space-md16px卡片内边距、区块间距圆角--radius-md12px按钮、输入框字号--font-body28rpx正文注意小程序里尺寸单位建议用 rpx它按屏幕宽度等比缩放在不同机型上视觉大小更一致。但 rpx 在超大屏上会显得过大所以关键尺寸可以设上限或者用 px 配合媒体查询。这个取舍看项目定位工具类应用偏 rpx展示类应用可以混用。6.2 组件封装与样式继承的平衡把常用组合封装成自定义组件能提升复用率但封装过度会让样式难以定制。我的原则是结构稳定、样式多变的封装成组件样式稳定、结构多变的保持为样式类。比如一个带图标和文字的列表项结构固定适合封装成组件通过属性控制图标和文字内容。而卡片的圆角和阴影可能在不同场景下要调整就保持为样式类让使用方自己组合。这样既复用了结构又保留了视觉调整的余地。封装组件时把可定制的视觉参数通过属性暴露出来比如圆角大小、是否显示阴影、内边距档位。这样使用方不用改组件内部样式就能调整外观避免了为了改一个圆角去改组件源码的尴尬。6.3 视觉走查的检查项上线前做一轮视觉走查比上线后改要省事得多。我常用的检查项有这么几条所有页面背景色是否统一、卡片阴影方向是否一致都朝下不能有的朝上、按钮圆角是否在同一体系内、文字层级是否清晰标题、正文、辅助文字三档分明、暗色模式下是否有元素消失。走查时把页面截图拼在一起看比单页看更容易发现不一致。人眼对并排对比的差异很敏感单独看一个页面觉得没问题放到一起就发现这个卡片圆角大那个小。7. 一些关于工具链选择的个人判断最后聊点偏主观的。ColorUI 这类视觉组件库不是唯一选择市面上还有偏逻辑封装的组件库、偏原子化样式的方案、以及完全自建设计系统的路线。选哪条路取决于项目阶段和团队构成。如果项目处于快速验证期需要尽快出可看的界面视觉组件库是最省时间的它把设计决策的成本前置了。如果项目已经稳定、有专职设计自建一套基于变量的样式系统会更贴合品牌。如果团队里前端功底强、喜欢原子化那用工具类样式方案也行但对小程序的适配要额外做工作。我的实际体会是不要指望一个库解决所有视觉问题。库能给你及格线从及格线到优秀靠的是对间距、层次、对比度这些基础原则的理解和反复调整。工具只是起点判断力才是终点。用 ColorUI 的过程中我花在改上的时间其实比花在用上的时间多但正是这些改造让它从一个通用库变成了这个项目的视觉语言。 
长河君 · 2026/10/29 12:40:15 · 阅读 1.2k 小程序视觉开发实战：ColorUI样式体系接入与主题定制
小程序界面做久了你会发现一个挺尴尬的现象功能逻辑写得再顺只要视觉上差一口气用户第一眼的信任感就建立不起来。很多人以为界面美化是设计师的事开发只管把组件拼上去就行结果做出来的页面能用但不好看配色发灰、间距拥挤、圆角生硬上线后自己都不太愿意截图分享。ColorUI 这类视觉组件库之所以在小程序圈子里被反复提起本质上就是它把好看这件事拆成了可以直接调用的样式资产——一套配色体系、一批现成的组件样式、一套间距与圆角的规范开发者不用从零调色也能把页面拉到及格线以上。这篇内容我想聊的不是复制粘贴就能用那种浅层教程而是把 ColorUI 放进一条完整的视觉开发链路里从项目初始化、样式体系怎么接入、组件怎么按需改造、主题色怎么统一管理到实际开发中最容易翻车的几个细节。适合已经能写小程序页面、但对视觉规范没什么系统概念的朋友也适合接过别人半成品项目、需要快速把界面收拾干净的同学。下面这些内容里有不少是我自己在几个模拟项目里反复试出来的踩过的坑会直接标出来能抄的部分我会给到具体做法。1. 先想清楚 ColorUI 到底解决的是哪一层问题很多人第一次接触这类组件库会误以为它是UI 框架跟那些带完整交互逻辑的组件库混为一谈。这个认知偏差会直接导致后面用得很别扭。ColorUI 的定位更接近一套视觉样式层它提供的是颜色、间距、圆角、阴影、字体层级这些皮肤层面的东西以及一批基于这些样式拼出来的静态组件结构。它不负责帮你处理数据绑定、事件流转、状态管理这些逻辑层的事。1.1 样式层与逻辑层的边界在哪理解这条边界特别重要。举个具体例子ColorUI 里有一个卡片样式类你把它加到 view 上立刻就有了白底、圆角、轻阴影的效果。但这个卡片里放什么内容、点击后跳哪里、数据从哪来全都得你自己写。它给你的是长什么样不是怎么动。这个边界带来的直接好处是侵入性极低。你不需要为了用它去改项目的目录结构不需要引入额外的运行时依赖甚至不需要动已有的业务代码。它本质上就是一堆 CSS 类你愿意用哪个就用哪个不想用的部分完全不影响项目。对比那些需要注册组件、配置编译参数的方案这种轻量接入对老项目改造特别友好。但边界也意味着责任划分视觉一致性得你自己守。组件库不会强制你用它的间距体系你完全可以在一个页面里混用 8px 和 13px 的边距它不会报错但页面看起来就会乱。所以用这类库的正确姿势是先把它提供的设计变量当成项目规范来遵守而不是当成可选的美化插件。1.2 为什么小程序的视觉开发特别需要这类工具小程序有个绕不开的限制包体积。主包和分包都有大小约束视觉资源如果全靠图片切图几张高清背景图就能把预算吃掉一大半。ColorUI 这类方案的核心思路是用样式代替图片——渐变用 CSS 写、阴影用 box-shadow、图标用字体或 SVG这样视觉丰富度和包体积之间就能取得一个不错的平衡。另一个原因是小程序的样式隔离机制。页面和组件之间的样式作用域有它自己的规则跨组件复用样式不像 Web 那么随意。一套提前定义好的全局样式类配合小程序的样式引入机制能省掉大量重复定义的工作。我在一个模拟项目里统计过同一个列表卡片样式如果每个页面各写一遍光重复的 CSS 就有两百多行抽成全局类之后每个页面只需要加一个 class 名。还有一点是团队协作。视觉规范如果只存在于设计稿里不同开发者实现出来的效果一定会有偏差。把颜色、间距、字号固化成一套可引用的类名相当于把设计规范变成了代码资产新人接手时照着类名用就行不用再去猜这个灰色到底是 #999 还是 #666。2. 项目接入从拿到样式文件到第一个页面跑起来接入这一步看起来简单但顺序和方式选错后面会一直别扭。我见过有人把整个样式文件直接塞进 app.wxss结果所有页面都被全局污染改一个类名影响一大片也见过有人每个页面单独引入导致样式重复打包。下面这套流程是我试下来比较稳的。2.1 样式文件的组织方式与引入位置拿到 ColorUI 的源码后核心文件通常是一个主样式文件和若干辅助文件图标字体、动画等。我的建议是不要直接改源文件而是建一个独立的样式目录来存放比如styles/colorui/把原始文件放进去然后在app.wxss里统一引入。/* app.wxss */ import styles/colorui/main.wxss; import styles/colorui/icon.wxss; import styles/colorui/animation.wxss;这样做的理由是源文件保持干净将来库更新时可以直接替换整个目录不用担心自己的定制被覆盖。你自己的定制样式单独放在另一个文件里比如styles/custom.wxss在引入顺序上放在 ColorUI 之后这样同优先级下你的覆盖规则能生效。注意小程序的import是编译期行为引入的文件会被合并进最终产物。所以引入顺序直接影响样式优先级后引入的同权重规则会覆盖前面的。这个特性既是定制的手段也是踩坑的来源。2.2 全局变量与主题色的落地方式ColorUI 自带一套配色但项目往往有自己的品牌色。直接改源文件里的颜色值是最省事的做法但也是最难维护的。更稳的方式是用 CSS 变量做一层中间层。小程序的 WXSS 对 CSS 变量的支持已经比较完善可以在app.wxss的 page 选择器上定义变量page { --brand-primary: #3d7eff; --brand-success: #2ecc71; --brand-warning: #f39c12; --brand-danger: #e74c3c; --text-main: #2c3e50; --text-sub: #7f8c8d; --bg-page: #f5f6fa; }然后在自定义样式里引用这些变量而不是写死色值。这样将来换主题只需要改变量定义不用全局搜索替换。ColorUI 的原始类名里如果写死了颜色可以在 custom 文件里用变量重新声明一遍覆盖掉。这里有个细节值得说变量定义在 page 上而不是 :root。小程序的根选择器是 page:root在部分基础库版本下行为不一致用 page 更稳妥。另外变量定义在 page 上之后所有页面和自定义组件都能继承到但自定义组件如果开启了样式隔离可能需要额外处理这个后面会讲。2.3 图标字体的加载与体积控制ColorUI 的图标方案通常是字体图标。字体文件体积相对可控但也不是没有代价。接入时要注意两点一是字体文件放在项目里用本地路径引用避免网络请求带来的首屏闪烁二是按需裁剪如果项目只用到几十个图标没必要把整套几百个图标的字体都打进去。裁剪字体图标需要一点工具配合思路是把用到的图标码点整理出来用字体编辑工具重新生成一个子集。如果嫌麻烦也可以退一步保留完整字体但确认它的体积在可接受范围内通常几百 KB 以内并且放在主包里只加载一次。我在一个模拟项目里对比过完整图标字体大约 200KB 出头对大多数项目来说可以接受但如果包体积已经很紧张裁剪就是必要动作。3. 组件改造把现成样式变成项目自己的东西直接套用组件库的默认样式做出来的页面会有很强的模板感——一看就知道用了哪个库。真正有价值的做法是在它的基础上做二次设计保留它的结构合理性替换掉视觉上的通用感。这一节讲几个改造的具体切入点。3.1 卡片与列表从默认样式到品牌化ColorUI 的卡片默认是白底、圆角、轻阴影。这个基础结构没问题但直接用会显得平淡。改造可以从三个维度入手圆角大小、阴影层次、边框处理。圆角方面默认值通常偏小如果项目调性偏柔和可以把圆角调大但要注意一致性——卡片、按钮、输入框的圆角应该属于同一个体系不能卡片是 16px 按钮是 4px那样看起来会割裂。我的做法是定义三档圆角变量小圆角用于标签和徽章中圆角用于按钮和输入框大圆角用于卡片和弹层。阴影方面默认的单层阴影容易显得脏。更好的做法是用双层阴影模拟真实光照一层近距离的浅阴影负责边缘轮廓一层远距离的扩散阴影负责层次感。.card-elevated { border-radius: var(--radius-lg); box-shadow: 0 2px 4px rgba(44, 62, 80, 0.06), 0 8px 24px rgba(44, 62, 80, 0.08); }边框处理上如果页面背景本身有颜色卡片可以去掉边框只留阴影如果背景是白色卡片就需要一条极浅的边框来区分层次否则边界会糊在一起。这个判断依据是背景与卡片的明度差差值小的时候靠边框差值大的时候靠阴影。3.2 按钮与交互态别忽略按下和禁用按钮是最容易被做糙的组件。很多人只做了默认态按下态和禁用态要么没有要么就是简单改个透明度。实际上按钮的交互反馈直接影响用户对产品质感的判断。ColorUI 的按钮类通常带了基础的按下效果但默认的反馈往往偏弱。我一般会强化三点按下时的缩放比例0.97 左右比较自然太小没感觉太大像在抖、阴影收缩按下时阴影变小模拟被按下去、颜色加深主色按钮按下时颜色深一档。.btn-primary { background: var(--brand-primary); transition: transform 0.12s ease, box-shadow 0.12s ease, background 0.12s ease; } .btn-primary:active { transform: scale(0.97); box-shadow: 0 1px 2px rgba(61, 126, 255, 0.2); background: #2f6ae0; }禁用态则要明确区分于不可点击和加载中两种语义。不可点击用降低饱和度和透明度加载中保留颜色但加一个转圈指示。这两种状态混用会让用户困惑——他不知道自己点不了是因为条件不满足还是因为正在处理。3.3 表单控件的视觉统一表单是最考验视觉一致性的地方。输入框、选择器、开关、滑块这些控件如果来自不同来源风格很容易打架。用 ColorUI 的好处是它们的基础样式是统一的但改造时要注意高度对齐。一个常见问题是输入框高度和按钮高度不一致放在同一行里高低不齐。解决办法是定义一组高度变量小号控件 32px、中号 40px、大号 48px所有控件都从这三档里取值。这样无论怎么组合同一行的元素高度都是对齐的。另一个细节是聚焦态。输入框获得焦点时边框颜色应该变成品牌色同时可以加一圈很淡的外发光。这个反馈告诉用户当前正在这里输入比单纯的光标闪烁更明确。但外发光要克制扩散范围太大反而显得廉价。4. 主题与暗色模式一套样式怎么撑起两种外观暗色模式现在几乎是标配需求但很多项目做暗色模式的方式是再写一套样式维护成本翻倍。用 CSS 变量的话这件事可以做得优雅很多。4.1 用变量切换实现主题切换核心思路是把所有颜色都抽成变量暗色模式只改变量值不改任何类名。小程序的暗色模式可以通过媒体查询prefers-color-scheme自动适配也可以提供手动切换开关。page { --bg-page: #f5f6fa; --bg-card: #ffffff; --text-main: #2c3e50; --border-color: rgba(44, 62, 80, 0.08); } media (prefers-color-scheme: dark) { page { --bg-page: #12141a; --bg-card: #1c1f27; --text-main: #e8eaed; --border-color: rgba(255, 255, 255, 0.08); } }这样所有引用变量的样式会自动跟着变。关键在于变量要覆盖完整——背景、文字、边框、阴影、分割线任何一个漏掉都会在暗色下露馅。我踩过的坑是阴影颜色写死成黑色暗色模式下阴影完全看不见卡片层次全丢了。暗色下的阴影应该用更深的黑加更高的透明度或者干脆改用边框来区分层次。4.2 暗色模式下的对比度陷阱暗色模式不是简单地把白底黑字反过来。纯黑背景配纯白文字对比度过高长时间看会累。比较舒服的组合是深灰背景比如 #12141a配略暗的白比如 #e8eaed对比度控制在 12:1 左右。还有一个容易忽略的点是品牌色在暗色下的表现。同一个蓝色在白色背景上很精神放到深色背景上可能显得刺眼或者发灰。解决办法是为暗色模式单独定义一档品牌色通常是把明度提高、饱和度略降。场景背景色文字主色品牌色调整亮色模式#f5f6fa#2c3e50原始品牌色暗色模式#12141a#e8eaed明度 15%饱和度 -10%这个调整没有绝对标准得对着实际页面看效果。我的经验是暗色下的品牌色要亮而不艳太艳会在深色背景上跳出来抢注意力。5. 实战中最容易翻车的几个细节前面讲的都是怎么做对这一节讲哪里容易做错。这些坑基本都是我在模拟项目里真实踩过的有些排查起来还挺费劲。5.1 自定义组件的样式隔离问题小程序的自定义组件默认开启样式隔离这意味着 app.wxss 里的全局类在组件内部不一定生效。ColorUI 的类如果定义在全局组件里用的时候可能完全没效果页面看起来就像样式丢了。解决办法有两个一是在组件的 json 配置里设置styleIsolation: apply-shared让外部样式能作用进来二是把需要的样式在组件内部再引入一次。前者更省事但有污染风险后者更干净但会增加重复。我的选择是基础样式颜色、间距变量用 apply-shared 共享组件特有的样式在组件内部定义。注意apply-shared 是单向的外部样式能进来组件内样式出不去。这个方向性要记清楚否则会疑惑为什么组件里定义的类在页面上用不了。5.2 字体图标不显示的三类原因图标突然变成方块或者空白排查顺序应该是字体文件是否加载成功、码点是否正确、样式是否被覆盖。第一类字体文件路径错误或者文件损坏控制台会有网络请求失败或者解析错误。第二类码点写错比如把\e600写成\e60图标就找不到对应字形。第三类最隐蔽图标的 font-family 被其他样式覆盖了尤其是引入了多个字体图标库的时候后引入的会覆盖前面的。排查方法很直接在开发者工具里选中那个图标元素看计算后的 font-family 是什么是不是你期望的那个字体名。如果不是往上找是哪条规则覆盖的。5.3 样式优先级打架的排查链路用组件库最常见的冲突是我写的样式不生效。排查链路我总结成三步看计算样式在开发者工具里选中元素看最终生效的是哪条规则来自哪个文件。比权重类选择器权重相同的情况下后定义的赢。如果你的样式文件在 ColorUI 之前引入同权重下就会被覆盖。查内联与 important内联样式优先级高于类选择器带!important的规则又高于内联。如果组件库某处用了 important你得用更高权重或者同样 important 去覆盖。大多数不生效问题到第二步就能定位。真正难查的是样式隔离导致的规则存在但不作用这种情况计算样式里根本看不到你的规则得回到 5.1 去检查组件配置。5.4 真机与开发者工具的渲染差异开发者工具用的是模拟渲染真机是真实渲染两者在阴影、渐变、字体渲染上会有细微差异。我遇到过阴影在工具里很柔和真机上偏硬也遇到过渐变在工具里过渡平滑真机上出现色带。应对方式是以真机为准做视觉验收工具只用来快速迭代。阴影参数可以适当调柔和一点给真机留余量渐变如果出现色带增加中间色标或者改用更接近的色相过渡。这些差异不影响功能但影响观感做视觉相关的工作时不能只信工具里的效果。6. 把视觉资产沉淀成可复用的规范做到这一步页面已经能看了。但如果项目要继续迭代、要多人协作光有能看的页面不够得有可复用的规范。这一节讲怎么把前面做的东西沉淀下来。6.1 建立项目自己的样式清单把用到的颜色、间距、圆角、字号、阴影整理成一份清单每个值对应一个变量名。这份清单就是项目的视觉契约新页面开发时只从清单里取值不临时拍脑袋定数值。类别变量名值用途颜色--brand-primary#3d7eff主按钮、链接、强调颜色--text-sub#7f8c8d次要文字、说明间距--space-sm8px元素内边距、图标与文字间距间距--space-md16px卡片内边距、区块间距圆角--radius-md12px按钮、输入框字号--font-body28rpx正文注意小程序里尺寸单位建议用 rpx它按屏幕宽度等比缩放在不同机型上视觉大小更一致。但 rpx 在超大屏上会显得过大所以关键尺寸可以设上限或者用 px 配合媒体查询。这个取舍看项目定位工具类应用偏 rpx展示类应用可以混用。6.2 组件封装与样式继承的平衡把常用组合封装成自定义组件能提升复用率但封装过度会让样式难以定制。我的原则是结构稳定、样式多变的封装成组件样式稳定、结构多变的保持为样式类。比如一个带图标和文字的列表项结构固定适合封装成组件通过属性控制图标和文字内容。而卡片的圆角和阴影可能在不同场景下要调整就保持为样式类让使用方自己组合。这样既复用了结构又保留了视觉调整的余地。封装组件时把可定制的视觉参数通过属性暴露出来比如圆角大小、是否显示阴影、内边距档位。这样使用方不用改组件内部样式就能调整外观避免了为了改一个圆角去改组件源码的尴尬。6.3 视觉走查的检查项上线前做一轮视觉走查比上线后改要省事得多。我常用的检查项有这么几条所有页面背景色是否统一、卡片阴影方向是否一致都朝下不能有的朝上、按钮圆角是否在同一体系内、文字层级是否清晰标题、正文、辅助文字三档分明、暗色模式下是否有元素消失。走查时把页面截图拼在一起看比单页看更容易发现不一致。人眼对并排对比的差异很敏感单独看一个页面觉得没问题放到一起就发现这个卡片圆角大那个小。7. 一些关于工具链选择的个人判断最后聊点偏主观的。ColorUI 这类视觉组件库不是唯一选择市面上还有偏逻辑封装的组件库、偏原子化样式的方案、以及完全自建设计系统的路线。选哪条路取决于项目阶段和团队构成。如果项目处于快速验证期需要尽快出可看的界面视觉组件库是最省时间的它把设计决策的成本前置了。如果项目已经稳定、有专职设计自建一套基于变量的样式系统会更贴合品牌。如果团队里前端功底强、喜欢原子化那用工具类样式方案也行但对小程序的适配要额外做工作。我的实际体会是不要指望一个库解决所有视觉问题。库能给你及格线从及格线到优秀靠的是对间距、层次、对比度这些基础原则的理解和反复调整。工具只是起点判断力才是终点。用 ColorUI 的过程中我花在改上的时间其实比花在用上的时间多但正是这些改造让它从一个通用库变成了这个项目的视觉语言。