@namewta/speculo 0.8.6 → 0.8.8

package/template/workflows/specdev/O-orchestrate-implementation/execution-loop.md

@@ -0,0 +1,30 @@
+# Continuous Implementation Loop
+
+## 每轮固定顺序
+
+1. 重读父 status、Map、Plan、成员 status/Tickets 和 repository；
+2. 校验 Map revision、Plan source revision、Lead epoch、授权、active dispatch、workspace 与 integration queue；
+3. 重建 super-DAG 并计算 ready frontier；
+4. 根据 current/required 策略选择本轮节点；
+5. 为每个节点形成不可变 Dispatch Packet，task ID 使用组合身份；
+6. 调用 I-implement 完成设计检查、TDD、commit、双轴审查、验证和 Evidence；
+7. Lead 独立验收返回事实并按 repository/ref 串行集成；
+8. 先写子 Ticket/Map/Evidence/change status，再写父 Plan 进度；
+9. 重读实际 Git 和全部受影响工件，运行 validator；
+10. 有 frontier 则继续，无 frontier 则完成或持久化 blocker。
+
+## 唯一写入者
+
+父 Lead 是全部 SpecDev 工件、E2E、integration queue 和父分支推进的唯一 owner。Implementation agent 在 current 模式写唯一当前 workspace，或在 required 模式写绑定 Ticket 的 source worktree；不得写父/子状态、Evidence、其他成员或父分支。
+
+## 自动继续边界
+
+子 Ticket 正常完成、candidate stale 后可机械重建、已批准的局部实现修正和下一 frontier 选择不再次询问用户。以下情况停止：
+
+- 高影响合同、范围、架构、数据、安全、迁移或验收需要新决定；
+- implementation commit、integration 或不可逆动作缺少授权；
+- dependency/serialization/path owner 无法由权威事实裁决；
+- 连续集成尝试达到父 Plan 上限；
+- 无合法 frontier 但仍有非终态 Ticket。
+
+停止时父 Plan 保存最后 accepted 节点、active/stale dispatch、Git checkpoint、blocker、owner、下一合法动作和恢复重读清单。

package/template/workflows/specdev/O-orchestrate-implementation/implementation-evidence-template.md

@@ -0,0 +1,39 @@
+# Implementation Orchestration Evidence
+
+## 1. Parent Plan and Final Revision
+
+- Parent change:
+- Final Implementation Map revision:
+- Workspace/integration strategy:
+- Lead and epoch:
+
+## 2. Member and Ticket Completion
+
+| Change | Composite Tickets | Final status | Child Evidence | Final Git result |
+|---|---|---|---|---|
+
+## 3. Dependency and Serialization Audit
+
+| Edge or pair | Required order/lock | Observed execution | Evidence |
+|---|---|---|---|
+
+## 4. Repository Integration Audit
+
+| Repository/ref | Ordered results | Stale candidates | Final checkpoint | Evidence |
+|---|---|---|---|---|
+
+## 5. Aggregate Verification
+
+| Command/check | Environment | Exit/result | Evidence |
+|---|---|---|---|
+
+## 6. Contract, Drift and Deviation Audit
+
+- Cross-change contracts:
+- Map/child drift disposition:
+- Deviations/blockers:
+
+## 7. Residual Risk and Boundary
+
+- Residual risk:
+- Not performed: archive, push, PR, remote merge, deploy, production migration unless separately authorized.

package/template/workflows/specdev/O-orchestrate-implementation/implementation-map-template.md

@@ -0,0 +1,50 @@
+---
+schema_version: 1
+artifact: implementation-map
+change: <YYYY-MM-DD-parent-topic>
+status: ready
+revision: 1
+members: [<child-change-a>, <child-change-b>]
+tasks: [<child-change-a>::T-01, <child-change-b>::T-01]
+dependencies: []
+serializations: []
+---
+
+# Implementation Map: <Outcome>
+
+## 1. Members and Source Authority
+
+| Change | Spec | Tickets Map | Change status | Role |
+|---|---|---|---|---|
+| `<child-change-a>` | ready | ready | active | delivery |
+| `<child-change-b>` | ready | ready | active | delivery |
+
+## 2. Composite Ticket Inventory
+
+| Composite ID | Child Ticket | Status | Ready | Writable/shared summary | Contracts |
+|---|---|---|---|---|---|
+| `<child-change-a>::T-01` | T-01 | ready | yes | pending | pending |
+| `<child-change-b>::T-01` | T-01 | ready | yes | pending | pending |
+
+## 3. Implementation Super-DAG
+
+| Edge | Kind | Source and reason | Start Gate | Evidence |
+|---|---|---|---|---|
+| none | none | independent until proven otherwise | n/a | n/a |
+
+## 4. Conflict and Serialization
+
+| Pair | Resource or overlap | Owner | Release condition |
+|---|---|---|---|
+| none | none observed | n/a | n/a |
+
+## 5. Contract and Path Coverage
+
+| Contract/shared surface | Producer task | Consumer tasks | Ordering/lock | Verification |
+|---|---|---|---|---|
+
+## 6. Revision Log
+
+| Revision | Source change | Affected tasks/edges | Reason |
+|---|---|---|---|
+| 1 | initial Ready inputs | all | parent creation |

