@namewta/speculo 1.0.24 → 2.0.1

package/template/workflows/specdev/specdev-p-prototype/design-library/catalog.json

@@ -0,0 +1,384 @@
+{
+  "schema_version": 1,
+  "templates": [
+    {
+      "id": "dense-ide",
+      "title": "高密度 IDE",
+      "tasks": [
+        "代码编辑",
+        "数据库与API",
+        "日志诊断"
+      ],
+      "platforms": [
+        "desktop",
+        "web"
+      ],
+      "density": "compact",
+      "preview": "research-snapshot/ui-gallery/01-dense-ide.html",
+      "reference_ids": [
+        "linear",
+        "vercel"
+      ],
+      "avoid": [
+        "低频消费者表单",
+        "以摄影叙事为主的页面"
+      ],
+      "guide": "templates/dense-ide.md"
+    },
+    {
+      "id": "monochrome-console",
+      "title": "单色运行控制台",
+      "tasks": [
+        "运行监控",
+        "Agent管理",
+        "本地工具"
+      ],
+      "platforms": [
+        "desktop",
+        "web"
+      ],
+      "density": "compact",
+      "preview": "research-snapshot/ui-gallery/02-monochrome-console.html",
+      "reference_ids": [
+        "vercel",
+        "linear"
+      ],
+      "avoid": [
+        "品牌叙事",
+        "图片购物目录"
+      ],
+      "guide": "templates/monochrome-console.md"
+    },
+    {
+      "id": "soft-personal-ai",
+      "title": "柔和个人 AI",
+      "tasks": [
+        "对话",
+        "个人助手",
+        "上下文整理"
+      ],
+      "platforms": [
+        "desktop",
+        "web"
+      ],
+      "density": "comfortable",
+      "preview": "research-snapshot/ui-gallery/03-soft-personal-ai.html",
+      "reference_ids": [
+        "notion"
+      ],
+      "avoid": [
+        "高密度财务表格"
+      ],
+      "guide": "templates/soft-personal-ai.md"
+    },
+    {
+      "id": "responsive-web",
+      "title": "响应式 Web 工作台",
+      "tasks": [
+        "多设备访问",
+        "自托管应用",
+        "会话与预览"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "default",
+      "preview": "research-snapshot/ui-gallery/04-responsive-web.html",
+      "reference_ids": [
+        "vercel",
+        "linear"
+      ],
+      "avoid": [
+        "原生手势为核心的移动工具"
+      ],
+      "guide": "templates/responsive-web.md"
+    },
+    {
+      "id": "mobile-supervisor",
+      "title": "移动监督与审批",
+      "tasks": [
+        "审批",
+        "通知",
+        "远程监督"
+      ],
+      "platforms": [
+        "mobile",
+        "web"
+      ],
+      "density": "touch",
+      "preview": "research-snapshot/ui-gallery/05-mobile-supervisor.html",
+      "reference_ids": [
+        "airbnb"
+      ],
+      "avoid": [
+        "手机完整复刻IDE"
+      ],
+      "guide": "templates/mobile-supervisor.md"
+    },
+    {
+      "id": "cross-platform-workspace",
+      "title": "跨端 Agent 工作区",
+      "tasks": [
+        "多工作区",
+        "会话切换",
+        "多端任务"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "default",
+      "preview": "research-snapshot/ui-gallery/06-cross-platform-workspace.html",
+      "reference_ids": [
+        "vercel",
+        "ibm"
+      ],
+      "avoid": [
+        "单页面品牌展示"
+      ],
+      "guide": "templates/cross-platform-workspace.md"
+    },
+    {
+      "id": "local-first-content",
+      "title": "Local-first 内容编辑器",
+      "tasks": [
+        "知识库",
+        "长文阅读",
+        "笔记编辑"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "comfortable",
+      "preview": "research-snapshot/ui-gallery/07-local-first-content.html",
+      "reference_ids": [
+        "mintlify"
+      ],
+      "avoid": [
+        "监控大盘"
+      ],
+      "guide": "templates/local-first-content.md"
+    },
+    {
+      "id": "media-first",
+      "title": "媒体优先应用",
+      "tasks": [
+        "媒体浏览",
+        "资产选择",
+        "内容库"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "default",
+      "preview": "research-snapshot/ui-gallery/08-media-first.html",
+      "reference_ids": [
+        "spotify"
+      ],
+      "avoid": [
+        "长表单",
+        "纯代码编辑"
+      ],
+      "guide": "templates/media-first.md"
+    },
+    {
+      "id": "enterprise-data",
+      "title": "企业数据与审批",
+      "tasks": [
+        "记录筛选",
+        "表格决策",
+        "批量审批"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "compact",
+      "preview": "templates/enterprise-data.html",
+      "reference_ids": [
+        "ibm",
+        "vercel"
+      ],
+      "avoid": [
+        "完整电子表格",
+        "低密度品牌叙事"
+      ],
+      "guide": "templates/enterprise-data.md"
+    },
+    {
+      "id": "marketing-conversion",
+      "title": "SaaS 营销与转化",
+      "tasks": [
+        "产品说明",
+        "方案比较",
+        "联系转化"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "comfortable",
+      "preview": "templates/marketing-conversion.html",
+      "reference_ids": [
+        "stripe",
+        "vercel",
+        "notion"
+      ],
+      "avoid": [
+        "已登录高密度工作台"
+      ],
+      "guide": "templates/marketing-conversion.md"
+    },
+    {
+      "id": "commerce-service",
+      "title": "消费者交易与服务",
+      "tasks": [
+        "服务详情",
+        "日期与人数选择",
+        "预约确认"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "touch",
+      "preview": "templates/commerce-service.html",
+      "reference_ids": [
+        "airbnb",
+        "stripe"
+      ],
+      "avoid": [
+        "专业IDE",
+        "未经授权真实付款"
+      ],
+      "guide": "templates/commerce-service.md"
+    },
+    {
+      "id": "brand-editorial",
+      "title": "品牌与编辑叙事",
+      "tasks": [
+        "品牌介绍",
+        "作品探索",
+        "合作咨询"
+      ],
+      "platforms": [
+        "desktop",
+        "web",
+        "mobile"
+      ],
+      "density": "comfortable",
+      "preview": "templates/brand-editorial.html",
+      "reference_ids": [
+        "apple",
+        "figma"
+      ],
+      "avoid": [
+        "实时监控",
+        "密集数据处理"
+      ],
+      "guide": "templates/brand-editorial.md"
+    }
+  ],
+  "references": [
+    {
+      "id": "linear",
+      "title": "Linear",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/linear.app/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/linear/DESIGN.md",
+      "guide": "visual-references/linear.md"
+    },
+    {
+      "id": "vercel",
+      "title": "Vercel",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/vercel/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/vercel/DESIGN.md",
+      "guide": "visual-references/vercel.md"
+    },
+    {
+      "id": "stripe",
+      "title": "Stripe-inspired",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/stripe/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/stripe/DESIGN.md",
+      "guide": "visual-references/stripe.md"
+    },
+    {
+      "id": "airbnb",
+      "title": "Airbnb",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/airbnb/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/airbnb/DESIGN.md",
+      "guide": "visual-references/airbnb.md"
+    },
+    {
+      "id": "spotify",
+      "title": "Spotify",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/spotify/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/spotify/DESIGN.md",
+      "guide": "visual-references/spotify.md"
+    },
+    {
+      "id": "apple",
+      "title": "Apple-inspired",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/apple/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/apple/DESIGN.md",
+      "guide": "visual-references/apple.md"
+    },
+    {
+      "id": "figma",
+      "title": "Figma",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/figma/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/figma/DESIGN.md",
+      "guide": "visual-references/figma.md"
+    },
+    {
+      "id": "mintlify",
+      "title": "Mintlify",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/mintlify/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/mintlify/DESIGN.md",
+      "guide": "visual-references/mintlify.md"
+    },
+    {
+      "id": "notion",
+      "title": "Notion",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/notion/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/notion/DESIGN.md",
+      "guide": "visual-references/notion.md"
+    },
+    {
+      "id": "ibm",
+      "title": "IBM / Carbon-inspired",
+      "source": "https://github.com/VoltAgent/awesome-design-md/blob/c7c1bada4eda972236d124e06ee58df129a9266b/design-md/ibm/DESIGN.md",
+      "revision": "c7c1bada4eda972236d124e06ee58df129a9266b",
+      "license": "MIT",
+      "document": "upstream/awesome-design-md/ibm/DESIGN.md",
+      "guide": "visual-references/ibm.md"
+    }
+  ]
+}

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

@@ -0,0 +1,42 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "urn:speculo:specdev:design-library-catalog:v1",
+  "title": "Speculo design library catalog",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["schema_version", "templates", "references"],
+  "properties": {
+    "schema_version": { "const": 1 },
+    "templates": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/template" } },
+    "references": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/reference" } }
+  },
+  "$defs": {
+    "id": { "type": "string", "pattern": "^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$" },
+    "localPath": { "type": "string", "minLength": 1, "pattern": "^(?!/)(?!.*(?:^|/)\\.\\.(?:/|$))(?!.*\\\\)(?![A-Za-z]+:)[^?#]+$" },
+    "strings": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "minLength": 1 } },
+    "template": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "title", "tasks", "platforms", "density", "preview", "reference_ids", "avoid", "guide"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" }, "title": { "type": "string", "minLength": 1 },
+        "tasks": { "$ref": "#/$defs/strings" },
+        "platforms": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "enum": ["desktop", "web", "mobile"] } },
+        "density": { "enum": ["compact", "default", "comfortable", "touch"] },
+        "preview": { "$ref": "#/$defs/localPath" }, "guide": { "$ref": "#/$defs/localPath" },
+        "reference_ids": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "$ref": "#/$defs/id" } },
+        "avoid": { "$ref": "#/$defs/strings" }
+      }
+    },
+    "reference": {
+      "type": "object", "additionalProperties": false,
+      "required": ["id", "title", "source", "revision", "license", "document", "guide"],
+      "properties": {
+        "id": { "$ref": "#/$defs/id" }, "title": { "type": "string", "minLength": 1 },
+        "source": { "type": "string", "format": "uri", "pattern": "^https://" },
+        "revision": { "type": "string", "pattern": "^[a-f0-9]{40}$" },
+        "license": { "type": "string", "minLength": 1 },
+        "document": { "$ref": "#/$defs/localPath" }, "guide": { "$ref": "#/$defs/localPath" }
+      }
+    }
+  }
+}

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

