微信小程序设计规范：从原则到组件库的完整实践指南

1. 项目概述为什么需要一份自己的设计规范做微信小程序开发的朋友可能都经历过这样的场景产品经理丢过来一个原型图你吭哧吭哧照着做完了。过两天另一个页面需要类似的交互你凭着记忆“复刻”了一个结果细节上总有出入。再过一个月团队来了新人你让他参考之前的页面做他交上来的东西风格五花八门你不得不花大量时间 review 和修改。最后整个小程序看起来像是几个不同团队拼凑出来的用户体验支离破碎。这就是为什么仅仅依赖微信官方那份《微信小程序设计指南》是远远不够的。官方指南像宪法规定了基本原则和底线比如导航清晰、流程明确、避免过度营销等。但具体到你的项目里按钮的圆角到底用 4px 还是 8px主色调的蓝色具体色值是什么弹窗出现的动画是淡入还是上滑这些细节官方指南不会、也不可能为你规定。因此“微信小程序设计规范”这个项目本质上是一份属于你自己或团队的《产品设计法典》。它不是对官方指南的简单复述而是将其原则落地为可执行、可检查的具体规则。它的核心价值在于统一、提效和传承统一产品体验提升设计和开发协作效率并将设计决策沉淀下来形成团队资产。无论你是独立开发者还是团队中的技术负责人建立并维护这份规范都是从“做功能”到“做产品”的关键一步。2. 规范的核心构成不止是视觉更是系统工程一份完整的小程序设计规范应该是一个立体、多维度的体系。很多新手会把它等同于一份 UI 组件库的说明文档这其实窄化了它的价值。根据我的经验它至少应该包含以下四个层次由内而外从抽象到具体。2.1 设计原则与品牌传达这是规范的“灵魂”是所有具体规则的出发点。它需要回答我们的小程序希望给用户传递什么样的感受是专业可信还是活泼有趣是高效简洁还是温暖贴心你需要用几句简洁有力的话定义核心设计原则。例如一个工具类小程序的原则可能是“聚焦、高效、克制”一个社区类小程序的原则可能是“友好、鼓励、清晰”。这些原则将指导后续所有视觉和交互决策。品牌传达则更具体包括色彩体系不仅仅是主色、辅助色、警示色。你需要定义一套完整的色彩使用逻辑。比如主色#07C160微信绿用于主要按钮和关键操作辅助色#576B95用于次要按钮和标签中性色#333333,#666666,#999999,#EEEEEE用于文字、边框和背景。更重要的是要规定在什么场景下使用什么颜色避免滥用。字体系统微信小程序环境相对封闭中文字体通常就是系统默认的-apple-system, BlinkMacSystemFont等。规范的重点在于定义字阶Font Scale。例如页面主标题用 20px卡片标题用 18px正文用 16px辅助说明用 14px标签文字用 12px。并规定行高如正文行高设为字号的 1.6 倍以确保阅读舒适度。图标与图形规定图标的风格线性、面性、混合、粗细2px、大小规格24px, 32px, 48px以及圆角、断点等细节。确保从不同设计师手里产出的图标放在一起看是一个家族的。实操心得定义色彩时务必在真实设备上测试对比度确保可访问性。对于字体不要只定义px更要同步定义rpx值并说明在何种屏幕宽度下如 375px 设计稿的换算关系这是开发直接使用的单位。2.2 基础组件与交互模式这是规范的“骨骼”是构成页面的基本元素。你需要将官方组件进行“二次封装”和“规则化”。按钮 (Button)这可能是最常用的组件也最容易混乱。规范必须明确类型主按钮、次按钮、文字按钮、危险按钮的明确样式颜色、边框、背景。状态默认态、点击态、禁用态的具体表现透明度、背景色变化。尺寸大、中、小三种尺寸的高度、内边距、圆角。布局按钮组合时间距是多少表单内按钮的摆放位置居右、通栏。导航 (Navigation)顶部导航栏的背景色、标题字号、返回图标样式。底部TabBar的图标选中/未选中态、文字颜色、Badge的显示规则最大数字显示99。表单 (Form)输入框、单选框、复选框、开关、滑动选择器的统一样式。特别要规定错误状态的提示方式是输入框变红还是在下方显示红色提示文字。反馈 (Feedback)加载中loading、提示Toast、模态弹窗Modal、操作菜单ActionSheet的触发条件、显示时长、动画效果和关闭方式。这里特别提一下热搜词里的“微信小程序单选框”。官方组件radio样式定制能力有限。在规范里你就要决定是使用官方默认样式以保持平台一致性还是为了品牌化进行深度定制如果定制是重写整个组件还是仅用 CSS 覆盖部分样式这个决策需要写进规范并附上实现代码示例避免每个开发者各搞一套。2.3 布局与栅格系统这是规范的“肌肉”决定了页面的结构美感与响应式适应性。微信小程序没有传统 Web 的div那么自由主要使用Flex布局和rpx单位但这不代表不需要规范。全局边距 (Global Gutter)规定页面内容距离屏幕左右两边的安全距离例如32rpx。这能保证在不同尺寸手机上内容都不会紧贴边缘。栅格系统 (Grid System)虽然小程序没有Bootstrap那样的栅格组件但思想可以沿用。你可以规定在 750rpx 的设计稿宽度下将内容区划分为 12 等份的栅格。定义好槽宽Gutter和边距Margin并给出典型布局的示例代码比如“三列等分布局每列占4份列间距为20rpx”。间距体系 (Spacing Scale)这是保持视觉节奏感的关键。定义一套基于8px倍数的间距尺度如8rpx,16rpx,24rpx,32rpx,48rpx。规定不同元素之间的间距标准例如“卡片与卡片之间用24rpx”“卡片内部标题与内容之间用16rpx”。这能极大减少设计师和开发之间“把这个间距调大一点点”的无效沟通。2.4 页面模板与典型场景这是规范的“皮肤”是最高层次的复用。它把前面所有的原子颜色、字体和分子按钮、表单组合成可复用的有机体——页面。你需要为小程序中典型的页面类型制定模板列表页模板搜索栏、筛选标签、列表项图文混排、纯文字、卡片式的布局加载更多和空状态的样式。详情页模板头部信息区、主体内容区、底部固定操作栏如“立即购买”的结构和滚动交互。表单页模板多步骤表单的进度指示、表单项的排列方式、提交按钮的位置。个人中心模板头像昵称区域、菜单列表的样式。为这些模板提供WXML和WXSS的代码片段开发者可以直接复制到对应页面进行修改能节省 70% 以上的基础布局时间。3. 从零开始搭建规范的实操流程知道了规范包含什么接下来我们看怎么做。这个过程不是一蹴而就的而是一个不断迭代和沉淀的过程。3.1 第一阶段审计与收集在动手写规范之前先“盘家底”。梳理现有页面把你小程序里所有页面截图贴到一个画板如 Figma、墨刀上。直观地看哪些地方不一致同一个功能的按钮在A页面是圆的在B页面是方的颜色用了多少种不同的蓝分析高频组件统计出使用频率最高的 5-10 个组件如按钮、列表项、弹窗。这些是规范需要优先覆盖的。收集问题反馈从用户反馈、测试报告、甚至客服记录中收集因体验不一致导致的困惑或操作错误。例如用户可能反馈“不知道这个灰色的按钮能不能点”禁用态样式不明确。3.2 第二阶段定义与设计基于审计结果开始制定规则。确立基石和产品、运营同学一起确定设计原则和品牌色。可以使用在线配色工具如 Adobe Color来生成一套和谐的色板。设计组件库在 UI 设计工具强烈推荐 Figma中创建你的小程序设计组件库。从原子颜色、文本样式开始逐步构建分子按钮、输入框最后组合成有机体卡片、列表和模板页面。Figma 的Auto Layout和Variants功能非常适合做这件事。编写文档设计稿定稿后开始编写规范文档。文档工具可以选择Notion、语雀或飞书文档它们都支持良好的团队协作和页面关联。文档结构就按照我们第二章说的四个层次来组织。注意事项在设计组件时必须考虑开发实现的便利性。例如定义一个按钮组件最好能通过修改一个type属性如type“primary”来切换所有样式而不是让开发写一堆if-else来拼接样式类。在设计阶段就和前端主力沟通实现方案能避免后期大量返工。3.3 第三阶段开发与封装这是将设计规范转化为代码的环节目标是创建可复用的代码组件库。选择技术方案自定义组件方案这是最主流和推荐的方式。将每个规范化的组件如MyButton,MyCard封装成微信小程序的自定义组件。这样做的好处是隔离性好样式和行为完全内聚在任何页面中引用都能保证一致性。CSS 类方案定义一套全局的、语义化的 CSS 类名如.btn-primary,.text-title。开发者通过组合这些类来构建界面。这种方式更灵活但依赖开发者自觉容易因类名组合错误导致样式偏差。创建组件库项目建议单独创建一个微信小程序项目作为“组件库”或“UI框架”项目。在这个项目里开发和测试所有自定义组件。实现关键组件以按钮组件为例其wxml结构可能很简单但js和wxss是关键。// my-button/index.js Component({ properties: { type: { // 类型primary, default, warn, text type: String, value: default }, size: { // 尺寸large, medium, small type: String, value: medium }, disabled: Boolean, loading: Boolean }, methods: { onTap(e) { if (!this.data.disabled !this.data.loading) { this.triggerEvent(tap, e) } } } })/* my-button/index.wxss */ .btn { display: inline-flex; align-items: center; justify-content: center; border-radius: 8rpx; /* 规范定义的圆角 */ font-size: 16px; transition: opacity 0.3s; } .btn--primary { background-color: #07C160; /* 品牌主色 */ color: #FFFFFF; } .btn--disabled { opacity: 0.6; cursor: not-allowed; } /* ... 其他样式 */发布与引入组件库开发完成后可以通过npm发布小程序支持 npm或者直接将miniprogram_dev目录下的组件代码复制到业务项目中。更优雅的方式是使用git submodule将组件库作为子模块链接到各个业务项目中实现同步更新。3.4 第四阶段应用、维护与迭代规范不是写完就束之高阁的。强制执行在代码审查Code Review环节将“是否符合设计规范”作为必审项。可以使用ESLint配合自定义规则或编写简单的脚本来检测页面是否使用了规范的组件或类名。建立更新流程当业务需要新增一个组件或修改现有样式时流程应该是先在 Figma 设计组件库中更新 - 更新规范文档 - 在代码组件库中实现 - 发布新版本 - 通知各业务项目更新依赖。确保设计和代码的同步。定期回顾每季度或每半年回顾一次规范。看看是否有组件已经没人用了新的交互趋势是否需要吸纳进来用户反馈是否暴露了规范的不足让规范随着产品一起成长。4. 高频问题与深度避坑指南在实际推行规范的过程中你会遇到各种各样的问题。下面我整理了一些典型难题和我的解决方案。4.1 如何平衡规范约束与开发灵活性这是最常见的矛盾。规范太死开发觉得束手束脚规范太松又形同虚设。解方分层管理。将规范分为“强制”、“推荐”和“参考”三个等级。强制级品牌色、字体、基础按钮/输入框样式、安全边距。这些必须严格遵守没有商量余地。推荐级布局模板、典型卡片样式、图标使用建议。鼓励使用但特殊业务场景下允许申请例外。参考级动画曲线、阴影深度、一些复杂组件的交互细节。提供最佳实践供开发者在需要时查阅。建立例外申请机制当业务确实需要突破规范时要求开发者在需求单或Pull Request中明确说明理由并由技术负责人和设计师共同审批。这个过程本身也能沉淀下哪些“例外”后来变成了“通用”需求从而反哺规范。4.2 如何处理第三方库或地图等特殊组件像热搜词里提到的“微信小程序可以使用天地图画地图组件吗”答案是肯定的但样式很难统一。解方封装与隔离。对于地图、图表如echarts-for-weixin、视频播放器等强依赖第三方、且样式定制能力弱的组件不要试图去深度定制其内部样式往往做不到。我们的规范策略应该是“封装和做外壳”。创建一个MyMap组件内部引用天地图或腾讯地图。规范只规定这个组件外部容器的样式如圆角、边框、比例尺和控制按钮的位置。在文档中明确说明“地图组件内部样式遵循官方SDK默认样式仅保证外部框架符合设计规范”。这样既接受了现实又保证了整体页面布局的和谐。4.3 如何解决真机样式兼容性问题开发工具里好好的一到真机特别是部分安卓机上样式就错乱。热搜词中“微信小程序的video在部分三星手机上的层级最高”就是典型问题。解方建立兼容性检查清单。rpx换算牢记1rpx 屏幕宽度/750。在非常规分辨率如平板或web-view内rpx可能会有问题复杂布局建议用Flex布局配合百分比替代部分rpx。字体渲染不同手机系统字体渲染差异大避免使用过细的字体粗细如font-weight: 300。正文尽量使用400(normal)。层级问题video、canvas、map等原生组件层级由客户端控制确实最高。规范中必须规定“禁止在可能弹出全屏视频、地图的页面上使用fixed定位的悬浮元素”否则会被遮挡。替代方案是使用cover-view和cover-image但它们能力有限。安全区域针对刘海屏、水滴屏使用wx.getSystemInfoSync()获取safeArea信息在规范中定义页面内容如何适配安全区域特别是底部有固定操作栏时。4.4 如何推动团队接受并使用规范技术问题好解决人的问题才是难点。解方降低使用门槛展示直接价值。工具化将组件库发布到内部npm并提供一键安装脚本。创建项目脚手架scaffold新项目初始化后就直接包含了规范组件库和基础模板。可视化将规范文档部署成内部网站并配上一个在线的“组件展示台”让开发者可以直观地看到每个组件的样式、代码和使用示例甚至能在线调整参数看效果。数据化在推行一段时间后用数据说话。比如统计使用规范组件后相同功能的页面开发时长是否缩短收集测试同学关于界面样式Bug的反馈是否减少。用实实在在的效率提升和品质改善来说服大家。5. 规范文档的撰写技巧与维护心法一份好的规范文档本身就应该是一个优秀的产品体验要好。5.1 文档结构清晰便于查找不要写成一整篇长篇大论。参考优秀的开源项目文档如Ant Design。首页设计原则、色彩、字体等全局概述。组件目录每个组件一个独立页面页面内结构固定为1概述2设计指南何时使用3代码演示可交互的示例4API 文档属性、事件、插槽5常见问题。搜索功能如果你的文档工具支持一定要开启全文搜索。让开发者能快速找到“弹窗怎么禁用蒙层点击关闭”。5.2 内容生动多举实例避免干巴巴的条文。多用对比图。正确 vs 错误示例这是最有效的方式。直接放两张图一张是符合规范的一张是不符合的高下立判。场景化示例不要只展示一个孤零零的按钮。展示这个按钮在表单底部、在卡片操作区、在列表项右侧等不同场景下的样子。代码示例要即拿即用提供的代码片段应该复制到项目的page里就能运行无需额外修改。注明所需的npm包和版本。5.3 建立可持续的维护机制规范不是一个人能维护的。明确负责人指定一位“规范守护者”通常是资深前端或UI设计师负责审核变更、解答疑问。融入工作流将规范文档的链接加入到需求模板、PR模板、Bug报告模板中。让大家在工作的各个环节都能方便地触达规范。定期分享与复盘在团队技术分享会上可以定期分享规范应用的最佳实践或者讨论遇到的挑战和解决方案。让维护规范成为团队共识。维护一份设计规范前期确实需要投入不少精力仿佛在做“看不见”的基础建设。但当你看到新页面以两倍的速度上线新人能在一天内写出风格一致的代码产品体验获得用户自发好评时你就会明白这份投入是所有技术债里回报率最高的一种。它让团队从手工作坊走向了标准化生产让产品拥有了统一的灵魂。