package/template/workflows/specdev/O-orchestrate-implementation/implementation-plan-template.md

@@ -0,0 +1,61 @@
+---
+schema_version: 1
+artifact: implementation-plan
+change: <YYYY-MM-DD-parent-topic>
+status: ready
+source_map_revision: 1
+orchestration: lead-directed
+lead: <owner-or-session-locator>
+implementation_agent_limit: 3
+integration_attempt_limit: 3
+ticket_workspace_policy: current
+integration_gate: direct-parent
+ready_for_execution: true
+---
+
+# Implementation Plan: <Outcome>
+
+## 1. Outcome and Authority
+
+- Outcome: <aggregate implementation outcome>
+- Lead: <recoverable owner/session locator>
+- False completion: <what must not be called done>
+- Authority: child Spec/Tickets for behavior and implementation; parent Map/Plan for cross-change execution only.
+
+## 2. Ready Frontier and Waves
+
+| Wave | Composite tasks | Dependency Gate | Serialization/resource Gate | Status |
+|---|---|---|---|---|
+| 1 | pending | dependencies satisfied | locks available | ready |
+
+## 3. Workspace and Dispatch Contract
+
+- Ticket workspace policy: current / required.
+- Dispatch IDs use `<member-change>::<ticket-id>`.
+- The implementation agent limit is global across all members; the Lead is not counted.
+- Read-only review/research/test-observation agents do not consume the implementation limit.
+
+## 4. Repository Integration Queue
+
+| Repository/ref | Ordered composite tasks | Current parent checkpoint | Active candidate | Owner |
+|---|---|---|---|---|
+| current repository/current ref | pending | pending-read | none | Lead |
+
+## 5. Gates and Aggregate Verification
+
+| Gate | Required tasks | Verification | Evidence | Status |
+|---|---|---|---|---|
+| child completion | all child Tickets | child completion contract | child Evidence | pending |
+| aggregate | all members completed | full suite and applicable E2E | parent Evidence | pending |
+
+## 6. Conflict, Drift and Recovery
+
+- Re-read Map revision, Lead epoch, child Tickets, Git HEAD, active dispatches and locks before every action.
+- Any parent advance makes older candidates stale and requires reconstruction.
+- On pause, persist last accepted task, stale candidates, blockers, next legal task and required reads.
+
+## 7. Progress and Decisions
+
+| Time | Composite task | Dispatch/result | Child Evidence | Parent checkpoint | Next recomputation |
+|---|---|---|---|---|---|
+| pending | none | not started | none | pending-read | compute frontier |

package/template/workflows/specdev/O-orchestrate-implementation/input-readiness.md

@@ -0,0 +1,25 @@
+# Implementation Input Readiness
+
+## 创建前硬门
+
+对每个用户指定成员穷尽检查：
+
+1. change 位于 active namespace，状态不是 archived，且没有另一个未完成父实现 owner；
+2. Ready Spec 使用当前 schema，`status: ready` 且 `ready_for_tickets: true`；
+3. Tickets Map 使用当前 schema，状态为 ready、in_progress 或 completed；
+4. Ticket 目录非空，Ticket ID/文件名唯一，全部内部 dependency 可解析且无环；
+5. 每个非终态 Ticket 决策完备、`ready: true`、路径/验证/验收完整，状态为 ready；
+6. done Ticket 有 Evidence 与完成 workspace 记录，cancelled Ticket 有权威理由；
+7. Spec 合同全部 covered 或有用户批准的 deferred；
+8. 没有未裁决的行为、接口、数据、兼容、安全、范围、迁移或验收问题；
+9. 当前代码与 Ticket 的入口、路径和验证接缝没有已知漂移。
+
+任一成员失败时，返回按 change 分组的缺口和真正 owning Work，不创建父目录、全局 active entry、Map 或 Plan。父 Work 不调用这些 owning Works。
+
+## 恢复状态
+
+父 change 创建后，Ticket 可以进入 in_progress、review、done、cancelled，或因执行事实进入 blocked/deviated。blocked/deviated 必须让父 Plan 同步为 blocked 并记录恢复 owner；这不是放宽创建前 Ready 门。
+
+## 已完成成员
+
+全部 Ticket 已 done/cancelled 且 change 已 completed 的成员可以作为 satisfied baseline，参与 dependency 判断但不进入 frontier或占用 agent 配额。用户只选择已完成成员且没有待实现 Ticket 时停止，因为不存在实现编排目标。

