Diagram Visualization Skill
Design Principles
- Claim first (DIAGRAM-CLAIM-01): before choosing a type, name the reader, the decision they face, and one claim they could disagree with. That sentence becomes the caption and the
<title>. If there is no claim, write the sentence and skip the diagram.
- Shape carries meaning (DIAGRAM-SCOPE-01): draw when the point is a relation — contains, precedes, causes, branches, outweighs. Definitions, single facts, and values a reader must compare precisely belong in prose or a table. Recipes:
reference/visual-story.md.
- Never invent data (DIAGRAM-EVIDENCE-01): every quantity is observed, user-supplied, assumed, or illustrative, and the figure or caption says which. A chart of numbers you made up is not a placeholder, it is a false claim that renders beautifully. Put units on the axis, and say so when an axis does not start at zero. Classes and worked form:
reference/visual-story.md.
- Flat: No gradients, shadows, blur, glow, or decorative effects. Clean flat surfaces only.
- Compact: Show the essential inline. Explain the rest in response text.
- Theme-aware: Every color must work in both light and dark mode. Use CSS classes for SVG,
window.__jawTokens for canvas/JS.
- Text in response, visuals in tool: All explanatory prose goes outside the diagram. Never put paragraphs of explanation inside the SVG or widget HTML.
- Accessibility (DIAGRAM-A11Y-01): give the visual a claim-shaped name and description, a text or data alternative for values, meaningful heading order, readable contrast, and labels or shapes that preserve meaning without color. Interactive widgets need visible keyboard focus and reduced-motion behavior. Inspect actual contrast and reading order when the render tier calls for it; ARIA alone does not prove accessibility.
Complexity Budget — Hard Limits
- Box subtitles: ≤5 words. Detail goes in
sendPrompt() or prose — not the box.
- Colors: ≤2 ramps per diagram. More = visual noise.
- Horizontal row: ≤4 boxes at 680px width. 5+ boxes → shrink or wrap to 2 rows.
- Nodes: ≤6 per diagram. 7+ → split into overview + detail diagrams. One takeaway per figure (DIAGRAM-SEQ-01): the overview shows the level where the claim is visible, then a named detail figure zooms into one region. Shrinking everything into one frame until labels are unreadable is the failure this budget exists to prevent.
- Always add prose between diagrams — never output consecutive SVG blocks or widget blocks without text between them. That prose is claim-shaped (DIAGRAM-HANDOFF-01): it states what to conclude, not "the diagram below shows the architecture". Detail that will not fit a five-word subtitle goes here.
Diagram Type Selection
Route on the verb, not the noun. Same subject gets different diagrams. Prefer Mermaid when the diagram type maps cleanly to a native Mermaid syntax — it's cheaper than hand-rolling SVG.
| User says / intent |
Type |
Output |
| "how does X work" |
Illustrative SVG |
Spatial metaphor, cross-section, physical layout |
| "architecture of X" (system context) |
Structural SVG |
Containers, regions, nesting |
| "steps of X" (generic process) |
Flowchart SVG or Mermaid flowchart |
Top-down boxes + arrows |
| "compare A vs B" |
Comparison SVG |
Side-by-side columns |
| "DB schema / entity relationship" |
Mermaid |
```mermaid erDiagram |
| "class diagram / OOP structure" |
Mermaid |
```mermaid classDiagram |
| "state machine / lifecycle" |
Mermaid |
```mermaid stateDiagram-v2 |
| "sequence / call order / API flow" |
Mermaid |
```mermaid sequenceDiagram |
| "timeline / roadmap / history" |
Mermaid |
```mermaid timeline |
| "mind map / brainstorm / outline" |
Mermaid |
```mermaid mindmap |
| "git branching / release history" |
Mermaid |
```mermaid gitGraph |
| "2×2 matrix / priority quadrant" |
Mermaid |
```mermaid quadrantChart |
| "radar / spider / skill profile" |
Mermaid v11.6+ (beta) |
```mermaid radar-beta |
| "gantt / project schedule" |
Mermaid |
```mermaid gantt |
| "user journey map" |
Mermaid |
```mermaid journey |
| "pie breakdown (simple)" |
Mermaid |
```mermaid pie |
| "kanban board" |
Mermaid v11.12+ (beta, test before use) |
```mermaid kanban |
| "cloud/infra architecture" |
Mermaid (beta) |
```mermaid architecture-beta |
| "hierarchy / proportional size" |
Mermaid (beta) |
```mermaid treemap-beta |
| "free-form block layout" |
Mermaid |
```mermaid block |
| "packet / network frame" |
Mermaid |
```mermaid packet |
| "ishikawa / fishbone / cause-effect" |
Mermaid |
```mermaid ishikawa |
| "swimlane / lane-based workflow" |
Mermaid |
```mermaid swimlane-beta |
| "requirement / traceability" |
Mermaid |
```mermaid requirementDiagram |
| "sankey / flow quantity" |
Mermaid |
```mermaid sankey |
| "XY chart / scatter / line" |
Mermaid |
```mermaid xychart |
| "venn / overlap / set intersection" |
Mermaid (beta) |
```mermaid venn-beta |
| "show sources / search results / citations" |
structured-renderers skill |
Non-diagram native card: load structured-renderers for search-results schema |
| "visual report / explainer document" |
reference/visual-reports.md |
Follow jaw-dev/references/reader-documents.md for structure, then this reference for composition |
| "PDF report / PDF explainer" |
jaw-pdf skill |
Use reference/visual-reports.md for composition and jaw-pdf for output and final-page checks |
| "write / draft / compose email, message, document" |
structured-renderers skill |
Non-diagram native card: load structured-renderers for compose-block schema |
| "table / rows / sortable data / filterable data" |
structured-renderers skill |
Non-diagram native card: load structured-renderers for dataframe schema |
| "patch / diff / unified diff" |
structured-renderers skill |
Non-diagram native display: load structured-renderers for diff routing |
| "show data / chart" |
chart-json for simple bar/line/pie; diagram-file for advanced charts |
For chart-json, load structured-renderers; use file-backed Chart.js / D3 / ECharts iframe widgets when custom JS, maps, advanced chart types, or richer interactivity are required |
| "simulate / interactive" |
diagram-file |
File-backed Matter.js / Canvas / sliders widget |
| "large widget / iterative widget editing" |
diagram-file |
Default for all HTML widgets: write the full widget HTML to ~/.cli-jaw/widgets/<chatId>/<widgetId>.html, then emit an id-only file-backed fence |
| "interactive map (with pan/zoom/markers)" |
diagram-file |
File-backed Leaflet iframe widget — see reference/module-map.md |
| "static country/state choropleth" |
diagram-file |
File-backed D3 + TopoJSON widget — see reference/module-chart.md |
Default to illustrative SVG for "how does X work?" — don't default to flowchart. Default to Mermaid when the type is in the table above — don't hand-roll an SVG when classDiagram/sequenceDiagram/stateDiagram already exists.
diagram-file is the default for all HTML widget types. Use diagram-html only as a fallback when the chatId cannot be determined or for very small throwaway widgets that do not warrant a file.
Native Web UI renderer boundary
Before producing a diagram-file HTML widget, check whether a native renderer is a better fit:
- Load
structured-renderers for search-results, compose-block, dataframe, chart-json, and diff schemas.
- Use
chart-json for simple single-series bar/line/pie charts.
- Stay in
diagram and use diagram-file for maps, multi-series charts, advanced chart types, custom JavaScript, external libraries, or richer interaction.
These renderers are lighter than HTML widgets, survive sanitizer/hydration, and avoid iframe overhead. They are final-answer-only structured fences; during streaming they remain inert code blocks. Keep JSON complete, compact, and schema-versioned. See the active structured-renderers skill for canonical schemas and examples.
OfficeCLI raster CJK rule
When OfficeCLI rasterizes Mermaid to PNG and the diagram contains Korean/CJK text,
prepend this directive to the Mermaid source before rendering:
%%{init: {"themeVariables":{"fontFamily":"Noto Sans KR, Apple SD Gothic Neo, NanumGothic, Malgun Gothic, sans-serif"}}}%%
After export, open and inspect the PNG. Confirm that Korean glyphs are not tofu
boxes, labels are not clipped, and the fallback font did not change node metrics.
Rendering or a successful OfficeCLI exit code is not visual verification.
Mermaid gotchas (read before using beta/experimental types)
- Do NOT use C4 diagrams (
C4Context, C4Container, etc.) — theme tokens are not applied in dark mode, text becomes unreadable (mermaid #4906). Substitute routing:
- C4 System Context → Structural SVG (custom) OR Mermaid
flowchart with subgraphs
- C4 Container → Mermaid
architecture-beta (cloud/infra layout)
- C4 Component → Mermaid
flowchart with subgraph grouping
- C4 Dynamic → Mermaid
sequenceDiagram
- C4 Deployment → Mermaid
architecture-beta
sankey-beta / xychart-beta — known to break scale-down at narrow chat widths. Prefer diagram-file + ECharts sankey for flow diagrams, Chart.js for simple XY.
- Now stable (no suffix needed):
block, packet, kanban, sankey, xychart, ishikawa.
- Still beta (suffix required):
radar-beta, architecture-beta, treemap-beta, venn-beta, wardley-beta, treeView-beta, cynefin-beta, swimlane-beta. Test beta types in the cli-jaw Web UI before finalizing.
sandbox securityLevel iframe background bug (mermaid #5034) — affects host rendering, not your output. No action needed from the agent.
- Theme: all stable Mermaid types pick up the host dark/light theme automatically via cli-jaw's
themeVariables. Do NOT set explicit colors in %%{init: ...}%% unless overriding for semantic reasons.
Syntax boundary (DIAGRAM-SYNTAX-01): use an existing SVG/Mermaid parser or checker when available. Valid syntax cannot prove labels do not overlap. Do not install a new runner solely to check an incidental visual.
When to Use
1. Explicit request (명시적 요청)
한국어: "그려줘", "시각화", "다이어그램", "차트로", "도표로", "비교표", "플로우차트"
영어: "draw", "visualize", "diagram", "chart", "graph", "illustrate", "show me"
2. Proactive generation (에이전트 판단)
다음 상황에서 텍스트만으로는 전달이 부족할 때 자동 생성:
- 시스템/프로세스 아키텍처 설명 (3+ 컴포넌트)
- 데이터 3항목 이상 비교
- 프로세스 5단계 이상 설명
- 계층 구조 (트리 2+ 레벨)
- 타임라인/히스토리 (4+ 이벤트)
- 수학적 관계 시각화
이 개수 조건은 그릴지 검토할 신호이지 그리라는 지시가 아니다 (DIAGRAM-SCOPE-01). 항목 사이에
관계가 없으면 그것은 목록이다. 주장 한 줄을 먼저 쓰고, 그 주장이 그림에서 보일 때만 그린다.
A report or explainer around the diagram follows jaw-dev/references/reader-documents.md.
The figure itself follows reference/visual-story.md: claim, evidence class, sequencing, handoff.
Rendering, formats and security stay owned here.
For a visual report or explainer document, also read reference/visual-reports.md for page and exhibit composition.
For PDF output, follow the jaw-pdf skill for creation and final-page verification.
3. Specification (명사구 스펙)
사용자가 시각물의 구조를 명사구로 기술:
- "X vs Y 비교" → comparison layout
- "X 구조" / "X 아키텍처" → architecture diagram
- "X 플로우" → flowchart
- "X 타임라인" → timeline
4. When NOT to use
- 단순 질의응답 (팩트 한 줄이면 충분)
- 코드 리뷰/디버깅 (코드가 더 명확)
- 이미 diagram-html 내에서 동작 중인 위젯 재생성
- 사용자가 "간단히 설명해줘"라고 한 경우
Delivery Mechanism (read before producing anything)
All four formats — inline SVG, ```mermaid, ```diagram-file, ```diagram-html — are **rendered inline in the chat response**. The jaw frontend parses your reply text and mounts them automatically. diagram-file and diagram-html go into sandboxed <iframe> elements that the host creates; you do not create the iframe.
Render verification (DIAGRAM-RENDER-VERIFY-01): follow reference/render-verification.md. Reread static inline or ordinary-flow source; render computed, interactive, and exported output at the final state. For a diagram-file, inspect the actual Web UI widget. Never call an unrun check passed.
File-backed widgets (diagram-file)
Use ```diagram-file as the default for all HTML widget output, including charts, maps, simulations, controls, games, and custom JavaScript widgets. Write the full widget HTML first to ~/.cli-jaw/widgets/<chatId>/<widgetId>.html, following the same HTML rules as diagram-html: the host renders it through the validator and sandboxed iframe, with the same CDN allowlist and theme token expectations.
The fence body is id-only: {"id": "<widgetId>"}. A bare widget id string is also accepted. Do not put paths in the fence; the host resolves <current chatId>/<widgetId>.html by convention. The file-backed cap is 2 MB, while inline diagram-html remains capped at 512 KB. File-backed widgets are mutable: editing the saved HTML updates every message that references the same id. Save under a new id when a frozen version is needed.
Determine the current chatId from runtime context when available. If it is not determinable, use inline diagram-html as the fail-safe. diagram-html is also acceptable for very small throwaway widgets that do not warrant a file.
| ❌ Don't |
✅ Do |
Save SVG/Mermaid outputs to .svg / .png files unless explicitly asked |
Paste SVG/Mermaid blocks directly into your reply |
Wrap diagram-html in your own <iframe> / <html> / <body> / <head> |
Start at <div> / <canvas> / <style> — host injects the shell |
Send via /api/channel/send or Telegram/Discord — it is NOT an attachment |
Let the renderer handle it; diagrams are response text |
| Reference an external image URL and call it a diagram |
Output the SVG/widget code itself |
If the user says "save this diagram" or "download it", still output it inline first so they see it rendered; only write a file if they explicitly ask for a file on disk (and even then, the inline version is the canonical delivery).
Output Formats
1. Inline SVG (static diagrams)
Output raw <svg> markup directly in the response. The chat UI renders it inline.
<svg viewBox="0 0 680 {height}" xmlns="http://www.w3.org/2000/svg"
role="img" aria-labelledby="title-id desc-id">
<title id="title-id">Retries are the only path that writes twice</title>
<desc id="desc-id">Request flow from client to queue, with the retry branch rejoining after the write step</desc>
<!-- shapes, text, paths -->
</svg>
Rules:
- viewBox width MUST be 680 (matches container width — do NOT change)
- Height varies by content: last element bottom + 40px padding
- Every SVG MUST have
role="img" + <title> + <desc>. The <title> states the takeaway, not the subject — a screen-reader user gets the claim, not the word "Diagram". The same applies to a canvas or widget aria-label and its fallback text. Never let a distinction live in color alone: carry it in the label, shape, or position too, so it survives grayscale and color vision deficiency. Widget controls stay keyboard reachable (reference/module-interactive.md).
- Check the visual at the tier in
reference/render-verification.md (DIAGRAM-RENDER-01). Computed and exported figures require inspection of the final render; CJK specifics: reference/korean-text.md.
- Use classes from the design system (
.node, .connector, .label, .label-start, etc.) — .label forces text-anchor: middle (centered text only); for left-aligned text use .label-start or just the color class
- Colors: use CSS classes, not inline fill/stroke colors
- Text: inline SVG inherits
font-family from the jaw host; do not set explicit fonts there. Exception: OfficeCLI-rasterized Mermaid with Korean/CJK text must use the init directive above because the raster renderer is not the jaw host.
2. Mermaid (simple flowcharts, ERDs)
Use standard ```mermaid code blocks. The existing renderer handles these.
3. Interactive HTML Widget (fallback form: charts, controls, simulations)
Use ```diagram-file by default. Wrap in a ```diagram-html code block only when the chatId cannot be determined or the widget is a very small throwaway. Rendered inside a sandboxed iframe.
` ` `diagram-html
<div id="chart-wrapper" style="position: relative; width: 100%; height: 300px;">
<canvas id="myChart" role="img"
aria-label="Signups doubled after the March pricing change">
Fallback text stating the same takeaway
</canvas>
</div>
<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"
library failed to load.</p>'">
</script>
<script>
const isDark = window.__jawTheme?.isDark ?? true;
// ... Chart.js code
</script>
` ` `
SVG Design System
Design Forbidden List
These are design quality rules (separate from security restrictions below):
- No gradients, drop shadows, blur, glow, or neon effects
- No emoji — use CSS shapes or SVG paths
- No decorative step numbers or oversized headings
- No icons or illustrations inside flowchart boxes — text only
- No rotated text
- No dark/colored backgrounds on outer containers (transparent only — host provides bg)
- Stroke width: 0.5px for borders and edges (not 1px or 2px)
- Font weights: 400 (regular) and 500 (bold) only. Never 600 or 700.
- Font sizes in SVG: 14px (node labels) and 12px (subtitles/arrow labels) only
- Sentence case always. Never Title Case or ALL CAPS.
<style> in Inline SVG
<style> tags inside inline SVG ARE preserved. Custom CSS classes work:
<svg viewBox="0 0 100 100">
<style>
.highlight { fill: #e94560; }
.dim { fill: #94a3b8; }
</style>
<rect class="highlight" width="50" height="50"/>
</svg>
Security filters applied automatically:
@import rules → stripped
@font-face blocks → stripped
- External
url() → replaced with none (internal url(#ref) preserved)
Best practice: Prefer predefined .c-* classes (see reference/color-palette.md) for theme-aware colors. Use custom <style> when you need colors/patterns not in the design system.
Forbidden in Inline SVG (Security)
These are stripped by DOMPurify — NEVER use in inline <svg>:
<foreignObject> — embeds HTML in SVG (XSS vector)
<animate>, <set>, <animateTransform>, <animateMotion> — animation XSS vectors
- Nested
<svg> — use <g> groups instead
Forbidden Attributes in Inline SVG
xlink:href — use href="#fragment" on <use> only (no external URLs)
- All
on* event handlers (onclick, onerror, etc.) — stripped by DOMPurify
Note: diagram-file and fallback diagram-html content run inside a sandboxed iframe where
<script>, on* handlers, and CDN imports ARE allowed. The restrictions
above apply only to inline SVG rendered in the main document.
Color Ramps (9 semantic colors)
Each ramp has 3 shades: fill (bg), stroke (border), text (label).
Use CSS class names — see reference/color-palette.md:
| Ramp |
Class prefix |
Preferred use |
| cyan |
.c-cyan |
General categories (preferred for neutral info) |
| pink |
.c-pink |
General categories, highlights |
| purple |
.c-purple |
General categories, grouping |
| orange |
.c-orange |
General categories, accent |
| slate |
.c-slate |
Neutral, disabled, structural (start/end nodes) |
| blue |
.c-blue |
Informational (semantic — use only when meaning is "info") |
| green |
.c-green |
Success, positive (semantic) |
| amber |
.c-amber |
Warning, attention (semantic) |
| red |
.c-red |
Error, negative (semantic) |
Color assignment: color encodes meaning, not sequence. Don't cycle through colors like a rainbow. Group by category — all nodes of the same type share one color. Prefer cyan/pink/purple/orange for general categories. Reserve blue/green/amber/red for genuinely semantic concepts.
Layout Patterns
- Flowchart: top-to-bottom, 680×auto
- Comparison: side-by-side columns
- Timeline: horizontal with markers
- Org chart: hierarchical tree
- See
reference/svg-components.md for templates and detailed SVG rules.
Layout (DIAGRAM-LAYOUT-01): keep HTML text in normal Grid/Flex flow. When SVG connectors depend on dynamic boxes, derive endpoints from rendered bounds. Paint connectors before labels; a label crossing one needs a paper-colored stroke halo or a clear position. Size SVG labels using actual text metrics and inspect them at final size.
Style-First, Script-Last
For diagram-file widgets and fallback diagram-html widgets:
- All
<style> and <link> tags first
- HTML structure
<script> tags last
This ensures visual content appears before scripts execute (important during streaming).
Theme Integration
CSS Variable Mapping (cli-jaw)
| Variable |
Use |
--bg |
Page background |
--surface |
Card/surface background |
--text |
Primary text |
--text-dim |
Muted/secondary text |
--border |
Default border |
--accent |
Accent color |
--font-ui |
UI font family |
--font-mono |
Code font family |
--radius-md |
8px border radius |
--radius-lg |
12px border radius |
By format
- Inline SVG: CSS classes adapt to host theme automatically
- iframe widgets: use
window.__jawTheme.isDark (boolean) for JS-side theme detection
- iframe widgets: use
window.__jawTokens['--bg'] etc. for computed host CSS values
- Do NOT use
matchMedia('prefers-color-scheme') — the host controls theme
SVG Mobile Notes
- viewBox 680px 기준은 유지하되, 텍스트는 최소 14px (모바일 축소 후 ~9px)
- CJK 텍스트: 최소 16px (축소 후 ~10px)
- 터치 가능한 SVG 요소: 최소 44×44 hit area
Animation Rules
Inline SVG (DOMPurify sanitized)
- SMIL tags (
<animate>, <set>, <animateMotion>) are stripped — do not use
- Inline SVG is static only — no animation
diagram-file and diagram-html (sandboxed iframe)
All CSS/JS animation is available:
CSS Transition (preferred for hover/state changes):
.element { transition: all 0.3s ease; }
.element:hover { transform: scale(1.05); opacity: 0.8; }
CSS Animation (keyframes):
@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }
.element { animation: fadeIn 0.5s ease-out; }
JS requestAnimationFrame: already documented in module-widget.md (Matter.js, Three.js, p5.js)
Performance
- Animate only
transform and opacity (GPU-accelerated)
- Avoid animating
width, height, top, left (layout thrashing)
- Always call
cancelAnimationFrame on cleanup
Reference Files
For detailed patterns, see:
reference/visual-story.md — read first: claim, evidence classes, one-takeaway sequencing, prose handoff, compositions to avoid, fresh-reader check
reference/render-verification.md — source, rendered, interaction, and page verification tiers
reference/visual-reports.md — report and explainer composition, exhibits, print and assurance guidance
reference/svg-components.md — SVG primitives, viewBox checklist, layout templates
reference/color-palette.md — Full color values (light + dark), assignment rules
reference/module-chart.md — Chart.js + D3 + ECharts 6 integration (bar/line/pie/choropleth + heatmap/sankey/radar/treemap/gauge/funnel/candlestick/chord)
reference/module-widget.md — Physics (Matter.js), math graphs (Math.js), 3D (Three.js), creative coding (p5.js), audio (Tone.js), mini-games
reference/module-interactive.md — Sliders, selects, segmented buttons, toggles, play/pause/reset, debouncing, sendPrompt, keyboard accessibility, control layout pattern
reference/module-map.md — Leaflet interactive maps (OpenStreetMap tiles, markers, popups, dark mode)
reference/module-mockup.md — UI mockup patterns
reference/module-art.md — Decorative SVG patterns
reference/module-domain-cards.md — Domain card templates (weather, finance, sports, product) + real-time data pipeline
reference/structured-renderers.md — native renderer delegation notes
1---2name: jaw-diagram3description: "SVG diagrams, charts, interactive visualizations, and visual reports or explainer documents; PDF output uses jaw-pdf"4metadata:5 source: https://skillmd.com/skills/lidge-jun/jaw-diagram6 version: "1.3.0"7capabilities:8 - "SVG: structural diagrams, comparisons, timelines, mockups, art"9 - "Mermaid: flowchart, sequence, ER, state, timeline, mindmap, gantt, pie, radar, git graph, block, venn-beta"10 - "Native chart shortcut: chart-json for simple single-series bar, line, and pie charts"11 - "Charts (Chart.js): bar, line, pie, scatter, doughnut, polar"12 - "Charts (ECharts): heatmap, sankey, radar, treemap, gauge, funnel, candlestick, chord"13 - "Maps (Leaflet): interactive maps with markers, popups, dark mode"14 - "Interactive: sliders, toggles, sendPrompt, physics (Matter.js), 3D (Three.js), audio (Tone.js), creative (p5.js)"15references:16 - "svg-components.md — SVG primitives, layout templates"17 - "visual-story.md — claim, evidence classes, sequencing, anti-slop, fresh-reader check"18 - "render-verification.md — proportionate source, rendered, interactive, and page checks"19 - "visual-reports.md — visual composition for reports and explainer documents"20 - "color-palette.md — 9-color design system"21 - "module-chart.md — Chart.js + ECharts + D3"22 - "korean-text.md — Korean/CJK text in SVG, HTML, D3, Chart.js, Mermaid, PDF embedding"23 - "structured-renderers.md — native renderer delegation notes"24 - "module-interactive.md — controls, sendPrompt, debouncing"25 - "module-widget.md — physics, 3D, audio, creative coding"26 - "module-map.md — Leaflet maps"27 - "module-mockup.md — UI mockup patterns"28 - "module-art.md — decorative SVG"29 - "module-domain-cards.md — weather, finance, sports, product card templates"30---3132# Diagram Visualization Skill3334## Design Principles3536- **Claim first** (DIAGRAM-CLAIM-01): before choosing a type, name the reader, the decision they face, and one claim they could disagree with. That sentence becomes the caption and the `<title>`. If there is no claim, write the sentence and skip the diagram.37- **Shape carries meaning** (DIAGRAM-SCOPE-01): draw when the point is a relation — contains, precedes, causes, branches, outweighs. Definitions, single facts, and values a reader must compare precisely belong in prose or a table. Recipes: `reference/visual-story.md`.38- **Never invent data** (DIAGRAM-EVIDENCE-01): every quantity is observed, user-supplied, assumed, or illustrative, and the figure or caption says which. A chart of numbers you made up is not a placeholder, it is a false claim that renders beautifully. Put units on the axis, and say so when an axis does not start at zero. Classes and worked form: `reference/visual-story.md`.39- **Flat**: No gradients, shadows, blur, glow, or decorative effects. Clean flat surfaces only.40- **Compact**: Show the essential inline. Explain the rest in response text.41- **Theme-aware**: Every color must work in both light and dark mode. Use CSS classes for SVG, `window.__jawTokens` for canvas/JS.42- **Text in response, visuals in tool**: All explanatory prose goes outside the diagram. Never put paragraphs of explanation inside the SVG or widget HTML.43- **Accessibility** (DIAGRAM-A11Y-01): give the visual a claim-shaped name and description, a text or data alternative for values, meaningful heading order, readable contrast, and labels or shapes that preserve meaning without color. Interactive widgets need visible keyboard focus and reduced-motion behavior. Inspect actual contrast and reading order when the render tier calls for it; ARIA alone does not prove accessibility.4445## Complexity Budget — Hard Limits4647- Box subtitles: **≤5 words**. Detail goes in `sendPrompt()` or prose — not the box.48- Colors: **≤2 ramps** per diagram. More = visual noise.49- Horizontal row: **≤4 boxes** at 680px width. 5+ boxes → shrink or wrap to 2 rows.50- Nodes: **≤6 per diagram**. 7+ → split into overview + detail diagrams. One takeaway per figure (DIAGRAM-SEQ-01): the overview shows the level where the claim is visible, then a **named** detail figure zooms into one region. Shrinking everything into one frame until labels are unreadable is the failure this budget exists to prevent.51- **Always add prose between diagrams** — never output consecutive SVG blocks or widget blocks without text between them. That prose is claim-shaped (DIAGRAM-HANDOFF-01): it states what to conclude, not "the diagram below shows the architecture". Detail that will not fit a five-word subtitle goes here.5253## Diagram Type Selection5455Route on the verb, not the noun. Same subject gets different diagrams. Prefer Mermaid when the diagram type maps cleanly to a native Mermaid syntax — it's cheaper than hand-rolling SVG.5657| User says / intent | Type | Output |58|---|---|---|59| "how does X work" | Illustrative SVG | Spatial metaphor, cross-section, physical layout |60| "architecture of X" (system context) | Structural SVG | Containers, regions, nesting |61| "steps of X" (generic process) | Flowchart SVG or Mermaid `flowchart` | Top-down boxes + arrows |62| "compare A vs B" | Comparison SVG | Side-by-side columns |63| "DB schema / entity relationship" | Mermaid | ` ```mermaid ` `erDiagram` |64| "class diagram / OOP structure" | Mermaid | ` ```mermaid ` `classDiagram` |65| "state machine / lifecycle" | Mermaid | ` ```mermaid ` `stateDiagram-v2` |66| "sequence / call order / API flow" | Mermaid | ` ```mermaid ` `sequenceDiagram` |67| "timeline / roadmap / history" | Mermaid | ` ```mermaid ` `timeline` |68| "mind map / brainstorm / outline" | Mermaid | ` ```mermaid ` `mindmap` |69| "git branching / release history" | Mermaid | ` ```mermaid ` `gitGraph` |70| "2×2 matrix / priority quadrant" | Mermaid | ` ```mermaid ` `quadrantChart` |71| "radar / spider / skill profile" | Mermaid v11.6+ (beta) | ` ```mermaid ` `radar-beta` |72| "gantt / project schedule" | Mermaid | ` ```mermaid ` `gantt` |73| "user journey map" | Mermaid | ` ```mermaid ` `journey` |74| "pie breakdown (simple)" | Mermaid | ` ```mermaid ` `pie` |75| "kanban board" | Mermaid v11.12+ (beta, test before use) | ` ```mermaid ` `kanban` |76| "cloud/infra architecture" | Mermaid (beta) | ` ```mermaid ` `architecture-beta` |77| "hierarchy / proportional size" | Mermaid (beta) | ` ```mermaid ` `treemap-beta` |78| "free-form block layout" | Mermaid | ` ```mermaid ` `block` |79| "packet / network frame" | Mermaid | ` ```mermaid ` `packet` |80| "ishikawa / fishbone / cause-effect" | Mermaid | ` ```mermaid ` `ishikawa` |81| "swimlane / lane-based workflow" | Mermaid | ` ```mermaid ` `swimlane-beta` |82| "requirement / traceability" | Mermaid | ` ```mermaid ` `requirementDiagram` |83| "sankey / flow quantity" | Mermaid | ` ```mermaid ` `sankey` |84| "XY chart / scatter / line" | Mermaid | ` ```mermaid ` `xychart` |85| "venn / overlap / set intersection" | Mermaid (beta) | ` ```mermaid ` `venn-beta` |86| "show sources / search results / citations" | `structured-renderers` skill | Non-diagram native card: load `structured-renderers` for `search-results` schema |87| "visual report / explainer document" | `reference/visual-reports.md` | Follow `jaw-dev/references/reader-documents.md` for structure, then this reference for composition |88| "PDF report / PDF explainer" | `jaw-pdf` skill | Use `reference/visual-reports.md` for composition and `jaw-pdf` for output and final-page checks |89| "write / draft / compose email, message, document" | `structured-renderers` skill | Non-diagram native card: load `structured-renderers` for `compose-block` schema |90| "table / rows / sortable data / filterable data" | `structured-renderers` skill | Non-diagram native card: load `structured-renderers` for `dataframe` schema |91| "patch / diff / unified diff" | `structured-renderers` skill | Non-diagram native display: load `structured-renderers` for `diff` routing |92| "show data / chart" | `chart-json` for simple bar/line/pie; diagram-file for advanced charts | For `chart-json`, load `structured-renderers`; use file-backed Chart.js / D3 / ECharts iframe widgets when custom JS, maps, advanced chart types, or richer interactivity are required |93| "simulate / interactive" | diagram-file | File-backed Matter.js / Canvas / sliders widget |94| "large widget / iterative widget editing" | diagram-file | Default for all HTML widgets: write the full widget HTML to `~/.cli-jaw/widgets/<chatId>/<widgetId>.html`, then emit an id-only file-backed fence |95| "interactive map (with pan/zoom/markers)" | diagram-file | File-backed Leaflet iframe widget — see `reference/module-map.md` |96| "static country/state choropleth" | diagram-file | File-backed D3 + TopoJSON widget — see `reference/module-chart.md` |9798Default to illustrative SVG for "how does X work?" — don't default to flowchart. Default to Mermaid when the type is in the table above — don't hand-roll an SVG when `classDiagram`/`sequenceDiagram`/`stateDiagram` already exists.99100`diagram-file` is the default for all HTML widget types. Use `diagram-html` only as a fallback when the chatId cannot be determined or for very small throwaway widgets that do not warrant a file.101102### Native Web UI renderer boundary103104Before producing a `diagram-file` HTML widget, check whether a native renderer is a better fit:105106- Load `structured-renderers` for `search-results`, `compose-block`, `dataframe`, `chart-json`, and `diff` schemas.107- Use `chart-json` for simple single-series bar/line/pie charts.108- Stay in `diagram` and use `diagram-file` for maps, multi-series charts, advanced chart types, custom JavaScript, external libraries, or richer interaction.109110These renderers are lighter than HTML widgets, survive sanitizer/hydration, and avoid iframe overhead. They are final-answer-only structured fences; during streaming they remain inert code blocks. Keep JSON complete, compact, and schema-versioned. See the active `structured-renderers` skill for canonical schemas and examples.111112### OfficeCLI raster CJK rule113114When OfficeCLI rasterizes Mermaid to PNG and the diagram contains Korean/CJK text,115prepend this directive to the Mermaid source before rendering:116```mermaid117%%{init: {"themeVariables":{"fontFamily":"Noto Sans KR, Apple SD Gothic Neo, NanumGothic, Malgun Gothic, sans-serif"}}}%%118```119After export, open and inspect the PNG. Confirm that Korean glyphs are not tofu120boxes, labels are not clipped, and the fallback font did not change node metrics.121Rendering or a successful OfficeCLI exit code is not visual verification.122123### Mermaid gotchas (read before using beta/experimental types)124125- **Do NOT use C4 diagrams** (`C4Context`, `C4Container`, etc.) — theme tokens are not applied in dark mode, text becomes unreadable ([mermaid #4906](https://github.com/mermaid-js/mermaid/issues/4906)). Substitute routing:126 - **C4 System Context** → Structural SVG (custom) OR Mermaid `flowchart` with subgraphs127 - **C4 Container** → Mermaid `architecture-beta` (cloud/infra layout)128 - **C4 Component** → Mermaid `flowchart` with `subgraph` grouping129 - **C4 Dynamic** → Mermaid `sequenceDiagram`130 - **C4 Deployment** → Mermaid `architecture-beta`131- **`sankey-beta` / `xychart-beta`** — known to break scale-down at narrow chat widths. Prefer `diagram-file` + ECharts sankey for flow diagrams, Chart.js for simple XY.132- **Now stable (no suffix needed):** `block`, `packet`, `kanban`, `sankey`, `xychart`, `ishikawa`.133- **Still beta (suffix required):** `radar-beta`, `architecture-beta`, `treemap-beta`, `venn-beta`, `wardley-beta`, `treeView-beta`, `cynefin-beta`, `swimlane-beta`. Test beta types in the cli-jaw Web UI before finalizing.134- **`sandbox` securityLevel iframe background bug** ([mermaid #5034](https://github.com/mermaid-js/mermaid/issues/5034)) — affects host rendering, not your output. No action needed from the agent.135- **Theme**: all stable Mermaid types pick up the host dark/light theme automatically via cli-jaw's `themeVariables`. Do NOT set explicit colors in `%%{init: ...}%%` unless overriding for semantic reasons.136137**Syntax boundary** (DIAGRAM-SYNTAX-01): use an existing SVG/Mermaid parser or checker when available. Valid syntax cannot prove labels do not overlap. Do not install a new runner solely to check an incidental visual.138139## When to Use140141### 1. Explicit request (명시적 요청)142143한국어: "그려줘", "시각화", "다이어그램", "차트로", "도표로", "비교표", "플로우차트"144영어: "draw", "visualize", "diagram", "chart", "graph", "illustrate", "show me"145146### 2. Proactive generation (에이전트 판단)147148다음 상황에서 텍스트만으로는 전달이 부족할 때 자동 생성:149- 시스템/프로세스 아키텍처 설명 (3+ 컴포넌트)150- 데이터 3항목 이상 비교151- 프로세스 5단계 이상 설명152- 계층 구조 (트리 2+ 레벨)153- 타임라인/히스토리 (4+ 이벤트)154- 수학적 관계 시각화155156이 개수 조건은 그릴지 **검토할** 신호이지 그리라는 지시가 아니다 (DIAGRAM-SCOPE-01). 항목 사이에157관계가 없으면 그것은 목록이다. 주장 한 줄을 먼저 쓰고, 그 주장이 그림에서 보일 때만 그린다.158159A report or explainer around the diagram follows `jaw-dev/references/reader-documents.md`.160The figure itself follows `reference/visual-story.md`: claim, evidence class, sequencing, handoff.161Rendering, formats and security stay owned here.162For a visual report or explainer document, also read `reference/visual-reports.md` for page and exhibit composition.163For PDF output, follow the `jaw-pdf` skill for creation and final-page verification.164165### 3. Specification (명사구 스펙)166167사용자가 시각물의 구조를 명사구로 기술:168- "X vs Y 비교" → comparison layout169- "X 구조" / "X 아키텍처" → architecture diagram170- "X 플로우" → flowchart171- "X 타임라인" → timeline172173### 4. When NOT to use174175- 단순 질의응답 (팩트 한 줄이면 충분)176- 코드 리뷰/디버깅 (코드가 더 명확)177- 이미 diagram-html 내에서 동작 중인 위젯 재생성178- 사용자가 "간단히 설명해줘"라고 한 경우179180## Delivery Mechanism (read before producing anything)181182All four formats — inline SVG, ` ```mermaid `, ` ```diagram-file `, ` ```diagram-html ` — are **rendered inline in the chat response**. The jaw frontend parses your reply text and mounts them automatically. `diagram-file` and `diagram-html` go into sandboxed `<iframe>` elements that the host creates; you do **not** create the iframe.183184**Render verification** (DIAGRAM-RENDER-VERIFY-01): follow `reference/render-verification.md`. Reread static inline or ordinary-flow source; render computed, interactive, and exported output at the final state. For a `diagram-file`, inspect the actual Web UI widget. Never call an unrun check passed.185186### File-backed widgets (`diagram-file`)187188Use ` ```diagram-file ` as the default for all HTML widget output, including charts, maps, simulations, controls, games, and custom JavaScript widgets. Write the full widget HTML first to `~/.cli-jaw/widgets/<chatId>/<widgetId>.html`, following the same HTML rules as `diagram-html`: the host renders it through the validator and sandboxed iframe, with the same CDN allowlist and theme token expectations.189190The fence body is id-only: `{"id": "<widgetId>"}`. A bare widget id string is also accepted. Do not put paths in the fence; the host resolves `<current chatId>/<widgetId>.html` by convention. The file-backed cap is 2 MB, while inline `diagram-html` remains capped at 512 KB. File-backed widgets are mutable: editing the saved HTML updates every message that references the same id. Save under a new id when a frozen version is needed.191192Determine the current chatId from runtime context when available. If it is not determinable, use inline `diagram-html` as the fail-safe. `diagram-html` is also acceptable for very small throwaway widgets that do not warrant a file.193194| ❌ Don't | ✅ Do |195|---|---|196| Save SVG/Mermaid outputs to `.svg` / `.png` files unless explicitly asked | Paste SVG/Mermaid blocks directly into your reply |197| Wrap `diagram-html` in your own `<iframe>` / `<html>` / `<body>` / `<head>` | Start at `<div>` / `<canvas>` / `<style>` — host injects the shell |198| Send via `/api/channel/send` or Telegram/Discord — it is NOT an attachment | Let the renderer handle it; diagrams are response text |199| Reference an external image URL and call it a diagram | Output the SVG/widget code itself |200201If the user says "save this diagram" or "download it", still output it inline first so they see it rendered; only write a file if they explicitly ask for a file on disk (and even then, the inline version is the canonical delivery).202203## Output Formats204205### 1. Inline SVG (static diagrams)206Output raw `<svg>` markup directly in the response. The chat UI renders it inline.207208```209<svg viewBox="0 0 680 {height}" xmlns="http://www.w3.org/2000/svg"210 role="img" aria-labelledby="title-id desc-id">211 <title id="title-id">Retries are the only path that writes twice</title>212 <desc id="desc-id">Request flow from client to queue, with the retry branch rejoining after the write step</desc>213 <!-- shapes, text, paths -->214</svg>215```216217Rules:218- viewBox width MUST be 680 (matches container width — do NOT change)219- Height varies by content: last element bottom + 40px padding220- Every SVG MUST have `role="img"` + `<title>` + `<desc>`. The `<title>` states the takeaway, not the subject — a screen-reader user gets the claim, not the word "Diagram". The same applies to a canvas or widget `aria-label` and its fallback text. Never let a distinction live in color alone: carry it in the label, shape, or position too, so it survives grayscale and color vision deficiency. Widget controls stay keyboard reachable (`reference/module-interactive.md`).221- Check the visual at the tier in `reference/render-verification.md` (DIAGRAM-RENDER-01). Computed and exported figures require inspection of the final render; CJK specifics: `reference/korean-text.md`.222- Use classes from the design system (`.node`, `.connector`, `.label`, `.label-start`, etc.) — `.label` forces `text-anchor: middle` (centered text only); for left-aligned text use `.label-start` or just the color class223- Colors: use CSS classes, not inline fill/stroke colors224- Text: inline SVG inherits `font-family` from the jaw host; do not set explicit fonts there. Exception: OfficeCLI-rasterized Mermaid with Korean/CJK text must use the init directive above because the raster renderer is not the jaw host.225226### 2. Mermaid (simple flowcharts, ERDs)227Use standard ` ```mermaid ` code blocks. The existing renderer handles these.228229### 3. Interactive HTML Widget (fallback form: charts, controls, simulations)230Use ` ```diagram-file ` by default. Wrap in a ` ```diagram-html ` code block only when the chatId cannot be determined or the widget is a very small throwaway. Rendered inside a sandboxed iframe.231232```233` ` `diagram-html234<div id="chart-wrapper" style="position: relative; width: 100%; height: 300px;">235 <canvas id="myChart" role="img"236 aria-label="Signups doubled after the March pricing change">237 Fallback text stating the same takeaway238 </canvas>239</div>240<script src="https://cdn.jsdelivr.net/npm/chart.js@4/dist/chart.umd.min.js"241 onerror="document.body.innerHTML='<p>Chart library failed to load.</p>'">242</script>243<script>244 const isDark = window.__jawTheme?.isDark ?? true;245 // ... Chart.js code246</script>247` ` `248```249250## SVG Design System251252### Design Forbidden List253These are design quality rules (separate from security restrictions below):254- No gradients, drop shadows, blur, glow, or neon effects255- No emoji — use CSS shapes or SVG paths256- No decorative step numbers or oversized headings257- No icons or illustrations inside flowchart boxes — text only258- No rotated text259- No dark/colored backgrounds on outer containers (transparent only — host provides bg)260- Stroke width: **0.5px** for borders and edges (not 1px or 2px)261- Font weights: **400** (regular) and **500** (bold) only. Never 600 or 700.262- Font sizes in SVG: **14px** (node labels) and **12px** (subtitles/arrow labels) only263- **Sentence case** always. Never Title Case or ALL CAPS.264265### `<style>` in Inline SVG266267`<style>` tags inside inline SVG ARE preserved. Custom CSS classes work:268269```xml270<svg viewBox="0 0 100 100">271 <style>272 .highlight { fill: #e94560; }273 .dim { fill: #94a3b8; }274 </style>275 <rect class="highlight" width="50" height="50"/>276</svg>277```278279**Security filters applied automatically:**280- `@import` rules → stripped281- `@font-face` blocks → stripped282- External `url()` → replaced with `none` (internal `url(#ref)` preserved)283284**Best practice:** Prefer predefined `.c-*` classes (see `reference/color-palette.md`) for theme-aware colors. Use custom `<style>` when you need colors/patterns not in the design system.285286### Forbidden in Inline SVG (Security)287These are stripped by DOMPurify — NEVER use in inline `<svg>`:288- `<foreignObject>` — embeds HTML in SVG (XSS vector)289- `<animate>`, `<set>`, `<animateTransform>`, `<animateMotion>` — animation XSS vectors290- Nested `<svg>` — use `<g>` groups instead291292### Forbidden Attributes in Inline SVG293- `xlink:href` — use `href="#fragment"` on `<use>` only (no external URLs)294- All `on*` event handlers (onclick, onerror, etc.) — stripped by DOMPurify295296> **Note**: `diagram-file` and fallback `diagram-html` content run inside a sandboxed iframe where297> `<script>`, `on*` handlers, and CDN imports ARE allowed. The restrictions298> above apply only to inline SVG rendered in the main document.299300### Color Ramps (9 semantic colors)301Each ramp has 3 shades: fill (bg), stroke (border), text (label).302Use CSS class names — see `reference/color-palette.md`:303304| Ramp | Class prefix | Preferred use |305|---|---|---|306| cyan | `.c-cyan` | General categories (preferred for neutral info) |307| pink | `.c-pink` | General categories, highlights |308| purple | `.c-purple` | General categories, grouping |309| orange | `.c-orange` | General categories, accent |310| slate | `.c-slate` | Neutral, disabled, structural (start/end nodes) |311| blue | `.c-blue` | Informational (semantic — use only when meaning is "info") |312| green | `.c-green` | Success, positive (semantic) |313| amber | `.c-amber` | Warning, attention (semantic) |314| red | `.c-red` | Error, negative (semantic) |315316**Color assignment**: color encodes **meaning**, not sequence. Don't cycle through colors like a rainbow. Group by category — all nodes of the same type share one color. Prefer cyan/pink/purple/orange for general categories. Reserve blue/green/amber/red for genuinely semantic concepts.317318### Layout Patterns319- Flowchart: top-to-bottom, 680×auto320- Comparison: side-by-side columns321- Timeline: horizontal with markers322- Org chart: hierarchical tree323- See `reference/svg-components.md` for templates and detailed SVG rules.324325**Layout** (DIAGRAM-LAYOUT-01): keep HTML text in normal Grid/Flex flow. When SVG connectors depend on dynamic boxes, derive endpoints from rendered bounds. Paint connectors before labels; a label crossing one needs a paper-colored stroke halo or a clear position. Size SVG labels using actual text metrics and inspect them at final size.326327### Style-First, Script-Last328For `diagram-file` widgets and fallback `diagram-html` widgets:3291. All `<style>` and `<link>` tags first3302. HTML structure3313. `<script>` tags last332333This ensures visual content appears before scripts execute (important during streaming).334335## Theme Integration336337### CSS Variable Mapping (cli-jaw)338| Variable | Use |339|---|---|340| `--bg` | Page background |341| `--surface` | Card/surface background |342| `--text` | Primary text |343| `--text-dim` | Muted/secondary text |344| `--border` | Default border |345| `--accent` | Accent color |346| `--font-ui` | UI font family |347| `--font-mono` | Code font family |348| `--radius-md` | 8px border radius |349| `--radius-lg` | 12px border radius |350351### By format352- **Inline SVG**: CSS classes adapt to host theme automatically353- **iframe widgets**: use `window.__jawTheme.isDark` (boolean) for JS-side theme detection354- **iframe widgets**: use `window.__jawTokens['--bg']` etc. for computed host CSS values355- Do NOT use `matchMedia('prefers-color-scheme')` — the host controls theme356357## SVG Mobile Notes358359- viewBox 680px 기준은 유지하되, 텍스트는 최소 14px (모바일 축소 후 ~9px)360- CJK 텍스트: 최소 16px (축소 후 ~10px)361- 터치 가능한 SVG 요소: 최소 44×44 hit area362363## Animation Rules364365### Inline SVG (DOMPurify sanitized)366- SMIL tags (`<animate>`, `<set>`, `<animateMotion>`) are stripped — do not use367- Inline SVG is static only — no animation368369### diagram-file and diagram-html (sandboxed iframe)370All CSS/JS animation is available:371372**CSS Transition** (preferred for hover/state changes):373```css374.element { transition: all 0.3s ease; }375.element:hover { transform: scale(1.05); opacity: 0.8; }376```377378**CSS Animation** (keyframes):379```css380@keyframes fadeIn { from { opacity: 0; } to { opacity: 1; } }381.element { animation: fadeIn 0.5s ease-out; }382```383384**JS requestAnimationFrame**: already documented in module-widget.md (Matter.js, Three.js, p5.js)385386### Performance387- Animate only `transform` and `opacity` (GPU-accelerated)388- Avoid animating `width`, `height`, `top`, `left` (layout thrashing)389- Always call `cancelAnimationFrame` on cleanup390391## Reference Files392For detailed patterns, see:393- `reference/visual-story.md` — **read first**: claim, evidence classes, one-takeaway sequencing, prose handoff, compositions to avoid, fresh-reader check394- `reference/render-verification.md` — source, rendered, interaction, and page verification tiers395- `reference/visual-reports.md` — report and explainer composition, exhibits, print and assurance guidance396- `reference/svg-components.md` — SVG primitives, viewBox checklist, layout templates397- `reference/color-palette.md` — Full color values (light + dark), assignment rules398- `reference/module-chart.md` — Chart.js + D3 + ECharts 6 integration (bar/line/pie/choropleth + heatmap/sankey/radar/treemap/gauge/funnel/candlestick/chord)399- `reference/module-widget.md` — Physics (Matter.js), math graphs (Math.js), 3D (Three.js), creative coding (p5.js), audio (Tone.js), mini-games400- `reference/module-interactive.md` — Sliders, selects, segmented buttons, toggles, play/pause/reset, debouncing, sendPrompt, keyboard accessibility, control layout pattern401- `reference/module-map.md` — Leaflet interactive maps (OpenStreetMap tiles, markers, popups, dark mode)402- `reference/module-mockup.md` — UI mockup patterns403- `reference/module-art.md` — Decorative SVG patterns404- `reference/module-domain-cards.md` — Domain card templates (weather, finance, sports, product) + real-time data pipeline405- `reference/structured-renderers.md` — native renderer delegation notes