Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.
HTML agent-skillsai-agentsarchitecture-diagramclaude-codeclaude-skillscodexcoding-agentsdeepseek-harnessdeveloper-toolsdiagramsdiagrams-as-codedsh-pluginflowchartllmmermaidopencodesequence-diagramsoftware-architecturesystem-designvisualization
Docs and version bump to 2.6.0
tt-a1i8da892e860cb
diff --git a/CHANGELOG.md b/CHANGELOG.mdindex 3dc339f8..6305b348 100644--- a/CHANGELOG.md+++ b/CHANGELOG.md@@ -4,6 +4,25 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo## [Unreleased]+## [2.6.0] — 2026-06-12++### Added+- **Architecture renderer.** The default, highest-traffic mode now has a constrained renderer (`renderers/architecture/render-architecture.mjs`) and JSON Schema (`schemas/architecture.schema.json`), bringing it to validation parity with the four typed modes — without auto-layout. Claude still picks all coordinates (`pos`/`size`); the renderer handles the mechanical work: the two-rect `c-mask` pattern, arrows-before-boxes z-order, an auto-built legend, and an auto-fitted `viewBox`.+- **Boundaries from `wraps`.** A `region` or `security-group` boundary lists the component ids it encloses; the renderer computes the box with correct 30/50 padding automatically, eliminating the hand-arithmetic that caused the v2.2.1 padding bug.+- **Architecture example.** Added `archify/examples/web-app.architecture.json` rendered to `examples/web-app-rendered.html`, wired into the golden suite (5th entry).+- **Geometry unit tests.** `archify/test/geometry.test.mjs` directly tests the pure helpers every renderer depends on (`rectsOverlap`, `anchor`, `roundedPath`, `labelPoint`, `chosenSide`, `textUnits`, …) — previously covered only transitively by golden byte-compares.+- **Layout-rule coverage matrix.** `archify/test/layout-rules.test.mjs` drives one minimal-violation case per high-value layout rule across all five modes and asserts the error message carries its numeric threshold and remediation hint (the LLM-facing DX contract).+- **Degraded-mode fuzz net.** `archify/test/degraded.test.mjs` asserts that type-wrong-but-JSON-legal input always fails friendly (non-zero exit, no `TypeError`, no `NaN`/`undefined` written) and that valid order-shuffles always render.++### Changed+- `npm test` now runs the golden suite plus `node --test test/*.test.mjs` (geometry, layout-rules, degraded). The `architecture` schema is registered in `validator.mjs` and covered by `render:examples`.+- `textUnits` now counts supplementary-plane CJK and emoji as double-width (added the `u` flag and astral ranges).++### Fixed+- **Degraded-mode robustness (no ajv).** A type-wrong top-level field (e.g. `nodes: "oops"`) or a missing coordinate field (e.g. a node with no `col`) previously threw a raw `TypeError` before the friendly checks ran, or exited 0 while writing `<rect x="NaN">` into the HTML. Renderers now coerce non-array fields via `asArray`, guard non-finite coordinates with `isFinitePoint`, and validate `cards`/`messages`/`segments`/`activations` are arrays — so malformed input always produces an actionable message instead of a crash or silent corruption.++## [2.5.0] — 2026-06-11+### Added- **Workflow diagram mode.** Archify now includes a renderer-backed workflow diagram type for technical flows, approval chains, tool calls, CI/CD paths, runbooks, and process ownership diagrams. Workflow diagrams use a JSON IR with lanes, nodes, routed edges, and summary cards, then render into the same standalone HTML shell with theme toggle and export menu.- **Workflow JSON Schema.** Added `archify/schemas/workflow.schema.json` to document and validate the workflow IR shape.@@ -18,10 +37,50 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo- **Lifecycle diagram mode.** Added a renderer-backed lifecycle/state-machine diagram type for object lifecycles, wait states, retries, cancellation, timeout, terminal states, and recovery paths.- **Lifecycle JSON Schema.** Added `archify/schemas/lifecycle.schema.json` to document and validate the lifecycle IR shape.- **Lifecycle example.** Added a rendered agent-run lifecycle example at `examples/lifecycle-agent-run.html`, plus a README preview screenshot.+- **Runtime JSON Schema validation.** All four typed renderers validate their JSON IR against the published schemas via ajv (draft 2020-12); violations exit non-zero with path-prefixed error messages, and error paths carry element ids (e.g. `/nodes/3 (id/label: "router")`). When dependencies aren't installed, the renderer warns and skips schema validation gracefully — layout checks still run.+- **GitHub Pages landing page.** Added a product landing site under `docs/` plus a repository social preview image.+- **Mermaid as an input dialect.** New `SKILL.md` section maps `flowchart` → workflow, `sequenceDiagram` → sequence, and `stateDiagram` → lifecycle so Claude can accept pasted Mermaid and lay out from scratch (prompt engineering, no parser) — closing roadmap item P2.+- **Label collision detection.** New validation checks flag label-vs-node and label-vs-label collisions, plus node labels overflowing their boxes.+- **CJK-aware text width estimation.** Full-width characters count as 2 units, and the template plus exported-SVG font stacks gained PingFang SC / Microsoft YaHei / Noto Sans CJK SC fallbacks.+- **Golden test suite.** `archify/test/golden.mjs` byte-compares the four rendered examples, runs 6 negative validation cases (schema + layout), and checks `web-app.html` template freshness and version sync — wired to `npm test`.+- **Example re-render script.** `archify/test/render-examples.mjs` re-renders every example in one shot via `npm run render:examples`.+- **CI workflow.** `.github/workflows/ci.yml` runs the test suite on a Node 20/22 matrix and verifies `archify.zip` freshness by rebuilding and diffing.+- **Release workflow.** `.github/workflows/release.yml` builds the zip on `v*` tags, verifies the tag matches `package.json`, and attaches the artifact to the GitHub Release.+- **Zip build script.** `scripts/build-zip.sh` builds `archify.zip` from `archify/` (including `package.json`, the lockfile, and the newly bundled `archify/LICENSE`; excluding `node_modules`). `package.json` declares `engines.node >= 18`.+- **Workflow preview image.** Added `docs/assets/archify-workflow.png` (4× dark export) — workflow was the only diagram type without a preview screenshot.+- **Generator metadata & accessibility.** Generated HTML carries `<meta name="generator" content="archify 2.5.0">`; the SVG root gets `role="img"` + `aria-label`, toasts get `role="status"`, and the export menu fixes focus return to the trigger, ArrowDown-to-open, and separator ARIA.+- **Async Google Fonts loading.** The `media="print"` onload trick plus preconnect and a noscript fallback mean an offline or slow network no longer blocks first paint.+- **Theme FOUC guard.** An early script in `<head>` applies the stored theme before first paint, and pages without an explicit preference now follow live system theme changes.+- **`--text-faint` UI variable.** Menu hints and the footer now meet contrast standards; the SVG `t-dim` color is unchanged.### Changed- **Template responsive polish.** The shared HTML template now handles narrow viewports better: the toolbar no longer overlaps the title, diagrams can scale down to the available width, and cards stack cleanly on mobile.- **Subtle swimlane styling.** Added `c-lane` for workflow/process swimlanes so workflow boundaries do not visually overpower the main path.+- **Lifecycle diagram reworked as a phase map.** The lifecycle visual model was redesigned across several composition passes: phase bands, decluttered middle lanes, and refined transition labels.+- **Shared renderer code.** The typed renderers share `utils.mjs` (with hardened template slot replacement), and this release extracts `renderers/shared/geometry.mjs` (geometry/class maps), `cli.mjs` (CLI head/tail), and `schemas/common.schema.json` (`$ref`-shared id/point/componentType/variant/cards definitions). ajv now runs in strict mode.+- **Validation error messages rewritten.** Every check now reports numeric thresholds, the valid range, and which field to change.+- **`SKILL.md` restructured (433 → ~205 lines).** New Setup section (npm install, graceful degradation, architecture-mode fallback when no shell is available), per-mode JSON examples upgraded from empty skeletons to renderable snippets (all verified to pass first try), per-mode layout budgets (columns/rows/coordinate ranges/spacing), documented lifecycle reserved-lane (`main`/`terminal`) semantics, a 6-item machine-checkable architecture-mode checklist, a pointer to the renderer README for depth, and corrected viewBox guidance. Frontmatter version is 2.5 and the description gained Mermaid/flowchart trigger words.+- **Lifecycle band titles.** Band titles now render from lane labels (the schema-required field is finally used), the main track length derives from actually occupied columns, and a missing `main` lane is a validation error.+- **Sequence timeline scaling.** The timeline scales with viewBox height (taller viewBox = more timeline room), and segments are validated (`to > from`, within the canvas).+- **Workflow sizing defaults.** Omitting the viewBox now auto-computes height from the lane count, and the default width dropped 1000 → 720, eliminating 320px of dead space.+- **Schema limits tightened.** Column caps added (workflow `col ≤ 5`, lifecycle `col ≤ 4`), sequence messages require `y ≥ 160`, and viewBox minimums are stricter.+- **Exported SVG embeds only SVG-relevant CSS.** ~9 KB of toolbar/cards/print rules are stripped from `.svg` downloads.+- **Download filename cleanup.** The redundant `-diagram` suffix is stripped from export filenames.+- **Docs images consolidated under `docs/assets/`.** `examples/images/` is removed, the orphaned `archify-print.png` deleted, and `archify-lifecycle.png` regenerated with the new band titles.+- **Docs accuracy.** README's "~3 KB embedded JS" corrected to ~19 KB; "4× export" is now documented as *up to* 4× (oversized diagrams automatically step down to 3×/2× via `pickSafeScale`); and "zero dependencies" is scoped to the generated HTML only — the renderers need `npm install` for ajv.++### Fixed+- **`applyTemplate` slot corruption.** Slot replacement now uses a function replacer, so `$&`, `$'`, `` $` ``, and `$$` in titles or labels no longer corrupt the output.+- **Lifecycle overlap detection across lanes.** Overlap checks now compare all state pairs across lanes — previously, identical coordinates in different lanes produced zero errors.+- **Sequence vertical-spacing false positives.** The spacing check now only fires for messages whose horizontal spans actually overlap, eliminating false reports on parallel messages.+- **Zero values swallowed.** `bias: 0` / `channelX: 0` / `channelY: 0` now use `??` instead of `||`, so schema-legal zero values are respected.+- **Workflow `fromSide`/`toSide: "auto"`.** Removed from the schema and normalized in code — an explicit `"auto"` used to anchor edges to the wrong side.+- **Route enums converged.** Workflow drops `drop-right`/`drop-left`/`same-lane` (byte-identical output to `drop`/`straight`); lifecycle drops `raise`, removes the dead `bias` field, and adds `cornerRadius` (the renderer read it but the schema rejected it).+- **Light-theme exports kept dark swimlanes.** The export pipeline now scans the stylesheet for CSS variables at runtime instead of using a hardcoded list — `--lane-fill`/`--lane-stroke` were slipping through, and newly added variables can no longer be missed.+- **Safari Copy PNG.** `ClipboardItem` is now constructed synchronously inside the user gesture (with a `Promise<Blob>` value), with a fallback path.+- **`localStorage` guarded.** All access is wrapped in try/catch, so disabled storage no longer takes down theme, export, and keyboard shortcuts together.+- **Print palette completed.** Print styles now carry a full light palette (no more neon strokes when printing from the dark theme), and the footer keyboard-shortcut hints are hidden in print.+- **Stale `archify.zip`.** Rebuilt — it had fallen 3 commits behind and was missing `renderers/shared/` and `package.json`; CI now enforces zip freshness.## [2.4.0] — 2026-04-18diff --git a/README.md b/README.mdindex b2f21e78..9e89c01b 100644--- a/README.md+++ b/README.md@@ -1,8 +1,8 @@-+# Archify-**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出 4× 清晰 PNG / JPEG / WebP / SVG,或直接复制到剪贴板。**+**聊两句就画出好看的架构图、技术流程图、调用时序图、数据流图和生命周期图。深色 / 浅色一键切。导出最高 4× 清晰 PNG / JPEG / WebP / SVG,或直接复制到剪贴板。**Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude):你用大白话描述自己的系统或流程,它就把你的描述变成一张做工精细的技术图 —— 一个单文件 HTML,在浏览器里打开就能切主题、复制到剪贴板、导出成各种图片格式。@@ -10,14 +10,16 @@ Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180- **支持 workflow / sequence / data flow / lifecycle** —— 技术流程、审批链、工具调用、CI/CD、请求调用链、数据管线、PII 边界、状态机都可以画- **内置主题切换** —— 深色 / 浅色一键切,浏览器记住偏好- **一键复制到剪贴板** —— 直接贴到 Slack、飞书、微信、Notion、GitHub issue-- **导出图片超清晰** —— PNG / JPEG / WebP 全部由浏览器在 4× 源分辨率下**原生光栅化**(不是位图放大,没有糊),或导出 SVG 做真矢量+- **导出图片超清晰** —— PNG / JPEG / WebP 全部由浏览器在最高 4× 源分辨率下**原生光栅化**(不是位图放大,没有糊),或导出 SVG 做真矢量- **SVG 自动跟系统深浅色** —— 导出的 SVG 内嵌两套变量 + `@media (prefers-color-scheme)`,贴到 GitHub README 里,读者切深浅色图跟着切(不用两张 PNG + `<picture>` 包起来)-- **单文件 HTML** —— 零依赖,发一个文件就能分享+- **单文件 HTML** —— 生成的 HTML 零运行时依赖,发一个文件就能分享- **聊天迭代** —— "把 Redis 挪到左边"、"鉴权服务换成玫红"、"加个 Kafka"-+++**[在线落地页 → tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)**<p align="right"><a href="./README_EN.md">English</a></p>@@ -27,11 +29,11 @@ Archify 是一个 [Claude Skill](https://support.claude.com/en/articles/12512180| 深色 | 浅色 ||---|---|-|  |  |+|  |  |Export 菜单 —— 复制到剪贴板 + 四种格式下载:-+想亲自玩一下:克隆仓库后打开 [`examples/web-app.html`](examples/web-app.html),按 <kbd>T</kbd> 切主题,<kbd>E</kbd> 打开导出菜单。给 URL 加上 `?theme=light` 或 `?openExport=1` 可以强制初始状态。@@ -57,6 +59,8 @@ Workflow 不是通用流程图的替代品,它更偏“技术沟通图”:本仓库里有一个可打开的示例:[`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html)。++Sequence 用来解释更细的交互顺序,比如:```@@ -66,7 +70,7 @@ Sequence 用来解释更细的交互顺序,比如:示例:[`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html)。-+Data Flow 适合解释“数据资产怎么走”,比如:@@ -78,7 +82,7 @@ Warehouse 存分析表,Feature Store 做每日特征,Dashboard 和 ML Model示例:[`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html)。-+Lifecycle 用来解释“对象状态怎么变”,比如:@@ -91,24 +95,25 @@ Needs Approval,缺少输入时进入 Blocked;工具失败可以 Failed 后示例:[`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html)。-+## 版本演进-Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。**2.4** SVG 导出升级成双主题自持版 —— 同一个 `.svg` 文件贴在 GitHub README 里,读者切深浅色图会自己跟着切。--| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 |-|---|---|---|---|---|---|---|-| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |-| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 |-| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 |-| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)|-| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(始终 4×)| 同 |-| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 |-| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 |-| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 |-| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 |-| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 |+Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。**2.4** SVG 导出升级成双主题自持版 —— 同一个 `.svg` 文件贴在 GitHub README 里,读者切深浅色图会自己跟着切。**2.5** 集中修复类型化渲染器的 bug 并强化 LLM 工程学(校验错误信息带数值阈值和修复建议),SKILL.md 新增 Mermaid 输入指引,字体栈加入 CJK 回退,修复浅色导出泳道配色和 Safari 剪贴板复制,并补齐 golden 测试与 CI。++| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |+|---|---|---|---|---|---|---|---|+| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |+| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 |+| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** |+| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)|+| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** |+| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 |+| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)|+| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 |+| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** |+| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 |+| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | **✓(含测试与 CI)** |## 快速上手@@ -122,6 +127,8 @@ Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Coc3. 点 **+ Add**,上传 zip4. 打开开关++**Claude Code CLI:**```bash# 全局(所有项目可用)@@ -131,9 +138,25 @@ unzip archify.zip -d ~/.claude/skills/unzip archify.zip -d ./.claude/skills/```+类型化渲染器(workflow / sequence / dataflow / lifecycle)依赖 ajv 做 schema 校验,需要在 skill 目录执行一次 `npm install`。首次使用时 Claude 会按 `SKILL.md` 的 Setup 指引自动安装;也可以自己先装好:++```bash+cd ~/.claude/skills/archify && npm install+```++没装依赖时渲染器会跳过 schema 校验(布局检查仍然运行)。+**Claude.ai Projects:**把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。+三种安装方式的能力差异:++| 安装方式 | 能力 |+|---|---|+| **Claude Code** | 完整 —— 可运行类型化渲染器 + schema 校验 |+| **Claude.ai 上传 zip** | 通常可用 —— 取决于沙箱能否 `npm install`,一般可以 |+| **Project Knowledge** | 仅架构模式 —— 不执行代码,纯 prompt 驱动 |+### 2. 准备系统描述下面几种都可以:@@ -182,7 +205,7 @@ unzip archify.zip -d ./.claude/skills/| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 || **Download SVG** | 矢量导出,所有样式内联,**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客,读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |-所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在 **4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。+所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。没有倍数选择器 —— 永远最高清晰度,默认也是唯一选项。如果偶尔需要小图,用下面的 URL 参数。@@ -281,7 +304,7 @@ unzip archify.zip -d ./.claude/skills/- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。-- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 3 KB 嵌入 JS。无构建步骤、无 JS 框架、无服务端。+- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 19 KB 嵌入 JS。生成的 HTML 零运行时依赖 —— 无构建步骤、无 JS 框架、无服务端(渲染器本身需要 `npm install`,见安装章节)。- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。## 致谢@@ -307,7 +330,7 @@ Archify 2.x 贡献:下一站是 **v3.0 — JSON IR 稳定迭代**:引入极简 `diagram.json` 中间格式,让 Claude 做局部坐标修改时不会漂移无关组件,同时支持 `git diff` 友好和 theme/palette 不重渲染。-> **关于 Mermaid 导入:** 经实验验证(auto-layout + archify CSS 并不比原生 Mermaid 好看多少),Mermaid 自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断,不是 CSS。用户仍可贴 Mermaid 代码让 Claude 从零布局出 archify 风格图 —— 只是走 prompt 而不是走 parser。+> **关于 Mermaid 输入:** 已实现 —— `SKILL.md` 现在有专门的「Mermaid as an Input Dialect」章节,把 flowchart / sequenceDiagram / stateDiagram 映射到 workflow / sequence / lifecycle。注意走的是 prompt 而不是 parser:经实验验证(auto-layout + archify CSS 并不比原生 Mermaid 好看多少),自动解析器路线已砍掉。archify 的美学核心是 Claude 的布局判断,不是 CSS —— 贴 Mermaid 代码,Claude 从零布局出 archify 风格图。>> 原 v2.4 / v2.5 计划(`?exportScale=N`、色盲调色板、分享链接)也已砍掉。理由见 [ROADMAP「Not planned」段落](ROADMAP.md#not-planned)。diff --git a/README_EN.md b/README_EN.mdindex 943c8e28..25072bca 100644--- a/README_EN.md+++ b/README_EN.md@@ -1,8 +1,8 @@-+# Archify-**Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat. Switch dark / light. Copy to clipboard or export crisp 4× PNG / JPEG / WebP / SVG.**+**Generate beautiful architecture, technical workflow, sequence, data-flow, and lifecycle diagrams in chat. Switch dark / light. Copy to clipboard or export crisp up-to-4× PNG / JPEG / WebP / SVG.**Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-using-skills-in-claude) that turns a plain-English description of your system or process into a polished, self-contained technical diagram — a single HTML file you can open, toggle themes on, copy to the clipboard, and export at maximum resolution.@@ -10,14 +10,16 @@ Archify is a [Claude Skill](https://support.claude.com/en/articles/12512180-usin- **Workflow, sequence, data-flow, and lifecycle diagrams too** — technical flows, approvals, tool calls, CI/CD, runbooks, request call chains, data pipelines, PII boundaries, and state machines can be drawn- **Built-in theme toggle** — one click between dark and light, persists across sessions- **Copy PNG to clipboard** — one click, paste straight into Slack / Notion / GitHub-- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at 4× source resolution (no upsampling blur), or SVG for true vector+- **Ultra-crisp image export** — PNG / JPEG / WebP rendered natively at up to 4× source resolution (no upsampling blur), or SVG for true vector- **SVG follows system dark/light** — exported SVGs ship with both variable sets + `@media (prefers-color-scheme)`, so dropping one into a GitHub README makes it follow the reader's color preference (no more two PNGs wrapped in `<picture>`)-- **Self-contained HTML** — zero dependencies, share by sending the file+- **Self-contained HTML** — the generated file has zero dependencies, share by sending it- **Iterate by chat** — "add Redis", "move auth to the left", "use emerald for the API"-+++**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)<p align="right"><a href="./README.md">中文</a></p>@@ -27,11 +29,11 @@ Same diagram, two themes, one click to switch:| Dark | Light ||---|---|-|  |  |+|  |  |-The Export menu — Copy PNG to clipboard plus 4 download formats (all raster exports at 4× source resolution):+The Export menu — Copy PNG to clipboard plus 4 download formats (all raster exports at up to 4× source resolution):-+Live example: [`examples/web-app.html`](examples/web-app.html) — open in a browser, press <kbd>T</kbd> to toggle theme, <kbd>E</kbd> to open Export. Append `?theme=light` or `?openExport=1` to the URL for deterministic screenshots.@@ -56,6 +58,8 @@ User submits a request -> Agent plans -> Approval Gate if needed -> Tool Call ->Open the example here: [`examples/workflow-agent-tool-call-rendered.html`](examples/workflow-agent-tool-call-rendered.html).++Sequence diagrams explain a narrower interaction over time:```text@@ -65,7 +69,7 @@ User opens a page, the frontend calls the API, the API verifies JWT, reads RedisOpen the example here: [`examples/sequence-cache-miss-request.html`](examples/sequence-cache-miss-request.html).-+Data Flow diagrams explain how data assets move and change:@@ -77,7 +81,7 @@ Warehouse stores analytics tables, Feature Store derives daily features, DashboaOpen the example here: [`examples/dataflow-product-analytics.html`](examples/dataflow-product-analytics.html).-+Lifecycle diagrams explain how an object changes state:@@ -89,24 +93,25 @@ wait at Blocked, retry after Failed, end at Cancelled or Expired, or finish at COpen the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-agent-run.html).-+## What's new-Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale). **2.4** upgraded the SVG export to a dual-theme self-contained file — drop the same `.svg` into a GitHub README and it follows the reader's dark/light preference automatically.--| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 |-|---|---|---|---|---|---|---|-| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes |-| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same |-| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same |-| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) |-| Copy PNG to clipboard | — | — | Yes | Same | Yes (always 4×) | Same |-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same |-| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same |-| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same |-| Local-font fallback on export | — | — | — | Yes | Yes | Same |-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same |+Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale). **2.4** upgraded the SVG export to a dual-theme self-contained file — drop the same `.svg` into a GitHub README and it follows the reader's dark/light preference automatically. **2.5** is a hardening release: a batch of verified renderer and validation bug fixes (template slot corruption, cross-lane lifecycle overlap detection, light-theme lane colors in PNG/SVG exports, Safari clipboard copy), LLM-ergonomic validation errors with numeric thresholds and fix suggestions, Mermaid accepted as an input dialect (mapped through `SKILL.md` prompts, not a parser), CJK-aware text measurement plus CJK font fallbacks, and a golden-file test suite with CI.++| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |+|---|---|---|---|---|---|---|---|+| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes |+| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same |+| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** |+| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) |+| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** |+| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same |+| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) |+| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same |+| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** |+| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same |+| Typed renderers + schema validation | — | — | — | — | — | — | **Yes (with tests & CI)** |## Quick start@@ -129,9 +134,25 @@ unzip archify.zip -d ~/.claude/skills/unzip archify.zip -d ./.claude/skills/```+The typed renderers (workflow / sequence / dataflow / lifecycle) rely on ajv for schema validation, which takes a one-time `npm install` in the skill directory. Claude installs it automatically on first use, following the Setup instructions in `SKILL.md` — or run it yourself:++```bash+cd ~/.claude/skills/archify && npm install+```++Without the dependency the renderers skip schema validation (layout checks still run).+**Claude.ai Projects (alternative):**Upload [`archify.zip`](archify.zip) to your Project Knowledge.+What each install surface can do:++| Install surface | Capability |+|---|---|+| **Claude Code** | Full — runs the typed renderers + schema validation |+| **Claude.ai (zip upload)** | Usually full — depends on whether the sandbox can `npm install`, which it typically can |+| **Project Knowledge** | Architecture mode only — no code execution, purely prompt-driven |+### 2. Describe your systemAny of these work:@@ -181,7 +202,7 @@ Open the generated HTML in any browser. Top-right you'll see two buttons:| **Download PNG / JPEG / WebP** | Saves a raster image. JPEG/WebP are painted over the current theme's background (no alpha); PNG keeps transparency. || **Download SVG** | Vector export with all styles inlined, **dual-theme self-contained**. The file ships with both dark and light CSS variable sets plus a `@media (prefers-color-scheme)` rule — drop the same `.svg` into a GitHub README or blog and it follows the reader's preference automatically. Still editable in Figma / Illustrator. Scales losslessly. |-Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **4× the diagram's intrinsic resolution** — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum sharpness is the default and the only option.+Every raster export (Copy PNG, Download PNG/JPEG/WebP) is rendered natively by the browser at **up to 4× the diagram's intrinsic resolution** (oversized diagrams step down to 3×/2× to stay within browser canvas limits) — the serialized SVG is given a `width`/`height` of `4 × viewBox`, rasterized by the browser at that resolution, and drawn to the canvas at natural size (no upsampling). This produces genuinely crisp output for retina displays, slides, and print. There is no scale dial — maximum safe sharpness is always chosen automatically.### Keyboard@@ -278,7 +299,7 @@ Each color has coordinated dark-mode and light-mode variants that switch togethe- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.-- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~3 KB of embedded JS. No build step, no JS framework, no server.+- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server — the generated HTML itself has zero dependencies (the typed renderers need `npm install` for ajv, see [Install](#1-install-the-skill)).- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.## Attribution@@ -297,6 +318,16 @@ Archify 2.x contributes:Both projects are MIT-licensed.+## Roadmap++See [ROADMAP.md](ROADMAP.md).++Next up is **v3.0 — JSON IR stabilization**: a minimal `diagram.json` intermediate format so Claude can make local coordinate edits without drifting unrelated components, with `git diff`-friendly output and theme/palette swaps that don't require re-rendering.++> **About Mermaid import:** the automatic Mermaid parser route was cut after an experiment showed that auto-layout + archify CSS doesn't look meaningfully better than native Mermaid ([experiments/v3-mermaid-validation/RESULT.md](experiments/v3-mermaid-validation/RESULT.md)). Archify's aesthetic core is Claude's layout judgment, not the CSS. You can still paste Mermaid code and have Claude lay out an archify-style diagram from scratch — it goes through the `SKILL.md` prompts, not a parser.+>+> The former v2.4 / v2.5 plans (`?exportScale=N`, color-blind palettes, share links) were also dropped. See the [ROADMAP "Not planned" section](ROADMAP.md#not-planned) for the rationale.+## License[MIT](LICENSE) — free to use, modify, and distribute.diff --git a/ROADMAP.md b/ROADMAP.mdindex 596f09a6..c4a1798f 100644--- a/ROADMAP.md+++ b/ROADMAP.md@@ -76,10 +76,10 @@ The "Claude in the loop" property is the moat, not a limitation. Auto-layout lib| Phase | Deliverable | Target ||---|---|---|| ~~**Validate**~~ | ~~5-Mermaid blind-rate experiment~~ | **DONE — FAILED** (see below) |-| **P0** | JSON IR + JSON Schema validator + `schema_version` enforcement | v3.0-alpha |-| **P0.5** | `render.js` — pure-JS renderer takes IR → HTML using existing template. Coordinates required (no auto-layout). | v3.0-alpha |+| **P0** | JSON IR + JSON Schema validator + `schema_version` enforcement | **DONE** — shipped for the four typed modes (workflow / sequence / dataflow / lifecycle), enforced at runtime via ajv |+| **P0.5** | `render.js` — pure-JS renderer takes IR → HTML using existing template. Coordinates required (no auto-layout). | **DONE** — the four typed renderers cover IR → HTML; an architecture-mode `render.js` is still not built || ~~**P1**~~ | ~~Mermaid flowchart parser → IR~~ | **KILLED** — experiment showed auto-layout + CSS is not enough |-| **P2** | Updated SKILL.md teaching Claude to accept Mermaid as input and lay out from scratch (prompt engineering, no parser) | v3.0-beta |+| **P2** | Updated SKILL.md teaching Claude to accept Mermaid as input and lay out from scratch (prompt engineering, no parser) | **DONE — 2026-06-11** — implemented in SKILL.md's "Mermaid as an Input Dialect" section || ~~**P3**~~ | ~~End-to-end parser pipeline~~ | **KILLED** || ~~**P4**~~ | ~~IR → Mermaid output + C4 input~~ | **KILLED** |@@ -94,9 +94,9 @@ The experiment tested whether auto-layout (dagre) + archify CSS (version B) look### Done when (revised, post-experiment)- `render.js` reproduces today's `examples/web-app.html` from a hand-written `diagram.json`.-- `schema_version: 1` is documented in `docs/diagram-json-schema.md` with the full JSON Schema published.+- `schema_version: 1` is documented in `archify/schemas/README.md` with the full JSON Schemas published (`docs/` now hosts the GitHub Pages site, not internal docs).- Claude, given an existing `diagram.json`, can make targeted coordinate edits without unrelated drift.-- SKILL.md updated to mention Mermaid as an accepted input dialect (prompt engineering, not parser).+- SKILL.md updated to mention Mermaid as an accepted input dialect (prompt engineering, not parser). **DONE — 2026-06-11**, see the "Mermaid as an Input Dialect" section.- README updated to describe the new stable-iteration workflow.### Workflow renderer pilot (2026-04-24)diff --git a/archify.zip b/archify.zipindex 8b75086a..12600d87 100644Binary files a/archify.zip and b/archify.zip differdiff --git a/archify/SKILL.md b/archify/SKILL.mdindex 5c3360b1..cda06669 100644--- a/archify/SKILL.md+++ b/archify/SKILL.md@@ -1,432 +1,236 @@---name: archify-description: Create professional architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as standalone HTML files with SVG graphics, a built-in dark/light theme toggle, and one-click export to PNG / JPEG / WebP / SVG. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology diagrams, technical workflows, approval flows, runbooks, CI/CD flows, process diagrams, API call sequences, request lifecycles, interaction diagrams, data pipelines, analytics flows, ETL/ELT maps, PII boundaries, governance/data lineage diagrams, state machines, lifecycle diagrams, status transitions, or terminal/retry paths.+description: Create professional architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as standalone HTML files with SVG graphics, a built-in dark/light theme toggle, and one-click export to PNG / JPEG / WebP / SVG. Accepts plain-language descriptions or pasted Mermaid code (flowchart, sequenceDiagram, stateDiagram) and lays the diagram out from scratch in archify style. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology, technical workflows, approval flows, runbooks, CI/CD flows, process diagrams, API call sequences, request lifecycles, data pipelines, ETL/ELT maps, PII boundaries, data lineage, state machines, lifecycle diagrams, status transitions, or asks to convert/beautify a Mermaid diagram.license: MITmetadata:- version: "2.4"+ version: "2.6"author: tt-a1ibased_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)---# Archify Skill-Create professional technical diagrams as self-contained HTML files with inline SVG, a theme toggle, and a built-in image/SVG export menu. No external runtime dependencies beyond Google Fonts.+Create professional technical diagrams as self-contained HTML files with inline SVG, a theme toggle, and a built-in image/SVG export menu.-Every diagram this skill produces ships with:+Every diagram ships with a **dark/light theme toggle** (persists in `localStorage`, respects `prefers-color-scheme`), an **export menu** (copy PNG to clipboard; download PNG/JPEG/WebP rasterized natively at up to 4× resolution; download a **dual-theme SVG** that follows the embedding host's `prefers-color-scheme` — ideal for GitHub READMEs), and a **CSS-variable color system** that keeps both themes consistent.-- A **Dark / Light theme toggle** (top-right, persists in `localStorage`, respects `prefers-color-scheme` on first visit).-- An **Export menu** with **Copy PNG to clipboard** plus downloads for **PNG / JPEG / WebP** (all rasterized natively at 4× source resolution for maximum sharpness) and **SVG** (vector, styles inlined). The SVG download is **dual-theme self-contained**: it ships with both dark and light variable sets plus a `@media (prefers-color-scheme)` rule, so embedding it in a GitHub README (or any `<img>` host that exposes a color scheme) makes it follow the reader's dark/light preference automatically. All rendering happens in-browser, no server.-- A **CSS-variable-driven color system** so both themes remain visually consistent with the same SVG markup.+## Setup (one-time, renderer modes only)-## Diagram Types+The four typed renderers validate JSON against schemas via `ajv`. From this skill's folder:-Archify supports five technical diagram modes:+```bash+npm install+```++Without it the renderers still run — they print a warning and skip schema validation, keeping their own layout checks. The **generated HTML never has dependencies**; only the renderers do.++If you have no shell access at all (e.g. the skill was added as project knowledge), fall back to architecture mode for every request: hand-place SVG into `assets/template.html` following the Design System below, and run the self-review checklist before delivering.-| Type | Use for | Output path |-|------|---------|-------------|-| `architecture` | System components, cloud resources, services, storage, security boundaries, and infrastructure relationships | Hand-place SVG components inside `assets/template.html` |-| `workflow` | Technical flows, request lifecycles, approval gates, tool calls, runbooks, CI/CD paths, incident response, and process ownership | Prefer `renderers/workflow/render-workflow.mjs` with a workflow JSON file |-| `sequence` | API calls, request lifecycles, service interactions, cache fallback paths, async trace/logging, and return paths over time | Prefer `renderers/sequence/render-sequence.mjs` with a sequence JSON file |-| `dataflow` | Data pipelines, ETL/ELT, analytics flows, PII isolation, governance boundaries, lineage, warehouse sync, and downstream consumers | Prefer `renderers/dataflow/render-dataflow.mjs` with a data-flow JSON file |-| `lifecycle` | State machines, object lifecycles, run/order/deployment status transitions, wait states, retries, terminal states, and recovery paths | Prefer `renderers/lifecycle/render-lifecycle.mjs` with a lifecycle JSON file |+## Choosing a Diagram Type-When the user says "architecture", "system diagram", "cloud diagram", or asks to understand a codebase structure, use the `architecture` mode unless the requested output is clearly process-oriented.+| Type | Use for | How |+|------|---------|-----|+| `architecture` | System components, cloud resources, services, security boundaries, infrastructure | `renderers/architecture/render-architecture.mjs` + JSON (or hand-place SVG when renderers can't run) |+| `workflow` | Technical flows, approval gates, tool calls, runbooks, CI/CD, incident response | `renderers/workflow/render-workflow.mjs` + JSON |+| `sequence` | API call chains, request lifecycles, cache fallback, async traces, return paths | `renderers/sequence/render-sequence.mjs` + JSON |+| `dataflow` | Pipelines, ETL/ELT, PII isolation, lineage, warehouse sync, consumers | `renderers/dataflow/render-dataflow.mjs` + JSON |+| `lifecycle` | State machines, status transitions, wait states, retries, terminal states | `renderers/lifecycle/render-lifecycle.mjs` + JSON |-When the user says "workflow", "flow", "process", "runbook", "sequence of steps", "approval", "CI/CD", "incident", or asks how work moves through actors/systems over time, use the `workflow` mode.+Trigger phrases: "architecture/system/cloud diagram" → `architecture` (unless clearly process-oriented). "workflow/flow/process/runbook/approval/CI-CD/incident" → `workflow`. "sequence/interaction/call chain/who calls whom" → `sequence`. "data flow/pipeline/ETL/lineage/PII/governance" → `dataflow`. "state/status/lifecycle/state machine/retry/terminal" → `lifecycle`.-When the user says "sequence", "interaction", "call sequence", "request lifecycle", "API call chain", "who calls whom", or asks how multiple participants interact over time, use the `sequence` mode.+## Mermaid as an Input Dialect-When the user says "data flow", "pipeline", "ETL", "ELT", "lineage", "analytics", "warehouse", "PII", "consent", "governance", or asks where data comes from, how it is transformed, and who consumes it, use the `dataflow` mode.+When the user pastes Mermaid code, do NOT try to render or parse it mechanically — read it for structure and **lay out from scratch** in the matching archify mode:-When the user says "state", "status", "lifecycle", "state machine", "terminal", "retry", "cancel", "timeout", "order lifecycle", "deployment lifecycle", "agent run lifecycle", or asks how an object changes state over time, use the `lifecycle` mode.+| Mermaid | Archify mode | Mapping |+|---------|--------------|---------|+| `flowchart` / `graph` | `workflow` (or `architecture` if it's a component map) | `subgraph` → lane or region boundary; node shape `{}` (diamond) → decision/security node; `-->` labels → edge labels (use sparingly); `classDef`/`style` → nearest semantic type |+| `sequenceDiagram` | `sequence` | `participant` → participants (pick semantic `type` from the name); `->>` → message, `-->>` → `return` variant; `Note` → message `note`; `rect` blocks → segments |+| `stateDiagram` | `lifecycle` | states → states (pick `start`/`active`/`waiting`/`success`/`failure` from names); `[*]` start/end → `start` type / `terminal` lane; transition labels → event-like labels |-### Schema Validation (all renderer modes)+Drop Mermaid styling; keep only the topology and meaning. You choose grouping, lane order, and what deserves emphasis — that judgment is the product.-Every JSON file is validated against its schema (`archify/schemas/*.schema.json`) before any layout work runs. Schema violations exit non-zero with a path-prefixed error message — for example `/cards/0/dot must be equal to one of the allowed values ["cyan","emerald","violet","amber","rose","orange","slate"]` or `/nodes/0/id must match pattern "^[a-zA-Z][a-zA-Z0-9_-]*$"`. Common things the schema catches before the renderer touches the file:+## Renderer Modes (workflow / sequence / dataflow / lifecycle)-- Unknown node/participant/state `type`, unknown card `dot`-- IDs containing spaces or starting with a digit-- Extra/misspelled fields (`additionalProperties: false` is set on every object)-- Missing required fields (`label`, `meta.title`, etc.)-- `schema_version` not equal to `1`+All four modes follow the same loop:-If a render fails with a schema error, fix the JSON and re-run; do not edit the renderer.+1. **Read first**: the schema (`schemas/<type>.schema.json`) and the complete worked example (`examples/*.{workflow,sequence,dataflow,lifecycle}.json`) — copy its patterns instead of guessing field shapes.+2. Write `<name>.<type>.json`.+3. Render: `node renderers/<type>/render-<type>.mjs <input>.json <output>.html` (paths relative to this skill's folder).+4. If it fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.-### Workflow Mode+Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. CJK text is measured at double width automatically.-Workflow diagrams use a compact JSON IR:+### Workflow```json{"schema_version": 1,"diagram_type": "workflow",- "meta": {- "title": "Release Workflow",- "subtitle": "PR to production deployment",- "output": "release-workflow.html",- "viewBox": [720, 780]- },- "lanes": [- { "id": "dev", "label": "Developer" },- { "id": "ci", "label": "CI" }+ "meta": { "title": "Release Workflow", "subtitle": "PR to production", "output": "release.html" },+ "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" } ],+ "nodes": [+ { "id": "pr", "lane": "dev", "col": 0, "type": "frontend", "label": "Open PR", "sublabel": "feature branch" },+ { "id": "build", "lane": "ci", "col": 1, "type": "backend", "label": "Build", "sublabel": "lint + test", "tag": "blocking" }+ ],+ "edges": [+ { "from": "pr", "to": "build", "label": "webhook", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" }],- "nodes": [],- "edges": [],"cards": []}```-If you have filesystem/tool access, create a workflow JSON file and render it with:--```bash-node archify/renderers/workflow/render-workflow.mjs workflow.json workflow.html-```--The renderer:--- Places nodes by lane + column instead of raw SVG coordinates-- Routes edges through explicit anchors and orthogonal route presets-- Uses `c-lane` swimlanes plus the normal semantic component classes-- Adds a `c-mask` label background for routed labels-- Fails fast on schema violations, overlapping nodes, out-of-lane placement, and labeled short links — keep adjacent-step labels minimal in the JSON to avoid the short-link error+**Layout budget**: 6 columns (`col` 0–5) at fixed x positions `[88, 220, 300, 430, 500, 625]` — columns 1↔2 and 3↔4 are only 70–80px apart, so default-width (92px) nodes in those adjacent columns of the same lane overlap; skip a column or shrink `width`. Lane content width is 640px. Omit `meta.viewBox` — the renderer sizes height to the lane count automatically. Edge routes: `straight`, `drop` (bend between lanes; `bias` 0–1 picks where), `outside-right`, `return-left`, `bottom-channel`, `up-channel`, or explicit `via` points. Keep adjacent-step edges unlabeled; reserve labels for cross-lane transitions, approvals, async writes, and returns.-Use workflow labels sparingly. Adjacent steps should often be unlabeled; reserve labels for cross-lane transitions, approval decisions, async trace writes, and return paths.--### Sequence Mode--Sequence diagrams use a compact JSON IR:+### Sequence```json{"schema_version": 1,"diagram_type": "sequence",- "meta": {- "title": "Cache Miss Request Sequence",- "subtitle": "Frontend request path with auth and cache fallback",- "output": "cache-miss-request.html",- "viewBox": [820, 760]- },+ "meta": { "title": "Cache Miss Request", "subtitle": "auth and cache fallback", "output": "cache-miss.html" },"participants": [{ "id": "web", "type": "frontend", "label": "Web App", "sublabel": "React UI" },- { "id": "api", "type": "backend", "label": "API", "sublabel": "request handler" }+ { "id": "api", "type": "backend", "label": "API", "sublabel": "handler" }+ ],+ "segments": [ { "from": 160, "to": 320, "label": "01 / AUTH" } ],+ "messages": [+ { "from": "web", "to": "api", "y": 200, "label": "GET /data", "variant": "emphasis" },+ { "from": "api", "to": "web", "y": 290, "label": "200 JSON", "variant": "return" }],- "messages": [],- "activations": [],+ "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],"cards": []}```-If you have filesystem/tool access, create a sequence JSON file and render it with:+**Layout budget**: participants sit at x = 62 + index×108, so a 920-wide viewBox fits at most 8. Message `y` must stay within `[160, viewBox_height − 83]`; messages that share horizontal space need ≥28px vertical separation; arrows need ≥60px horizontal span. `segments[].from/to` and `activations[].from/to` are **y pixel coordinates**, not participant ids. A taller `meta.viewBox` (default `[920, 760]`) buys more timeline room. Keep labels short: "GET /path", "verify JWT", "cache miss", "200 JSON".-```bash-node archify/renderers/sequence/render-sequence.mjs sequence.json sequence.html-```--The renderer:--- Places participants across the top and time downward-- Uses semantic message variants: `emphasis`, `security`, `return`, and `dashed`-- Uses activation bars to show ownership duration-- Uses light segment bands as story landmarks-- Fails fast on schema violations, overflowing participants, unknown message endpoints, and rows that are too tight--Use sequence diagrams when the important thing is order over time. Keep labels short; prefer "GET /path", "verify JWT", "cache miss", "emit trace", and "200 JSON" over prose sentences.--### Data-flow Mode--Data-flow diagrams use a compact JSON IR:+### Dataflow```json{"schema_version": 1,"diagram_type": "dataflow",- "meta": {- "title": "Product Analytics Data Flow",- "subtitle": "Events, consent, PII isolation, warehouse sync, and consumers",- "output": "product-analytics.html",- "viewBox": [900, 720]- },- "stages": [- { "label": "Sources" },- { "label": "Ingest" },- { "label": "Process" },- { "label": "Store" },- { "label": "Consume" }+ "meta": { "title": "Product Analytics", "subtitle": "events to consumers", "output": "analytics.html" },+ "stages": [ { "label": "Sources" }, { "label": "Ingest" }, { "label": "Store" } ],+ "nodes": [+ { "id": "web", "type": "frontend", "label": "Web App", "stage": 0, "row": 0, "sublabel": "clickstream" },+ { "id": "kafka", "type": "messagebus", "label": "Kafka", "stage": 1, "row": 0, "tag": "accepted events" }+ ],+ "flows": [+ { "from": "web", "to": "kafka", "label": "events", "classification": "PII touch", "variant": "emphasis" }],- "nodes": [],- "flows": [],"cards": []}```-If you have filesystem/tool access, create a data-flow JSON file and render it with:--```bash-node archify/renderers/dataflow/render-dataflow.mjs dataflow.json dataflow.html-```--The renderer:--- Places nodes by lifecycle stage + row-- Uses vertical stage bands for source, ingest, process, store, and consume boundaries-- Uses flow labels to name data assets, plus optional `classification` for PII/governance context-- Uses semantic variants: `emphasis` for the primary data path, `security` for PII/policy/consent/restricted joins, and `dashed` for async or batch derivations-- Fails fast on schema violations, node overlap, stage overflow, unknown flow endpoints, missing labels, and unreadably short arrows+**Layout budget**: 2–5 stages at x = 100 + stage×215; 5 rows (`row` 0–4) at y `[128, 242, 356, 470, 584]`; default node 112×58. Default viewBox `[940, 720]`. Flow labels are mandatory and asset-like ("clickstream", "identity map", "feature vectors"); put sensitivity in `classification` ("PII touch", "approved only", "non-PII"). Variants: `emphasis` = primary path, `security` = PII/policy/consent, `dashed` = async/batch.-Use data-flow diagrams when the important thing is data lineage and governance. Keep labels asset-like: "clickstream", "identity map", "normalized facts", "feature vectors", "restricted join". Put sensitivity in `classification`: "PII touch", "encrypted PII", "approved only", "non-PII", "read-only".--### Lifecycle Mode--Lifecycle diagrams use a compact JSON IR:+### Lifecycle```json{"schema_version": 1,"diagram_type": "lifecycle",- "meta": {- "title": "Agent Run Lifecycle",- "subtitle": "State machine for planning, execution, waits, retries, and terminal outcomes",- "output": "agent-run.html",- "viewBox": [980, 720]- },+ "meta": { "title": "Agent Run Lifecycle", "subtitle": "states and terminal outcomes", "output": "agent-run.html" },"lanes": [- { "id": "main", "label": "Main lifecycle" },- { "id": "waiting", "label": "Wait states" },- { "id": "exceptions", "label": "Exceptions + recovery" }+ { "id": "main", "label": "Lifecycle phases" },+ { "id": "waiting", "label": "Interruptions" },+ { "id": "terminal", "label": "Terminal exits" }+ ],+ "states": [+ { "id": "queued", "type": "start", "label": "Queued", "lane": "main", "col": 0, "step": "01" },+ { "id": "running", "type": "active", "label": "Executing", "lane": "main", "col": 2, "step": "02" },+ { "id": "approval", "type": "waiting", "label": "Needs Approval", "lane": "waiting", "col": 0 },+ { "id": "done", "type": "success", "label": "Completed", "lane": "terminal", "col": 2 }+ ],+ "transitions": [+ { "from": "queued", "to": "running", "variant": "emphasis" },+ { "from": "running", "to": "approval", "label": "needs approval", "variant": "security", "fromSide": "bottom", "toSide": "right" },+ { "from": "running", "to": "done", "label": "success", "variant": "emphasis", "fromSide": "bottom", "toSide": "top" }],- "states": [],- "transitions": [],"cards": []}```-If you have filesystem/tool access, create a lifecycle JSON file and render it with:--```bash-node archify/renderers/lifecycle/render-lifecycle.mjs lifecycle.json lifecycle.html-```--The renderer:--- Places states by lane + column-- Uses lanes to separate the happy path, wait states, and exception/recovery paths-- Uses semantic state types: `start`, `active`, `waiting`, `decision`, `success`, `failure`, and `neutral`-- Uses transition variants: `emphasis` for the primary lifecycle, `security` for failure/cancel/timeout/policy paths, and `dashed` for retry/resume paths-- Fails fast on schema violations, state overlap, out-of-lane placement, unknown lanes, unknown transition endpoints, and legends pushed outside the viewBox--Use lifecycle diagrams when the important thing is state, not step-by-step work. Keep transition labels event-like: "start", "plan ready", "needs approval", "retry", "timeout", "cancel". Put terminal states on the right or in the bottom lane so endings are visually unambiguous.--## The Cardinal Rule: Use CSS Classes, Not Inline Colors--The theme toggle works by switching CSS custom properties. If you hardcode `fill="rgba(...)"` or `stroke="#22d3ee"` on SVG elements, those values will NOT update when the theme changes. Always prefer the class-based system.--### Do this--```svg-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>-<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>-<text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>-```--### Don't do this--```svg-<!-- Hardcoded colors break the theme toggle -->-<rect fill="rgba(6, 78, 59, 0.4)" stroke="#34d399" .../>-<text fill="white" .../>-```--## Design System--### Component color classes--| Component Type | Fill class | Text color class | When to use |-|------------------|------------------|------------------|--------------------------------------------|-| Frontend | `c-frontend` | `t-frontend` | Client apps, browsers, mobile, UI |-| Backend | `c-backend` | `t-backend` | Services, APIs, workers, daemons |-| Database | `c-database` | `t-database` | DBs, caches, log files, data stores |-| Cloud / AWS | `c-cloud` | `t-cloud` | Managed cloud services, infra |-| Security | `c-security` | `t-security` | Auth providers, secrets, guards |-| Message Bus | `c-messagebus` | `t-messagebus` | Kafka/RabbitMQ/SNS/Event buses |-| External/Generic | `c-external` | `t-muted` | Users, 3rd parties, anything uncategorized |+**Layout budget — lane ids are semantic and reserved**: `main` is required and maps to the top phase band (cols 0–4); `terminal` maps to the bottom outcome band (cols 0–2); **every other lane id shares the single middle event band** (cols 0–2) — separate same-band states with different `col` or `yOffset`. Band headers render from your lane labels. Default viewBox `[980, 660]`. Keep transition labels event-like and sparse ("retry", "timeout", "cancel"); prefer state `tag`s, `step` numbers, and summary cards over label-heavy arrows. Put terminal states in the `terminal` lane so endings are unambiguous.-Text on a dark or light background uses three neutral helpers:+### Per-mode deep guidance-| Text class | Role |-|-------------|-------------------------------|-| `t-primary` | Component names / titles |-| `t-muted` | Sublabels, annotations |-| `t-dim` | Tertiary / footer metadata |+Each renderer has a README with its full design language (route presets, semantic types, story guidance): `renderers/workflow/README.md`, `renderers/sequence/README.md`, `renderers/dataflow/README.md`, `renderers/lifecycle/README.md`. Read the matching one before your first diagram of that mode in a session.-Per-semantic text accents also exist: `t-frontend`, `t-backend`, `t-database`, `t-cloud`, `t-security`, `t-messagebus`, `t-external` — use when you want a label colored to match its component type (e.g., a small "OAI Protected" caption inside a cloud-type box).+## Architecture Mode-### Arrow classes+Architecture has the same read-schema-then-render loop as the other modes — prefer it. Hand-placed SVG is the fallback for when renderers can't run.-| Class | Marker id | Semantic |-|---------------|----------------------------|--------------------------------|-| `a-default` | `#arrowhead` | Standard data/flow arrow |-| `a-emphasis` | `#arrowhead-emphasis` | Live event stream / hot path |-| `a-security` | `#arrowhead-security` | Auth / security flow (dashed) |-| `a-dashed` | `#arrowhead-dashed` | Async / secondary (dashed) |--Always set `stroke-width` on the line (e.g., `1.5`) — the class only sets color and dasharray.--### Boundary classes--| Class | Purpose |-|---------------------|------------------------------------|-| `c-security-group` | Dashed rose boundary for SGs |-| `c-region` | Large dashed amber region/cluster |-| `c-lane` | Subtle swimlane for workflow/process diagrams |--### Typography--Inherit from the SVG root (already wired to JetBrains Mono). Font sizes: 12px for component names, 9px for sublabels, 8px for annotations, 7px for tiny labels.--### Visual Elements--**Background grid:** Automatically themed via `.c-grid` inside the `<pattern id="grid">`. Don't modify.--**Component boxes:** Rounded rectangles (`rx="6"`), `stroke-width="1.5"`, using the `.c-<type>` classes.--**Arrow z-order:** Draw connection arrows BEFORE component boxes (earlier in the SVG). SVG paints in document order, so arrows drawn first appear behind shapes drawn later.--**Masking arrows behind transparent fills:** Component fills are semi-transparent, which means arrows behind them bleed through. The template solves this with a two-rect pattern — an opaque mask rect, then the styled component on top:--```svg-<!-- 1. opaque mask (themed: dark=#0f172a, light=#ffffff) -->-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>-<!-- 2. styled component on top -->-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-database" stroke-width="1.5"/>-```--Always use `c-mask` instead of hardcoded `fill="#0f172a"` — the mask color itself is themed.--**Message buses / Event buses:** Small connector elements between services:--```svg-<rect x="X" y="Y" width="120" height="20" rx="4" class="c-messagebus" stroke-width="1"/>-<text x="CENTER_X" y="Y+14" class="t-messagebus" font-size="7" text-anchor="middle">Kafka / RabbitMQ</text>-```--### Spacing Rules--**CRITICAL:** When stacking components vertically, ensure proper spacing to avoid overlaps:--- **Standard component height:** 60px for services, 80-120px for larger components-- **Minimum vertical gap between components:** 40px-- **Inline connectors (message buses):** Place IN the gap between components, not overlapping--**Example vertical layout:**-```-Component A: y=70, height=60 -> ends at y=130-Gap: y=130 to y=170 -> 40px gap, place bus at y=140 (20px tall)-Component B: y=170, height=60 -> ends at y=230-```--**Wrong:** Placing a message bus at y=160 when Component B starts at y=170 (causes overlap)-**Right:** Placing a message bus at y=140, centered in the 40px gap (y=130 to y=170)--### Security Group & Region Boundary Padding--When a component sits inside a `c-security-group` or `c-region` boundary, the small label on the boundary (e.g., `sg-name :port`, `AWS Region: us-west-2`) needs room above the inner component — otherwise the label visually crashes into the box below it.--**Rule:** boundary `y` = inner-component `y` − 30, boundary `height` = inner-component `height` + 50. Place the label 18px below the boundary top (baseline). This yields ~12px clear gap between the label baseline and the inner component's top edge.--**Example** — a Load Balancer (y=280, h=50) inside a security group:--```svg-<!-- Security group — extends 30px above and 20px below the inner box -->-<rect x="350" y="250" width="120" height="100" rx="8" class="c-security-group" stroke-width="1"/>-<text x="358" y="268" class="t-security" font-size="8">sg-name :port</text>--<!-- Inner component — unchanged coordinates -->-<rect x="360" y="280" width="100" height="50" rx="6" class="c-mask"/>-<rect x="360" y="280" width="100" height="50" rx="6" class="c-cloud" stroke-width="1.5"/>+```json+{+ "schema_version": 1,+ "diagram_type": "architecture",+ "meta": { "title": "Sample Web App", "subtitle": "3-tier SaaS on AWS", "output": "web-app.html" },+ "components": [+ { "id": "users", "type": "external", "label": "Users", "sublabel": "Browser", "pos": [40, 300] },+ { "id": "api", "type": "backend", "label": "API Server", "sublabel": "FastAPI :8000", "pos": [460, 300] },+ { "id": "db", "type": "database", "label": "PostgreSQL", "sublabel": ":5432", "pos": [680, 300] }+ ],+ "boundaries": [+ { "kind": "region", "label": "AWS us-west-2", "wraps": ["api", "db"] }+ ],+ "connections": [+ { "from": "users", "to": "api", "label": "HTTPS", "variant": "emphasis" },+ { "from": "api", "to": "db", "label": "SQL" }+ ],+ "cards": []+}```-If the inner component is taller (e.g., a 100px multi-line box), keep the 30/50 offsets — the extra vertical room on top stays the same, the bottom padding grows naturally.+Render: `node renderers/architecture/render-architecture.mjs <input>.json <output>.html`.-### Legend Placement+**The renderer does the mechanical work that used to be hand-tuned**, so you only choose coordinates and meaning:-**CRITICAL:** Place legends OUTSIDE all boundary boxes (region boundaries, cluster boundaries, security groups).+- **Free coordinates** — `pos: [x, y]` is the component's top-left; `size: [w, h]` defaults to `[120, 60]`. Unlike the typed modes there is no lane/stage grid — asymmetric placement is yours to choose. `meta.viewBox` is optional (auto-fitted to your components + a legend row).+- **Boundaries from `wraps`** — list the component ids a `region` (dashed amber) or `security-group` (dashed rose) encloses; the renderer computes the box with correct 30/50 padding automatically. Never hand-arithmetic a boundary again.+- **Connections** route like edges (`variant`, `fromSide`/`toSide`, `route: straight|orthogonal-h|orthogonal-v|auto`, `via`, `labelDx/labelDy/labelAt`). For a vertical labeled connection, push the label into the gap with `labelDy` (the validator will tell you if it lands on a box).+- The renderer auto-emits the two-rect `c-mask` pattern, draws arrows before boxes (z-order), builds the legend from the component types you used, and **fails fast on component overlap, off-canvas components/boundaries, unknown wraps/connection ids, label-vs-component collisions, and non-finite coordinates** — the same reliability the other four modes already had.-- Calculate where all boundaries end (y position + height)-- Place legend at least 20px below the lowest boundary-- Expand SVG viewBox height if needed to accommodate+### Hand-placed fallback (no renderer available)-### Layout Structure+When Node/ajv can't run, copy `assets/template.html` and place SVG by hand. Study the worked diagram inside the template and `examples/web-app.html` for coordinate idioms, follow the Design System below, and run the self-review checklist before delivering.-1. **Header** — Title with pulsing dot indicator, subtitle-2. **Toolbar** (auto-included from template) — theme toggle + export menu, top-right fixed position-3. **Main SVG diagram** — contained in rounded border card-4. **Summary cards** — grid of 3 cards below diagram with key details-5. **Footer** — minimal metadata line+### The Cardinal Rule: CSS classes, not inline colors-## Component Box Pattern+The theme toggle works by switching CSS custom properties. Hardcoded `fill="rgba(...)"` or `stroke="#22d3ee"` will NOT update on theme change. Always use the class system:```svg<rect x="X" y="Y" width="W" height="H" rx="6" class="c-mask"/>-<rect x="X" y="Y" width="W" height="H" rx="6" class="c-<type>" stroke-width="1.5"/>-<text x="CENTER_X" y="Y+20" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">LABEL</text>-<text x="CENTER_X" y="Y+36" class="t-muted" font-size="9" text-anchor="middle">sublabel</text>+<rect x="X" y="Y" width="W" height="H" rx="6" class="c-backend" stroke-width="1.5"/>+<text x="CX" y="CY" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">API Server</text>+<text x="CX" y="CY+16" class="t-muted" font-size="9" text-anchor="middle">FastAPI :8000</text>```-## Arrow Patterns+### Design system-```svg-<!-- Standard -->-<line x1="..." y1="..." x2="..." y2="..." class="a-default" stroke-width="1.5" marker-end="url(#arrowhead)"/>+Component fills `c-frontend` (clients/UI), `c-backend` (services/APIs), `c-database` (stores/caches), `c-cloud` (managed infra), `c-security` (auth/secrets), `c-messagebus` (Kafka/queues), `c-external` (3rd parties); text accents `t-<same>` plus neutrals `t-primary` / `t-muted` / `t-dim`. Arrows `a-default`, `a-emphasis` (hot path), `a-security` (dashed), `a-dashed` (async) — always set `stroke-width` and pair `marker-end="url(#arrowhead[-variant])"` with the matching class. Boundaries: `c-security-group` (dashed rose), `c-region` (dashed amber), `c-lane` (swimlane).-<!-- Emphasis (live events / hot path) -->-<line x1="..." y1="..." x2="..." y2="..." class="a-emphasis" stroke-width="1.5" marker-end="url(#arrowhead-emphasis)"/>+Typography inherits JetBrains Mono from the SVG root. Sizes: 11–12px component names, 9px sublabels, 8px annotations, 7px tiny labels.-<!-- Security / auth flow (dashed) -->-<path d="..." class="a-security" stroke-width="1.5" marker-end="url(#arrowhead-security)"/>+### Hard layout rules-<!-- Async / secondary (dashed) -->-<path d="..." class="a-dashed" stroke-width="1" marker-end="url(#arrowhead-dashed)"/>-```+- **Two-rect pattern everywhere**: opaque `c-mask` rect first, styled `c-<type>` rect on top — semi-transparent fills otherwise let arrows bleed through.+- **Arrows before components** in document order (SVG paints in order; arrows must sit behind boxes).+- **Vertical stacking**: ≥40px gap between components; inline connectors (message buses, 20px tall) live inside the gap, never overlapping boxes.+- **Boundary padding**: boundary `y` = inner `y` − 30, boundary `height` = inner `height` + 50, label baseline 18px below the boundary top.+- **Legend placement**: outside ALL boundary boxes, ≥20px below the lowest one; grow the viewBox if needed.-Pair each arrow class with the matching marker id (same suffix).--## Info Card Pattern--```html-<div class="card">- <div class="card-header">- <div class="card-dot COLOR"></div>- <h3>Title</h3>- </div>- <ul>- <li>• Item one</li>- <li>• Item two</li>- </ul>-</div>-```+### Self-review checklist (run before delivering)-Valid `card-dot` colors: `cyan`, `emerald`, `violet`, `amber`, `rose`, `orange`, `slate` — all automatically re-theme. Pair the dot to its component semantic (e.g., `orange` for a "Messaging" card, `slate` for an "External Services" card).--## Template--Copy and customize the template at `assets/template.html`. Customization points:--1. Update the `<title>` and header `<h1>` text + subtitle-2. Modify SVG `viewBox` dimensions if needed (default: `1000 x 680`)-3. Add/remove/reposition component boxes using the `.c-<type>` classes-4. Draw connection arrows using `.a-<variant>` classes-5. Update the three summary cards-6. Update footer metadata--Do NOT remove the `.toolbar` element, the `<script>` blocks, or the `:root` / `[data-theme="..."]` CSS. Those are what give every generated diagram the theme toggle and export buttons.+1. `grep -E 'fill="(#|rgb)|stroke="(#|rgb)' out.html` inside the SVG returns nothing except the template's own defs (Cardinal Rule).+2. Every `c-<type>` rect has an identical-geometry `c-mask` rect immediately before it.+3. All `<line>`/`<path>` arrows appear before all component rects in document order.+4. Compute max(y + height) over all SVG elements: viewBox height must exceed it by ≥20px; same for x/width.+5. Legend y is below every boundary's y + height.+6. The `.toolbar`, `<script>` blocks, and `:root` / `[data-theme]` CSS are untouched — they ARE the theme toggle and export menu.## Output-Produce a single self-contained `.html` file with:--- Embedded CSS (no external stylesheets except Google Fonts)-- Inline SVG (no external images)-- Small amount of embedded JS (theme toggle + export) — keep as-is from template--The file should render correctly when opened directly in any modern browser. The **Export** menu should cleanly copy PNG to the clipboard, download PNG / JPEG / WebP (all at 4× source resolution, rendered natively by the browser — no bitmap upsampling), and download a **dual-theme self-contained SVG** whose colors follow the embedding host's `prefers-color-scheme` (dark by default; swaps to light under a light host; `svg[data-theme="..."]` still works as a manual override).+A single self-contained `.html`: embedded CSS (Google Fonts loads async and degrades to system monospace offline), inline SVG, ~19KB embedded JS for theme + export. It renders directly in any modern browser. Raster exports render natively at up to 4× the viewBox (large diagrams step down to 3×/2× to stay under canvas limits); the SVG download is dual-theme self-contained and follows the host's `prefers-color-scheme` (manual override via `svg[data-theme="..."]`).diff --git a/docs/index.html b/docs/index.htmlindex e2b4d8a5..acdd706b 100644--- a/docs/index.html+++ b/docs/index.html@@ -131,6 +131,8 @@.step-num { width:48px; height:48px; border-radius:50%; border:1px solid var(--border-hi); display:flex; align-items:center; justify-content:center; font-size:.8125rem; font-weight:700; color:var(--cyan); background:var(--bg); flex-shrink:0; position:relative; z-index:1; }.step-content h4 { font-size:.9375rem; font-weight:600; letter-spacing:-.02em; color:var(--text); margin-bottom:.5rem; padding-top:.75rem; }.step-content p { font-size:.8125rem; color:var(--muted); line-height:1.7; text-wrap:pretty; }+ .step-content a { color:var(--cyan); text-decoration:none; border-bottom:1px solid rgba(34,211,238,.4); transition:border-color .15s; }+ .step-content a:hover { border-bottom-color:var(--cyan); }/* CODE BLOCK */.code-block { background:rgba(15,23,42,.8); border:1px solid var(--border-hi); border-radius:.75rem; overflow:hidden; }@@ -214,7 +216,7 @@<div class="container"><div class="hero-badge fade-up"><div class="pulse-dot"></div>- <span data-i18n="hero-badge">Claude Skill · v2.4.0</span>+ <span data-i18n="hero-badge">Claude Skill · v2.6.0</span></div><h1 class="fade-up d1" data-i18n="hero-h1">From plain English<br>to architecture <em>in seconds.</em></h1><p class="hero-sub fade-up d2" data-i18n="hero-sub">Describe your system in chat. Archify generates a polished, self-contained HTML diagram — with dark/light themes, clipboard copy, and ultra-crisp 4× export built in.</p>@@ -247,6 +249,7 @@</div><div class="type-tabs fade-up d2"><button class="type-tab active" data-type="arch" data-i18n="tab-arch">Architecture</button>+ <button class="type-tab" data-type="wf" data-i18n="tab-wf">Workflow</button><button class="type-tab" data-type="seq" data-i18n="tab-seq">Sequence</button><button class="type-tab" data-type="flow" data-i18n="tab-flow">Data Flow</button><button class="type-tab" data-type="life" data-i18n="tab-life">Lifecycle</button>@@ -268,6 +271,20 @@<div class="type-img-wrap"><img src="assets/archify-dark.png" alt="Architecture diagram"></div></div>+ <div class="type-panel fade-up" data-type="wf">+ <div class="type-info">+ <h3 data-i18n="wf-h">Workflow</h3>+ <p data-i18n="wf-p">Swim-lane processes with semantic nodes and anchored edges — approval gates, async branches, and observability paths, lane by lane.</p>+ <ul class="type-use-cases">+ <li data-i18n="wf-li1">CI/CD pipelines</li>+ <li data-i18n="wf-li2">Incident runbooks</li>+ <li data-i18n="wf-li3">Agent tool-call flows</li>+ <li data-i18n="wf-li4">Approval & async paths</li>+ </ul>+ </div>+ <div class="type-img-wrap"><img src="assets/archify-workflow.png" alt="Workflow diagram"></div>+ </div>+<div class="type-panel fade-up" data-type="seq"><div class="type-info"><h3 data-i18n="seq-h">Sequence</h3>@@ -336,7 +353,7 @@<svg width="18" height="18" viewBox="0 0 24 24" fill="none"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4" stroke="#34d399" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/><polyline points="7 10 12 15 17 10" stroke="#34d399" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round"/><line x1="12" y1="15" x2="12" y2="3" stroke="#34d399" stroke-width="1.75" stroke-linecap="round"/></svg></div><h3 data-i18n="f2-h">Ultra-crisp 4× export</h3>- <p data-i18n="f2-p">PNG, JPEG, WebP — all rasterized natively at 4× source resolution by the browser. No upsampling blur. Sharp on retina displays, slides, and print.</p>+ <p data-i18n="f2-p">PNG, JPEG, WebP — all rasterized natively at up to 4× source resolution by the browser. No upsampling blur. Sharp on retina displays, slides, and print.</p><span class="feature-tag" style="background:rgba(52,211,153,0.1);color:var(--emerald)" data-i18n="f2-tag">PNG · JPEG · WEBP</span></div><div class="feature-card fade-up d2">@@ -451,7 +468,7 @@<div class="step-num">1</div><div class="step-content"><h4 data-i18n="step1-h">Install the Skill</h4>- <p data-i18n="step1-p">Download archify.zip, go to Claude Settings → Capabilities → Skills, click + Add and upload it. Or unzip to ~/.claude/skills/ for CLI use.</p>+ <p data-i18n="step1-p">Download <a href="https://github.com/tt-a1i/archify/raw/main/archify.zip">archify.zip</a>, go to Claude Settings → Capabilities → Skills, click + Add and upload it. Or unzip to ~/.claude/skills/ for CLI use.</p></div></div><div class="step fade-up d2">@@ -536,7 +553,7 @@ this description.</span><svg width="22" height="22" viewBox="0 0 28 28" fill="none"><polygon points="14,2 26,8 26,20 14,26 2,20 2,8" fill="rgba(8,51,68,0.7)" stroke="#22d3ee" stroke-width="1.5"/><circle cx="14" cy="15" r="2.5" fill="#22d3ee"/></svg><span style="font-size:.8125rem;font-weight:700;color:var(--muted)">Archify</span></a>- <p class="footer-meta" data-i18n="footer-meta">v2.4.0 · MIT License<br>Based on Cocoon-AI/architecture-diagram-generator</p>+ <p class="footer-meta" data-i18n="footer-meta">v2.6.0 · MIT License<br>Based on Cocoon-AI/architecture-diagram-generator</p></div><div class="footer-links"><a href="https://github.com/tt-a1i/archify" target="_blank" rel="noopener">GitHub</a>@@ -553,17 +570,20 @@ this description.</span>const LANGS = {en: {'nav-docs':'Docs','nav-install':'Install Skill',- 'hero-badge':'Claude Skill · v2.4.0',+ 'hero-badge':'Claude Skill · v2.6.0','hero-h1':'From plain English<br>to architecture <em>in seconds.</em>','hero-sub':'Describe your system in chat. Archify generates a polished, self-contained HTML diagram — with dark/light themes, clipboard copy, and ultra-crisp 4× export built in.','hero-cta':'Get started','hero-gh':'View on GitHub','label-types':'Diagram Types','types-h2':'Five ways to see your system.','types-body':'Architecture, workflows, sequences, data flows, or state machines — describe what you need and Archify picks the right visual language.',- 'tab-arch':'Architecture','tab-seq':'Sequence','tab-flow':'Data Flow','tab-life':'Lifecycle',+ 'tab-arch':'Architecture','tab-wf':'Workflow','tab-seq':'Sequence','tab-flow':'Data Flow','tab-life':'Lifecycle','arch-h':'Architecture','arch-p':'System components, cloud resources, databases, caches, services, security groups, and the connections between them.','arch-li1':'AWS / GCP / Azure infra','arch-li2':'Microservices topology','arch-li3':'Security boundaries','arch-li4':'Network layout',+ 'wf-h':'Workflow',+ 'wf-p':'Swim-lane processes with semantic nodes and anchored edges — approval gates, async branches, and observability paths, lane by lane.',+ 'wf-li1':'CI/CD pipelines','wf-li2':'Incident runbooks','wf-li3':'Agent tool-call flows','wf-li4':'Approval & async paths','seq-h':'Sequence','seq-p':'API call chains, request lifecycles, cache fallback paths, auth checks, async traces — who calls whom, in what order, and what returns.','seq-li1':'API request / response','seq-li2':'Cache miss fallback','seq-li3':'Auth & JWT flow','seq-li4':'Async trace emit',@@ -576,7 +596,7 @@ this description.</span>'label-features':'Features','features-h2':'Production-ready output,<br>zero configuration.','f1-h':'One-click theme toggle','f1-p':'Every diagram ships with dark and light themes. Toggle with a click or press T. Persists to localStorage, respects prefers-color-scheme on first visit.','f1-tag':'DARK & LIGHT',- 'f2-h':'Ultra-crisp 4× export','f2-p':'PNG, JPEG, WebP — all rasterized natively at 4× source resolution by the browser. No upsampling blur. Sharp on retina displays, slides, and print.','f2-tag':'PNG · JPEG · WEBP',+ 'f2-h':'Ultra-crisp 4× export','f2-p':'PNG, JPEG, WebP — all rasterized natively at up to 4× source resolution by the browser. No upsampling blur. Sharp on retina displays, slides, and print.','f2-tag':'PNG · JPEG · WEBP','f3-h':'Dual-theme SVG','f3-p':"The SVG export ships with both variable sets plus a @media prefers-color-scheme rule. Drop one file into a GitHub README — it follows the reader's theme.",'f3-tag':'VECTOR · SELF-THEMED','f4-h':'Copy to clipboard','f4-p':'One button puts a PNG straight on your clipboard. Paste directly into Slack, Notion, GitHub, or Figma — no intermediate save step.','f4-tag':'INSTANT SHARE','f5-h':'Self-contained HTML','f5-p':'One HTML file. Zero dependencies, no server, no runtime. Open it in any browser and it works. Share by attaching it to an email or PR comment.','f5-tag':'ZERO DEPS',@@ -596,27 +616,30 @@ this description.</span>'label-qs':'Quick Start','qs-h2':'Up and running<br>in three steps.','qs-body':'Requires Claude Pro, Max, Team, or Enterprise — or Claude Code CLI.',- 'step1-h':'Install the Skill','step1-p':'Download archify.zip, go to Claude Settings → Capabilities → Skills, click + Add and upload it. Or unzip to ~/.claude/skills/ for CLI use.',+ 'step1-h':'Install the Skill','step1-p':'Download <a href="https://github.com/tt-a1i/archify/raw/main/archify.zip">archify.zip</a>, go to Claude Settings → Capabilities → Skills, click + Add and upload it. Or unzip to ~/.claude/skills/ for CLI use.','step2-h':'Describe your system','step2-p':'Write a plain-English description of your architecture — components, connections, cloud services. Or ask Claude to analyze your codebase first.','step3-h':'Ask Claude to draw it','step3-p':'Tell Claude to use the Archify skill. It generates a self-contained HTML file you open in any browser. Iterate from there — in plain English.','code-label':'example prompt','kbd-label':'Keyboard shortcuts','kbd-theme':'Toggle theme','kbd-export':'Open export menu','kbd-nav':'Navigate menu','kbd-close':'Close menu',- 'footer-meta':'v2.4.0 · MIT License<br>Based on Cocoon-AI/architecture-diagram-generator',+ 'footer-meta':'v2.6.0 · MIT License<br>Based on Cocoon-AI/architecture-diagram-generator','footer-changelog':'Changelog','footer-license':'License'},zh: {'nav-docs':'文档','nav-install':'安装技能',- 'hero-badge':'Claude 技能 · v2.4.0',+ 'hero-badge':'Claude 技能 · v2.6.0','hero-h1':'用自然语言,<br>秒级生成<em>架构图。</em>','hero-sub':'在对话中描述你的系统,Archify 生成精美、独立的 HTML 架构图——内置深色/浅色主题、一键复制剪贴板、超清 4× 图片导出。','hero-cta':'快速开始','hero-gh':'在 GitHub 查看','label-types':'图表类型','types-h2':'五种方式,读懂你的系统。','types-body':'架构图、工作流、时序图、数据流图、状态机——描述需求,Archify 自动选择最合适的可视化语言。',- 'tab-arch':'架构图','tab-seq':'时序图','tab-flow':'数据流图','tab-life':'生命周期图',+ 'tab-arch':'架构图','tab-wf':'工作流图','tab-seq':'时序图','tab-flow':'数据流图','tab-life':'生命周期图','arch-h':'架构图','arch-p':'系统组件、云资源、数据库、缓存、服务、安全组及其连接关系,一图清晰呈现。','arch-li1':'AWS / GCP / Azure 基础设施','arch-li2':'微服务拓扑','arch-li3':'安全边界','arch-li4':'网络布局',+ 'wf-h':'工作流图',+ 'wf-p':'泳道式流程:语义化节点与锚定连线——审批门、异步分支、观测路径,逐泳道清晰铺开。',+ 'wf-li1':'CI/CD 流水线','wf-li2':'事故处置 Runbook','wf-li3':'Agent 工具调用流','wf-li4':'审批与异步路径','seq-h':'时序图','seq-p':'API 调用链、请求生命周期、缓存回退路径、鉴权检查、异步追踪——谁调用谁、顺序如何、返回什么。','seq-li1':'API 请求 / 响应','seq-li2':'缓存未命中回退','seq-li3':'Auth & JWT 流程','seq-li4':'异步 Trace 上报',@@ -629,7 +652,7 @@ this description.</span>'label-features':'功能特性','features-h2':'生产级输出,<br>零配置。','f1-h':'一键切换主题','f1-p':'每张图内置深色和浅色两套主题。点击按钮或按 T 键切换,自动持久化,首次访问遵循系统颜色偏好。','f1-tag':'深色 & 浅色',- 'f2-h':'超清 4× 导出','f2-p':'PNG、JPEG、WebP——由浏览器以 4 倍分辨率原生栅格化,无上采样模糊。视网膜屏、幻灯片、印刷均清晰。','f2-tag':'PNG · JPEG · WEBP',+ 'f2-h':'超清 4× 导出','f2-p':'PNG、JPEG、WebP——由浏览器以最高 4 倍分辨率原生栅格化,无上采样模糊。视网膜屏、幻灯片、印刷均清晰。','f2-tag':'PNG · JPEG · WEBP','f3-h':'双主题 SVG','f3-p':'SVG 导出同时内置深色和浅色变量集,并附 @media prefers-color-scheme 规则。放入 GitHub README,自动跟随读者主题。','f3-tag':'矢量 · 自适应主题','f4-h':'复制到剪贴板','f4-p':'一键将 PNG 写入剪贴板,直接粘贴到 Slack、Notion、GitHub 或 Figma,无需手动保存。','f4-tag':'即时分享','f5-h':'独立 HTML 文件','f5-p':'单个 HTML 文件,零依赖、无需服务器或构建工具,任意浏览器打开即用。作为附件发邮件或贴 PR 评论均可。','f5-tag':'零依赖',@@ -649,12 +672,12 @@ this description.</span>'label-qs':'快速开始','qs-h2':'三步上手,<br>即刻运行。','qs-body':'需要 Claude Pro、Max、Team 或 Enterprise 计划,或 Claude Code CLI。',- 'step1-h':'安装技能','step1-p':'下载 archify.zip,进入 Claude 设置 → 能力 → 技能,点击「+ 添加」上传。或解压至 ~/.claude/skills/ 供 CLI 使用。',+ 'step1-h':'安装技能','step1-p':'下载 <a href="https://github.com/tt-a1i/archify/raw/main/archify.zip">archify.zip</a>,进入 Claude 设置 → 能力 → 技能,点击「+ 添加」上传。或解压至 ~/.claude/skills/ 供 CLI 使用。','step2-h':'描述你的系统','step2-p':'用自然语言描述你的架构——组件、连接关系、云服务。也可以先让 Claude 分析你的代码仓库。','step3-h':'让 Claude 绘制','step3-p':'告诉 Claude 使用 Archify 技能,它会生成独立的 HTML 文件,用任意浏览器打开即可。然后继续用自然语言迭代。','code-label':'示例提示词','kbd-label':'键盘快捷键','kbd-theme':'切换主题','kbd-export':'打开导出菜单','kbd-nav':'菜单导航','kbd-close':'关闭菜单',- 'footer-meta':'v2.4.0 · MIT 许可证<br>基于 Cocoon-AI/architecture-diagram-generator',+ 'footer-meta':'v2.6.0 · MIT 许可证<br>基于 Cocoon-AI/architecture-diagram-generator','footer-changelog':'更新日志','footer-license':'许可证'}};