设计与开发工作流

Design System + Code-First 的 Solo Dev 工作流 — 2026-02-07

1. 核心思路

一句话总结：设计系统管组件规范，代码管页面组装，不做中间层的全量页面设计稿。

作为 solo dev，我们需要的是最短的反馈环，而不是最完整的文档链。 传统设计流程中，页面级设计稿（mockup）是设计师和开发者之间的沟通媒介。 但当设计和开发是同一个人时，这个中间层带来的价值远小于它的维护成本。

2. 最终工作流

graph TD
    A["设计系统 (.pen)"] -->|"组件规范"| B["Flutter 代码"]
    B -->|"活文档"| C["Widgetbook"]

    style A fill:#C89B3C22,stroke:#C89B3C,color:#fff
    style B fill:#6366F122,stroke:#6366F1,color:#fff
    style C fill:#0B6E6E22,stroke:#0B6E6E,color:#fff
层级 工具 职责 维护时机
设计系统 Pencil (.pen) 单个组件的视觉规范（颜色、尺寸、间距、状态） 组件级别的变更时更新
代码实现 Flutter + celoria_ui 页面组装、交互逻辑、状态管理 每次开发时
活文档 Widgetbook 组件的真实渲染预览，视觉回归验证 自动跟随代码

3. 为什么不做全量页面设计稿

我们讨论后排除了"为每个 App 的每个页面都出 Pencil 设计稿"的方案。原因：

问题只有两种

  1. 组件长什么样 → 改设计系统 (.pen)
  2. 组件怎么拼 → 改代码

页面级设计稿夹在这两者之间，对 solo dev 来说：

反面教训

很多团队的 Figma 文件里充满了和实际产品不一致的"历史设计"。 没人知道哪个版本是最新的，最后大家都只看代码。 我们直接跳过这个阶段。

4. 例外：什么时候需要先做设计

Case-by-case 判断，不作为固定流程。

以下场景值得在 Pencil 里先画再写代码：

场景 原因 示例
全新的复杂交互流程 信息层级不确定，先视觉验证更快 多步骤预约 wizard、复杂表单
信息密度很高的页面 需要反复调整布局才能找到最优方案 Dashboard、数据报表页
需要利益相关方确认的页面 先出 mockup 给人看，再开发 客户定制需求
新增/修改设计系统组件 先在 .pen 里定义规范，再同步到 Flutter 新按钮变体、新卡片类型

5. 设计系统现状

文件位置

designs/
└── celoria-design-system.pen    # Pencil 设计系统

组件清单 (65 个 reusable components)

类别数量组件
Button5Primary, Secondary, Outline, Ghost, Destructive
IconButton5同上五种变体
Input4Default, Filled, Focused, Error
InputGroup2Default, Error（含 Label）
Card3Default, Plain, Image
Chip4Default, Selected, Outline, Disabled
Alert4Success, Warning, Error, Info
Badge5Success, Warning, Error, Info, Default
Dialog1标准确认对话框
Avatar2Text, Image
Controls7Divider, Switch×2, Checkbox×2, Radio×2
ProgressBar1线性进度条
Celoria UI14EmailInput, PasswordInput, PinInput, SelectableCard, DateChip, TimeSlotChip, Toast, Loading, EmptyState, ErrorView, SettingsMenuItem, WeekView 等
Extended8AppBar, BottomNavBar, Tabs, ListTile, Snackbar, BottomSheet, Dropdown, SearchBar

Token 变量

6. 与 Flutter 端的关系

Pencil (.pen)                    Flutter
─────────────                    ──────────
celoria-design-system.pen   ←→   packages/celoria_tokens/ (tokens.json)
  Token 变量                       Token 定义
  65 组件规范                       packages/celoria_ui/ (14 组件)
  示例屏幕                         Widgetbook (组件预览)

架构决策

Web 端与 Flutter 端设计系统保持分离。 Pencil 设计系统对齐的是 Flutter 端（celoria_tokens + celoria_ui）。 Web 端继续用 Tailwind CSS 独立维护。这是有意为之，不是遗漏。

7. 日常操作手册

场景 A：新增组件

  1. 在 designs/celoria-design-system.pen 中设计组件（设定尺寸、颜色、状态）
  2. 截图验证 → 满意后在 Flutter 中实现 Widget
  3. Widgetbook 中注册预览

场景 B：修改现有组件

  1. 先改 .pen 中的组件规范
  2. 同步修改 celoria_tokens/tokens.json 或 celoria_ui/ 中的 Widget
  3. Widgetbook 自动更新预览

场景 C：新功能开发（复杂页面）

  1. 写 Spec 文档
  2. （可选）在 Pencil 中拼装关键页面的 mockup，引用设计系统组件
  3. 并行推进：测试 + Flutter 实现
  4. 验收：Widgetbook 截图对比

场景 D：新功能开发（简单页面）

  1. 直接写代码，引用 celoria_ui 组件
  2. 不出设计稿

8. 文件组织规范

designs/
├── celoria-design-system.pen       # 设计系统（组件库 + Token）
├── guest-app/                      # Guest App 按流程组织
│   ├── auth-flow.pen               # 认证流程（登录/注册/忘记密码）
│   └── booking-flow.pen            # 预约流程
├── employee-app/                   # Employee App
│   └── ...
└── kiosk-app/                      # Kiosk App
    └── ...

组织原则