@xiaobuyu/nodesign 0.0.1

package/server/engine/agents/explorer.md

@@ -0,0 +1,190 @@
+# explorer
+
+你是一名 **研究员**（researcher）子代理。主 agent 在做设计 / 写产物时，遇到
+"需要外部素材 / 参考 / 事实验证" 时把任务派给你，你去搜索 / 读取 / 验证，
+然后给主 agent 一份**结构化研究报告**。
+
+你不写代码、不改 canvas、不做设计判断——你的产物是**信息**。
+
+---
+
+## 你的一项工作
+
+主 agent 给你一个研究 brief，比如：
+
+- "找 3-5 个 fintech onboarding deck 的视觉参考图 URL（要能直接 `<img src>` 引用）"
+- "找 1 段适合'雨天阅读' deck 的背景音 hotlink CC0 链接"
+- "Inter 字体的 Google Fonts CDN 链接是什么？兼容性怎么样？"
+- "lucide-react 在 CDN 上的最新版本是？怎么用 unpkg 引？"
+- "查一下 2026 年 Q1 deck 设计趋势的 3 个权威 source"
+- "找一张关于 '数据驱动决策' 的高质量插画 / icon 资源链接"
+- "validation：'人均 GDP 2025 中国' 这个数字"
+
+你的回应固定形态（见下方 Output format）。
+
+---
+
+## 工具
+
+**你只能用这些**：
+
+- `mcp__nodesign__web_search` —— 多 provider 联网搜索。CJK query → baidu 优先；
+  英文 → tavily 优先。次数按 brief 复杂度自己定 —— 单维度事实核验一两次就该收，
+  多维度素材搜集该搜就搜；每次先想清 query，同义反复的重搜是浪费不是勤奋
+- `mcp__nodesign__screenshot_url` —— **外站截图，找视觉参考的主力**。设计参考
+  必须用眼睛看：拿到候选站 URL 后直接截图（默认首屏，够判断气质；要看整页版式
+  传 fullPage:true），基于你真看到的版面/配色/字号描述，别用 WebFetch 的文本
+  转述想象视觉。**单次任务上限 4 张** —— 图占你自己的上下文窗口，挑最有代表性的截；
+  报告里给"你亲眼看过"的具体结论（版式结构 / 主色 / 字号对比 / 图像手法）+ URL
+- `WebFetch` —— SDK 内置。两用途：
+  1. 抓 URL 内容按 prompt 总结（搜索 snippet 不够时；snippet 够就别 fetch）
+  2. **Hotlink 验证**：对资源 URL（图 / 音频）verify 响应 + content-type；prompt
+     写 `'just confirm this URL responds and report HTTP status + Content-Type header'`，
+     fetch 完看返回。hotlink 验证 ≤5 条（候选超 5 条主 agent 也用不完）
+- `Read` / `Glob` / `Grep` —— 看本地 `./assets/` 里的素材 / `./spec.json` 决策档案
+- `TodoWrite` —— 3 步以上研究列计划
+
+**工具集外的工具**（用了也无效，且打破子代理边界）：Write / Edit / Bash / screenshot_canvas / export / record_decision /
+AskUserQuestion —— 你的产物是信息不是修改，跟用户对话由主 agent 负责。研究就是研究。
+
+---
+
+## 工作流（标准）
+
+1. **拆解 brief**：主 agent 给的需求往往不止一个维度（"找 5 个参考 + 取色 +
+   字体推荐" → 拆成 3 个 sub-query）
+2. **搜索**：先 web_search 拿候选；snippet 够用就别 WebFetch（baidu snippet
+   通常 500-3000 字够了）
+3. **筛选**：只保留**直接可用**的 URL —— 图片要返 `https://...png|jpg|webp`，
+   字体要返 CDN link，资源要返直接引用方式
+4. **Hotlink 验证（图片 / 音频资源专用）**：候选 URL 多于 5 条时先按"信息密度"
+   挑 top 5，再用 WebFetch 验每条 200 + Content-Type 匹配：
+   - 图：`image/(png|jpeg|webp|svg+xml|gif)` 接受
+   - 音：`audio/(mpeg|ogg|mp4|wav)` 接受
+   - 403 / referer-required / 404 / wrong content-type → drop，进 NOTES 标
+     "<url> hotlink-blocked / dead / wrong-mime" 一行
+   - **Cap 5 条**（防 fetch 爆 turn）；候选超 5 条主 agent 也用不完
+5. **结构化输出**：按下方 Output format 给主 agent，每条资源含 `validated` + `mime` 字段
+
+---
+
+## 轮次预算与随手记（决定你的工作是不是白干）
+
+你有**硬上限 12 个回合**。超限时 SDK 直接掐断循环——不是提醒你收尾，是当场
+断流，不会再给你说话的机会。真实事故：两次 16-17 次调用的研究在上限处被掐，
+一次只回传了开场白，一次回传了空，几十秒的搜索全部作废。
+
+- **每轮发起工具调用之前，先用一两行 text 记下上一轮拿到的关键结果**
+  （URL / 结论 / 排除项），再调工具。这不是花絮：被掐时主 agent 拿到的就是
+  你**最后一段 text**——平时随手记了，被掐也能交出大半成果；闷头搜到底，
+  被掐就是全损。
+- **预算分配**：拆解 1 轮 + 搜索/截图 ≤7 轮 + 验证 ≤2 轮 + 报告 2 轮。
+  感觉过半还没收敛就立即缩范围——CONFIDENCE: medium 的完整报告，
+  好过被掐断的满地碎片。
+- brief 超过 3 个独立维度时别硬吃：先把吃得下的做完，NOTES 里建议主 agent
+  把其余维度拆成新的子任务。
+
+---
+
+## Output format
+
+收尾用这套结构。主 agent 会按章节抽你的结果——格式漂移会让抽取失败。
+
+```
+RESEARCH BRIEF: <主 agent 给你的原 brief，一句话复述>
+
+FINDINGS:
+
+## <类目 1>（如：参考图 URLs）
+- **<title>** — <一句描述>
+  URL: <https://...>
+  validated: <yes | no | n/a>      # n/a 用于非资源类（字体 CDN / 文档 / 数字）
+  mime: <image/png | audio/mpeg | ...>   # 资源类必填；非资源 omit
+  适用：<什么场景能用 / 为什么挑它>
+
+- **<title>** — ...
+
+## <类目 2>（如：字体推荐）
+...
+
+## <类目 N>
+
+NOTES:
+- <可选：补充说明 / 验证结果 / 不确定的点 / 主 agent 应留意的边界>
+- <hotlink dropped 列表：URL → 原因（403 / dead / wrong-mime）>
+
+CONFIDENCE: <high | medium | low>
+- high  = 多 source 验证，URL 已 fetch 过能用
+- medium = 单 source / snippet 推断，可能要主 agent 自己验
+- low   = 没找到好答案，已尽力，主 agent 自己判断要不要换思路
+```
+
+如果**没找到任何可用结果**：
+```
+RESEARCH BRIEF: <复述>
+
+FINDINGS: (无)
+
+NOTES:
+- 已尝试 query: "..." / "..." / "..."
+- 失败原因：<provider 全 fail / 关键词跑题 / 资源不存在>
+- 建议主 agent：<换关键词 / 跳过这步 / 让用户上传>
+
+CONFIDENCE: low
+```
+
+---
+
+## 推荐源 cheatsheet（hotlink 友好的常用源）
+
+**图**：
+- `unsplash.com` —— 高质量 stock 摄影，hotlink 友好，CC 协议（注明摄影师即可）
+- `pexels.com` —— 同 unsplash 思路，hotlink 多数能用
+- `heroicons.com` —— SVG icon 套，可 hotlink 单 SVG
+- `unpkg.com/lucide@latest` / `cdn.jsdelivr.net/npm/lucide@latest` —— Lucide icon 库 CDN
+- `commons.wikimedia.org` —— 历史图 / 文化主题图（CC0 / CC-BY）
+
+**音**：
+- `pixabay.com/music/` / `pixabay.com/sound-effects/` —— **CC0**，hotlink 直链友好
+- `archive.org` —— 公共领域音频 / 历史录音
+- `soundbible.com` —— 短音效（注意每条单独看协议）
+- ⚠️ `freesound.org` —— 协议杂 + 多数需 API token，**别推荐 hotlink**（直链可能挂）
+
+**字体**：
+- `fonts.googleapis.com` —— Google Fonts，标配
+- `cdn.jsdelivr.net/npm/cn-fontsource-*` —— 中文字体打包（思源黑/宋 / HarmonyOS Sans 等）
+- `cdn.jsdelivr.net/gh/lxgw/lxgw-wenkai-screen-webfont@latest/style.css` —— 霞鹜文楷
+
+**坑**：
+- ❌ Pinterest / 微博 / 公众号图——**全部 hotlink-blocked**（403 + referer 检查）
+- ❌ 各厂商官网截图——多数 hotlink-blocked（hotlink 验证会跳掉）
+- ❌ 图床（图床.com / sm.ms 等）——稳定性差，CDN 缓存可能挂
+- ⚠️ Google Images 搜出来的 URL **是 Google 跳板不是直链**，需要 fetch 跳板页解析真实 src 后才能 `<img src>`
+
+---
+
+## 工作守则（边界）
+
+- **返事实，不返推断 / 设计建议** —— 主 agent 找你研究**事实**，设计判断是它的活。
+  "我认为这个色号好看" 不在你的工作范围；"这是 Stripe 官网用的色号 #635BFF，
+  来源 https://..." 是。
+- **有限收尾** —— 研究是有限动作。搜不到换关键词再试，还不行就报告
+  CONFIDENCE: low 让主 agent 决定。无限迭代会拖垮 turn 预算（硬上限 12 turn，
+  超限当场断流，见「轮次预算与随手记」）。
+- **保 context 健康** —— 调查次数没有死数字，但你的转录会回主 agent 上下文窗口，
+  图和长文是主要开销：截图挑最有代表性的（≤4 张）、Read 大文件没意义、fetch
+  回来的长文自己消化成结论再写报告，别原文转抄。
+- **URL 必须真访问过** —— 给的 URL 是 web_search 真返回过、或 WebFetch 真访问过的。
+  凭印象拼 URL 比"没找到"更糟（错的链接 = 主 agent 写进 deck → 用户点击 404）。
+- **不直接对用户说话** —— 你没有 AskUserQuestion 工具。brief 模糊时在 NOTES 里写
+  "brief 不够具体，建议主 agent 反问用户：'你想要哪种风格—— X / Y / Z'"，
+  让主 agent 去问。
+
+---
+
+## Tone
+
+- 简短、事实、可操作。"https://..../inter.woff2 — Inter Regular，自托管 244KB"
+  比 "Inter 是一款专门为屏幕优化的字体" 有用 10 倍
+- 主 agent 看完你的报告就能**直接 Edit canvas.html 引用**。它不需要你的
+  设计建议

package/server/engine/agents/index.js

@@ -0,0 +1,230 @@
+/**
+ * server/engine/agents/index.js — subagent 定义集合
+ *
+ * 通过 SDK 的 query options.agents 字段挂载 4 个子代理：
+ *
+ *   explorer          — ⏸ 停用中（2026-08-14）。研究员（搜索 + 读资料 + 验证事实）
+ *   vision-checker    — 截图 + a11y / 视觉合理性评审（C14 真实 prompt 在 vision-checker.md）
+ *   ds-extractor      — 抽 design system tokens（C15 真实 prompt + design-system.json schema）
+ *   tweak-proposer    — 推可调 slider schema（C16 真实 prompt + tweak-schema.json schema）
+ *
+ * 调用：main agent 用 Task 工具调（SDK 自动暴露）。
+ * **注意**：'Task' 必须在主 agent 的 toolAllowlist 里（session-loop.js DEFAULT_TOOL_ALLOWLIST）
+ * 否则 SDK 拒绝调用，所有子代理形同摆设。
+ *
+ * P0+ stage 1 范围：
+ *   - 只挂定义骨架，main agent 通过 SKILL.md 引导**不主动调**这些子代理
+ *   - 真调用流程留 stage 2（用户测试 + 真接通 H/F 流时再发力）
+ *   - prompt 在 C14-C16 用 .md 文件填实，本 commit 用占位短句
+ *
+ * AgentDefinition 字段（sdk.d.ts:38）：
+ *   description: string         自然语言描述何时该用
+ *   tools?: string[]            允许的工具，omit 继承父 agent
+ *   disallowedTools?: string[]
+ *   prompt: string              system prompt
+ *   model?: string              alias 或 full id；'inherit' / omit 沿父
+ *   mcpServers?: AgentMcpServerSpec[]
+ *   skills?: string[]
+ *   initialPrompt?: string      首条自动 user 消息
+ *   maxTurns?: number
+ *   background?: boolean        true = fire-and-forget 不阻塞
+ *   memory?: 'user' | 'project' | 'local'
+ *   effort?: EffortLevel | number
+ *   permissionMode?: PermissionMode
+ */
+
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { resolveModelRoute } from '../agent/model-context.js';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+
+/**
+ * 同步读 agents/<name>.md 作为 agent prompt。模块加载时一次性读完，
+ * 后续每次 createAgents() 复用 cache，避免 spawn 时 IO。
+ *
+ * 缺失或读失败时降级到 STUB_PROMPT —— SDK 不至于 crash，main agent
+ * 调用时收到说明文字。
+ */
+const PROMPT_CACHE = {};
+function loadPrompt(name) {
+  if (PROMPT_CACHE[name] !== undefined) return PROMPT_CACHE[name];
+  const file = path.join(HERE, `${name}.md`);
+  try {
+    PROMPT_CACHE[name] = fs.readFileSync(file, 'utf8');
+  } catch (err) {
+    console.warn(`[agents] failed to load ${name}.md (${err.message}); using stub`);
+    PROMPT_CACHE[name] = STUB_PROMPT(name);
+  }
+  return PROMPT_CACHE[name];
+}
+
+const STUB_PROMPT = (name) =>
+  `(P0+ stage 1 placeholder for ${name} agent. agents/${name}.md not found — `
+  + `the file should ship with this commit. If you're an agent reading this, `
+  + `report "agents/${name}.md missing" and stop.)`;
+
+/**
+ * 给定主 model，挑一个搭配的快速 model（subagent + SDK helper 共用）。
+ *
+ * 2026-08-19 起查表：API 通路模型的 fastModel 在 model-context.js 表里逐行配
+ * （必须同表可路由 —— 订阅 haiku 在 API 模式会 404，旧的 DMXAPI haiku-cc
+ * 硬编码就是"换了 api 之后 helper 起不来"的病根之一）。订阅模型沿用主 model
+ * 自己（不强制降级避免拼错模型名导致 404）。env NODESIGN_FAST_MODEL 显式覆盖
+ * 只对订阅路生效，见 session-loop 的通路注释。
+ */
+export function resolveDefaultFastModel(mainModel) {
+  if (!mainModel) return null;
+  const route = resolveModelRoute(mainModel);
+  return route.mode === 'api' ? route.fastModel : mainModel;
+}
+
+/**
+ * 按 role 决定子代理 model。
+ *
+ * - **structural / search 类**（explorer / ds-extractor / tweak-proposer）→ subModel
+ *   功能是搜外链 / 抽 token / 推 slider，capability 不需跟主同级，走 fast model 省成本。
+ *
+ * - **judgment 类**（vision-checker）→ sdkSpoofMain
+ *   视觉评审要看出 plan compliance / palette match / 反 AI 套路这些细节，
+ *   capability 必须跟主 agent 同级——直接喂主 agent **SDK 视角的 model**
+ *   （Kimi 主时是 spoofing alias `claude-opus-4-7[1m]`，SDK 信 1M context；
+ *   binary-fixup-proxy 出口反向还原成真 `kimi-k2.6` 给 gateway）。
+ *
+ *   绕开两个坑：
+ *   1. memory part4 — 喂 SDK 真 `kimi-k2.6` → SDK 不识别 → rawMaxTokens
+ *      fallback 200k → 子代理 context window 被腰斩
+ *   2. memory feedback_kimi_split_messages — `'inherit'` 字面虽被 retract 为非
+ *      root cause，但从未独立验证过；走"具体 sdkModel id 直传"绕开字面解析路径
+ */
+function pickAgentModel(role, { sdkSpoofMain, subModel }) {
+  if (role === 'vision-checker') return sdkSpoofMain || subModel;
+  return subModel;
+}
+
+/**
+ * 创建 agents 配置 —— 喂给 query options.agents 字段。
+ *
+ * @param {object} [opts]
+ * @param {string} [opts.mainModel]    主 agent appModel（如 'kimi-k2.6'）
+ * @param {string} [opts.sdkModel]     主 agent SDK 视角 model（spoofing 后的 alias，如 'claude-opus-4-7[1m]'）。
+ *                                     缺省 = mainModel（非 Kimi 主时两者本就相等）。vision-checker 用这个。
+ * @param {string} [opts.fastModel]    显式覆盖 fast model；优先级：fastModel > NODESIGN_FAST_MODEL > resolveDefaultFastModel(mainModel)
+ * @returns {Record<string, AgentDefinition>}
+ */
+export function createAgents({ mainModel, sdkModel, fastModel } = {}) {
+  const subModel = fastModel
+    || process.env.NODESIGN_FAST_MODEL
+    || resolveDefaultFastModel(mainModel)
+    || mainModel
+    || 'claude-haiku-4-5';
+  // sdkSpoofMain：vision-checker 用的"主 agent SDK 视角 model"。
+  // 调用方未传 sdkModel 时 fallback 到 mainModel（非 Kimi 主时两者相等无害）。
+  const sdkSpoofMain = sdkModel || mainModel;
+  return {
+    // explorer —— 研究员子代理。主 agent 在做 deck/产物时遇到"需要外部素材
+    // / 参考 / 事实验证" 就 Task 派给它。它去搜 + 读 + 总结，给主 agent 一份
+    // 结构化研究报告（URLs / 字体 / 数据 / 趋势）。主 agent 拿报告直接 Edit
+    // canvas.html 用，不必自己分心去搜。
+    //
+    // tools 显式收窄到 read-only researcher：
+    //   - mcp__nodesign__web_search（多 provider 联网搜）
+    //   - mcp__nodesign__screenshot_url（外站截图 —— 找视觉参考要能看见视觉，
+    //     2026-07-29 前只能 WebFetch 文本转述"这个站是深色的"，等于瞎子摸象）
+    //   - WebFetch（SDK 内置，按 prompt 总结 URL 内容）
+    //   - Read / Glob / Grep（看本地 ./assets 和 ./spec.json）
+    //   - TodoWrite（多步研究列计划）
+    // 不给：Write/Edit（不写代码）/ Bash（不要 shell shenanigans）/
+    //       AskUserQuestion（子代理不直接跟用户说话）/ screenshot/export/
+    //       record_decision（不是它的角色）/ Task（不允许嵌套子代理）
+    // ⏸ explorer 研究员（2026-08-14 用户暂时停用："有点没用"）。定义与
+    // prompt（explorer.md）原样保留，恢复 = 取消注释 + prelude 补回子代理
+    // 清单那两行。停用期间搜索/读外链由主 agent 直接用 web_search / WebFetch。
+    // explorer: {
+    //   description: 'Research/explorer subagent. …',
+    //   prompt: loadPrompt('explorer'),
+    //   model: pickAgentModel('explorer', { sdkSpoofMain, subModel }),
+    //   tools: [
+    //     'mcp__nodesign__web_search', 'mcp__nodesign__screenshot_url',
+    //     'WebFetch', 'Read', 'Glob', 'Grep', 'TodoWrite',
+    //   ],
+    //   // maxTurns 12 的来历：8 轮在真实多维 brief 上会被 SDK 硬掐断流
+    //   // （2026-08-05 两次报告全损），提级 + explorer.md「随手记」纪律。
+    //   maxTurns: 12,
+    // },
+
+    'vision-checker': {
+      description:
+        'Visually inspect the current canvas.html design via screenshot. '
+        + 'Use this when you need an independent second-pair-of-eyes review on '
+        + 'whether the design looks right — alignment, contrast, hierarchy, spacing, '
+        + 'a11y readability, and (when design-plan.md exists) per-page plan compliance. '
+        + 'Returns a structured per-page critique with concrete fix suggestions.',
+      prompt: loadPrompt('vision-checker'),
+      // judgment 类——视觉评审 capability 必须跟主 agent 同级，走 sdkSpoofMain
+      // （Kimi 主时是 'claude-opus-4-7[1m]' alias，SDK 信 1M context；proxy 出口
+      // 反向还原成真 'kimi-k2.6' 给 gateway）。详见 pickAgentModel 注释。
+      model: pickAgentModel('vision-checker', { sdkSpoofMain, subModel }),
+      // 显式列 tools：read-only 视觉评审需要的最小集合。
+      // SDK doc 说"omit tools 继承父" 但跨 mcp 工具的继承行为不确定（explorer 也
+      // 显式列 mcp__nodesign__web_search 是同样的稳妥做法）。Phase 1.1 audit 后
+      // 改成显式声明，保证 vision-checker.md 里写的 mcp__nodesign__screenshot_canvas
+      // 真实可调。
+      //
+      // 2026-05-10：新增 list_pages（枚举页数 → 决定循环 pageIndex 上界）+
+      // TodoWrite（多步逐页评审编排，让前端可见 vision-checker 在做啥）。
+      tools: [
+        'mcp__nodesign__screenshot_canvas',
+        'mcp__nodesign__list_pages',
+        'Read', 'Glob',
+        'TodoWrite',
+      ],
+      // maxTurns：逐页评审下界估算 = 1 (Read plan) + 1 (list_pages) + 1
+      // (fullPage 总览) + N (per-page 截图) + 1-2 (think + report)。N 页 deck
+      // 至少 N+5 turn。16 容纳到 ~10 页 deck；超长 deck 主 agent 应 prompt
+      // 里点名分批评审。
+      maxTurns: 16,
+    },
+
+    'ds-extractor': {
+      description:
+        'Extract a design system spec (color tokens, type scale, spacing scale, '
+        + 'shadow tokens, border radius) from the current canvas.html. Returns a '
+        + 'JSON document conformant to schemas/design-system.json. '
+        + 'Use this when the user asks "抽 design system" / "extract design tokens" / '
+        + '"capture the visual rules" — typically right before reusing the style.',
+      prompt: loadPrompt('ds-extractor'),
+      // SDK AgentDefinition 没有 outputFormat 字段（query options 级别才有）。
+      // 子代理走 prompt 内嵌 JSON Schema 引导输出，main agent 收到后 JSON.parse。
+      // schema 文件在 agents/schemas/design-system.json，prompt 里有完整摘录。
+      // structural 类（结构化抽 token），走 fast model
+      model: pickAgentModel('ds-extractor', { sdkSpoofMain, subModel }),
+      tools: [
+        'Read', 'Glob', 'Grep',
+        'mcp__nodesign__list_pages',
+        'mcp__nodesign__read_page',
+        'mcp__nodesign__get_computed_styles',
+      ],
+    },
+
+    'tweak-proposer': {
+      description:
+        'Propose 4–10 tweakable dimensions of the current canvas (e.g., heading '
+        + 'scale, spacing density, accent color, corner style). Returns JSON '
+        + 'conformant to schemas/tweak-schema.json — the frontend renders each '
+        + 'tweak as slider / select / color picker / toggle. Use this when the '
+        + 'user wants to fine-tune without rewriting.',
+      prompt: loadPrompt('tweak-proposer'),
+      // 同 ds-extractor：SDK 不支持 per-agent outputFormat，schema 内嵌 prompt
+      // structural 类（schema 推导），走 fast model
+      model: pickAgentModel('tweak-proposer', { sdkSpoofMain, subModel }),
+      tools: [
+        'Read', 'Glob',
+        'mcp__nodesign__list_pages',
+        'mcp__nodesign__read_page',
+        'mcp__nodesign__expose_tweaks',
+      ],
+    },
+  };
+}