package/template/workflows/specdev/O-orchestrate-implementation/super-dag.md

@@ -0,0 +1,27 @@
+# Implementation Super-DAG
+
+## 组合身份
+
+每个节点使用 `<member-change>::<ticket-id>`。父 Map 的 `tasks` 必须与所有成员 Ticket 一一对应，包括已经 done/cancelled 的节点；不得用标题、文件名或局部 Ticket ID 代替组合身份。
+
+## Dependency
+
+- 子 change 内部 dependency 从 Ticket `blocked_by` 精确提升，不得遗漏或改序；
+- 跨 change dependency 只表达后置 Ticket 实际消费前置 Ticket 的合同、代码、迁移或产物；
+- 格式为 `dependent <- prerequisite`；端点必须存在；自依赖、重复边和循环阻塞 Ready。
+
+## Serialization
+
+serialization 格式为 `task-a <> task-b`，只表示两个无语义依赖的 Ticket 因 writable/shared path、repository/ref、环境、迁移窗口或唯一资源不能同时执行。无方向重复 pair 非法。
+
+依赖与串行不能互相冒充。Map 正文必须记录跨 change 边或 serialization 的事实来源、owner、开始 Gate 和解除证据。
+
+## Frontier 与 Wave
+
+节点只有在所有 prerequisite done/cancelled、子 Ticket Ready、无 blocker/deviation、serialization lock 可用、workspace/授权有效且 agent 配额可用时进入 frontier。
+
+current 策略每个 Wave 只能含一个节点。required 策略可以放入多个节点，但任意两节点必须不存在传递依赖、serialization、writable/shared overlap 或同一不可并发资源。
+
+## 漂移
+
+每轮从子 Ticket 重新构建预期 task set 和内部 edges。与父 Map 不一致时停止派单、递增 revision、更新 Map 与 Plan，再重新计算；不能用旧投影覆盖子权威。

package/template/workflows/specdev/P-goal-plan/planning-modes.md

@@ -10,7 +10,7 @@
 - Tickets Map 与全部 Ticket 存在、Ready、DAG 无环；
 - 每个验收合同被 Ticket 覆盖；
 - writable/shared path 有唯一 owner，Wave 候选无写冲突；
-- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；原型变体范围读取 planning 配置；
+- config schema v5，`max_implementation_agents` 与 `max_integration_attempts` 为正整数；UI 设计候选范围读取 planning 配置；
 - 父分支可定位，implementation commit 与本地 integration 已获授权；
 - Deep Ticket 的迁移、兼容、监控、恢复和不可逆批准点完整。
 - Ticket 与 `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`、`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`、`<Path>{roots.state}/specdev/adr/</Path>`、`<Path>{roots.state}/specdev/context/</Path>` 和当前代码事实不存在未处理冲突；

package/template/workflows/specdev/P-prototype/P-prototype.md

@@ -2,47 +2,51 @@
 id: specdev/prototype
 type: workflow-entry
 workflow: specdev
-name: 原型
-description: 在获授权的临时 branch/worktree 中构建一次性 Logic 或 UI 原型，回答一个明确设计问题并持久化答案、资产定位和清理状态。
-keywords: [prototype, 原型, logic, UI, variant, 一次性代码, 设计问题]
+name: UI 设计原型
+description: 检测现有项目的 UI 事实，按产品任务推荐并逐步选择设计风格，生成持久化设计系统文档、多风格 HTML 对照和可运行 HTML/CSS/JS 原型。
+keywords: [prototype, UI 原型, 风格检测, 设计系统, HTML, CSS, 交互, design tokens]
 ---
 
-# 原型
+# UI 设计原型
 
 > 激活本 Work 后，先读取 `<Path>{roots.workflows}/specdev/README.md</Path>`，再执行本入口。
 
-原型是**回答一个问题的一次性代码**。P 不交付生产实现，也不把原型代码提升到 main；它把答案和一手资料 locator 交给后续 G/S/Tickets/I。
+本 Work 的主导词是**设计定向**：先从项目事实识别现状，再让用户看到基于功能而非流行色推荐的候选，最后把选择固化为既可阅读又可运行的 UI 设计包。P 不修改生产 UI；后续 S、Tickets 和 I 以设计包为视觉与交互权威。
 
 ## 输入与所有权
 
-- 一个可精确陈述的问题，来自用户、G、Spec 或 `<Path>{roots.state}/specdev/changes/{change}/investigation/{investigation-id}.md</Path>`；
-- 相关代码、组件系统、领域上下文和 ADR；
-- 获授权的项目可写范围及临时 branch/worktree。
+- 必需输入：目标项目或新产品设想、核心用户任务，以及当前 SpecDev change。
+- 可选输入：现有代码、页面、截图、设计 token、品牌约束、ADR、Spec、调查和用户明确给出的参考产品。
+- 项目事实权威：依赖清单、样式源码、组件实现、路由、真实页面、测试和可复现截图；仅凭依赖名称不得断言实际风格。
+- 用户决定权威：产品方向、候选风格、密度、色调、字体气质、圆角、交互反馈和跨端优先级。
 
