01 / Context & diagnosis
先解决组件多、规则散的问题
Pisell 2.0 已经积累了大量基础组件和业务组件。我先从三个方面重新整理：组件如何分层，状态与边界是否齐全，以及主题和代码能否复用同一套规则。
基础控件、可配置 Pro 组件和开箱即用 Plus 组件同时增长，需要明确依赖方向，避免页面级方案反向污染底层组件。
默认、选中、禁用只是起点；加载、异常、冲突、权限、空数据、超长内容和不同终端才决定组件能否进入真实业务。
现有变量已支持 Light / Dark，下一步需要补充语义 Token 与组件 Token，让主题、品牌和业务状态分别管理。
Current baseline
现有资产与基线
我把现有组件、主题与规范重新放回真实业务里核对，先确认哪些规则应该稳定复用，哪些能力应该留给业务配置。
02 / Component model
我如何建立组件的组织与状态模型
我先按复用范围划分 Foundation、Atom、Pro、Plus 与 Pattern，再把尺寸、类型、状态、意图、插槽和断点写成显式属性。这样新增业务场景时，团队优先组合现有能力，而不是再复制一套相似组件。
Atomic specimen atlas
基础组件的状态与属性
下面按操作、输入、状态和反馈，整理了 Button、Input、Badge、Tooltip 等组件的主要变体。
Figma component set
Input field 变体模型
我把 Input field 拆成尺寸、输入类型、交互状态、校验意图和内容插槽五个维度。设计稿与代码使用同一套属性名，新增场景时只组合已有维度，不再复制一个“看起来差不多”的输入框。
- Size
- sm / md
- Type
- Default、Icon leading、Dropdown、Payment、Tags、Trailing button
- State
- Placeholder / Filled / Focused / Disabled
- Destructive
- False / True，并同时绑定错误文案
- Properties
- Label、Hint text、Help icon、Icon swap
保留状态矩阵与可组合属性
把 Size、Type、State、Error、Slot、Breakpoint 显式化，让设计稿与代码 Props 共享同一套语言，减少“看起来差不多”的隐性分支。
为复杂 SaaS 增加业务层
Pisell 不停留在通用组件，而是补充 Pro 可配置能力与 Plus 业务答案，覆盖销售、预约、资源、促销、权限与多终端现场。
03 / System architecture
从基础规则到业务组件
我按照规则的复用程度和业务语义进行分层：底层稳定视觉与交互规则，上层组件再带入销售、预约、支付等具体场景。
One system · multiple outcomes
同一套规则在四类产品中的应用
Architecture example
Shell Frame：固定“头尾”，开放“中间”
我把标题、工具、统计、滚动、批量操作和状态提示收进同一套外壳；中间只负责接入具体 Layout。切换下面的视图可以看到：数据和内容呈现会变化，但头部能力、底部状态与操作位置始终稳定。
- 头部固定标题、搜索、筛选、统计和视图管理保持同一位置
- 中部开放Grid、Calendar、Timeline、Kanban、Floor Map、Resource 按需注入
- 底部统一选中项、同步状态、分页和批量操作共享同一套反馈
订单与交易
同一订单数据 · 管理者视角
04 / Theme system
主题如何控制品牌、密度与组件状态
我把主题拆成四层：Seed 记录品牌与密度意图，Map 负责派生完整色阶和尺寸，Alias 把值映射到跨组件语义，Component Token 再处理局部业务状态。品牌调整只改上层输入，不需要逐页修改组件。
colorPrimary、fontSize、sizeUnit、borderRadius、success / warning / error
品牌色阶、背景层级、字号与间距阶梯、暗色与紧凑算法
text.primary、surface.canvas、border.subtle、action.primary
grid.row.hover、promo.selected、floor.resource.reserved
Interactive token lab
切换主题与界面密度
Default 与 Dark 展示颜色语义，Compact 展示同一结构在高密度场景中的变化。
05 / Component specification
组件文档需要回答哪些问题
除了视觉样式，组件文档还要说明使用场景、状态变化、配置权限和异常处理。我将现有文档整理为八个固定部分。
名称、编号、类型、分类、版本、依赖关系
问题、目标、适用与不适用场景
区域、Slot、层级、必选与可选模块
默认、焦点、禁用、加载、错误、空状态
断点、滚动、固定区、触控与鼠标输入
触发、反馈、提交、冲突与恢复路径
样式、能力、数据、权限与默认行为
输入输出、边缘情况、可访问性与变更记录
Documentation system
把设计判断整理成团队可以执行的交付物
组件设计文档
说明组件为什么存在、怎么组成、有哪些变体和状态，以及配置项、边界、可访问性和研发验收标准。
- Anatomy & variants
- States & edge cases
- Props & acceptance
设计与交互规范
统一 Token、排版、色彩、布局、反馈、错误恢复、响应式和多设备适配，减少页面之间的临时判断。
- Foundation & tokens
- Interaction rules
- Responsive & devices
业务模式说明
把预约、订单、空间资源、促销和页面外壳等重复问题整理成对象、流程、状态与权限都清楚的复用模式。
- Objects & workflow
- State & permission
- Reusable patterns
Design System 白皮书
解释体系目标、适用范围、分层原则、角色分工、贡献流程、版本发布、迁移与废弃机制，帮助团队长期维护。
- Vision & scope
- Governance & owners
- Release & migration
Documentation project
白皮书、设计规范和组件文档，整理成一套完整的文档资产
包含独立的白皮书与设计规范阅读页，以及 100+ 组件文档中的代表样例。重点说明体系原则、跨端规则、配置契约和长期维护方式。
进入文档体系项目 →
Configuration as a product
把组件能力整理成明确的配置项
选择组件与上下文后，右侧会同步显示对应的 Props 契约和文档页面。
Zoom 80% · Pan off · Controls on
Component documents
查看组件规范原稿
可以按组件打开对应的状态、冲突和配置规则。
06 / Business patterns
从通用组件走向业务模式
我选取四类业务组件，说明数据视角、空间资源、促销冲突和页面外壳如何被抽象与复用。
Sales Grid · Perspective
不复制多个订单列表，而是用同一数据源 + Perspective 决定默认字段、排序、筛选、统计与可用操作。
Floor Map · Spatial resource
用统一资源模型映射位置、尺寸、形状和状态；组件只负责展示、缩放、平移和事件输出，不接管业务数据。
Promotion Selector · Rule engine
把优惠券、会员权益、积分、礼品卡和 Promo Code 收敛为统一入口；新旧方案冲突时必须明确替换与差额。
Shell Frame · Composable shell
统一标题、工具、统计、内容、滚动与底部状态，按角色、设备与视角控制显隐、顺序和权限。
07 / Governance
组件如何进入系统并持续维护
每个组件都需要经过需求收集、分类、设计、研发评审、发布和使用反馈，并在 Figma、文档与代码中保持一致状态。
收集场景、重复证据与现有替代方案
判断 Atom、Pro、Plus 或页面私有
状态矩阵、边界、响应式与可访问性
设计 + 研发联合评审与 API 对齐
版本、变更说明、迁移与回滚策略
使用反馈、重复建设与缺陷回流
Planned → In design → In development → Released → Deprecated。Figma 页面、文档和代码版本使用同一状态词，减少口头同步。
Figma 属性对应前端 Props；Token 避免硬编码；每次不兼容变更必须提供 migration note，而不是只更新设计稿。
接下来的完善方向
08 / Outcome & reflection
从组件建设到系统维护
这套工作覆盖基础规范、业务组件、主题架构、配置契约、组件文档、设计白皮书和维护流程，也让设计与研发在日常协作中有了更清楚的共同语言。
我的目标是让团队能够理解、复用和配置这些组件，并在产品继续扩展时保持一致。