一天一个SKILL——uniapp小程序样式规范终极方案!32条强约束+16类组件+Utility原子类,彻底告别不规范UI

大家好，我是【考拉搞AI】，一个专注于 VibeCoding 分享 & AI 工程化 的博主。

之前给大家介绍了 uniapp 的请求层、审计、主题系统等技能，项目架构搭好了，代码质量也有保障了——但一打开模拟器，我的妈，页面简直惨不忍睹：

标题颜色东一个 #333 西一个 #222，字体大的大小的小；
A 页面左右留白 32rpx，B 页面变成 24rpx，C 页面某个模块直接干到 40rpx；
弹窗有的滑入滑出丝滑，有的直接硬闪毫无过渡；
自定义头部跟胶囊按钮打架，标题被挡一半；
z-index: 99999，到底谁该在谁的上面，全靠缘分；
底部固定按钮每个页面写一遍，宽高、圆角、颜色五花八门。

这些问题不是 UI 不好看，而是缺少一套完整的样式设计规范。AI 毕竟不知道你心里"好看"的标准是什么——你不给它约束，它就放飞自我。

今天的主角就是来解决这些问题的：uniapp-style-skill，一套专为 uniapp 小程序打造的全局样式设计规范 + 审计修复工具。

最近楼主接到一个单子，正在做一个非常复杂，页面数量众多的小程序，这套技能规范也是从中总结而来，有机会会继续分享给大家做这个小程序的点点滴滴。（最终会打包成APP）

一、样式规范的必要性

AI 做出来的不使用任何技能的UI（随着AI 的快速迭代，这些技能也迟早会被AI 吃进去，但个性化的不会）：

痛点	后果
颜色硬编码	`#2b2e31` / `#333` / `#222` 三个"黑色"轮着用
字号满天飞	标题有的 32rpx 有的 36rpx 有的 30rpx，毫无层次
间距各自为政	模块间距 24rpx/20rpx/32rpx 混搭，视觉参差不齐
圆角不一致	卡片 8rpx、弹窗 12rpx、按钮 16rpx，毫无统一感
弹窗无动画	有的滑入滑出，有的直接闪现，体验割裂
z-index 乱写	`999` / `9999` / `99999`，层级全靠人工猜
胶囊按钮被挡	自定义导航栏标题跟胶囊重叠，或者跑到胶囊上面
底部按钮重复写	每个页面自己写一遍固定底部按钮，宽高颜色全不同
空列表各写各的	有的写"暂无数据"，有的写"没有内容"，样式各不相同

二、详细介绍

我分为两大类介绍：强约束 + 组件规范。

强约束

这是我常常遇到的一些常见常用的强约束

Token 强制：颜色/字号/间距/圆角/阴影/z-index 必须用变量，禁止硬编码
样式约束：scoped、嵌套≤3层、动画限transform/opacity、深色模式适配
页面布局：全页禁止scroll-view、外边距统一、模块间距一致
组件约束：Popup必有动画、列表项结构统一、表单控件统一
项目级：   胶囊对齐、自定义头/底全局统一、禁止第三方UI库

比如 D12：自定义导航栏必须对齐胶囊——标题在第一行、与胶囊按钮水平居中、不遮挡不跑偏。违反就是 bug。

D24：可点击元素必须 ≥ 44x44pt（≈88rpx）——随便一个按钮小于 88rpx，直接判定违规。

组件规范

模块	覆盖内容
Design Tokens	四层架构（config → primitive → semantic → mixins），vite 自动注入
排版系统	7 级字号（xs~xxxl）+ 行高 + 字重 + 字体家族 + 文本层级 H1~H4
间距系统	基于 4rpx 的完整阶梯 + Page Gutter + 模块间距
语义变量	文字色（基色自动派生！）、背景色、功能色、边框、圆角、阴影、Z 层级
色板函数	`tint()` / `shade()` 自动生成 50-900 完整色板
动画 Token	3 档时长 + 4 条缓动曲线
Button	5 种类型 + loading 态 + hover 态 + 底部固定按钮全局样式
Popup	3 种方向动画（底部/居中/右侧）+ 统一内边距
Card / Modal / Toast / Input / NavBar	属性规范 + 样式约定
Divider / Badge / ListItem / Avatar / Grid	完整 CSS 实现
Empty	空列表统一组件（禁止页面各自写"暂无数据"）
Image	宽高比 + 占位 + 兜底
交互状态	8 种视觉模式 + 最小触摸区域
深色模式	CSS 变量桥接 + 媒体查询 + data-theme 手动切换
Utility 原子类	类似 TailwindCSS 的 flex/gap/text/bg/rounded 高频 class
设计合规审计	扫描硬编码 → 出报告 → 一键修复