-P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{prototype-id}/record.md</Path>`。代码写在临时 workspace 的项目路径附近；state 只保存项目相对 Path、branch、commit 和可迁移 `workspace_ref`。
+P 拥有 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/</Path>`。其中 `design-id` 使用当前 change 内最小未占用的 `UI-NNN`；目录中的设计系统主文档是唯一设计权威，comparison 和 final 文件均由它或其中已记录的候选决定派生。P 不写永久 research namespace，不创建 branch/worktree，不提交生产代码。
 
 ## 流程
 
-1. **锁定问题**：一个 record 只回答一个问题。业务逻辑、状态转换或数据形态使用 Logic；页面外观、信息层级或交互布局使用 UI。问题含糊且用户不在线时按周围代码选择，并在 record 写明假设。
-2. **建立临时工作区**：按 `<Path>{roots.workflows}/specdev/common/skills/dev-worktree/SKILL.md</Path>` 创建/恢复工作区。创建 branch、commit 或删除 worktree 分别遵守现有授权边界；路径名明确包含 prototype。
-3. **执行分支**：Logic 加载 `<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`；UI 加载 `<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`。两个分支都把完整状态呈现给评审者，不依赖生产数据写入。
-4. **捕获答案**：使用 `<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>` 记录问题、运行方法、资产、验证反馈、赢家/拒绝项、结论、promotion target 和清理状态，原子重读。
-5. **关闭或阻塞**：答案已确认时 `status: answered`；用户选择不继续时 `discarded`；原型无法回答问题时 `blocked` 并说明缺失输入。Wayfinder 调用时，把 record/branch/URL 写入当前 Ticket 的 solution comment，并只关闭该 Ticket。
-6. **验证与路由**：使用 `<Path>{roots.workflows}/specdev/common/tools/validate-specdev.mjs</Path>` 的 `--stage prototype` 校验当前 change。需要产品决定返回 G，需要外部行为合同返回 S，需要执行计划返回 Tickets；生产实现只进入 I。
+1. **创建或恢复设计包**：读取 change 与 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`。不存在时从 `<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>` 创建，写入 `status: detecting` 并原子重读；存在时只询问尚未确认的高影响选择。
+2. **检测现有风格**：加载 `<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，穷尽技术栈、布局、视觉 token、组件状态、响应式与可访问性证据。新项目明确记录 `project_kind: new`，不伪造检测结果。
+3. **建立功能候选**：读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，依据产品任务、平台和信息密度从八种风格及六种布局中推荐 2-4 个候选。每个候选写明适合原因、需要保留/调整/替换的现有事实、参考项目和迁移成本。
+4. **逐项选择并持久化**：加载 `<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`。每轮只处理一个决策层；每个答案立即写回设计系统主文档并重读。高影响偏好未确认时保持 `status: selecting`，不得自行标记 Ready。
+5. **生成可视对照与最终原型**：加载 `<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`。为每个候选生成独立 comparison variant，再生成 comparison 索引。用户确认或明确组合后，把最终 HTML/CSS/JS 作为具名代码块写入设计系统主文档，再物化到 final 目录。
+6. **验证并封板**：运行 `<Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> --check` 和 `<Path>{roots.workflows}/specdev/P-prototype/tools/validate-design-package.mjs</Path>`；随后运行 SpecDev `--stage prototype`。全部通过且选择闭合后设置 `status: ready`，更新 `works_run` 并清空 `current_work`。缺少项目事实或用户决定时设置 `blocked` 并保留恢复位置。
+7. **返回路由**：返回设计包、comparison 和 final 的完整路径、验证命令与结果、未决问题和下一 Work。需要补足产品决定时返回 G；需要写外部行为合同返回 S；需要拆实施工作返回 Tickets；已有 Ready Ticket 才返回 I。Wayfinder 调用时只把设计包与 comparison locator 写入对应 solution comment。
 
 ## 完成标准
 
