@namewta/speculo 1.0.22 → 2.0.1

package/template/workflows/specdev/specdev-p-prototype/assets/design-package.schema.json

@@ -0,0 +1,248 @@
+{
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "const": 3
+    },
+    "artifact": {
+      "const": "ui-prototype"
+    },
+    "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",
+        "awaiting-confirmation",
+        "ready",
+        "blocked"
+      ]
+    },
+    "project_kind": {
+      "enum": [
+        "existing",
+        "new"
+      ]
+    },
+    "platforms": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "enum": [
+          "desktop",
+          "web",
+          "mobile"
+        ]
+      }
+    },
+    "candidates": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "template_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "primary_reference": {
+            "type": "string",
+            "minLength": 1
+          },
+          "auxiliaries": {
+            "type": "array",
+            "minItems": 0,
+            "items": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "reference_id": {
+                  "type": "string",
+                  "minLength": 1
+                },
+                "dimension": {
+                  "type": "string",
+                  "minLength": 1
+                }
+              },
+              "required": [
+                "reference_id",
+                "dimension"
+              ]
+            }
+          },
+          "rationale": {
+            "type": "string",
+            "minLength": 1
+          },
+          "structural_difference": {
+            "type": "string",
+            "minLength": 1
+          },
+          "task_id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "entry": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "required": [
+          "id",
+          "template_id",
+          "primary_reference",
+          "auxiliaries",
+          "rationale",
+          "structural_difference",
+          "task_id",
+          "entry"
+        ]
+      }
+    },
+    "candidate_count_override": {
+      "anyOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "count": {
+              "type": "integer",
+              "minimum": 1
+            },
+            "request": {
+              "type": "string",
+              "minLength": 1
+            }
+          },
+          "required": [
+            "count",
+            "request"
+          ]
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "selected_candidate": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "sources": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "id": {
+            "type": "string",
+            "minLength": 1
+          },
+          "locator": {
+            "type": "string",
+            "minLength": 1
+          },
+          "url": {
+            "type": "string",
+            "minLength": 1
+          },
+          "revision": {
+            "type": "string",
+            "minLength": 1
+          },
+          "license": {
+            "type": "string",
+            "minLength": 1
+          },
+          "digest": {
+            "type": "string",
+            "pattern": "^[a-f0-9]{64}$"
+          }
+        },
+        "required": [
+          "id",
+          "locator"
+        ]
+      }
+    },
+    "prototype_files": {
+      "type": "array",
+      "uniqueItems": true,
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "allOf": [
+        {
+          "contains": {
+            "const": "final/index.html"
+          }
+        },
+        {
+          "contains": {
+            "const": "final/styles.css"
+          }
+        },
+        {
+          "contains": {
+            "const": "final/app.js"
+          }
+        }
+      ]
+    },
+    "browser_evidence": {
+      "anyOf": [
+        {
+          "type": "string",
+          "minLength": 1
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "updated_at": {
+      "type": "string",
+      "format": "date-time"
+    }
+  },
+  "required": [
+    "schema_version",
+    "artifact",
+    "change",
+    "design_id",
+    "status",
+    "project_kind",
+    "platforms",
+    "candidates",
+    "candidate_count_override",
+    "selected_candidate",
+    "sources",
+    "prototype_files",
+    "browser_evidence",
+    "updated_at"
+  ],
+  "$id": "urn:speculo:specdev:ui-prototype:v3",
+  "$schema": "https://json-schema.org/draft/2020-12/schema"
+}

package/template/workflows/specdev/specdev-p-prototype/assets/design-system-template.md

@@ -0,0 +1,307 @@
+---
+schema_version: 3
+artifact: ui-prototype
+change: <YYYY-MM-DD-topic>
+design_id: UI-001
+status: detecting
+project_kind: existing
+platforms: [web]
+candidates:
+  - id: candidate-a
+    template_id: <catalog-template-id>
+    primary_reference: <source-id>
+    auxiliaries: []
+    rationale: <task-and-project-fit>
+    structural_difference: <task-structure-or-interaction-difference>
+    task_id: <shared-task-id>
+    entry: comparison/variants/candidate-a.html
+candidate_count_override: null
+selected_candidate: null
+sources:
+  - id: <source-id>
+    locator: <verified-source-locator>
+prototype_files: [final/index.html, final/styles.css, final/app.js]
+browser_evidence: null
+updated_at: <ISO-8601>
+---
+
+# UI Prototype UI-001: <产品或功能名称>
+
+本文件只保存检测、候选和源码/验证证据。设计规则唯一位于 <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>；永久基线见其 baseline 引用。以下代码是未验证的物化示例，必须按当前任务替换；它不预设项目品牌，也不能直接封板。
+
+## Project Evidence
+
+- **Target app / scope:**
+- **Primary users / shared task:**
+- **Platforms and input methods:**
+- **Evidence mode:** rendered / source-only / new-product
+- **Existing design authority and owner:**
+- **Baseline revision and inspected rule IDs:**
+
+| Dimension | Observed fact | Project-relative evidence | Confidence |
+|---|---|---|---|
+| Framework, styling, components and icons | | | |
+| Layout, themes, typography and density | | | |
+| Shapes, elevation, interaction and states | | | |
+| Responsive and accessibility | | | |
+
+### Keep, Adjust, Replace, Add
+
+| Action | Observation and proposed change | Evidence and reason |
+|---|---|---|
+| Keep | | |
+| Adjust | | |
+| Replace | | |
+| Add | | |
+
+## Candidate Composition
+
+frontmatter 的 candidates/sources 是结构化记录；此处解释采用理由及冲突裁决，不重复 token 值。
+
+| Candidate | Primary / auxiliary dimensions | Structural difference | Cost and risk | Feedback |
+|---|---|---|---|---|
+| candidate-a | | | | pending |
+
+- **Candidate count:** config default / explicit user override with request locator.
+- **Recommended final:** pending; recommendation is not approval.
+- **Rejected candidates and reasons:** pending.
+- **Composition boundary and conflicts resolved:**
+
+## Approval Package
+
+- **Change design:** <Path>{roots.state}/specdev/changes/{change}/DESIGN.md</Path>
+- **First baseline draft, when needed:** <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/baseline-draft.md</Path>
+- **User confirmation source:** pending.
+- **Approved designDigest / prototype digest:** pending.
+- **Bootstrap publication receipt, when applicable:** pending / not-applicable.
+- **Bootstrap preview binding:** project-relative path/sha256 for this final HTML, package_path for this source package, and computed prototype_digest covering all final/comparison resources and candidates.
+
+One user confirmation binds the displayed HTML/interaction, change DESIGN and explicit first-baseline publication scope. It grants no production implementation or archive-move permission. Exact approval fields belong to change DESIGN and the A gateway, not a second authority here.
+
+## Prototype Sources
+
+Named blocks own runnable source only; their materialized files must match exactly. Replace the illustrative workspace below with the user's complete task, content, states and approved system. Rules and token meaning remain in change DESIGN; CSS contains their executable values.
+
+<!-- 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
+
+| Command or observation | Exit code / result | Evidence locator |
+|---|---|---|
+| materialize and materialize --check | pending | |
+| design package --check-preview before confirmation | pending | |
+| design package --check-ready before ready | pending | |
+| prototype gate with UI-NNN | pending | |
+| desktop and narrow browser tasks | unverified | |
+| independent design critique | unverified | |
+| technical audit and recheck | unverified | |
+
+Browser evidence follows <Path>{roots.workflows}/specdev/common/schemas/prototype-browser-evidence.schema.json</Path> and is saved under <Path>{roots.state}/specdev/changes/{change}/prototypes/{design-id}/evidence/browser.json</Path>. Populate only actual observations and real screenshot paths. Source-only inspection cannot pass this gate.
+
+- [ ] Every requested candidate has a standalone comparison HTML page.
+- [ ] Final source blocks and materialized files are byte-equivalent and offline.
+- [ ] Keyboard, focus, long text, zoom, reduced motion and applicable states were exercised.
+- [ ] Actual desktop and narrow screenshots show no blank canvas, overlap or unintended overflow.
+- [ ] Design confirmation, prototype digest, baseline revision and source bytes still agree.
+- [ ] No unresolved high-impact design issue remains.
+
+- **Design authority:** <Path>{roots.state}/specdev/changes/{change}/DESIGN.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.
+- **Unverified items / recovery point:**

package/template/workflows/specdev/specdev-p-prototype/assets/project-design-template.md

@@ -0,0 +1,60 @@
+---
+schema_version: 1
+artifact: project-design
+revision: DESIGN-0001
+owner: specdev/archive-and-consolidate
+scope: [<app-or-surface-scope>]
+tokens:
+  <semantic-token>: <established-value>
+rules:
+  - id: DS-001
+    statement: <approved-reusable-rule>
+    scope: [<app-or-surface-scope>]
+    verification: approved-intent
+    sources: []
+sources:
+  - id: <source-id>
+    locator: <verified-project-or-reference-locator>
+supersedes: null
+updated_at: <ISO-8601>
+---
+
+# Project Design: <项目名称>
+
+本模板由 P 在当前原型包的 baseline-draft 准备候选，只有 A 网关可发布到 <Path>{roots.state}/specdev/design/DESIGN.md</Path>。初始化不得创建此内容。替换全部占位符；以 <Path>{roots.workflows}/specdev/common/schemas/project-design.schema.json</Path> 校验。初始规则为 approved-intent；归档提升为 implemented 必须附真实 change、locator 与 digest。
+
+## Overview
+
+目标受众、适用 app/页面、设计目标、已承诺品牌、信息密度与模板组合依据。产品事实引用既有 CONTEXT；架构选择引用 ADR，不复制其权威。
+
+## Colors
+
+解释 frontmatter 语义 token 的用途、主题和对比策略，不另写冲突数值。
+
+## Typography
+
+字体角色、中文与数字、正文可读性、层级及允许的本地字体资产；沿用项目事实。
+
+## Layout
+
+网格、间距/密度、布局和跨端重排原则；不固化某次 change 的页面文案或单次内容。
+
+## Elevation & Depth
+
+表面、边框、阴影与浮层层级的职责。
+
+## Shapes
+
+形状、圆角和图标一致性，注明适用边界。
+
+## Components
+
+共享组件的用途、状态、键盘/focus、触屏、异步反馈、失败恢复与 reduced motion。规则使用稳定 ID；每项可追溯批准或实现来源。
+
+## Do's and Don'ts
+
+用户和项目确认的具体约束；外部设计反模式是辅助诊断，不自动变成项目绝对禁令。
+
+## Provenance and Supersession
+
+记录实际读取的来源、版本、许可、确认 locator，以及替代的规则和原因。未验证建议与已实现规则分开；一次初始批准可发布意图，不声称生产已经采用。

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

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