diff --git a/SKILL.md b/SKILL.md
index 221c8f6..d53621e 100644
--- a/SKILL.md
+++ b/SKILL.md
@@ -17,7 +17,7 @@ description: "Render structured interactive UI inline in your reply via the dsh-
展示：`stat` `badge` `progress` `list` `table` `keyvalue` `avatar` `timeline` `file-tree` `breadcrumb` `diff` `json` `code` `callout` `steps`
图表：`chart`（bars/line/donut，可多序列）`plot`（数学函数图）
交互：`button` `input` `select` `checkbox` `radio` `switch` `textarea` `tabs` `accordion` `copy`
-高级：`mermaid`（流程图/时序/甘特等）`scene3d`（3D WebGL）`quiz`（点选判题 + 解析 + 重试）
+高级：`mermaid`（流程图/时序/甘特等）`diagram`（编辑级品牌图，27 种类型）`scene3d`（3D WebGL）`quiz`（点选判题 + 解析 + 重试）
### 布局
- text: `{"type":"text","size":"h1|h2|h3|body|muted|caption","content":"...","center":true?}`
@@ -69,6 +69,7 @@ description: "Render structured interactive UI inline in your reply via the dsh-
### 高级
- mermaid: `{"type":"mermaid","code":"graph TD\\nA-->B"}` — flowchart/sequence/class/gantt/pie/er/state/journey；主题自动跟随宿主（暗/浅）
+- diagram: `{"type":"diagram","kind":"architecture","title":"可选标题","variant":"light|dark|editorial","nodes":[...],"edges":[...],"theme":{...}}` — **编辑级品牌图**（移植自 diagram-design 的 27 种视觉类型）。节点: `{"id":"a","label":"Web","type":"focal|backend|store|external|input|optional|security","x":40,"y":40,"w":128,"h":48,"sub":"可选技术子标签","tag":"可选角标如 API"}`；边: `{"from":"a","to":"b","label":"WRITE","kind":"solid|dashed|accent|link"}`。**规则由渲染器强制**: 正交连接器（r=8 弯折、禁止斜线）、4px 网格、语义 token（paper/ink/muted/accent）、焦点色 ≤2 个、复杂度预算（≤9 节点/≤12 边）、z-order（箭头在节点后）、边标签 6-10px 间隙。27 种 kind：architecture / it-state / flowchart / sequence / state / er / timeline / swimlane / quadrant / radar / loop / nested / tree / org-chart / layers / venn / pyramid / bar / line / gantt / scatter / high-level / process / medallion / data-flow / dp-integration / dp-security-matrix。**坐标类 kind**（architecture/it-state/high-level/process/medallion/data-flow/dp-integration）用 x/y/w/h 精确定位；**规则类 kind** 只给数据自动排版。架构/流程/层次结构优先用 diagram 而非 mermaid（自动布局用 mermaid，编辑级排版用 diagram）。
- scene3d: `{"type":"scene3d","title":"...","meshes":[{"shape":"box|sphere|cone|cylinder|torus","color":"#hex?","size":n|[w,h,d]?,"position":[x,y,z]?,"rotation":[rx,ry,rz]?,"scale":n?|[...]?}],"ambient":0-2?,"background":"#hex?"}` — 3D WebGL，可拖拽旋转、滚轮缩放；mesh 数量 1–5 个
- quiz: `{"type":"quiz","question":"...","options":[{"label":"...","correct":true?,"feedback":"..."?}],"explanation":"...","id":"..."?,"action":"answer"?}` — 教学问答：点选即判题、可重试；`id` 变化时重置；带 action 时答案同时回传模型
@@ -83,6 +84,7 @@ description: "Render structured interactive UI inline in your reply via the dsh-
| 数据对比 / 趋势 / 占比 | `chart`（bars/line/donut）、`table` |
| 关键指标数字 / 进度状态 | `stat`、`progress`、`badge` |
| 流程 / 步骤 / 阶段 / 时间线 | `steps`、`timeline`、`mermaid`（flowchart/sequence/gantt） |
+| 架构 / 系统拓扑 / 数据流 / 品牌图 | `diagram`（编辑级，27 种类型；自动布局需求才用 `mermaid`） |
| 目录 / 文件结构 / 层级关系 | `file-tree`、`mermaid`、`accordion` |
| 状态一览 / 检查结果 | `badge` + `table` + `progress` 组合 |
| 代码 / 配置 / 改动对比 | `code`、`diff`、`json` |
diff --git a/docs/diagram-component-design.md b/docs/diagram-component-design.md
new file mode 100644
index 0000000..b22374d
--- /dev/null
+++ b/docs/diagram-component-design.md
@@ -0,0 +1,246 @@
+# dsh-genui `diagram` 组件设计文档(移植 diagram-design)
+
+> 目标:把 [cathrynlavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
+> 的 27 种编辑级视觉类型 + 设计系统(语义 token、正交连接器、反模式清单)
+> 移植为 dsh-genui 的一等公民组件 `diagram`,让模型能在 ```dsh-ui 围栏里
+> 直接输出品牌化、可访问、编辑级的 SVG 图。
+>
+> 状态:设计定稿(实现前基线)。上游版本:diagram-design v2.4 / dsh-genui 0.8.3。
+
+---
+
+## 1. 设计目标与原则
+
+| 原则 | 含义 |
+|---|---|
+| **一等公民** | `diagram` 进 spec.ts 白名单 + render-node switch,与 `mermaid`/`plot` 同级,自动获得 guard、流式、持久化、自愈 |
+| **声明式 spec** | 模型输出**数据**(节点/边/布局意图),渲染器负责布局与样式——模型不需要手写 SVG path |
+| **编辑级默认** | 正交连接器、4px 网格、语义 token、反模式清单全部编码进渲染器,模型无法产出"AI slop" |
+| **可访问** | 每个图 `role="img"` + `aria-label`/`aria-describedby`;交互不引入 |
+| **上限硬编码** | 节点数、边数、accent 数等沿用 diagram-design 的复杂度预算,守卫层钳制 |
+| **轻依赖** | 纯 React + SVG,无 mermaid/three 运行时依赖;不新增资产路由 |
+
+### 与 mermaid 的关系(不重复)
+
+`mermaid` 已覆盖 flowchart/sequence/class/gantt/pie/er/state/journey 的**自动布局**通用图。
+`diagram` 定位不同:**编辑级布局**——模型提供坐标意图(或按类型规则自动布局),
+渲染器按 diagram-design 规范精确排版。两者并存:用户要"快速自动布局"用 mermaid,
+要"编辑级品牌图"用 diagram。
+
+---
+
+## 2. Spec 形状
+
+### 顶层
+
+```json
+{
+ "type": "diagram",
+ "kind": "architecture | flowchart | sequence | state | er | timeline | swimlane | quadrant | radar | loop | nested | tree | org-chart | layers | venn | pyramid | bar | line | gantt | scatter | high-level | process | medallion | data-flow | dp-integration | dp-security-matrix | it-state",
+ "title": "可选标题(Instrument Serif)",
+ "variant": "light | dark | editorial",
+ "nodes": [ ... ],
+ "edges": [ ... ],
+ "meta": { "focal": 2, "density": 4 }
+}
+```
+
+- `kind` 决定布局语法与复杂度预算(见 §4)。
+- `variant` 缺省跟随宿主主题(`light` 或 `dark`);`editorial` 强制编辑级皮肤。
+- 品牌 token 缺省用内置 style-guide 默认;可选 `theme` 字段覆盖(见 §5)。
+
+### 节点 Node
+
+```json
+{
+ "id": "n1",
+ "label": "用户可见名称(Geist sans)",
+ "sub": "可选技术子标签(Geist mono)",
+ "type": "focal | backend | store | external | input | optional | security",
+ "x": 40, "y": 40, "w": 120, "h": 48,
+ "tag": "可选类型角标,如 API"
+}
+```
+
+### 边 Edge
+
+```json
+{
+ "from": "n1", "to": "n2",
+ "label": "可选边标签(≤14 字符,全大写)",
+ "kind": "solid | dashed | accent | link",
+ "route": "auto | orthogonal | straight"
+}
+```
+
+### 布局模型
+
+**两种模式,由 `kind` 决定:**
+
+1. **坐标模式**(architecture / it-state / high-level / process / data-flow / dp-* 等自由布局类):
+ 模型给 `x/y/w/h`,渲染器负责正交连线、端口选择、桥接、边标签遮罩。
+2. **规则布局模式**(flowchart / sequence / state / er / timeline / swimlane / quadrant /
+ radar / loop / nested / tree / org-chart / layers / venn / pyramid / bar / line /
+ gantt / scatter):模型只给数据,渲染器按类型规则自动排版(与 diagram-design
+ 各 type-*.md 的布局约定一致)。
+
+两种模式都执行**规范强制层**(§6):4px 网格、复杂度预算、反模式检查。
+
+---
+
+## 3. 组件清单(27 种 kind → 渲染策略)
+
+| kind | 布局模式 | 数据形状 | 复杂度预算 |
+|---|---|---|---|
+| `architecture` | 坐标 | nodes+edges+可zone | ≤9 节点,≤12 边,≤3 zones |
+| `it-state` | 坐标 | phase 分组 nodes | ≤9 节点,≤3 阶段 |
+| `flowchart` | 规则 | 节点+分支边 | ≤9 节点 |
+| `sequence` | 规则 | lifelines+messages | ≤5 lifelines,≤1 fragment |
+| `state` | 规则 | states+transitions+guards | ≤9 states |
+| `er` | 规则 | entities+fields+relations | ≤8 entities |
+| `timeline` | 规则 | events on axis | ≤12 events |
+| `swimlane` | 规则 | lanes+steps+handoffs | ≤5 lanes |
+| `quadrant` | 规则 | 2 轴 + items | ≤12 items |
+| `radar` | 规则 | axes+series | ≤5 axes,≤5 series |
+| `loop` | 规则 | hub+stations | ≤8 stations |
+| `nested` | 规则 | containment 树 | ≤6 层 |
+| `tree` | 规则 | 父子树 | ≤4 深 |
+| `org-chart` | 规则 | 归属/汇报树 | ≤12 节点,≤4 深 |
+| `layers` | 规则 | 层列表 | ≤6 层 |
+| `venn` | 规则 | 集合 | ≤3 圆 |
+| `pyramid` | 规则 | 层级值 | ≤6 层 |
+| `bar` | 规则 | 类目值 | ≤8 bars |
+| `line` | 规则 | 序列点 | ≤5 series |
+| `gantt` | 规则 | tasks+phases | ≤12 tasks |
+| `scatter` | 规则 | 点 | ≤30 点 |
+| `high-level` | 坐标 | 栈+集群 | ≤9 节点 |
+| `process` | 坐标 | 多角色步骤+数据交接 | ≤9 节点 |
+| `medallion` | 坐标 | 分层数据存储 | ≤9 节点 |
+| `data-flow` | 坐标 | 角色+步骤 | ≤9 节点 |
+| `dp-integration` | 坐标 | 源→核心→消费者 | ≤9 节点 |
+| `dp-security-matrix` | 规则 | 角色×权限矩阵 | ≤9×9 |
+| `it-state` | 坐标 | 阶段分组 | ≤9 节点 |
+
+> 具体每个 kind 的 spec 字段与布局规则见 `docs/diagram-kinds.md`(随实现同步生成)。
+
+---
+
+## 4. 设计系统(内置 style-guide,语义 token)
+
+渲染器内置 diagram-design 的默认皮肤,以 CSS 变量或 SVG 常量形式存在:
+
+| 角色 | Light | Dark |
+|---|---|---|
+| `paper` | `#f5f5f5` | `#2d3142` |
+| `paper-2` | `#ececec` | `#393e53` |
+| `ink` | `#2d3142` | `#f5f5f5` |
+| `muted` | `#4f5d75` | `#bfc0c0` |
+| `soft` | `#7a8399` | `#8e98ac` |
+| `rule` | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
+| `accent` | `#eb6c36` | `#f08a59` |
+| `accent-tint` | `rgba(235,108,54,0.08)` | `rgba(240,138,89,0.10)` |
+| `link` | `#2e5aa8` | `#6a95d8` |
+
+- **焦点规则**:`accent` 只上 1–2 个元素;spec 的 `meta.focal` 计数,超出降级为 `ink`。
+- **节点类型 → 填充/描边**:focal→accent-tint/accent;backend→white/ink;
+ store→ink@5%/muted;external→ink@3%/ink@30%;input→muted@10%/soft;
+ optional→ink@2%/ink@20% dashed;security→accent@5%/accent@50% dashed。
+- **字体栈**:标题 Instrument Serif;节点名 Geist sans 600;子标签/边标签 Geist Mono。
+ (渲染器内用 CSS 栈,不强制外链 Google Fonts——宿主已提供字体环境时直接继承。)
+
+### 主题覆盖(可选)
+
+```json
+"theme": { "paper": "#fffdf7", "ink": "#2a2416", "accent": "#c94f1e" }
+```
+
+渲染器合并进语义 token;未提供字段回退内置默认。PR 阶段先支持整组 token 覆盖,
+品牌抓取(onboarding)属于后续迭代(见 §9)。
+
+---
+
+## 5. 渲染器结构
+
+新增 `src/client/blocks/diagram.tsx`(+ 必要时 `diagram/` 子模块):
+
+```
+src/client/blocks/diagram/
+ index.tsx # DiagramNode 入口:variant/主题解析、复杂度守卫、a11y 外壳
+ layout.ts # kind → 布局器(坐标透传或规则布局)
+ geometry.ts # 正交连接器(elbow path r=8)、端口选择、桥接、边标签遮罩
+ theme.ts # 语义 token 表 + 主题合并
+ kinds/ # 每个规则布局 kind 一个布局器(共 ~27,可分组)
+```
+
+**接入点:**
+- `src/client/spec.ts` — 新增 `GenuiDiagram` / `GenuiDiagramNode` / `GenuiDiagramEdge` 接口,并入 `GenuiNode` 联合。
+- `src/client/blocks/render-node.tsx` — `case 'diagram': return `。
+- `src/client/guard.ts` — 新增 `maxDiagramNodes`(9)/`maxDiagramEdges`(12)/`maxDiagramZones`(3)等上限,
+ 并在 `repairGenuiSpec` 里按 kind 钳制(未知 kind 降级为 `architecture` 或丢弃)。
+- `src/client/GenuiBlock.module.css` — diagram 容器样式(尺寸、边框、可访问焦点)。
+- `src/plugin/index.ts` 的 `GENUI_SECTION_TEXT` + `SKILL.md` — 教模型 `diagram` 语法。
+
+**可访问性:** 根 `