Diagrams Default Active v1.1.0

SVG diagrams, Mermaid charts, and interactive visualizations — rendered inline in the chat UI. From architecture overviews to interactive data dashboards, this skill turns any visual request into a rendered output directly in the conversation.

Design Principles

Every diagram produced by this skill follows four core principles:

• 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 works in both light and dark mode. 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.

Complexity Budget

Hard limits enforced on every diagram to prevent visual noise:

Diagram Type Selection

The skill routes on the verb, not the noun. The same subject can produce different diagram types depending on what the user asks. When a type maps cleanly to native Mermaid syntax, Mermaid is preferred over hand-rolled SVG.

SVG types

Mermaid types

Interactive HTML widget types

Mermaid Gotchas

Important caveats when working with Mermaid diagram types:

Additional notes:

• sankey-beta / xychart-beta break at narrow chat widths. Prefer diagram-html + ECharts sankey or Chart.js for XY charts.
• radar-beta requires the -beta suffix (Mermaid v11.6+). Other beta types: treemap-beta, block-beta, architecture-beta, packet-beta, kanban.
• All stable Mermaid types inherit the host dark/light theme automatically. Do NOT set explicit colors in %%{init: ...}%% unless overriding for semantic reasons.

Output Formats

1. Inline SVG (static diagrams)

Raw <svg> markup output 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">Diagram Title</title>
  <desc id="desc-id">Brief description for screen readers</desc>
  <!-- shapes, text, paths -->
</svg>

Inline SVG rules

• viewBox width MUST be 680 (matches container width — never change this)
• Height varies by content: last element bottom + 40px padding
• Every SVG MUST have role="img" + <title> + <desc>
• Use CSS classes from the design system (.node, .connector, .label, .label-start)
• .label forces text-anchor: middle (centered only); use .label-start for left-aligned text
• Colors: use CSS classes, not inline fill/stroke
• Font-family inherited from host — do NOT set explicit fonts

2. Mermaid (structured diagrams)

Standard ```mermaid code blocks. The existing renderer handles these automatically.

```mermaid
sequenceDiagram
    participant A as Client
    participant B as Server
    A->>B: GET /api/data
    B-->>A: 200 OK (JSON)
```

3. Interactive HTML widget (charts, controls, simulations)

Wrapped in ```diagram-html code blocks. Rendered inside a sandboxed iframe created by the host.

```diagram-html
<div id="chart-wrapper" style="position: relative; width: 100%; height: 300px;">
  <canvas id="myChart" role="img" aria-label="Chart description">
    Fallback text
  </canvas>
</div>
<script src="https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.4.1/chart.umd.js"
  onerror="document.body.innerHTML='<p>Chart library failed to load.</p>'">
</script>
<script>
  const isDark = window.__jawTheme?.isDark ?? true;
  // ... Chart.js code
</script>
```

Delivery Mechanism

All three formats — inline SVG, ```mermaid, ```diagram-html — are rendered inline in the chat response. The jaw frontend parses the reply text and mounts them automatically. diagram-html goes into a sandboxed <iframe> that the host creates; the skill does not create the iframe.

SVG Design System

Design forbidden list

Quality rules enforced on all SVG output (separate from the 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: 14px (node labels) and 12px (subtitles/arrow labels) only
• Sentence case always — never Title Case or ALL CAPS

Security restrictions (inline SVG)

These elements and attributes are stripped by DOMPurify. Never use them in inline <svg>:

Color ramps (9 semantic colors)

Each ramp has 3 shades: fill (background), stroke (border), and text (label). Always use CSS class names, not inline colors.

Layout patterns

Theme Integration

CSS variable mapping

The cli-jaw host exposes these CSS variables for diagram theming:

Theme detection by format

Reference Modules

The diagram skill loads additional reference files for specialized diagram types. These provide detailed patterns, library integration guides, and templates:

Usage Examples

Quick Reference

Decision tree for choosing the right output format: