TrueGrowth/openspec/changes/add-stitch-design-workflow/design.md at main

Files

Jammy 3b6781d695 Initial TrueGrowth source import

2026-07-07 09:36:36 +08:00

4.9 KiB

Raw Permalink Blame History

Context

opentu 当前的前端结构以编辑器能力为中心，apps/web/src/app/app.tsx 负责应用初始化、工作区恢复、URL 状态、崩溃恢复、安全模式等应用级装配；packages/drawnix/src/drawnix.tsx 承担核心白板编辑器、工具栏、抽屉、AI 面板、媒体库、项目切换等大量交互能力。

这意味着并不是所有 UI 都适合先进入 Stitch：

编辑器核心区域高度依赖本地状态与插件链
外围页面和面板则更接近典型的“信息架构 + 视觉布局”问题，适合由 Stitch 提供方案探索

如果不先定义边界，Stitch 很容易被误用为“直接产出生产代码”的工具，导致设计稿与业务实现失去可维护性。

Goals / Non-Goals

Goals:
- 为 opentu 建立一条可重复使用的 Stitch 设计闭环
- 让仓库内持久化保存设计系统上下文与 screen 映射
- 优先提升外围页面、抽屉、弹窗、空状态页的设计探索效率
- 保持代码实现为交互逻辑与生产行为的唯一真源
Non-Goals:
- 本次不让 Stitch 直接接管核心白板编辑器 UI
- 本次不把 Stitch 生成的 HTML 直接作为生产代码运行
- 本次不要求一次性覆盖所有前端页面

Decisions

Decision: Stitch 只主导“受边界约束的页面与面板”
- 优先覆盖弹窗、设置面板、项目抽屉、媒体库、空状态页
- 不直接覆盖核心画布、框选、拖拽、缩放、插件联动区域
Decision: 仓库内必须保存 Stitch 设计资产的映射关系
- 通过 .stitch/screens.json 记录 surfaceId -> projectId -> screenId
- 通过 .stitch/DESIGN.md 沉淀视觉系统、品牌语言与 prompt 约束
- 避免 Stitch screen 只存在于外部系统、无法被后续开发和维护复用
Decision: 设计结果进入代码前必须经过“结构转译”
- Stitch screen 的 HTML 与 screenshot 只作为视觉参考和结构蓝本
- 最终组件仍按 React + 现有工程模式手工实现
- 所有状态、事件、服务调用、数据依赖继续留在本地代码
Decision: 首批只跑通一个最小闭环，再逐步扩展
- 先选低风险单元，如 CrashRecoveryDialog
- 跑通完整流程后，再扩展到项目抽屉、设置面板、媒体库等

Proposed Repository Artifacts

.stitch/
  DESIGN.md
  screens.json
  prompts/
    crash-recovery-dialog.md
    project-drawer.md
    settings-panel.md
  downloads/
    <surface-id>/
      screen.json
      screenshot.png
      design.html

Artifact Roles

DESIGN.md
- 项目级视觉系统说明
- 颜色、字体、圆角、阴影、语气、信息密度等约束
- 作为 Stitch prompt 的上下文来源
screens.json
- 每个 surface 的唯一映射
- 示例：

{
  "crash-recovery-dialog": {
    "projectId": "17192920079115887108",
    "screenId": "49b0b7c5283f462d8fafd181b7cbaf5b",
    "entry": "apps/web/src/app/CrashRecoveryDialog.tsx"
  }
}

prompts/*
- 记录每个页面/模块送入 Stitch 的 prompt
- 保证后续编辑与再生成时上下文可追溯
downloads/*
- 保存从 MCP 拉回的 HTML / screenshot / metadata 快照
- 作为编码阶段的参考输入

Workflow

选择一个受边界约束的页面/模块
在 .stitch/prompts/ 中整理 prompt，并结合 .stitch/DESIGN.md
使用 Stitch 生成或编辑 screen
将 projectId / screenId 固化到 .stitch/screens.json
通过 Stitch MCP 拉取 get_screen、设计系统与截图
按仓库规范将结果实现为 React 组件
完成后回写下载快照与必要的设计说明

Initial Candidate Surfaces

apps/web/src/app/CrashRecoveryDialog.tsx
- 优势：边界清晰、交互简单、适合先跑闭环
packages/drawnix/src/components/project-drawer/*
- 优势：信息层级明确，适合 Stitch 做布局与信息架构
packages/drawnix/src/components/settings-dialog/*
- 优势：表单和分组较多，适合先做视觉系统统一
packages/drawnix/src/components/media-library/*
- 优势：典型内容浏览 UI，适合做卡片、筛选、空状态设计

Risks / Trade-offs

风险: 团队把 Stitch 结果误当成最终代码
- Mitigation: 在 spec 中明确“结构参考，不是生产代码”
风险: screen 映射与代码实现脱节
- Mitigation: 每个 surface 必须在 .stitch/screens.json 中绑定入口文件
风险: 过早接入复杂编辑器区域，增加返工成本
- Mitigation: 首批只选低风险外围页面
风险: 外部 Stitch 项目变动无法追溯
- Mitigation: 在仓库中保存 prompt、screen 映射和下载快照

Open Questions

.stitch/screens.json 是否需要加入 status 字段，如 concept / approved / implemented
下载快照是统一提交进仓库，还是仅作为本地辅助资产
首批试点是否只选一个页面，还是并行推进多个低风险面板

4.9 KiB Raw Permalink Blame History Unescape Escape