owwzo/ai-agent/dynamic-archify

Dynami-carchify Skill

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 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.

Setup (one-time, renderer modes only)

The four typed renderers validate JSON against schemas via ajv. From this skill's folder:

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.

Choosing a Diagram Type

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.

Mermaid as an Input Dialect

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:

Drop Mermaid styling; keep only the topology and meaning. You choose grouping, lane order, and what deserves emphasis — that judgment is the product.

Renderer Modes (workflow / sequence / dataflow / lifecycle)

All four modes follow the same loop:

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.

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

{
  "schema_version": 1,
  "diagram_type": "workflow",
  "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" }
  ],
  "cards": []
}

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.

Sequence

{
  "schema_version": 1,
  "diagram_type": "sequence",
  "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": "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" }
  ],
  "activations": [ { "participant": "api", "from": 190, "to": 300, "type": "backend" } ],
  "cards": []
}

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".

Dataflow

{
  "schema_version": 1,
  "diagram_type": "dataflow",
  "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" }
  ],
  "cards": []
}

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.

Lifecycle

{
  "schema_version": 1,
  "diagram_type": "lifecycle",
  "meta": { "title": "Agent Run Lifecycle", "subtitle": "states and terminal outcomes", "output": "agent-run.html" },
  "lanes": [
    { "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" }
  ],
  "cards": []
}

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 tags, step numbers, and summary cards over label-heavy arrows. Put terminal states in the terminal lane so endings are unambiguous.

Per-mode deep guidance

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.

Architecture Mode

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.

{
  "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": []
}

Render: node renderers/architecture/render-architecture.mjs <input>.json <output>.html.

The renderer does the mechanical work that used to be hand-tuned, so you only choose coordinates and meaning: