设计理念
Snake UI 面向 uni-app Vue 3 的移动商城与页面装修场景。它不隐藏所有平台和业务差异，而是提供稳定的 UI 底座，并让宿主应用明确接管自己的数据、服务和运行环境。
以 uni-app Vue 3 为运行边界
组件使用 uni-app 内置组件、条件编译和 uni API，因此目标环境是 uni-app Vue 3，而不是任意 Vue Web 工程。明确运行边界可以直接使用多端能力，也避免为不存在的通用 Web 兼容增加复杂度。
平台目标表示能够参与构建，不代表所有业务流程在所有基础库、系统版本和机型上表现完全相同。导航、弹层、滚动、主题和外部能力仍需在实际目标端验证。
基础 UI 与业务服务分离
按钮、图片、弹层等基础组件可以独立使用。商品查询、优惠券领取和外链跳转依赖业务后端、登录态和路由规则，因此通过 cms.services 由宿主注入。
这种边界让 Snake UI 不绑定某个接口格式或业务系统，也让宿主可以在不修改组件的情况下替换请求、缓存和跳转实现。
远端数据先适配再渲染
TypeScript 类型不能保证接口 JSON 在运行时合法。装修数据进入组件前，应由业务层完成解析、默认值、字段转换和最小校验。
Snake CMS 负责按 component 分发、报告诊断并处理渲染状态，不负责理解每个后端的历史字段。标识差异使用别名，结构差异使用 normalizer，业务私有模块使用 extension 插槽。
主题使用语义令牌
组件优先使用 --snake-color-* 语义变量，而不是依赖固定品牌色。主题负责提供主色、文字、表面、边框和状态色，组件只表达这些颜色的用途。
业务样式沿用相同变量后，可以与多主题和暗色模式同步变化。必须写死颜色时，应同时考虑暗色模式和文字对比度。
渐进演进
组件能力按需逐步演进，不追求一次性全量覆盖。历史兼容接口以具体组件文档为准，未声明的属性不属于兼容承诺；发布前应完成目标端回归。
实践建议
单位
- 字体、宽高、间距推荐使用
rpx，随屏幕宽度等比缩放；需要固定尺寸时用px。 - 全屏高度使用
100vh，避免依赖内容撑开。 - 不在 uni-app 中使用
rem，它依赖根字体设置，多端行为不一致。
布局
- 统一使用 flex 布局，避免 float；移动端 flex 无兼容顾虑。
- 栅格与间距优先使用
gap，需要兼容旧基础库时改用margin方案。
导航栏
- 页面需要自绘导航或沉浸式头部时，用
snake-navbar自绘；其余场景优先使用 uni-app 原生导航栏（pages.json 配置）。 - 遮罩、弹层要覆盖原生导航栏时，必须在
pages.json关闭对应页面的原生导航栏，否则层级受限。
真机调试
- 写布局阶段用浏览器或 H5 快速迭代；浏览器预览的精细度不等于真机表现。
- 涉及小程序或 App 的逻辑，每完成一个页面就用真机或模拟器验证一次，避免问题堆积到发布前。
- 需要兼容小程序和 App 时，导航、弹层、滚动和吸顶行为必须在实际目标端回归。
安全区适配
iPhone 等机型底部带有指示条。弹层、底部操作栏等贴近屏幕底部的组件要注意安全区；safe-area-inset-bottom 相关处理以具体组件文档的平台说明为准，并在真机上确认。