package/server/engine/agents/schemas/design-system.json

@@ -0,0 +1,156 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "$id": "nodesign://schemas/design-system.json",
+  "title": "Design System",
+  "description": "Token-based design system extracted from a canvas.html. Captures the visual rules so a different agent or designer can replicate the style in a new artifact.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["meta", "colors", "typography", "spacing", "radius", "shadow"],
+  "properties": {
+    "meta": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["extractedAt", "sourceArtifact"],
+      "properties": {
+        "extractedAt": { "type": "string", "format": "date-time" },
+        "sourceArtifact": { "type": "string", "description": "Relative path of the canvas this DS was extracted from (usually 'canvas.html')." },
+        "summary": { "type": "string", "description": "One-sentence vibe of the system (e.g., 'editorial monochrome with a single warm accent')." }
+      }
+    },
+
+    "colors": {
+      "type": "object",
+      "description": "Semantic color tokens. Hex with alpha allowed (#RRGGBBAA).",
+      "additionalProperties": false,
+      "required": ["text", "background"],
+      "properties": {
+        "primary":    { "$ref": "#/definitions/colorToken" },
+        "secondary":  { "$ref": "#/definitions/colorToken" },
+        "accent":     { "$ref": "#/definitions/colorToken" },
+        "text":       { "$ref": "#/definitions/colorPalette" },
+        "background": { "$ref": "#/definitions/colorPalette" },
+        "border":     { "$ref": "#/definitions/colorPalette" },
+        "status":     {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "success": { "$ref": "#/definitions/colorToken" },
+            "warning": { "$ref": "#/definitions/colorToken" },
+            "error":   { "$ref": "#/definitions/colorToken" },
+            "info":    { "$ref": "#/definitions/colorToken" }
+          }
+        }
+      }
+    },
+
+    "typography": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["families", "scale"],
+      "properties": {
+        "families": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "sans":  { "type": "string" },
+            "serif": { "type": "string" },
+            "mono":  { "type": "string" }
+          }
+        },
+        "scale": {
+          "type": "object",
+          "description": "Type scale steps. px values (numeric).",
+          "additionalProperties": false,
+          "properties": {
+            "h1":      { "$ref": "#/definitions/typeStep" },
+            "h2":      { "$ref": "#/definitions/typeStep" },
+            "h3":      { "$ref": "#/definitions/typeStep" },
+            "h4":      { "$ref": "#/definitions/typeStep" },
+            "body":    { "$ref": "#/definitions/typeStep" },
+            "small":   { "$ref": "#/definitions/typeStep" },
+            "caption": { "$ref": "#/definitions/typeStep" }
+          }
+        }
+      }
+    },
+
+    "spacing": {
+      "type": "object",
+      "description": "Spacing tokens. px values (numeric). Should follow a consistent rhythm (e.g., 4 / 8 / 12 / 16 / 24 / 32 / 48 / 64).",
+      "additionalProperties": false,
+      "properties": {
+        "xs":   { "type": "number" },
+        "sm":   { "type": "number" },
+        "md":   { "type": "number" },
+        "lg":   { "type": "number" },
+        "xl":   { "type": "number" },
+        "xxl":  { "type": "number" },
+        "page": { "type": "number", "description": "Outer page padding" }
+      }
+    },
+
+    "radius": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sm":   { "type": "number" },
+        "md":   { "type": "number" },
+        "lg":   { "type": "number" },
+        "pill": { "type": "number", "description": "For badges / chips" }
+      }
+    },
+
+    "shadow": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "sm": { "type": "string" },
+        "md": { "type": "string" },
+        "lg": { "type": "string" }
+      }
+    },
+
+    "idioms": {
+      "type": "array",
+      "description": "Recurring composition patterns observed in the canvas (e.g., 'stat row uses 3-column grid with 24px gap', 'each section starts with a 1px border-top'). Capture these so a new artifact can repeat them.",
+      "items": { "type": "string" }
+    }
+  },
+
+  "definitions": {
+    "colorToken": {
+      "type": "string",
+      "pattern": "^#([0-9a-fA-F]{6}|[0-9a-fA-F]{8})$",
+      "description": "Hex color, 6 or 8 chars (RGB or RGBA)."
+    },
+    "colorPalette": {
+      "type": "object",
+      "description": "Tonal scale for semantic role. Keys 100-900 like Tailwind, but only the steps actually used need to appear.",
+      "additionalProperties": false,
+      "properties": {
+        "50":  { "$ref": "#/definitions/colorToken" },
+        "100": { "$ref": "#/definitions/colorToken" },
+        "200": { "$ref": "#/definitions/colorToken" },
+        "300": { "$ref": "#/definitions/colorToken" },
+        "400": { "$ref": "#/definitions/colorToken" },
+        "500": { "$ref": "#/definitions/colorToken" },
+        "600": { "$ref": "#/definitions/colorToken" },
+        "700": { "$ref": "#/definitions/colorToken" },
+        "800": { "$ref": "#/definitions/colorToken" },
+        "900": { "$ref": "#/definitions/colorToken" },
+        "default": { "$ref": "#/definitions/colorToken", "description": "Fallback when no tonal step is needed." }
+      }
+    },
+    "typeStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["fontSize"],
+      "properties": {
+        "fontSize":   { "type": "number", "description": "px" },
+        "lineHeight": { "type": ["number", "string"] },
+        "weight":     { "type": "number", "minimum": 100, "maximum": 900 },
+        "letterSpacing": { "type": ["number", "string"] }
+      }
+    }
+  }
+}