@namewta/speculo 0.8.6 → 0.8.8

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

@@ -0,0 +1,32 @@
+# 八种可运行 UI 风格
+
+八个页面都是独立静态 HTML，使用 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/styles/</Path>` 的共享样式、`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/scripts/gallery.js</Path>` 和本地 Lucide。先按任务与平台选风格，不按颜色选；页面是原型起点，不是生产组件库。
+
+| ID | 风格与入口 | 适用任务 | 主要研究参考 | 样板中的结构与视觉签名 |
+|---|---|---|---|---|
+| 01 | 高密度 IDE：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/01-dense-ide.html</Path>` | IDE、数据库、API、日志工具 | cdesktop、DBeaver、DBX | 工具轨 + 230px explorer + tabs/editor + review panel + status bar；橙色小面积 accent，2/3/4px 圆角，12px 级代码密度 |
+| 02 | 单色桌面控制台：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/02-monochrome-console.html</Path>` | Agent 管理台、本地开发控制台 | Opcode | 252px 侧栏 + 控制台/分析内容；近黑多层表面、浅中性 accent，4/8/12px 圆角，状态与图表依赖层级而非品牌铺色 |
+| 03 | 柔和个人 AI 桌面：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/03-soft-personal-ai.html</Path>` | 个人 AI 助手、消费级桌面工具 | CodePilot、TOKENICODE | 264px 会话/项目栏 + 对话 + 360px 上下文；暖中性、克制阴影、8/12/16px 圆角，浅深主题与 context meter |
+| 04 | 响应式 Web 工作台：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/04-responsive-web.html</Path>` | 自托管 Web UI、PWA、多设备访问 | CloudCLI | 260px 会话栏 + transcript/tools + 350px preview；蓝色动作 accent、4/6/8px 圆角；窄屏使用 drawer、底部导航与安全区，而非压缩三栏 |
+| 05 | 移动监督与审批：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/05-mobile-supervisor.html</Path>` | 通知、审批、远程监督、follow-up | Happy | 最大 390px 的移动任务流；15px UI 字号、44px 级触控目标、紫色 tonal palette、12/18/22px 圆角；审批结果必须可见 |
+| 06 | 多端 Agent 工作区：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/06-cross-platform-workspace.html</Path>` | 跨桌面/Web/移动的 Agent 工作区 | Paseo | 54px 工作区轨 + 250px Agent/会话栏 + tabbed workspace + 330px 工具栏；zinc 中性表面、绿色 accent、4/6/8px 圆角，关注等待审批状态 |
+| 07 | Local-first 内容编辑器：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/07-local-first-content.html</Path>` | 笔记、知识库、local-first 编辑 | Notesnook、Joplin、Outline | 214px 全局栏 + 300px 内容列表 + 无框正文；暖纸面、锈色 accent、4/6/8px 圆角，正文宽度与阅读节奏优先 |
+| 08 | 媒体优先个人应用：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/08-media-first.html</Path>` | 相册、资产库、视觉内容应用 | Immich | 224px 导航 + 自适应媒体网格 + 上传状态；深色低干扰 chrome、蓝色 accent、4/8/10px 圆角，真实图片和媒体本体是第一信号 |
+
+## 选择规则
+
+1. 先匹配用户的主要任务、目标输入设备和信息密度。
+2. 按配置生成 2-4 个功能候选；候选必须在布局、信息层级或主要操作入口上不同，最终再收束为一个主风格或边界明确的组合。
+3. 保留共享基础中的 keyboard focus、reduced motion、safe area、drawer/sheet 和稳定尺寸约束。
+4. 先改 `.theme-*` 的语义变量，再改局部组件；不要在业务节点散落 hex、任意圆角或单次间距。
+5. 保留布局职责，替换 demo 数据与状态。示例中的 Git、权限、同步、审批和上传只是交互演示。
+
+## 复用定位
+
+- 风格总览：`<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/styles/base.css</Path>`
+- 八种主题与页面实现：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/styles/pages.css</Path>`
+- 主题、密度、drawer、tab 与演示交互：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/scripts/gallery.js</Path>`
+- Playwright 行为检查：`<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/tests/gallery.spec.js</Path>`
+
+所有页面可直接用浏览器打开。只有重复执行 Playwright 时才在复制出的 change 设计包安装依赖；不要在研究快照内生成 `node_modules` 或 `test-results`。

package/template/workflows/specdev/P-prototype/design-package.schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:ui-design-system:v2",
+  "title": "SpecDev UI design system frontmatter",
+  "type": "object",
+  "additionalProperties": true,
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "design_id",
+    "status",
+    "project_kind",
+    "platforms",
+    "style_candidates",
+    "research_snapshot",
+    "prototype_files",
+    "updated_at"
+  ],
+  "properties": {
+    "schema_version": { "const": 2 },
+    "artifact": { "const": "ui-design-system" },
+    "change": { "type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$" },
+    "design_id": { "type": "string", "pattern": "^UI-\\d{3,}$" },
+    "status": { "enum": ["detecting", "selecting", "ready", "blocked"] },
+    "project_kind": { "enum": ["existing", "new"] },
+    "platforms": {
+      "type": "array",
+      "minItems": 1,
+      "uniqueItems": true,
+      "items": { "enum": ["desktop", "web", "mobile"] }
+    },
+    "detected_style": { "type": ["string", "null"] },
+    "style_candidates": {
+      "type": "array",
+      "minItems": 2,
+      "maxItems": 4,
+      "uniqueItems": true,
+      "items": { "type": "string", "minLength": 1 }
+    },
+    "selected_style": { "type": ["string", "null"] },
+    "density": { "enum": ["compact", "default", "comfortable", "touch", null] },
+    "color_mode": { "enum": ["light", "dark", "system", "both", null] },
+    "research_snapshot": { "const": "49b5659" },
+    "prototype_files": {
+      "type": "array",
+      "uniqueItems": true,
+      "allOf": [
+        { "contains": { "const": "final/index.html" } },
+        { "contains": { "const": "final/styles.css" } },
+        { "contains": { "const": "final/app.js" } }
+      ],
+      "items": { "type": "string" }
+    },
+    "updated_at": { "type": "string", "format": "date-time" }
+  },
+  "allOf": [
+    {
+      "if": { "properties": { "status": { "const": "ready" } } },
+      "then": {
+        "required": ["selected_style", "density", "color_mode"],
+        "properties": {
+          "selected_style": { "type": "string", "minLength": 1 },
+          "density": { "type": "string" },
+          "color_mode": { "type": "string" }
+        }
+      }
+    }
+  ]
+}

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

@@ -0,0 +1,366 @@
+---
+schema_version: 2
+artifact: ui-design-system
+change: <YYYY-MM-DD-topic>
+design_id: UI-001
+status: detecting
+project_kind: existing
+platforms: [desktop, web]
+detected_style: null
+style_candidates: [dense-ide, responsive-web]
+selected_style: null
+density: null
+color_mode: null
+research_snapshot: 49b5659
+prototype_files: [final/index.html, final/styles.css, final/app.js]
+updated_at: <ISO-8601>
+---
+
+# UI Design System UI-001: <产品或功能名称>
+
+## Project Evidence
+
+### Scope and Tasks
+
+- **Target app:**
+- **Primary users:**
+- **Top tasks:**
+- **Platforms:**
+- **Evidence mode:** rendered / source-only / new-product
+
+### Existing Stack and Design Facts
+
+| Dimension | Observed fact | Project-relative evidence | Confidence |
+|---|---|---|---|
+| Framework | | | |
+| Styling | | | |
+| Components and icons | | | |
+| Layout | | | |
+| Color and themes | | | |
+| Type and density | | | |
+| Radius and elevation | | | |
+| Interaction and states | | | |
+| Responsive and accessibility | | | |
+
+### Keep, Adjust, Replace, Add
+
+| Action | Decision | Evidence and reason |
+|---|---|---|
+| Keep | | |
+| Adjust | | |
+| Replace | | |
+| Add | | |
+
+## Style Decision
+
+### Functional Candidates
+
+| Candidate | Product fit | Structural difference | Research references | Migration cost | Decision |
+|---|---|---|---|---|---|
+| dense-ide | | | DBX, DBeaver, cdesktop | | pending |
+| responsive-web | | | CloudCLI | | pending |
+
+### Decision Log
+
+| Layer | Decision | Status | Reason |
+|---|---|---|---|
+| Product and platform | | pending | |
+| Information architecture | | pending | |
+| Density and typography | | pending | |
+| Tone and theme | | pending | |
+| Shape and elevation | | pending | |
+| Interaction and motion | | pending | |
+| Cross-platform reflow | | pending | |
+| Visual convergence | | pending | |
+
+### Selected Direction and Rejections
+
+- **Selected style:** pending
+- **Composition boundary:** none
+- **Rejected candidates and reasons:** pending
+
+## Foundation Tokens
+
+### Design Intent
+
+Describe how the chosen shell, density, tone and hierarchy serve the primary task. Fixed defaults use a 4px spacing base, role-based colors, two or three main radii, borders for persistent regions and shadows only for overlays. Record every justified override.
+
+### Token Contract
+
+| Role | Token | Value | Usage |
+|---|---|---|---|
+| Canvas | `--canvas` | | App background |
+| Surface | `--surface-1` | | Primary work area |
+| Text | `--text-primary` | | Main content |
+| Border | `--border-default` | | Persistent separation |
+| Accent | `--accent` | | Primary action and selection |
+| Focus | `--focus-ring` | | Keyboard focus only |
+| Radius | `--radius-control` | | Input and button |
+| Density | `--control-height` | | Default control |
+
+## Component and State Contract
+
+| Component or pattern | Default | Hover | Pressed | Focus | Disabled/loading/error | Keyboard and touch |
+|---|---|---|---|---|---|---|
+| App shell | | | | | | |
+| Navigation | | | | | | |
+| Button and icon button | | | | | | |
+| Form controls | | | | | | |
+| Primary work surface | | | | | | |
+| Overlay | | | | | | |
+
+Include empty, no-result, loading, error, offline, read-only and permission-denied where applicable. A state color always has a text, icon or shape cue.
+
+## Interaction Contract
+
+| Trigger | Immediate response | Completion response | Failure/recovery | Persistence |
+|---|---|---|---|---|
+| Navigation | | | | URL / local state |
+| Primary action | | | | |
+| Async action | | | | |
+| Destructive action | | | | |
+
+- Under 100ms: no loading indicator unless state would otherwise be ambiguous.
+- 100ms-1s: local progress or skeleton without whole-page flashing.
+- Over 1s: persistent progress with cancellation or background-task access.
+- Motion defaults to 120-180ms for local state and 200-240ms for sheets; reduced motion removes nonessential transforms.
+
+## Responsive Contract
+
+| Desktop structure | Narrow-screen replacement | Breakpoint evidence | Return/recovery path |
+|---|---|---|---|
+| Fixed sidebar | Drawer or single-level navigation | | |
+| Right inspector | Sheet or full-screen detail | | |
+| Wide toolbar | Primary action plus overflow | | |
+| Hover tools | Explicit button or menu | | |
+
+Document desktop, Web and mobile separately when their primary tasks differ. Touch targets are at least 44px; compact desktop controls may look smaller while keeping a usable hit area.
+
+## Prototype Sources
+
+The following named blocks are the authoritative runnable prototype. Materialized files must match them exactly.
+
+<!-- PROTOTYPE-FILE: final/index.html -->
+```html
+<!doctype html>
+<html lang="zh-CN">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Workspace Prototype</title>
+  <link rel="stylesheet" href="styles.css">
+</head>
+<body>
+  <div class="app-shell">
+    <aside class="sidebar" id="sidebar">
+      <div class="brand">Project</div>
+      <nav aria-label="Primary">
+        <button class="nav-item active" type="button">Workspace</button>
+        <button class="nav-item" type="button">Activity</button>
+        <button class="nav-item" type="button">Settings</button>
+      </nav>
+    </aside>
+    <main class="workspace">
+      <header class="toolbar">
+        <button class="menu-button" type="button" data-sidebar-toggle aria-controls="sidebar" aria-expanded="false">Menu</button>
+        <div>
+          <span class="eyebrow">Current project</span>
+          <h1>Workspace</h1>
+        </div>
+        <div class="toolbar-actions">
+          <button type="button" data-density-toggle>Density</button>
+          <button type="button" data-theme-toggle>Theme</button>
+        </div>
+      </header>
+      <section class="content" aria-live="polite">
+        <div class="section-heading">
+          <div>
+            <h2>Recent work</h2>
+            <p>Three active items, one waiting for review.</p>
+          </div>
+          <button class="primary" type="button" data-primary-action>New item</button>
+        </div>
+        <div class="work-list" role="list">
+          <button class="work-row selected" type="button" role="listitem">
+            <span><strong>Design system</strong><small>Updated 4 minutes ago</small></span>
+            <span class="status">In progress</span>
+          </button>
+          <button class="work-row" type="button" role="listitem">
+            <span><strong>Responsive shell</strong><small>Updated yesterday</small></span>
+            <span class="status neutral">Review</span>
+          </button>
+        </div>
+        <div class="feedback" data-feedback hidden>Draft created. The workspace state is preserved.</div>
+      </section>
+    </main>
+  </div>
+  <script src="app.js"></script>
+</body>
+</html>
+```
+<!-- /PROTOTYPE-FILE -->
+
+<!-- PROTOTYPE-FILE: final/styles.css -->
+```css
+:root {
+  color-scheme: light;
+  --canvas: #f3f4f2;
+  --surface-1: #ffffff;
+  --surface-2: #eef0ed;
+  --text-primary: #20221f;
+  --text-secondary: #666b64;
+  --border-default: #d9ddd7;
+  --accent: #176b4d;
+  --accent-subtle: #e2f0e9;
+  --focus-ring: #2478d4;
+  --radius-control: 6px;
+  --radius-panel: 8px;
+  --control-height: 36px;
+  --sidebar-width: 248px;
+  --font-ui: Inter, "Segoe UI", "PingFang SC", sans-serif;
+}
+
+html.dark {
+  color-scheme: dark;
+  --canvas: #151715;
+  --surface-1: #1c1f1c;
+  --surface-2: #272b27;
+  --text-primary: #f1f3ef;
+  --text-secondary: #adb3aa;
+  --border-default: #343934;
+  --accent: #79bd98;
+  --accent-subtle: #21382c;
+  --focus-ring: #72aef0;
+}
+
+* { box-sizing: border-box; }
+html, body { min-width: 320px; min-height: 100%; margin: 0; }
+body { background: var(--canvas); color: var(--text-primary); font: 14px/1.5 var(--font-ui); }
+button { min-height: var(--control-height); border: 1px solid var(--border-default); border-radius: var(--radius-control); background: var(--surface-1); color: inherit; font: inherit; cursor: pointer; }
+button:hover { background: var(--surface-2); }
+button:active { transform: translateY(1px); }
+button:focus-visible { outline: 3px solid color-mix(in srgb, var(--focus-ring) 35%, transparent); outline-offset: 2px; }
+button:disabled { cursor: not-allowed; opacity: .48; }
+.app-shell { display: flex; min-height: 100vh; }
+.sidebar { width: var(--sidebar-width); flex: 0 0 var(--sidebar-width); border-right: 1px solid var(--border-default); background: var(--surface-1); }
+.brand { height: 56px; padding: 17px 16px; border-bottom: 1px solid var(--border-default); font-weight: 700; }
+.sidebar nav { display: grid; gap: 4px; padding: 10px; }
+.nav-item { justify-content: flex-start; border-color: transparent; text-align: left; }
+.nav-item.active { border-color: color-mix(in srgb, var(--accent) 32%, var(--border-default)); background: var(--accent-subtle); color: var(--accent); }
+.workspace { min-width: 0; flex: 1; }
+.toolbar { display: flex; min-height: 64px; align-items: center; gap: 12px; padding: 8px 20px; border-bottom: 1px solid var(--border-default); background: var(--surface-1); }
+.toolbar h1, .section-heading h2 { margin: 0; font-size: 18px; letter-spacing: 0; }
+.eyebrow, small { display: block; color: var(--text-secondary); font-size: 12px; }
+.toolbar-actions { display: flex; gap: 8px; margin-left: auto; }
+.menu-button { display: none; }
+.content { width: min(960px, calc(100% - 40px)); margin: 0 auto; padding: 32px 0; }
+.section-heading { display: flex; align-items: flex-end; justify-content: space-between; gap: 16px; }
+.section-heading p { margin: 4px 0 0; color: var(--text-secondary); }
+.primary { border-color: var(--accent); background: var(--accent); color: #fff; }
+.primary:hover { background: color-mix(in srgb, var(--accent) 88%, #000); }
+.work-list { margin-top: 20px; border-top: 1px solid var(--border-default); }
+.work-row { display: flex; width: 100%; min-height: 64px; align-items: center; justify-content: space-between; border-width: 0 0 1px; border-radius: 0; padding: 10px 12px; text-align: left; }
+.work-row.selected { background: var(--accent-subtle); }
+.status { color: var(--accent); font-size: 12px; font-weight: 700; }
+.status.neutral { color: var(--text-secondary); }
+.feedback { margin-top: 16px; border-left: 3px solid var(--accent); padding: 10px 12px; background: var(--accent-subtle); }
+.density-compact { --control-height: 30px; }
+.density-compact .work-row { min-height: 48px; }
+
+@media (max-width: 760px) {
+  .sidebar { position: fixed; z-index: 20; inset: 0 auto 0 0; transform: translateX(-100%); transition: transform 180ms ease; }
+  .sidebar.open { transform: translateX(0); }
+  .menu-button { display: inline-flex; align-items: center; }
+  .toolbar { padding-inline: 12px; }
+  .toolbar-actions button { min-width: 44px; }
+  .content { width: calc(100% - 24px); padding: 24px 0; }
+  .section-heading { align-items: stretch; flex-direction: column; }
+  .primary { min-height: 44px; }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { scroll-behavior: auto !important; transition-duration: .01ms !important; animation-duration: .01ms !important; }
+  button:active { transform: none; }
+}
+```
+<!-- /PROTOTYPE-FILE -->
+
+<!-- PROTOTYPE-FILE: final/app.js -->
+```javascript
+(function () {
+  const root = document.documentElement;
+  const body = document.body;
+  const sidebar = document.querySelector("#sidebar");
+  const themeButton = document.querySelector("[data-theme-toggle]");
+  const densityButton = document.querySelector("[data-density-toggle]");
+  const sidebarButton = document.querySelector("[data-sidebar-toggle]");
+  const actionButton = document.querySelector("[data-primary-action]");
+  const feedback = document.querySelector("[data-feedback]");
+
+  const savedTheme = localStorage.getItem("prototype-theme");
+  if (savedTheme === "dark" || (!savedTheme && matchMedia("(prefers-color-scheme: dark)").matches)) root.classList.add("dark");
+
+  themeButton?.addEventListener("click", () => {
+    root.classList.toggle("dark");
+    localStorage.setItem("prototype-theme", root.classList.contains("dark") ? "dark" : "light");
+  });
+
+  densityButton?.addEventListener("click", () => body.classList.toggle("density-compact"));
+
+  sidebarButton?.addEventListener("click", () => {
+    const open = sidebar?.classList.toggle("open") ?? false;
+    sidebarButton.setAttribute("aria-expanded", String(open));
+  });
+
+  document.querySelectorAll(".work-row").forEach((row) => row.addEventListener("click", () => {
+    document.querySelectorAll(".work-row").forEach((item) => item.classList.toggle("selected", item === row));
+  }));
+
+  actionButton?.addEventListener("click", () => {
+    actionButton.disabled = true;
+    actionButton.textContent = "Creating...";
+    window.setTimeout(() => {
+      actionButton.disabled = false;
+      actionButton.textContent = "New item";
+      feedback.hidden = false;
+    }, 650);
+  });
+
+  document.addEventListener("keydown", (event) => {
+    if (event.key === "Escape" && sidebar?.classList.contains("open")) {
+      sidebar.classList.remove("open");
+      sidebarButton?.setAttribute("aria-expanded", "false");
+      sidebarButton?.focus();
+    }
+  });
+})();
+```
+<!-- /PROTOTYPE-FILE -->
+
+## Validation and Handoff
+
+### Commands and Evidence
+
+| Command | Exit code | Key result | Evidence path |
+|---|---:|---|---|
+| materialize | | | |
+| materialize --check | | | |
+| design package validator | | | |
+| desktop viewport | | | |
+| mobile viewport | | | |
+
+### Acceptance
+
+- [ ] Every candidate has a standalone comparison HTML page.
+- [ ] Final source blocks and materialized files are byte-equivalent.
+- [ ] Light/dark, keyboard, focus, long text and reduced motion were checked.
+- [ ] Desktop and mobile screenshots show no blank canvas, overlap or unintended overflow.
+- [ ] No unresolved high-impact design decision remains.
+
+### Handoff
+
+- **Authoritative artifact:** `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>`
+- **Comparison:** `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/index.html</Path>`
+- **Runnable final:** `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/final/index.html</Path>`
+- **Next Work:** G / S / T / I / blocked
+- **Unresolved high-impact questions:** none / ...

package/template/workflows/specdev/P-prototype/detect-existing-style.md

@@ -0,0 +1,53 @@
+# Existing Style Detection
+
+在推荐风格前使用。本协议只记录可发现事实；依赖名称、README 宣传语和单张截图都不能单独证明实际 UI。
+
+## 1. 确定检测面
+
+先定位用户实际要设计的应用、入口、代表性路由和目标平台。多应用仓库按 app 分开记录，不把后台、营销站、桌面壳和移动端混为同一风格。至少选择一个主任务页面，以及存在时的列表、详情、设置、空状态和窄屏页面。
+
+**完成标准**：检测范围、排除范围、核心用户和最高频 3-5 个任务均已写入 `Project Evidence`。
+
+## 2. 技术与组件证据
+
+穷尽读取与目标 app 相关的 manifest、框架配置、样式入口、主题、组件封装、图标、路由和测试：
+
+- Web：React/Vue/Svelte 等框架、SSR/SPA、CSS/Tailwind/SCSS/CSS-in-JS、组件原语和图标库；
+- Desktop：Electron/Tauri/Flutter/原生壳、窗口 chrome、菜单、快捷键、文件和终端能力；
+- Mobile：React Native/Expo/Flutter/原生导航、safe area、keyboard controller、sheet 与手势；
+- 设计系统：raw/semantic/component/business token 层级、浅深主题和密度机制。
+
+记录项目相对路径与具体 symbol/token；不存在时写 `not-found`，不得用常见默认值补齐事实。
+
+**完成标准**：每项技术断言可回到 manifest、配置或源码，第三方默认值与项目覆写已区分。
+
+## 3. 视觉与布局盘点
+
+统计或抽样确认重复出现的颜色、字号、行高、字重、间距、控件高度、图标尺寸、圆角、边框、阴影、动画时长和 breakpoint。识别 shell 属于全局侧栏、双层导航、列表-详情、编辑器/画布、仪表盘网格或内容中心，也允许明确的组合。
+
+按 `一致且可复用 / 存在但分裂 / 缺失 / 无法确认` 分类，不因某个页面用了 16px 圆角就把整个产品称为柔和风格。
+
+**完成标准**：`Project Evidence` 含可核查的 token 表、布局尺寸和置信度，异常值与主流值分开。
+
+## 4. 交互与状态盘点
+
+检查导航恢复、URL 状态、hover、pressed、focus-visible、selected、disabled、loading、empty、no-result、error、offline、read-only、permission-denied、危险操作和撤销。检查键盘、触屏、200% 缩放、长中文、reduced motion 与深浅主题。
+
+可以运行现有应用时，使用真实页面和极端数据观察；不能运行时明确记录 `source-only`，不虚构浏览器观察。
+
+**完成标准**：主要任务的鼠标、键盘和触屏路径均有结论，缺失状态成为后续设计要求。
+
+## 5. 输出检测摘要
+
+形成以下四栏：
+
+| 分类 | 含义 |
+|---|---|
+| 保留 | 已一致、符合任务且有证据的设计 |
+| 调整 | 方向正确但 token、状态或跨端行为不完整 |
+| 替换 | 与核心任务、输入设备或可访问性冲突 |
+| 补齐 | 当前不存在但完成任务必须具备 |
+
+最后写出 `detected_style`、密度、色调、主布局、平台和置信度；无法归入单一风格时使用 `hybrid` 并列出组成，不强行贴标签。
+
+**完成标准**：候选推荐可以逐条引用本摘要，所有推断均明确标记。

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

@@ -0,0 +1,50 @@
+# Generate Design Package
+
+在候选已形成后使用。设计系统主文档是源；HTML/CSS/JS 是可运行投影，不能成为第二套未记录规则。
+
+## 1. 生成候选页面
+
+为每个候选创建 `<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/variants/{style-id}.html</Path>`。每页使用相同真实任务、数据和状态，差异集中在 shell、信息层级、操作入口、密度、token 与跨端策略。页面必须离线运行，不引用 CDN、远程字体或远程图片；可从 `<Path>{roots.workflows}/specdev/P-prototype/design-library/research-snapshot/ui-gallery/assets/</Path>` 复制已归属的本地资产。
+
+每页至少展示默认、hover/focus、selected、loading、empty/error 中与任务相关的状态，并包含浅/深主题或明确说明为何只有单主题。图标按钮使用项目已有图标库；新项目可复制 design library 内的 Lucide 资产。
+
+**完成标准**：2-4 个候选各有独立 HTML，使用同一任务语义，页面差异不只是颜色。
+
+## 2. 生成 comparison 索引
+
+`<Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/comparison/index.html</Path>` 提供候选名称、适合原因、关键 token、迁移成本、拒绝风险和打开入口。桌面并排或分栏比较；窄屏改为顺序浏览，不把预览压成不可读小窗。索引只帮助比较，不在用户选择前偷偷设置赢家。
+
+**完成标准**：所有候选均可从索引到达，返回路径明确，键盘可操作，390px 与 1440px 均无意外溢出。
+
+## 3. 写入最终源码
+
+用户确认后，在设计系统主文档的 `Prototype Sources` 中写入且只写入以下具名块：
+
+````text
+<!-- PROTOTYPE-FILE: final/index.html -->
+```html
+...
+```
+<!-- /PROTOTYPE-FILE -->
+````
+
+CSS 与 JS 分别使用约定的 final 目标。源码不得包含占位符、生产 secret、生产写操作或无法离线取得的依赖。HTML 必须使用相对引用连接物化后的 CSS 与 JS。
+
+**完成标准**：三个块路径唯一、语言正确、代码完整，Markdown 单独阅读即可理解全部实现。
+
+## 4. 物化与校验
+
+运行：
+
+```bash
+node <Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> \
+  <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>
+
+node <Path>{roots.workflows}/specdev/P-prototype/tools/materialize-prototype.mjs</Path> \
+  --check \
+  <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/design-system.md</Path>
+```
+
+随后运行局部 validator、项目可用的 HTML/CSS/JS 检查和浏览器视口检查，把命令、退出码、关键输出与截图相对路径写入 `Validation and Handoff`。
+
+**完成标准**：物化二次运行无 diff；最终页面离线可用；所有验收项有证据而不是口头断言。

package/template/workflows/specdev/P-prototype/style-selection-protocol.md

@@ -0,0 +1,41 @@
+# Style Selection Protocol
+
+在检测完成并已生成 2-4 个功能候选后使用。每轮只关闭一个决策层，每次回答立即写入设计系统主文档；已确认内容不重复询问。
+
+## 决策顺序
+
+1. **产品与平台**：确认主用户、最高频任务、桌面/Web/移动优先级及是否真正跨端。
+2. **信息架构**：从全局侧栏、双层导航、列表-详情、画布/检查器、仪表盘网格、内容中心中选择 shell 或明确组合。
+3. **密度与排版**：选择 Compact、Default、Comfortable 或 Touch，并确认 UI/正文/代码字体角色。
+4. **色调与主题**：选择暖中性、冷中性、单色、品牌强调或媒体深色；确认 light、dark、system 或 both。
+5. **形状与层级**：确认主圆角组、边框/表面/阴影职责、常驻区与浮层差异。
+6. **交互与运动**：确认点击、异步、危险操作、拖动、键盘、触屏和 reduced-motion 行为。
+7. **跨端重排**：确认侧栏、检查器、表格、工具栏、hover 工具在窄屏的任务级替代。
+8. **可视收束**：打开 comparison，选择一个候选、拒绝其余候选，或明确哪些区域组合；不得只说“更现代”。
+
+## 候选说明合同
+
+每个候选必须包含：风格 id、适用任务、布局变化、token 摘要、三项关键交互、平台策略、现有 UI 的保留/调整/替换项、研究项目、迁移成本和不适用风险。候选必须在信息层级或操作入口上有结构差异，不能只是颜色与文案变化。
+
+候选数读取 `<Path>{roots.state}/specdev/config.json</Path>` 的 `planning.ui_design_default_candidates` 与 `planning.ui_design_max_candidates`，两者必须落在 2-4。事实只支持两个方向时可以少于默认值；达到配置上限前也不得为了凑数引入不适合产品的风格。
+
+## 八种风格路由
+
+| 风格 | 首选任务 | 避免场景 |
+|---|---|---|
+| dense-ide | 数据库、API、日志、专业开发工具 | 低频消费级表单 |
+| monochrome-console | Agent 管理、本地控制台、运行监控 | 品牌内容与媒体浏览 |
+| soft-personal-ai | 个人 AI、轻量桌面助手 | 极端数据密度和大表格 |
+| responsive-web | 自托管 Web、PWA、多设备访问 | 强原生手势为核心的移动产品 |
+| mobile-supervisor | 审批、通知、远程监督 | 手机内完整复刻 IDE |
+| cross-platform-workspace | 桌面/Web/移动 Agent 工作区 | 只需单页面内容展示 |
+| local-first-content | 笔记、知识库、长内容 | 监控大盘和媒体墙 |
+| media-first | 相册、视频、资产库 | 长表单和密集代码任务 |
+
+需要 CRM、仪表盘、画布、客服、通信或 API 分窗时，读取 `<Path>{roots.workflows}/specdev/P-prototype/design-library/product-pattern-index.md</Path>`，将产品布局模式与最接近的视觉风格组合，并记录组合边界。
+
+## 持久化与阻塞
+
+每轮更新 frontmatter、`Style Decision` 中的选择表和拒绝理由，再原子重读。用户尚未看到候选 HTML、回答含糊或多个方向仍会改变核心布局时保持 `status: selecting`。用户不在线时可以继续补充可发现证据和生成候选，但不得替用户选择最终风格。
+
+**完成标准**：八层决策均为 confirmed 或明确 not-applicable；被拒绝候选有原因，组合候选有逐区域边界，最终方向能直接生成 token 与页面。