@@ -0,0 +1,65 @@
+# 色彩、主题与视觉层级
+
+视觉系统先定义角色，再选择色值。固定快照中的 `<Path>{roots.workflows}/specdev/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/specdev-p-prototype/design-library/research-snapshot/ui-gallery/styles/pages.css</Path>`，综合 token 的使用约束在 `<Path>{roots.workflows}/specdev/specdev-p-prototype/design-library/research-snapshot/reference/USAGE.md</Path>`。

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

@@ -0,0 +1,39 @@
+# 模板选择与视觉组合
+
+在项目事实与需求已定位、准备生成候选时读取。功能模板决定任务骨架，视觉 reference 提供可选择的表达机制；用户最新决定与已确认项目 DESIGN 优先。静态设计库不写 runtime，不自动改写生产 UI 或永久知识。
+
+## 推荐顺序
+
+1. 用核心对象、3–5 个高频任务、输入设备、状态复杂度检索 [catalog](catalog.json) 的 tasks/platforms/avoid。已有 UI 优先保留可复用组件与交互；新项目明确记录缺少既有事实。
+2. 从命中模板选一个主布局。默认候选数量仍为项目配置的 3、上限 4；事实只支持两个方向时不凑数。12 个模板是能力清单，不是一次运行必须交付 12 个页面。
+3. 对每个候选选择一个主视觉 reference，再按需求加入最多两个辅助 reference。主视觉拥有文字、表面、密度和主操作的一致表达；辅助只影响明确区域或维度。用户明确要求更多组合时记录额外来源与冲突裁决，不静默改变数量。
+4. 用户给出参考时优先评估其适配；用户没有偏好时，依据任务与代码基线自主推荐并生成 HTML，不等待用户先选颜色。已确认的项目规则直接继承，只有冲突或高影响新取舍需要提前询问。
+5. 为每个候选使用相同真实任务、数据、页面和状态。结构、层级或任务入口有实际差异；不把换色当作三个方案。用户看到 HTML 后可选一个、要求调整或指定组合；没有最终确认不能伪造用户接受。
+
+## 组合记录
+
+每个候选记录以下信息，存入 P 拥有的当前 change 工件，不修改此库：
+
+| 字段 | 含义 |
+|---|---|
+| 主模板 | 一个 catalog template ID，说明任务匹配与不适用条件 |
+| 主视觉 | 一个 reference ID，或明确 project-existing/custom 并记录证据 |
+| 辅助参考 | reference ID + role（排版/表面/组件/页面区域）+ 明确作用范围 |
+| 项目继承 | 基线 locator/revision，复用的 token、组件、导航和状态 |
+| 局部覆盖 | 被覆盖规则、理由、仅本 change 或待提升的范围 |
+| 裁决 | 冲突、采用方、拒绝方、用户决定或可逆假设 |
+| 证据 | 固定上游 revision/hash 与所读原文节；截图推断明确标注 |
+
+只选一个主信息架构和一组语义 token。相同 role 不允许两个未裁决 owner；如两个参考定义主按钮、密度或焦点，明确选择其一。Figma 的营销色块不成为编辑器工具栏；Apple 的产品大片不成为后台默认留白；Notion 的营销页不证明笔记产品交互；暗色原文未覆盖的浅色主题必须由项目独立设计与验证。
+
+## 离线复制与补齐
+
+原始 Markdown 保持原字节，归一化指南单独维护。只复制本次采用样板及其本地资源闭包，保留相对目录、许可和 attribution。字体默认使用项目已有或系统字体；图片优先使用用户资产或本库已归属样例。浏览器可直接打开的 HTML 不应依赖 CDN、远程字体、远程图片、网络 API 或在线 catalog fetch。
+
+每种候选都补齐项目适用的正常、空、加载、失败、权限、取消、重试和恢复路径；文案、时序和信息保留由行为合同决定。上游 Known Gaps 不会取消这些义务。原型只证明模拟路径。
+
+## 审美与行为审查
+
+先审任务是否清楚、主内容是否占据正确层级，再审文字节奏、对齐、密度、表面、图片裁切和细节一致性；检查是否出现通用卡片墙、装饰抢主体、按钮无结果、假数据掩盖真实长度等问题。每项问题落到具体页面、状态与修复，不以“现代”“高级”替代判断。
+
+运行真实浏览器在 390px 与 1440px 检查，再按项目设备补充；测试键盘、200% 缩放、长中文、reduced motion 和适用主题。保留来源、观察、修复和截图证据。最终 HTML 确认与永久设计毕业仍使用 P/A 的 owning 合同；模板选择不授予实施、外部写入或知识提升权限。

package/template/workflows/specdev/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/specdev-p-prototype/design-library/research-snapshot/report/OPEN_SOURCE_UI_RESEARCH_2026.md</Path>` 第 6-7、11-13 节。