00 / Executive summary
先统一底层语言，再让不同产品保留自己的业务差异
Pisell 同时服务商家后台、POS、Terminal、在线商店、预约和员工移动端。问题不只是页面数量多，而是同一个订单、客户、支付或资源对象在不同角色和设备里有不同密度、权限和操作方式。Design System 的任务，是稳定共同的语义、状态和配置契约，让差异发生在正确的层级。
稳定语义
名称、状态和反馈方式跨终端一致，用户不需要重新学习。
允许配置
主题、密度、能力和业务规则通过明确配置改变，不复制组件。
连接交付
Figma Properties、前端 Props、文档与验收标准使用同一套语言。
白皮书负责回答“系统如何工作”；设计规范负责回答“所有界面要遵守什么”；组件文档负责回答“这个组件具体怎么用”。
01 / Vision & scope
系统的边界，从复用价值和业务责任出发
进入 Design System 的能力需要能够跨页面或跨终端复用，并且有清楚的状态、配置和维护责任。一次性的活动视觉、单一客户定制内容和没有稳定规则的探索方案，不会过早沉淀进基础层。
| 进入系统 | 保留在产品 | 判断依据 |
|---|---|---|
| Foundation 与通用组件 | 页面内容与单次活动视觉 | 是否跨场景复用，是否有稳定语义 |
| 订单、资源、促销等业务模式 | 特定客户的流程例外 | 是否能抽象出对象、状态和权限契约 |
| 主题、密度和多端规则 | 未经验证的视觉实验 | 是否需要由团队长期维护 |
02 / System architecture
六层架构，让基础能力和业务方案各司其职
依赖只向下发生：上层可以组合下层，下层不感知具体业务。这样既能支持通用组件，也能承载预约、支付、资源调度等复杂模式。
Color、Type、Space、Radius、Elevation、Motion。
Button、Input、Badge、Tooltip 等基础构件。
表格、筛选、导航、日期、资源视图等可配置组件。
订单、支付、促销、预约等有业务语义的能力。
列表管理、创建流程、确认与异常恢复。
Admin、POS、Terminal、Booking、Mobile。
03 / Design principles
四条原则，约束每一次组件和模式决策
语义优先
先确定对象、动作和状态，再决定视觉和组件形式。
契约可见
配置、权限、输入输出和异常不藏在页面实现里。
业务隔离
通用组件保持稳定，业务规则在 Plus 与 Pattern 层处理。
多端一致
不同设备可以改变密度和布局，但不改变核心语义和状态。
04 / Theme architecture
主题不是换颜色，而是受约束的视觉配置
主题由 Seed、Alias 和 Component Token 三层组成。品牌色、字号基线和圆角等 Seed Token 先映射为语义 Alias，再由组件 Token 处理局部需求。Light、Dark 和 Compact 是模式，不是另一套组件。
| 层级 | 负责内容 | 变更边界 |
|---|---|---|
| Seed Token | 品牌色、字号基线、圆角、间距基线 | 改变品牌或产品基调时调整 |
| Alias Token | 文本、背景、边框、状态和层级语义 | 跨组件共享，禁止业务页面直接绕过 |
| Component Token | 组件局部尺寸、状态和结构差异 | 只在通用语义不足时增加 |
05 / Product mapping
一套对象模型，分发到五类产品触点
Merchant Core
配置、运营、订单、客户、商品、资源和经营数据的完整工作台。
Store operations
高频触控、支付、履约、员工切换和断网恢复，强调速度与准确。
Consumer & staff
预约、结账、会员与员工任务，强调单手操作和逐步确认。
跨端一致的不是页面长相，而是对象 ID、状态含义、操作结果和错误恢复方式。
06 / Governance
治理不是审批，而是让变更有清楚的责任和路径
提交场景、问题、复用范围和现有替代方案。
确认层级、命名、状态、可访问性和技术影响。
同步设计变体、代码实现、文档和测试样例。
记录版本、影响范围、迁移方式和废弃计划。
从接入问题、重复方案和缺陷反馈中继续调整。
| 角色 | 主要责任 | 交付证据 |
|---|---|---|
| Design System Owner | 架构、命名、视觉与交互规则、发布判断 | Figma、规范、评审记录、版本说明 |
| Engineering Owner | Props 契约、实现质量、测试与包发布 | 代码、Story、测试、Changelog |
| Product Contributor | 业务场景、对象规则、权限和边界案例 | 流程、状态、异常与验收条件 |
07 / Release & migration
每次更新都要说明：谁受影响、怎么迁移、何时结束
- 01变更分类区分新增、兼容性调整、行为变化和破坏性更新。
- 02影响范围列出涉及组件、产品、设备、角色和主题模式。
- 03迁移说明给出旧方案、目标方案、替换步骤和验证标准。
- 04废弃周期保留明确的兼容窗口、负责人和最终移除版本。
- 05发布记录把设计、代码、文档和演示链接放在同一条记录中。
08 / Decision list
真正进入评审的，不是口号，而是这些可检查的决定
白皮书把体系原则转成团队可以逐条确认的问题。外部规范只负责校准通用底线，具体层级、终端和业务边界仍由 Pisell 的真实场景决定。
- 01归属层级这是基础 Token、通用组件、业务组件、Pattern，还是只属于某个产品的页面方案？
- 02复用边界能否跨角色、页面或终端复用；哪些差异必须通过配置表达，哪些应留在产品层？
- 03状态契约默认、焦点、禁用、加载、错误、空状态和恢复路径是否齐全，状态语义是否跨端一致？
- 04所有权谁提出、谁评审、谁实现、谁验收、谁维护，设计与代码的变更是否在同一条记录中？
- 05发布影响变更影响哪些组件、产品、设备和主题；是否需要迁移说明、兼容窗口和废弃计划？
- 06质量基线是否通过布局、可读性、键盘、触控、焦点、对比度和错误识别等跨平台检查？