scrum-skills 0.3.2 → 0.3.3

package/.agents/skills/diagram-design/references/style-guide.md

@@ -0,0 +1,236 @@
+# Style Guide
+
+> **本项目有效皮肤：** [`style-vivid.md`](style-vivid.md) —— 纯白 `#ffffff` 纸面、`#0b0b0f` 墨色、
+> 五个高饱和语义色（`#334155` / `#be123c` / `#047857` / `#b45309` / `#6d28d9`）+ 内联线性图标。
+> 与下表的出厂默认值冲突时，以 `style-vivid.md` 为准：本项目不画米白纸，也不用单一珊瑚 accent。
+
+**The single source of truth for colors, typography, and tokens.** Every diagram draws from this — not from hex values inlined in other reference files. If you want to change the visual skin of Diagram Design, change this file.
+
+Default skin is a cool editorial palette — white-smoke paper, jet-black ink, burnt-tangerine accent, blue-slate muted. It's designed to look good out of the box; swap these values (or run [`onboarding.md`](onboarding.md)) and every new diagram inherits the new skin without touching any type-specific logic.
+
+To generate your own from a website URL, see [`onboarding.md`](onboarding.md).
+
+---
+
+## Tokens
+
+### Semantic roles
+
+Every token is referred to by **semantic role**, not by its hex value. Type references (`type-*.md`) and SKILL.md say `accent`, not `#bf4520`.
+
+| Role | Purpose | Default (light) | Default (dark) |
+|---|---|---|---|
+| `paper` | Page background, default node fill | `#f5f5f5` (white-smoke) | `#2d3142` (jet-black) |
+| `paper-2` | Diagram container bg, secondary fill | `#ececec` | `#393e53` |
+| `ink` | Primary text, primary stroke | `#2d3142` (jet-black) | `#f5f5f5` (white-smoke) |
+| `ink-strong` | High-contrast text on warm accent fills | `#111111` | `#111111` |
+| `muted` | Secondary text, default arrow stroke | `#4f5d75` (blue-slate) | `#bfc0c0` (silver) |
+| `soft` | Sublabels, boundary labels | `#5a6580` | `#949eb2` |
+| `rule` | Hairline borders | `rgba(45,49,66,0.12)` | `rgba(245,245,245,0.12)` |
+| `rule-solid` | Stronger borders, baselines | `#bfc0c0` (silver) | `rgba(191,192,192,0.25)` |
+| `accent` | Focal / 1–2 max per diagram | `#bf4520` (burnt-tangerine) | `#f08a59` |
+| `accent-tint` | Fill for accent-bordered boxes | `rgba(191,69,32,0.08)` | `rgba(240,138,89,0.10)` |
+| `link` | HTTP/API calls, external arrows | `#2e5aa8` | `#739fdf` |
+
+> **Brand palette source:** this skin maps to a five-color brand palette: `jet-black #2d3142`, `silver #bfc0c0`, `white-smoke #f5f5f5`, `atomic-tangerine`, `blue-slate #4f5d75`. The light `accent` is not the raw brand tangerine. Raw atomic-tangerine reads 2.86:1 on `paper`, too faint for an arrow or a label, so the skin uses `#bf4520`, the same hue darkened until it clears 4.5:1 as text. The `soft`, `rule`, and `link` tokens are derived (a darker slate, ink at opacity, and a saturated variant in the blue-slate hue family) to cover roles the brand palette doesn't name directly. Every derived value is held to the contrast contract below.
+
+### Contrast contract
+
+Every token must clear the threshold for each role it plays, against the background it actually sits on, in both skins. `scripts/verify-contrast.py` computes the WCAG 2.x ratio for every row above against the `paper` of its skin (`ink-strong` against the 0.85 `accent` fill it labels) and fails CI when one falls short.
+
+| Use | Minimum vs. its actual background |
+|---|---|
+| Regular text, including any `soft`, `link`, or `accent` used as text | 4.5:1 |
+| Large text (24px+, or 18.7px+ at weight 600+) | 3:1 |
+| Essential non-text marks: lines, arrows, borders, focus outlines, data points | 3:1 against the adjacent color |
+| Decorative rules and translucent tints (`rule`, `rule-solid`, `paper-2`, `accent-tint`, fills at opacity) | No minimum, but never the only carrier of meaning |
+
+- **A token used in several roles must pass each one.** `accent` is a stroke in one place and a label in another, so it is held to 4.5:1, not the 3:1 its strokes alone would need. Don't assume a token is non-text because it usually is.
+- **Translucent colors are composited first.** An `rgba()` fill or stroke is blended over `paper` before its ratio is measured. A value that clears the bar at full strength can fail at 0.5 opacity.
+- **Surfaces other than `paper` cost contrast.** Inside an `accent-tint` box or on `paper-2` every ratio drops. Measure text placed there against that surface, not against `paper`.
+- **Current defaults:** light `accent` 4.71:1, `soft` 5.34:1, `link` 6.13:1, `muted` 6.11:1 on `#f5f5f5`; dark `accent` 5.21:1, `soft` 4.78:1, `link` 4.76:1 on `#2d3142`.
+
+### Inversion rule (light → dark)
+
+Any `rgba(45,49,66, X)` in light becomes `rgba(245,245,245, X)` in dark. Same opacities, RGB flipped. The accent gets a slight hue-shift brighter to read on dark paper.
+
+### Series palette (multi-series chart types only)
+
+A small set of desaturated, editorial-tone colors for chart types that genuinely need to distinguish multiple overlapping entities (currently: **radar**). The "1-focal" rule still holds — `accent` is reserved for the focal series; the palette below covers the rest.
+
+| Token | Light | Dark | Notes |
+|---|---|---|---|
+| `series-1` | `#7c8f6f` (sage) | `#9caf8f` | Non-focal series |
+| `series-2` | `#5e7a9b` (dusty-blue) | `#82a0c0` | Non-focal series |
+| `series-3` | `#b8915a` (mustard) | `#d3ad7a` | Non-focal series |
+| `series-4` | `#9c6b50` (rust-brown) | `#b88670` | Non-focal series |
+| `series-5` | `#6e6479` (slate) | `#8d8298` | Non-focal series |
+
+Fills sit at `0.18` opacity light, `0.22` dark; strokes use the full color. **Don't backfill these tokens to non-chart types** — architecture, swimlane, etc. continue to use muted-ink variants. The series palette is opt-in for diagrams where overlapping shapes demand distinguishable color, not a license to add color elsewhere.
+
+### Terminal skin (opt-in alternate)
+
+A self-contained palette for the terminal-window primitive (see [primitive-terminal.md](primitive-terminal.md)) — a CLI-chrome register for dev-tool posts and technical social cards. It does not replace the default skin above and isn't affected by onboarding; it's a second, fixed skin you opt into per-diagram.
+
+| Token | Hex | Purpose |
+|---|---|---|
+| `terminal-page` | `#0a0a0a` | Page background behind the window |
+| `terminal-paper` | `#141414` | Window body, node fill |
+| `terminal-bar` | `#1b1b1b` | Titlebar strip |
+| `terminal-border` | `#2b2b2b` | Window border, hairlines |
+| `terminal-ink` | `#f5f5f5` | Primary text, primary stroke (same white-smoke as default `ink`) |
+| `terminal-muted` | `#9a9a9a` | Secondary text, sublabels, ring stroke |
+| `terminal-soft` | `#5c5c5c` | Tertiary — inactive dots, spokes |
+| `terminal-accent` | `#ff5a36` | The one accent — focal station, prompt sign, active dot |
+| `terminal-accent-tint` | `rgba(255,90,54,0.12)` | Fill for accent-bordered boxes |
+
+**1-accent rule still holds.** Everything that isn't `terminal-ink` or `terminal-muted`/`terminal-soft` should be `terminal-accent` — never introduce a second hue.
+
+---
+
+## Typography
+
+| Role | Family | Size | Weight | Usage |
+|---|---|---|---|---|
+| `title` | Instrument Serif | 1.75rem | 400 | Page H1 |
+| `node-name` | Geist (sans) | 12px | 600 | Human-readable labels |
+| `sublabel` | Geist Mono | 9px | 400 | Port, protocol, URL, field type |
+| `eyebrow` | Geist Mono | 7–8px | 500, tracked 0.18em, uppercase | Type tags, axis labels |
+| `arrow-label` | Geist Mono | 8px | 400, tracked 0.06em | Arrow annotations |
+| `callout` | Instrument Serif *italic* | 14px | 400 | Editorial asides only |
+
+### Font stack
+
+```html
+<link href="https://fonts.googleapis.com/css2?family=Instrument+Serif:ital@0;1&family=Geist:wght@400;500;600&family=Geist+Mono:wght@400;500;600&family=Noto+Serif:ital@0;1&family=Noto+Sans+KR:wght@400;500;600&family=Noto+Serif+KR:wght@400&family=Noto+Sans+TC:wght@400;500;600&family=Noto+Serif+TC:wght@400&display=swap" rel="stylesheet">
+```
+
+### Font source
+
+The font source decides whether a diagram makes any network request. It is a skin setting, so a saved profile carries it too.
+
+Font source: `web`
+
+| Value | What ships | Network |
+|---|---|---|
+| `web` (default) | The Google Fonts `<link>` above; text renders in Instrument Serif, Geist, and Geist Mono | One stylesheet request to `fonts.googleapis.com`, plus the font files |
+| `system` | No font `<link>`; every family stack falls through to the platform's own serif, sans, and monospace faces | None |
+
+Use `system` when the user asks for offline output, system fonts, or no Google Fonts, or when this line says `system`. In `system` mode:
+
+- Omit the font `<link>` (and the export `@import`) entirely. Keep every `font-family` stack as written: each one already ends in a generic family (`serif`, `system-ui, sans-serif`, `ui-monospace, monospace`), so a viewer who has Geist installed still gets it and everyone else gets their system face.
+- Fallback faces have different metrics from Geist, so keep the 8px label padding intact rather than trimming boxes to the Geist measurement.
+- Export with `（导出由看板完成：从产物 HTML 抽取 SVG，PNG 在浏览器端渲染）
+
+The render linter's default run (`lint-render.py` with network blocked) measures exactly this fallback rendering, so every shipped template and example is already checked in system-font mode.
+
+To keep the editorial faces with no network at all, install Instrument Serif, Geist, and Geist Mono locally (all three are SIL Open Font License) and use `system`: the stacks resolve to the installed faces first.
+
+### Korean labels
+
+Geist and Instrument Serif carry no Hangul. A Korean `<text>` element extends its own family — never swap the skin:
+
+```svg
+<text font-family="'Geist', 'Noto Sans KR', 'Apple SD Gothic Neo', 'Malgun Gothic', sans-serif">결제 서비스</text>
+```
+
+Both Noto faces ship in the font link above, so the web font resolves before any locally installed one and the same file renders identically on macOS, Windows, and a reviewer's browser. The local families follow it for offline viewing. Page titles need the serif equivalent — `'Instrument Serif', 'Noto Serif KR', serif` — or a mixed Latin/Korean title resolves Hangul through the platform's generic serif and the two halves disagree. Google's `css2` endpoint slices Korean by unicode-range, so a diagram with a handful of Korean labels downloads only the slices it touches. The four templates carry both faces because a new diagram may contain Hangul; the shipped Latin-only examples keep the shorter link, since a file with no Hangul has nothing to resolve.
+
+**Width budget.** Measure per character, not per script: **every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance** (0.60em sans, 0.62em mono), and nonspacing/enclosing marks cost nothing. Sum over the string and multiply by the font size for the text width, then add padding and round the box up to the next multiple of 4. `verify-treemap.py` enforces exactly this text width for treemap cell labels; the padding and rounding are authoring convention, and no other type carries an automatic check, so on those the budget is yours to hold.
+
+Counting by script is the trap. `주문 v2.1` is two full-width syllables and five narrow characters; a formula that tallies Hangul, Latin letters, and spaces silently drops `2`, `.`, and `1` and sizes the box for four of its seven characters. Every rendered character costs something — measure per character, never per script.
+
+Three rules follow from Hangul metrics:
+
+- **Sublabels stay Latin.** Ports, protocols, field types, and URLs are Latin anyway — keep `Geist Mono` there and don't translate them. Hangul in a 9px mono sublabel is unreadable and has no mono face to fall back to.
+- **Floor of 12px.** Hangul goes muddy below 12px. If a Korean name doesn't fit at 12px, cut the name — don't shrink the type.
+- **Arrow labels, eyebrows, and legend text switch register.** Those slots are 7–8px Geist Mono, uppercase and tracked, which Hangul has neither a face nor legibility for. A Korean label in one of those slots becomes 12px sans at weight 500 with no tracking and no uppercase transform, and its mask rect grows to match (16px tall, width from the budget above, still rounded to a multiple of 4). Latin labels in the same diagram keep the mono treatment.
+
+**Load-bearing rule:** Mono is for *technical* content (ports, commands, URLs, field types). Names go in Geist sans. Page title is Instrument Serif. Italic Instrument Serif is reserved for annotation callouts (see [primitive-annotation.md](primitive-annotation.md)). **Never JetBrains Mono** as a blanket "dev" font.
+
+### Traditional Chinese labels
+
+Geist and Instrument Serif carry no Han. A Traditional Chinese `<text>` element extends its own family — never swap the skin:
+
+```svg
+<text font-family="'Geist', 'Noto Sans TC', 'PingFang TC', 'Microsoft JhengHei', sans-serif">請求項比對</text>
+```
+
+Both Noto TC faces ship in the font link above, so the web font resolves before any locally installed one and the same file renders identically on macOS, Windows, and a reviewer's browser. The local families follow it for offline viewing. Page titles need the serif equivalent — `'Instrument Serif', 'Noto Serif TC', serif` — or a mixed Latin/Han title resolves Han through the platform's generic serif and the two halves disagree. Google's `css2` endpoint slices Chinese by unicode-range, so a diagram with a handful of Chinese labels downloads only the slices it touches.
+
+**Width budget.** The per-character contract above is unchanged: every Unicode wide or full-width character costs 1em, every other character costs its face's Latin advance, and nonspacing marks cost nothing. Full-width punctuation — `（）「」，。：` — is wide and costs 1em as well, which is the part most often dropped.
+
+Counting by script is the trap. `請求項 v2.1` is three full-width characters and five narrow ones; a formula that tallies Han and Latin letters silently drops `2`, `.`, and `1` and sizes the box for six of its nine characters.
+
+Three rules follow from Han metrics, mirroring the Hangul ones:
+
+- **Sublabels stay Latin.** Ports, protocols, field types, and URLs are Latin anyway — keep `Geist Mono` there and don't translate them. Han in a 9px mono sublabel is unreadable and has no mono face to fall back to. A sublabel that is prose rather than a value may be Chinese, but it then switches register by the third rule below.
+- **Floor of 12px.** Han packs more strokes than Hangul into the same em box, so the 12px floor binds at least as hard here. If a Chinese name doesn't fit at 12px, cut the name — don't shrink the type.
+- **Arrow labels, eyebrows, and legend text switch register.** Those slots are 7–8px Geist Mono, uppercase and tracked, which Han has neither a face nor legibility for. A Chinese label in one of those slots becomes 12px sans at weight 500 with no tracking and no uppercase transform, and its mask rect grows to match (16px tall, width from the budget above, still rounded to a multiple of 4). Latin labels in the same diagram keep the mono treatment.
+
+Simplified Chinese takes the same three rules with the Simplified stack (`'Noto Sans SC'`, `'PingFang SC'`, `'Microsoft YaHei'`). That face does not ship in the link, so Simplified labels still resolve through whatever the viewer has locally.
+
+### Cyrillic labels
+
+Geist and Geist Mono ship Cyrillic (`cyrillic` and `cyrillic-ext` on Google Fonts), so names, sublabels, arrow labels, eyebrows, and legend text in Bulgarian, Russian, Ukrainian, or Serbian keep the Latin treatment: same faces, sizes, tracking, and uppercase. There is no register switch: Hangul and Han switch register because Geist Mono has no face for them, and Geist Mono does cover Cyrillic.
+
+Instrument Serif carries no Cyrillic. A page title extends its family — `'Instrument Serif', 'Noto Serif', serif` — or a mixed Latin/Cyrillic title resolves Cyrillic through whatever face comes next and the two halves disagree. Noto Serif ships in the font link above, upright and italic, so an italic callout in Cyrillic takes the same stack.
+
+**Noto Serif goes ahead of the CJK serifs.** When a stack also lists `'Noto Serif KR'` or `'Noto Serif TC'`, put `'Noto Serif'` ahead of them. Google Fonts slices Cyrillic into those faces as well, so a stack that reaches a CJK face first draws its Cyrillic from it. That is why the templates put `'Noto Serif'` between `'Instrument Serif'` and `'Noto Serif KR'`; Noto Serif has no Hangul or Han, so Korean and Chinese titles pass straight through it.
+
+**Width budget.** The per-character contract above is unchanged: every character costs its face's Latin advance (0.60em sans, 0.62em mono). It fits Geist Mono exactly and Geist sans only on average. Geist Mono is monospaced: a Cyrillic glyph advances exactly as far as a Latin one, so sublabels, arrow labels, eyebrows, legend text, and their mask rects are sized as for Latin. Geist sans is not. Its wide Cyrillic letters, capitals and lowercase alike (such as `Ж Ш Щ Ю Ы`, `ж ш щ ы ю`), run well past the 0.60em average: `Шкаф ODF-2` at 12px is budgeted at 72px and draws at about 76. Rounding the box up to a multiple of 4 recovers at most 3px, so it is not the remedy. Leave the overshoot in the box padding and measure a Cyrillic sans name in the browser — `verify-treemap.py` holds the budget, not the drawn width, so it will not catch the overshoot.
+
+Counting by script is still the trap. `Шкаф ODF-2` is four Cyrillic letters, a space, three Latin letters, a hyphen, and a digit; a formula that tallies Cyrillic letters, Latin letters, and spaces silently drops `-` and `2` and sizes the box for eight of its ten characters.
+
+**Preserve printed labels.** A label the reader matches against a physical thing — a cabinet, a splice closure, a port map — carries the exact printed string. Don't transliterate it and don't re-case it; if one has to sit in an uppercase slot such as an eyebrow, drop the transform for that label rather than re-case the printed string. `Шкаф ODF-2` stays `Шкаф ODF-2`, not `Shkaf ODF-2`.
+
+---
+
+## Stroke, radius, spacing
+
+| Token | Value | Use |
+|---|---|---|
+| `stroke-thin` | `0.8` | Tag-box outlines, leaf nodes |
+| `stroke-default` | `1` | Most strokes |
+| `stroke-strong` | `1.2` | Emphasis strokes |
+| `radius-sm` | `4` | Small tags |
+| `radius-md` | `6` | Node boxes |
+| `radius-lg` | `8` | Containers, rings |
+| `grid` | `4` | Every coord, size, and gap is divisible by 4 (hard rule) |
+
+---
+
+## Node type → treatment
+
+Semantic role combinations — reference these by name in type specs.
+
+| Type | Fill | Stroke |
+|---|---|---|
+| `focal` (1–2 max) | `accent-tint` | `accent` |
+| `backend` | `#ffffff` (white) | `ink` |
+| `store` | `ink @ 0.05` | `muted` |
+| `external` | `ink @ 0.03` | `ink @ 0.30` |
+| `input` | `muted @ 0.10` | `soft` |
+| `optional` | `ink @ 0.02` | `ink @ 0.20` dashed `4,3` |
+| `security` | `accent @ 0.05` | `accent @ 0.50` dashed `4,4` |
+
+---
+
+## Customizing the skin
+
+Four options:
+
+1. **Run onboarding** — see [`onboarding.md`](onboarding.md). Drop a URL; the skill extracts the palette + fonts and rewrites this file.
+2. **Edit by hand** — change the hex values in the tables above. Run the pre-output taste gate afterward to verify the accent still reads as "focal" against the new paper color.
+3. **Brand handoff** — paste your existing design-token JSON into a new section here and map its tokens to the semantic roles above.
+4. **Client profiles** — save and switch named skins, or bind one to a project, using [`profiles.md`](profiles.md).
+
+### Constraints (don't break these)
+
+- **Contrast**: every text token (`ink`, `muted`, `soft`, `link`, and `accent`) must clear 4.5:1 on `paper`, in both skins. See the [contrast contract](#contrast-contract); `scripts/verify-contrast.py` checks it.
+- **One accent**: pick one color for `accent`. Two accents erases the focal signal.
+- **No rainbow palette**: if your brand ships 8 colors, pick 3 (paper, ink, accent). The rest become `muted` variants.
+- **Serif + sans + mono**: three families, not more. If brand typography is all sans, keep Instrument Serif for `title` and `callout` anyway — the contrast is load-bearing.
+- **Paper is warm-neutral, not pure white**: pure white turns the design sterile. Pick a cream, bone, or light grey with a hint of warmth.
+- **Dot pattern is optional, not default**: the 22×22 dot pattern is an opt-in "dotted paper" variant (good for long-form editorial hero diagrams). The default background is a clean `paper` fill, no pattern. When the pattern is enabled, it should sit at ~10% opacity of `ink` on `paper` — visible but quiet.
+- **Container is clean by default**: the diagram sits directly on the page paper, no secondary container background or border. A framed variant (`paper-2` bg + `rule` border + 8px radius + padding) is available as an opt-in for card-heavy layouts, but don't reach for it by default — the extra chrome fights the figure.

package/.agents/skills/diagram-design/references/style-vivid.md

@@ -0,0 +1,148 @@
+# Vivid White —— 本项目有效皮肤（覆盖 style-guide.md 的出厂默认）
+
+> 本文件由 `scripts/sync-diagram-skill.mjs` 注入到 `.agents/skills/diagram-design/references/style-vivid.md`。
+> 改皮肤改这里，不要直接改 skill 目录（同步会被覆盖）。
+>
+> **它优先于 `style-guide.md` 的默认 token。** 两者冲突时以本文件为准；
+> 出厂默认的米白纸（`#f5f5f5`）、近黑墨（`#2d3142`）、单一珊瑚 accent（`#bf4520`）在本项目**一律不用**。
+
+## 0. 一句话方向
+
+**纯白纸面 + 粗黑骨架 + 五个高饱和语义色 + 白色线性图标。**
+
+像一张印在铜版纸上的信息图：底色是亮的，边框是硬的，颜色是敢用的，但每个颜色都有明确归属。
+不是莫兰迪、不是暗色仪表盘、不是灰阶为主只点一抹珊瑚。
+
+三条不可让：
+
+1. **纯白**：页面与图面 `#ffffff`，不许米白、象牙、纸纹、渐变底。
+2. **高对比**：正文墨色 `#0b0b0f`（19.64:1），任何文字/图标对底色 ≥ 4.5:1。
+3. **图标区分**：每个语义节点（状态、阶段、角色、存储）必须有一个线性图标，不靠纯文字。
+
+## 1. 纸面与墨色
+
+| Role | Hex | 白底对比 | 用途 |
+|---|---|---|---|
+| `paper` | `#ffffff` | — | 页面与图面底色，唯一背景 |
+| `panel` | `#f4f4f5` | 1.10:1 | 只给「证据面板 / 数据带」这类二层容器，必须配 2px `ink` 实线边框 |
+| `ink` | `#0b0b0f` | 19.64:1 | 主文字、主描边、卡片边框 |
+| `muted` | `#3f3f46` | 10.44:1 | 说明文字、次要标签 |
+| `soft` | `#52525b` | 7.73:1 | 出处、图例小字、刻度 |
+| `rule` | `#e4e4e7` | 1.27:1 | 卡内分隔线、刻度基线（仅装饰，不承载语义） |
+
+- 背景是**一整块白**。不要给整张图套灰底容器，不要点阵纹理。
+- 分层靠**边框与色带**，不靠阴影深浅。
+
+## 2. 语义色板（一个色相只归属一个语义）
+
+| Token | Hex | 白底对比 | 语义（本项目） |
+|---|---|---|---|
+| `state-todo` | `#334155` | 10.35:1 | todo / 待办 / 未开始 |
+| `state-red` | `#be123c` | 6.29:1 | red / 失败 / 缺陷 / 阻断 |
+| `state-green` | `#047857` | 5.48:1 | green / 通过 / 正常 |
+| `state-refactor` | `#b45309` | 5.02:1 | refactored / 重构 / 打磨 |
+| `state-done` | `#6d28d9` | 7.10:1 | done / 交付 / 焦点结论 |
+| `link` | `#1d4ed8` | 6.70:1 | 旁路、外部调用、类型例外 |
+
+规则：
+
+- **色相预算 5**（+ `link` 例外）。第 6 个颜色不是设计，是噪音。
+- **一个色相只解释一件事**：`#be123c` 在这张图里永远是 red，下一张图里也还是「失败」。同一份数据里换色 = 读者白学一遍。
+- 色块可以铺满（图标底、色带、进度段），但**彩色文字一律用上表的深色值**，不要用亮粉/亮绿那类 3:1 的糖果色。
+- 反白图标/文字放在语义色实底上，对比度与上表一致（≥ 4.5:1）。
+- 中性色不抢戏：结构、次要说明用 `ink` / `muted` / `soft`，不额外引入第 6 种灰蓝。
+
+## 3. 结构语法
+
+| 元素 | 做法 |
+|---|---|
+| 节点卡 | 白底 + **2px `ink` 描边** + `rx=10`；顶部一条 **8px 高的语义色带**（沿卡宽，上两角圆角） |
+| 硬投影 | 卡片背后偏移 `6px,6px` 的同色块（语义色 20% 与白混合后的实色，**0 模糊**）。这是唯一允许的「阴影」，禁止高斯模糊光晕 |
+| 序号 | 右上角大号等宽数字 `01`–`05`，语义色实色，24–30px 700 |
+| 图标徽章 | 左上角 40–44px 圆角方块，语义色实底 + 白色线性图标（`stroke=#ffffff`, `stroke-width=2.2`） |
+| 主标题 | 页面 `h1` 28–34px，`ink`，700；左侧 8px 语义色竖条或下方 4px 色带做锚 |
+| 数据带 | `panel` 底 + 2px `ink` 边 + 4px 顶部多色条；每列左侧 4px 竖色条对应语义 |
+| 连接线 | 2.4px，颜色 = **目标状态**的语义色；箭头 marker 与之同色；旁路用 `link` 虚线 `6,5` |
+| 进度轨 | 一条 10px 高的横向色带，按状态切成 4px 白缝的分段，每段一个语义色 |
+| 图例 | 底部横条，白底无框；每项：色块/线型 + 12px `muted` 文字，绝不浮在图中间 |
+
+几何仍守 4px 网格；`rx` 允许 4 / 6 / 10，不用胶囊（`rx≥999`）当标签。
+
+## 4. 图标（必须）
+
+- **每个语义节点一个图标**，取 Tabler Icons 的线性款（MIT），`24×24`、`stroke-width` 2–2.2、`stroke-linecap/linejoin=round`，内联进 SVG。
+- 图标一律 `aria-hidden="true"`，不参与无障碍树；页面上唯一可访问的 `<svg>` 是整张图。
+- 不用 emoji、不用字体图标、不引 `icons.html` 或远程 SVG。
+- 状态机常用搭配：`clipboard-list`（待办）、`bug`（失败）、`circle-check`（通过）、`adjustments`（重构）、`trophy`（交付）。
+- 图标与颜色**同时**编码语义：色盲读者看形状，正常读者看颜色。只靠颜色区分是失败。
+
+## 5. 字体
+
+| Role | 中文 / 通用 | 尺寸 | 字重 |
+|---|---|---|---|
+| `title` | `PingFang SC` / `Noto Sans SC` / system-ui | 28–34px | 700 |
+| `eyebrow` | `ui-monospace` + 中文字体回退 | 10–11px，字距 0.18em，大写 | 600 |
+| `node-name` | 等宽（状态 id / 字段名） | 14–15px | 700 |
+| `body` | `PingFang SC` / `Noto Sans SC` / system-ui | 12px（下限） | 400–500 |
+| `label` | `PingFang SC` / system-ui | 12px | 600–700 |
+
+- **中文不小于 12px**，8px 的中文在截图里就是灰块。
+- 等宽只给 id、命令、字段名、状态码；中文说明一律无衬线。
+- 不引 Google Fonts（中文用系统字体，离线也能看）；纯白底 + 系统字体已经够锐。
+
+## 6. 复杂度
+
+- 节点 ≤ 9，连线 ≤ 12，图标徽章 ≤ 9。
+- 「焦点」不再靠单一 accent，而靠**色相归属 + 尺寸差**：结论节点可以更大、更粗，不必再借第 6 种颜色。
+- 超过预算就拆两张：一张主流程，一张证据/明细。
+
+## 7. 禁止项（与出厂皮肤的差异点）
+
+| 禁止 | 原因 |
+|---|---|
+| 米白 / 象牙 / 纸纹 / 暗色底 | 用户明确要纯白；杂底会把饱和色拉脏 |
+| 只点一抹珊瑚，其余全灰 | 那是编辑风，不是本项目要的张扬 |
+| 彩色小字用糖果色（`#16a34a`、`#f43f5e`） | 白底过不了 4.5:1 |
+| 高斯模糊阴影 / 发光 / 玻璃拟态 | 廉价；硬投影才配得上粗边框 |
+| 纯文字节点（没有图标） | 五个状态会长得一模一样 |
+| 同一色相承担两种语义 | 读者无法建立颜色记忆 |
+| emoji 当图标 | 平台字体不同，跨端会崩 |
+
+## 8. 可直接套用的片段
+
+卡片（含色带、硬投影、图标徽章）：
+
+```svg
+<!-- 硬投影：语义色 20% 与白混合后的实色，偏移 6px，无模糊 -->
+<rect x="46" y="222" width="180" height="168" rx="10" fill="#f2e4e7"/>
+<!-- 卡体 -->
+<rect x="40" y="216" width="180" height="168" rx="10" fill="#ffffff" stroke="#0b0b0f" stroke-width="2"/>
+<!-- 顶部色带（上两角圆角，下边直角） -->
+<path d="M40 226 a10 10 0 0 1 10 -10 h160 a10 10 0 0 1 10 10 v8 h-180 z" fill="#be123c"/>
+<!-- 图标徽章 -->
+<rect x="56" y="244" width="44" height="44" rx="12" fill="#be123c"/>
+<g transform="translate(66 254)" fill="none" stroke="#ffffff" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+  <svg width="24" height="24" viewBox="0 0 24 24" aria-hidden="true">
+    <path d="M9 7a1 1 0 0 1 1 -1h4a1 1 0 0 1 1 1v1h3v12h-12v-12h3z"/>
+  </svg>
+</g>
+```
+
+连接线（颜色跟目标状态，标签必须有白底遮罩）：
+
+```svg
+<line x1="220" y1="300" x2="292" y2="300" stroke="#be123c" stroke-width="2.4" marker-end="url(#arrow-red)"/>
+<rect x="228" y="278" width="56" height="16" fill="#ffffff"/>
+<text x="256" y="290" text-anchor="middle" font-size="12" font-weight="600" fill="#be123c">先红</text>
+```
+
+## 9. 自检（画完逐条过）
+
+- [ ] 底色是 `#ffffff`，没有第二层灰底盖住全图？
+- [ ] 五个语义色都在规范里、各自只解释一件事？
+- [ ] 每个状态/阶段卡有图标，且图标 `aria-hidden="true"`？
+- [ ] 所有文字对白底 ≥ 4.5:1（彩色文字用深色值）？
+- [ ] 卡片是 2px 硬边 + 硬投影，没有模糊阴影？
+- [ ] 连接线是正交折线或同行直线，标签有白底遮罩且不压在线上？
+- [ ] 图例在底部横条，没有飘在图中间？
+- [ ] `node tools/diagram-lint.mjs <file>` 通过？

package/.agents/skills/diagram-design/references/type-architecture-delta.md

@@ -0,0 +1,143 @@
+# Architecture delta
+
+**Best for:** explaining a system migration, service extraction, infrastructure redesign, or integration change through two synchronized topology snapshots. Show which components and relationships survive, appear, disappear, change their properties, move, or reconnect.
+
+**Not this type:**
+
+- One system snapshot → **Architecture** (`type-architecture.md`).
+- Attribute-only differences without a topology story → a **comparison table**. Two versions of a configuration do not need two node maps.
+- Requests over time → **Sequence** (`type-sequence.md`); deployment phases → **Timeline** (`type-timeline.md`). A delta has exactly two states and does not establish migration order, downtime, or causality.
+- Host/container placement in one environment → **Deployment** (`type-deployment.md`).
+
+## Layout conventions
+
+- **Three panels, one reading order: Before · Changes · After.** Both topology panels use the same width, height, and internal grid pitch. The center panel is a short change ledger, not a third topology. Name the two snapshots with meaningful versions or dates.
+- **Keep the mental map stable.** Start by copying the Before coordinates into After. Move a retained component only when its movement is part of the story and receives a `MOVED` entry. Do not independently run a layout algorithm on each panel.
+- **Panel positions are not component positions.** Put each snapshot in one SVG `<g transform="translate(x y)">`; write component bounds and relationship paths in local coordinates. The Before and After origins share one y-coordinate, with the ledger occupying the horizontal gap.
+- **Shared grid:** use a 4px pitch by default. Every component's local x, y, width, and height is a multiple of that pitch. The shipped example uses two `336 480 4` grids; scale the overall SVG responsively without changing their local geometry.
+- **Budget:** at most **8 unique components**, **10 unique relationships**, and **8 ledger entries** across the complete comparison. A retained ID counts once, not once per snapshot. A component that is both changed and moved consumes two ledger entries. Split larger migrations into named subsystems or phases; never drop edges to fit.
+- **Connectors:** use Architecture's rounded orthogonal routing and port rules. In this type, even straight connectors are `<path>` elements so relationship identity and endpoints have one grammar. Draw paths before components. A stable relationship may take a different route to meet a moved component without becoming `REWIRED`.
+- **Nodes:** print the same stable ID in both states along with the human-readable name. Treat names, responsibilities, implementation versions, and protocols as semantic attributes; identities survive a rename when the underlying object survives.
+- **Ledger:** one brief entry per `(object ID, change)` pair. Begin with the uppercase change word, name the object, and state the actual difference. Do not describe unchanged objects in the ledger. Keep a readable text measure, with wrapped `<tspan>` lines when needed.
+- **Responsive presentation:** preserve the three-panel comparison on small screens with an accessible horizontal scroll region and a visible scroll hint. Do not compress labels until they become illegible or stack snapshots into independently scaled pictures. Print and export keep the whole comparison.
+
+## Change vocabulary and redundant encoding
+
+Color is secondary. Every change is readable from text plus a shape or line treatment; unchanged objects remain quiet context. Use the existing skin tokens and reserve the accent for the editorial focus, rather than assigning five status colors.
+
+| State | Meaning | Non-color treatment |
+|---|---|---|
+| `unchanged` | Same identity, semantics, position, and endpoints | Plain solid outline; no ledger entry |
+| `added` / **ADDED** | Present only in After | `+` badge or plus-shaped marker; solid outline |
+| `removed` / **REMOVED** | Present only in Before | `−` badge and dashed outline/path |
+| `changed` / **CHANGED** | Retained object whose semantic signature differs | `Δ` badge or inset rule, plus an explicit old → new ledger description |
+| `moved` / **MOVED** | Retained component whose local x or y differs | Direction/position marker and a ledger entry naming the relocation |
+| `rewired` / **REWIRED** | Retained relationship whose ordered source/target IDs differ | Distinct dash treatment or endpoint marker, with old → new endpoints written in the ledger |
+
+Do not use a missing After node to stand for a removal without a `REMOVED` entry. Do not substitute an `ADDED` edge for a `REWIRED` edge just to avoid explaining endpoint identity. A replacement component gets a new stable ID and separate removal/addition entries; its location alone cannot establish continuity.
+
+## Public HTML metadata contract
+
+This is the authoring and validation surface, not a serialization inferred from visible labels. All attributes below are required where applicable; empty, boolean, duplicate, or malformed declarations are findings. IDs are case-sensitive and match `[A-Za-z][A-Za-z0-9_.:-]*`; they contain no whitespace.
+
+### Diagram and snapshots
+
+The file has exactly one `<svg data-diagram="architecture-delta">`. Keep the standard accessible SVG title/description contract. Two direct child `<g>` elements declare `data-snapshot="before"` and `data-snapshot="after"`. Each has:
+
+- `data-grid="<width> <height> <pitch>"`: the same three positive finite numbers in both panels. Width and height are multiples of pitch.
+- `transform="translate(<x> <y>)"`: exactly one finite two-number translation, solely for the panel origin. Comma-separated translations are also accepted.
+
+Snapshot membership is inherited from the enclosing group. An object cannot be outside both snapshots, in nested snapshots, or nested inside another object. Other geometry transforms, nested SVG viewports, SVG animation, `<use>`, and foreign objects are outside this static grammar. Do not put objects or ledger entries in `<defs>`, `<symbol>`, templates, or other nonrendering containers.
+
+### Components
+
+Each component is a `<g>` declaring:
+
+| Attribute | Contract |
+|---|---|
+| `data-kind="component"` | Identifies a component group |
+| `data-object-id` | Stable object identity, unique within each snapshot |
+| `data-status` | One lowercase state or the space-separated combination `changed moved` |
+| `data-signature` | Nonempty semantic signature; see the signature rules below |
+
+The group contains exactly one **direct** `<rect data-role="bounds">` with explicit finite numeric `x`, `y`, `width`, and `height`. Position is nonnegative, size is positive, and the rectangle stays inside its local grid. All four values align with grid pitch. These are the actual drawn node bounds, not a hidden proxy rectangle.
+
+### Relationships
+
+Each relationship is a `<path>` with `data-kind="relationship"`, `data-object-id`, `data-status`, `data-signature`, and `data-from` / `data-to`. Its stable ID is separate from component IDs. Both endpoints resolve to component IDs in the **same snapshot**. Endpoint order is directional: swapping source and target is a rewire.
+
+Every path inside a snapshot and outside a component is a relationship and must carry the complete metadata. Decorative paths belong inside their component, or outside the snapshot for panel rules and ledger separators. Deleting all metadata from a connector must not make it disappear from validation.
+
+Relationship statuses are `unchanged`, `added`, `removed`, `changed`, `rewired`, or the combination `changed rewired`. `moved` applies to components only; `rewired` applies to relationships only. `unchanged`, `added`, and `removed` cannot be combined with any other token.
+
+The `d` attribute is one absolute `M` followed by absolute `L`, `H`, `V`, `Q`, or `C` segments. Implicit repeated coordinate groups are accepted. Relative commands, additional subpaths, closed paths, arcs, missing coordinates, and non-finite coordinates fail closed. Use orthogonal lines and quadratic corners for the standard layout; cubic segments are available for a small crossing bridge. Endpoints and control points remain inside the local grid. The path's start meets the source rectangle's perimeter and its end meets the target's perimeter, within 2px for stroke/arrow-cap rounding.
+
+### Status and signature rules
+
+- An ID present only in Before is exactly `removed`; an ID present only in After is exactly `added`.
+- A retained ID keeps its kind and the same status set in both snapshots. Never recycle a component ID for a relationship or vice versa.
+- A signature differs **if and only if** the retained object is `changed`. Construct it deterministically from the semantic attributes you want to compare, such as `orders-api:v2;mode=enqueue` or `protocol=https;operation=create-order`. Include a changed display name if renaming is part of the story. Preserve attribute order and spelling when values are unchanged.
+- Signatures exclude the object ID, snapshot, status, coordinates, visual styles, and relationship endpoints. These have their own checks. A movement or rewire alone must not change the signature.
+- A retained component's local `(x,y)` differs **if and only if** it is `moved`. A width/height change additionally requires `changed` and a changed signature. A changed signature alone does not require different bounds.
+- A retained relationship's ordered `(data-from,data-to)` pair differs **if and only if** it is `rewired`. Its path may reroute while that pair stays the same, for example when an endpoint component moves.
+- Numeric declarations are finite and have absolute values no larger than 10,000,000; unit suffixes, percentages, and CSS calculations are not coordinate declarations.
+
+### Ledger
+
+Each entry is a visible SVG `<text>` outside both snapshots, with `data-change="ADDED|REMOVED|CHANGED|MOVED|REWIRED"` and `data-target="<one object ID>"`. Its rendered text begins with the same uppercase word and continues with an explanation. Descendant `<tspan>` text is included when checking the wording; put the metadata on the outer `<text>` only.
+
+The ledger is an exact set of `(target, change)` pairs implied by object statuses. There are no missing entries, duplicate pairs, unknown targets, or entries for unchanged objects. The same target can have two entries only when it declares two changes. Every diagram contains at least one ledger entry, at least one component in each snapshot, and at least one relationship overall.
+
+### Worked metadata pattern
+
+This excerpt shows one changed component; a complete diagram also needs its other components, relationships, and accessible SVG title/description.
+
+```svg
+<svg data-diagram="architecture-delta" viewBox="0 0 1000 400">
+  <g data-snapshot="before" data-grid="320 320 4" transform="translate(24 64)">
+    <g data-kind="component" data-object-id="orders" data-status="changed"
+       data-signature="orders-api:v1;mode=dispatch">
+      <rect data-role="bounds" x="80" y="96" width="144" height="64"/>
+      <text x="96" y="120">orders · direct dispatch</text>
+    </g>
+  </g>
+  <g data-snapshot="after" data-grid="320 320 4" transform="translate(656 64)">
+    <g data-kind="component" data-object-id="orders" data-status="changed"
+       data-signature="orders-api:v2;mode=enqueue">
+      <rect data-role="bounds" x="80" y="96" width="144" height="64"/>
+      <text x="96" y="120">orders · enqueue</text>
+    </g>
+  </g>
+  <text data-change="CHANGED" data-target="orders" x="376" y="176">
+    <tspan>CHANGED orders</tspan>
+    <tspan x="376" dy="20">Direct dispatch → enqueue</tspan>
+  </text>
+</svg>
+```
+
+## Verification and its boundaries
+
+Run `（仓库级脚本未随包分发：越界与动画契约以 node tools/diagram-lint.mjs 为准）
+
+The verifier enforces the declared structure, differential semantics, grid/bounds geometry, drawn relationship endpoints, budgets, and exact ledger coverage. It rejects CSS transforms/position overrides, CSS sizing that could change bounds, escaped CSS declarations, explicit hidden objects/ledger, and common CSS hiding rules. Ordinary responsive sizing of the outer SVG remains legal.
+
+It is **not** a browser renderer or a proof of the source system. Authors remain responsible for honest signatures, labels matching those signatures, readable shape/dash treatments, and an accurate migration story. Exotic CSS cascade/variable effects, clipping and occlusion, connector crossings, intermediate segment clearance, ledger placement, and screen-reader quality still require the normal skin, accessibility, geometry, and rendered-layout gates plus desktop/mobile visual review. Keep semantic geometry in the SVG attributes instead of making CSS part of the data model.
+
+## Anti-patterns
+
+- Two independently arranged snapshots that manufacture apparent movement.
+- A center ledger that says only “updated” without naming the object and difference.
+- Color-only statuses or a separate bright color for every kind of change.
+- Unchanged node positions drifting to make room, with no `MOVED` entry.
+- Semantic edits hidden behind an unchanged signature, or all signatures regenerated just because the snapshot changed.
+- Redrawing an edge to a different component while keeping its endpoint metadata unchanged.
+- Counting retained objects twice to justify dropping other objects from the comparison.
+- Treating this comparison as an executable migration plan. Ordering, rollback, availability, and data consistency need their own explanation.
+
+## Examples
+
+- `assets/example-architecture-delta.html` — minimal light order-fulfilment migration; all five change kinds.
+- `assets/example-architecture-delta-dark.html` — minimal dark, identical IDs, signatures, topology, and coordinates.
+- `assets/example-architecture-delta-full.html` — full editorial treatment of the same migration.
+
+The example retains the storefront and order store, changes the order API to enqueue work, removes the legacy dispatcher, adds a durable order queue, moves the fulfilment worker, and rewires order submission. Stable relationships follow the worker's new location while preserving their IDs and endpoint semantics.