-- 只有一个问题和一个正确分支；
-- 原型极易运行，完整状态可见；
-- 临时 branch/worktree 与项目路径可恢复且不含机器绝对路径；
-- 原型没有测试、生产数据库依赖或伪装成生产代码；
-- 答案、资产、赢家、拒绝项、promotion target 和清理状态完整；
-- main 不保留落选变体、switcher 或原型外壳；
-- Wayfinder Ticket、solution comment 与 prototype record 可互相定位。
+- 现有项目的检测结论逐项有项目相对证据；新项目明确没有既有风格。
+- 候选由功能、平台和密度推导，不只更换颜色；用户已看到每个候选的独立 HTML。
+- 设计系统主文档完整包含 UI 结构、CSS token、交互 JS 和最终 HTML 源码，并记录研究出处与拒绝理由。
+- comparison 索引可导航到 2-4 个候选，final HTML 可离线运行；桌面与移动宽度不存在空白、遮挡或无意横向溢出。
+- 字体、间距、圆角、色彩、层级、控件状态、异步反馈、响应式、键盘、focus 和 reduced motion 均有明确合同。
+- Markdown 代码块与 `final/` 文件逐字一致，schema、局部校验和 SpecDev stage 校验全部通过。
+- 设计包不包含机器绝对路径、敏感值、生产数据写入、发布动作或未授权的生产实现。
 
 ## 子文件引用
 
-- Logic：`<Path>{roots.workflows}/specdev/P-prototype/logic-prototype.md</Path>`
-- UI：`<Path>{roots.workflows}/specdev/P-prototype/ui-prototype.md</Path>`
-- Record：`<Path>{roots.workflows}/specdev/P-prototype/prototype-record-template.md</Path>`
-- Schema：`<Path>{roots.workflows}/specdev/common/schemas/prototype-record.schema.json</Path>`
+- 检测：`<Path>{roots.workflows}/specdev/P-prototype/detect-existing-style.md</Path>`，仅在步骤 2 加载。
+- 选择：`<Path>{roots.workflows}/specdev/P-prototype/style-selection-protocol.md</Path>`，仅在步骤 4 加载。
+- 生成：`<Path>{roots.workflows}/specdev/P-prototype/generate-design-package.md</Path>`，仅在步骤 5 加载。
+- 模板：`<Path>{roots.workflows}/specdev/P-prototype/design-system-template.md</Path>`，创建设计包时加载。
+- 设计库：`<Path>{roots.workflows}/specdev/P-prototype/design-library/INDEX.md</Path>`，建立候选或查具体规则时渐进读取。
+- Schema：`<Path>{roots.workflows}/specdev/P-prototype/design-package.schema.json</Path>`。

package/template/workflows/specdev/P-prototype/design-library/INDEX.md

@@ -0,0 +1,43 @@
+# P-prototype 设计库
+
+本目录是 P-prototype 的静态设计参考层。它帮助 UI 原型先按任务、对象、密度和平台选择结构，再选择视觉表达；它不拥有运行时状态，不替代项目现有设计系统，也不授权修改生产代码。
+
+研究快照固定在 commit `49b565913c52f4867456e609696625157f19b930`。快照是证据与可运行样板，不在原型过程中原地修改；需要复用时，把所需 HTML/CSS/JS/图片和 attribution 复制到当前 change 的设计包。
+
+## 渐进披露入口
+
+| 当前问题 | 读取 | 读完应得到 |
+|---|---|---|
+| 先决定信息架构、密度和组件边界 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/foundations.md</Path>` | 一个主布局范式、密度档和设计系统边界 |
+| 在八种可运行风格中选择起点 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/style-index.md</Path>` | 一个主风格、必要时一个受控对照风格 |
+| 寻找相似产品及其真实模式 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/product-pattern-index.md</Path>` | 对应项目、可借鉴模式和一手研究路径 |
+| 定义浅色/深色、语义 token、字号与层级 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/color-and-theme.md</Path>` | 可实现的主题与密度假设 |
+| 设计导航、表格、表单、反馈或危险操作 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/interaction-patterns.md</Path>` | 完整状态和验证动作 |
+| 需要窄屏、触屏、桌面/Web/移动重排 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/responsive-and-platforms.md</Path>` | 每个平台的任务职责和断点行为 |
+| 需要引用、复制资产或判断证据强度/许可 | `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-provenance.md</Path>` | 可追溯来源、复用边界和 attribution |
+
+## 使用顺序
+
+1. 检测现有项目或明确新产品设想，并列出核心对象、最常见的 3-5 个任务、目标输入设备和最坏数据状态。
+2. 读取 foundations，选择一个主布局范式。不要先按品牌色、圆角或流行风格选择页面。
+3. 读取 style-index，按功能推荐 2-4 个结构不同的候选，并为每个候选生成独立 comparison HTML。
+4. 读取 product-pattern-index，只深入与当前对象、任务或平台相似的项目研究；星标不构成设计质量或许可结论。
+5. 只加载当前问题涉及的 theme、interaction 或 responsive 文件。精确值必须能回到 snapshot 中的 token、CSS 或研究证据。
+6. 复制样板时保留相对目录关系和所需 attribution；把 demo 名称、权限、Git、同步与审批状态替换为原型自己的假数据，不把演示逻辑当作真实业务逻辑。
+7. 用真实极端数据、键盘、目标宽度和浅/深主题验证。选择、拒绝理由和最终源码进入设计系统主文档，设计库本身保持不变。
+
+## 快照入口
+
+- 总报告：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/report/OPEN_SOURCE_UI_RESEARCH_2026.md</Path>`
+- 八种风格总览：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/index.html</Path>`
+- 样板使用说明：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/README.md</Path>`
+- 结构化项目数据：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/projects.json</Path>` 与 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/data/extended-projects.json</Path>`
+- 综合 token：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>`
+
+## 完成门
+
+- 选择理由落在任务模型、信息密度、输入设备和状态复杂度，而不是“看起来像”；
+- 一个布局范式和一个主风格已明确，所有新增 token 都有语义角色；
+- loading、empty、no-results、error、offline、read-only、permission 与长文本按适用性逐项处理；
+- 窄屏改变任务流而非压缩桌面多栏；
+- 引用与复制均可回到固定 commit、研究文件和 attribution。