字体默认色阶

字体色和主题色不同，主题色可能是任意颜色，但是字体色并不一定是主题色，字体色一般是黑色，以及派生浅色，如灰色、浅白色等等（副标题、卡片底部时间日期、人物名称以及 border线等等）

$color-text-primary: #2b2e31;    // 标题
$color-text-secondary: #5b6167;  // 副标题
$color-text-tertiary: #737a82;   // 时间、作者
$color-text-disabled: #b5b9bf;   // 禁用

问题来了：哪天想整体调亮或调暗？四个值一个个改，肉眼对齐，改到眼瞎。

uniapp-style-skill 的做法：

$color-text-primary: #2b2e31;  // 只设这一个基色

// 全部自动派生！
$color-text-secondary: tint($color-text-primary, 30%);   // 混30%白 = 变浅
$color-text-tertiary: tint($color-text-primary, 50%);    // 混50%白 = 更浅
$color-text-disabled: tint($color-text-primary, 70%);    // 混70%白 = 极浅

改一处，全部联动。你甚至可以在脑内直接推理：标题是黑色的，副标题是其 30% 白色版本，时间是 50%，禁用是 70%。

应用到实际页面：

卡片标题   → $color-text-primary（黑，大字）
副标题     → $color-text-secondary（浅一层，小字）
左下角时间 → $color-text-tertiary（更浅，最小字）
右下角作者 → $color-text-tertiary（同上）

视觉层次一目了然，不需要人工反复调色。

三、原子类

借鉴 TailwindCSS 但专为小程序精简。98 个高频原子类：

<!-- ❌ 之前：一堆内联样式 -->
<view style="background: #fff; border-radius: 16rpx; padding: 16rpx; 
  box-shadow: 0 2rpx 4rpx rgba(0,0,0,0.06); display: flex; 
  align-items: center; justify-content: space-between">
  <view style="display: flex; flex-direction: column; flex: 1">
    <text style="color: #2b2e31; font-size: 32rpx; font-weight: 600;
      overflow: hidden; white-space: nowrap; text-overflow: ellipsis">标题</text>
    <text style="color: #5b6167; font-size: 24rpx; margin-top: 8rpx">描述</text>
  </view>
  <text style="color: #737a82; font-size: 20rpx; margin-left: 8rpx">2024-01-01</text>
</view>

<!-- ✅ 之后：utility class -->
<view class="bg-white rounded-md p-4 shadow-sm flex-between">
  <view class="flex-col flex-1">
    <text class="text-primary text-lg font-semibold text-ellipsis">标题</text>
    <text class="text-secondary text-sm mt-2">描述</text>
  </view>
  <text class="text-tertiary text-xs ml-2">2024-01-01</text>
</view>

把上面那个 2024-01-01 换成浅灰色？不用调色，text-tertiary 搞定。

flex 系列：.flex.flex-between.flex-center.flex-col.flex-1
gap 系列：.gap-1 ~ .gap-8
文字系列：.text-primary ~ .text-disabled + .text-xs ~ .text-xxl + .font-normal ~ .font-bold
圆角阴影：.rounded-sm ~ .rounded-full + .shadow-sm.shadow-md

四、全局扫描

规范写得再好，人也会漏。所以 uniapp-style-skill 附带了一个审计修复模式：

你：审计 src/pages/
它：扫描中...
    → 发现 15 处违规：
      颜色硬编码 #333 等 6 处
      字号硬编码 32rpx 等 4 处
      z-index 硬编码 999 等 3 处
      缺失 scoped 2 处

你：全部修复
它：#333    → $color-text-primary
    32rpx   → $font-size-lg
    16rpx   → $spacing-4
    999     → $z-max
    ... 15 处修完 → lint 通过 ✓

它不碰你的业务逻辑，不碰第三方库，不碰 _theme-config.scss（那是你的配置源），只修硬编码的样式值。

案例：

能干啥直接问：

AI 自带 scroll-view 异常烦人：

日常欠缺一个固定的空白页面：

边距不统一：

胶囊按钮问题：

五、干活模式

触发词直接抄：

/uniapp-style-skill 样式规范
/uniapp-style-skill 颜色变量
/uniapp-style-skill 按钮怎么写
/uniapp-style-skill 弹窗规范
/uniapp-style-skill 自定义导航栏胶囊对齐
/uniapp-style-skill 页面间距统一
/uniapp-style-skill 深色模式
/uniapp-style-skill 设计审计
/uniapp-style-skill 修复硬编码