package/template/workflows/specdev/P-prototype/design-library/color-and-theme.md

@@ -0,0 +1,65 @@
+# 色彩、主题与视觉层级
+
+视觉系统先定义角色，再选择色值。固定快照中的 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/design-tokens.css</Path>` 是跨项目综合起点，不是任何单一产品的 token 复制品。
+
+## 最小语义集合
+
+```text
+canvas
+surface-1 / surface-2 / surface-3 / overlay
+text-primary / text-secondary / text-tertiary / text-disabled
+border-subtle / border-default / border-strong
+accent / accent-hover / accent-subtle / accent-contrast
+success / warning / danger / info (+ subtle variants)
+hover / selected / pressed / focus-ring / scrim
+```
+
+业务组件消费语义角色，不直接写 `#fff`、`black` 或任意透明度。品牌 accent 只服务主要动作、选中和链接；状态色必须同时配图标、文本或形状。数据可视化色板、Git diff、syntax highlight 和业务状态分别建组，不复用 UI accent 充当所有含义。
+
+## 浅色与深色
+
+- 两种主题一起设计，不把深色简单反相。深色 overlay 往往比基础表面更亮，边框和语义色需要重新分配明度与对比。
+- 分别检查正文、次要文字、图标、边框、focus ring 和状态，而不只检查按钮。
+- 中性色保持低 chroma，避免所有表面都带强品牌倾向。
+- 用户切换主题时保持布局、选择、输入和面板尺寸；主题改变不应触发内容重排。
+- 高对比需求不能只靠增加饱和度，应重新检查边界、文字与焦点。
+
+## 字体和密度
+
+| 角色 | 字号/行高起点 |
+|---|---|
+| 坐标、元数据、辅助标签 | 11-12px / 16px；不承载长文本、错误原因或主要操作 |
+| 表格、侧栏、紧凑控件 | 13px / 18-20px |
+| 默认 UI 正文与表单 | 14px / 20px |
+| 内容正文 | 15-16px / 24-26px |
+| 小节/弹窗标题 | 16-18px / 22-26px |
+| 页面标题 | 20-24px / 28-32px |
+
+工具界面不使用营销页级大标题。数字表格可启用 tabular numerals，代码/SQL/ID 使用 mono；中英文混排单独验证 CJK 回退和行高。不使用负字距挤压 UI，长名称通过布局、换行或中间截断处理。
+
+| 密度 | 控件高度 | 表格行高 | 典型任务 |
+|---|---:|---:|---|
+| Compact | 28px | 32px | SQL、日志、开发工具 |
+| Default | 32-36px | 36-40px | CRM、项目管理、后台 |
+| Comfortable | 40px | 44-48px | 文档、协作、低频表单 |
+| Touch | 44-48px | 48-52px | 移动与触屏 |
+
+## 圆角、边框与阴影
+
+- 2-4px：代码块、表格小元素、密集工具按钮。
+- 4-6px：输入、按钮、菜单项、紧凑面板。
+- 6-8px：普通卡片、popover、较大控件。
+- 8-12px：dialog、sheet、移动大容器；移动样板可因触屏语言使用更大值。
+- pill：状态徽标、分段选择滑块或真正胶囊语义，不用于所有按钮。
+
+同一视觉层只保留 2-3 个主圆角。常驻页面分区、侧栏、表格和检查器用 1px 边框或背景差建立层级，不用浮卡阴影；popover/menu 使用清晰边框和中等阴影；dialog 使用 scrim 与较大阴影；focus ring 独立于层级阴影。hover、selected、pressed 必须是不同 token。
+
+## 原型验证
+
+- 浅色、深色、200% 缩放和常见色觉差异下，文本与状态仍可区分；
+- 页面没有绕过 token 的随机颜色、圆角和阴影；
+- 状态不只依赖颜色；
+- 最长名称、中文、数字和错误文案不会撑坏控件；
+- reduced motion 时 token 中的 UI duration 降为零或对应交互停止非必要动画。
+
+八种具体 `.theme-*` 实现在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/styles/pages.css</Path>`，综合 token 的使用约束在 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/reference/USAGE.md</Path>`。

package/template/workflows/specdev/P-prototype/design-library/foundations.md

@@ -0,0 +1,66 @@
+# 设计基础与六种布局
+
+先按任务模型选择布局，再决定视觉风格。以下结论来自固定研究快照的综合报告；尺寸是原型起点，不是脱离目标用户的硬规范。
+
+## 决策顺序
+
+1. 定义核心对象，以及用户最常做的 3-5 个任务。
+2. 定义对象层级、可恢复 URL、权限和状态模型。
+3. 从六种布局中选择一个主范式，并画出空、错、加载、只读和无权限状态。
+4. 根据任务时长、信息密度和输入设备选择密度档，再定字号、控件高度和面板宽度。
+5. 同时建立浅色与深色的语义 token。
+6. 先建立 primitives，再建立高频 patterns，最后组合页面。
+7. 用真实极端数据、键盘和目标宽度验证。
+
+## 六种高价值布局范式
+
+| 范式 | 适用任务 | 结构与不可丢失的行为 | 代表项目 |
+|---|---|---|---|
+| 全局侧栏 + 页面内容 | 项目管理、CRM、设置、普通后台 | 全局栏只放跨页面稳定对象，页面动作靠近内容头；二级项超过约 5-7 个再引入上下文栏；折叠后保留 tooltip、选中态和持久化状态 | Plane、Twenty、Cal.com |
+| 图标轨 + 上下文侧栏 | 多产品模块、组织或工作区平台 | 图标轨回答“在哪个产品/工作区”，上下文栏回答“范围内有哪些对象”；两层不重复菜单；移动端通常合并为一层 drawer | Supabase Studio、Directus、Mattermost、Paseo |
+| 列表-详情主从 | 客服、邮件、任务、对象浏览、数据库表 | 选择与 URL 同步，宽度可恢复；处理未保存修改、键盘上下移动、空选择、删除落点；窄屏提供列表与详情的明确返回路径 | Chatwoot、Twenty、Open WebUI、CloudCLI |
+| 编辑器/画布 + 检查器 | 设计、白板、SQL、API、低代码 | 主创作面无装饰卡框；工具区和检查器可折叠/调整；快捷键、选择、撤销、缩放和平移属于统一交互模型 | Penpot、Excalidraw、Appsmith、DBX、Hoppscotch |
+| 仪表盘网格 | BI、可观测性、运营概览 | 稳定列系统、拖放手柄、组件最小/最大尺寸；区分编辑/查看；每个 panel 独立呈现无数据、加载和错误 | Grafana、Metabase |
+| 内容中心/文档编辑器 | 知识库、文档、长内容 | 正文限制行长，资源树、目录和评论独立占栏；工具随选择出现；自动保存安静但可确认；低频动作进入斜杠命令或命令面板 | Outline、AFFiNE、AppFlowy、Notesnook、Joplin |
+
+一个原型可以在局部嵌套第二范式，例如“全局侧栏 + 页面内容”中的仪表盘，但必须明确哪个是 shell、哪个只服务当前页面；不要让两套导航或两个检查器竞争同一职责。
+
+## 基础尺度
+
+| 项目 | 建议起点 |
+|---|---|
+| 全局图标轨 | 48-56px |
+| 展开侧栏 | 224-272px |
+| 顶栏 | 44-56px |
+| 右侧检查器 | 288-360px，可调整 |
+| 阅读/表单宽度 | 720-960px |
+| 宽应用内容 | 最多约 1280-1440px；表格、画布、日志和仪表盘使用可用宽度 |
+| 紧凑/默认/触屏控件 | 28-32px / 32-36px / 44-48px |
+| 常用图标 | 14 / 16 / 20px |
+| 主圆角 | 4 / 6 / 8px；更大值留给 dialog、sheet 与触屏容器 |
+
+采用 4px 间距基准，2px 只做视觉校正。图标与文字通常间隔 6-8px，相邻字段 12-16px，表单分组 24-32px，页面区块 32-48px。不要仅靠缩小字体提高密度；先去掉重复标签、合并工具栏并使用渐进披露。
+
+## 工程边界
+
+原型应保持四层逻辑边界，即使暂时没有拆成发布包：
+
+```text
+tokens/       raw scale + semantic roles + themes
+primitives/   button, input, dialog, menu, tooltip
+patterns/     table, filter bar, command palette, inspector
+domain/       注入业务数据、文案、权限与动作
+```
+
+`primitives` 不依赖业务；`patterns` 组合原语但不拥有页面数据；业务层不得绕过 token 散落任意颜色、圆角和阴影。组件库需要薄封装，以固定默认密度、焦点、圆角和 API。
+
+## 原型检查
+
+- 用户能在 5 秒内判断当前位置、作用域和主要动作；
+- 全局、上下文与对象内导航没有重复职责；
+- 画布、表格、正文或消息流是第一视觉信号，而不是装饰卡片；
+- 最长名称、中文、数字、空值和错误文案不会重叠或改变稳定布局；
+- token、primitive、pattern 与领域组件边界可说清；
+- 选择的布局在窄屏有任务重排方案。
+
+更完整的原始论证见 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/report/OPEN_SOURCE_UI_RESEARCH_2026.md</Path>` 第 6-7、11-13 节。

package/template/workflows/specdev/P-prototype/design-library/interaction-patterns.md

@@ -0,0 +1,61 @@
+# 交互模式
+
+原型要呈现完整状态和可恢复行为，而不只展示静态 happy path。以下模式按工具型产品的高频任务组织。
+
+## 导航与状态保持
+
+- shell 在路由切换时保持挂载，侧栏滚动、展开组、面板宽度、筛选和编辑上下文不意外丢失。
+- 选中态同时使用背景、文字/图标对比和位置线索；breadcrumb 只表达层级，不替代明确返回动作。
+- 深层对象提供可复制 URL；刷新后尽量恢复选择、筛选和视图。
+- 列表-详情必须定义空选择、删除当前对象后的落点、未保存修改处理和窄屏返回路径。
+
+## 搜索、命令与快捷键
+
+命令面板服务跨模块跳转、低频动作和主题/设置切换；当前列表的局部搜索仍放在对象附近。命令项包含分组、最近使用、键盘导航、不可用原因和快捷键提示。不要把所有能力藏进 `Cmd/Ctrl+K`。
+
+## 数据表格与网格
+
+按原型问题逐项决定并呈现：
+
+- 列显示/隐藏、排序、筛选、调整宽度和固定列；
+- 行选择与批量动作，批量工具条只在有选择时出现；
+- 虚拟滚动和键盘导航，编辑态不因滚动丢失；
+- 空值、布尔、长文本、代码、日期、时区和大数字格式；
+- loading、无数据、无结果、局部错误和无权限分别建模；
+- 危险写操作展示预览、影响范围、只读或事务提示。
+
+## 表单与保存
+
+- 创建流程有明确主要动作和取消路径；提交后错误与字段程序化关联并可快速定位。
+- 设置页选择“显式保存”或“可靠自动保存 + 可见状态”，不混用而不说明。
+- 长表单按领域分组，标签位置一致；帮助文字解释决策，不重复标签。
+- 危险设置独立成区；只有高损失、不可逆操作才要求输入对象名确认。
+
+## 异步反馈
+
+| 时长 | 反馈 |
+|---|---|
+| 约 100ms 内 | 通常不显示 loading，避免闪烁 |
+| 约 100ms-1s | 按钮局部进度或轻量 skeleton |
+| 1s 以上 | 持续进度、取消能力或后台任务入口 |
+
+Toast 只承载非阻塞确认，不承载必须阅读的错误修复步骤。错误说明发生了什么、影响什么、下一步是什么，并保留用户输入。离线、只读和权限不足不是通用 error 的文案变体，应各有可行动状态。
+
+## 危险操作与撤销
+
+能撤销时优先“执行后短时撤销”；真正不可逆或影响范围不明显时才用 confirmation dialog。按钮写具体动作和范围，例如“删除 12 条记录”，不用“确定”。审批流程同时呈现请求对象、能力边界、允许范围、拒绝路径和可见结果。
+
+## 画布、编辑器与可调面板
+
+- 选择、撤销、缩放、平移和快捷键由统一模型管理；上下文工具随选择出现。
+- 可调 panel 有最小/最大尺寸、键盘或替代控制、持久化和重置路径。
+- 画布型产品为核心对象和操作提供非纯画布的可访问替代路径。
+- 代码/diff/terminal/preview 的 tabs 或 panes 保持稳定尺寸，loading、长标签和状态图标不引起布局跳动。
+
+## 完整组件状态
+
+Button、IconButton、Link、Input、Textarea、Select/Combobox、Checkbox、Radio、Switch、Tooltip、Menu、Popover、Dialog、Drawer/Sheet、Tabs、Toast、InlineAlert、Skeleton 和 EmptyState 至少覆盖适用的 `default / hover / pressed / focus / disabled / loading / error / selected`。工具产品再按问题补 AppShell、Sidebar、CommandPalette、DataTable、FilterBar、ResizablePanel、Inspector、Tree、CodeEditor wrapper 和 PermissionGate。
+
+## 样板验证证据
+
+快照的 Playwright 测试验证九个页面在 390x844 下无横向溢出、Lucide 与图片加载、主题和 token drawer 可交互，以及移动审批产生可见结果：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/tests/gallery.spec.js</Path>`。复制样板后，用原型自己的状态和任务补充测试，不把这组检查当作生产验收。