CommunityImagegithub.com

html-diagrams-decks

Build animated, interactive SVG diagrams, hand-drawn architecture figures and 16:9 slide decks as single self-contained HTML files (light and dark themes, stepped builds with captions, packets flowing along connectors, hover details, a layout check, a 50-icon sprite including grid/energy symbols). Use when asked for an architecture or flow diagram, a layered or platform view, an explainer figure, a stepped walkthrough, or a presentation/deck as an HTML page or claude.ai artifact.

What is html-diagrams-decks?

html-diagrams-decks is a Claude Code agent skill that build animated, interactive SVG diagrams, hand-drawn architecture figures and 16:9 slide decks as single self-contained HTML files (light and dark themes, stepped builds with captions, packets flowing along connectors, hover details, a layout check, a 50-icon sprite including grid/energy symbols). Use when asked for an architecture or flow diagram, a layered or platform view, an explainer figure, a stepped walkthrough, or a presentation/deck as an HTML page or claude.ai artifact.

Works with✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/nilsonfh/trazo/tree/HEAD/skills/html-diagrams-decks

Installed? Explore more Image skills: steipete/songsee, affaan-m/frontend-design, mattpocock/improve-codebase-architecture · View all 6 →

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

HTML diagrams and decks

This skill (an Agent Skill: Claude Code, GitHub Copilot and other agents read it) provides two small figure libraries, a deck engine, three themes and three templates. Each result is one HTML file that works offline once GSAP is cached, follows the viewer's light or dark theme, and can be published as a claude.ai artifact.

PathWhat it is
lib/edgediagram.jsDeclarative SVG graphs: zone, node, text, link (orthogonal by default, arrows, labels, packet flows), fan (one point feeding several nodes), bindFocus, steps, and a layout check at every step
lib/edgesketch.jsHand-drawn figures on a grid: zone, box (fits its text; vertical columns and centred bars), arrow (right angles, two heads), connect (box to box), fan, text; and EdgeSketch.check, a layout check for any SVG, slanted and curved wires included
lib/icons.jswindow.EDGE_ICONS: 50 line icons on a 24-unit grid (grid equipment, compute, trust, operations)
lib/edgedeck.jsEdgeDeck.run: a 1600×900 slide stage with per-slide steps, captions, keyboard, swipe and #n links
themes/*.cssColour and type themes, light and dark, on one token contract: engineering (blue on green-grey, Archivo Narrow and IBM Plex), indigo (indigo on lavender-grey, Space Grotesk and Inter), drafting (teal on warm paper, Barlow Condensed and Source Sans 3)
templates/diagram.htmlA stepped EdgeDiagram figure with captions, Previous/Next and dots
templates/sketch.htmlA hand-drawn EdgeSketch figure: zones left to right, columns, services, two-headed arrows, a legend
templates/deck.htmlA title slide plus a content slide whose diagram builds step by step
scripts/inline.pyInlines the library files and the theme into a page so it publishes as one file; fails on anything it cannot find
scripts/shot.shHeadless screenshots (light or dark, any width, after given clicks, --only one element, --full page) and --check, the layout check of every figure on a page
scripts/todrawio.shExports one figure of a built page to a draw.io file, to be edited there: EdgeDiagram figures with their links attached, hand-drawn SVG figures, HTML figures
scripts/check_theme.pyChecks a theme's WCAG contrast in light and dark, and that its two dark blocks agree
scripts/theme_from_design.pyMakes a theme from a DESIGN.md file (a brand's colours and faces), light and dark, every pair at its contrast
scripts/test.shRuns the tests in tests/; run it after changing lib/, scripts/ or themes/
scripts/vendor.shCopies the library into another project, and --check shows whether that copy is behind
references/api.mdEvery option of both libraries and the deck engine
references/conventions.mdTokens, the meaning of each tone, layout rules, publishing, and the checks to run
examples/ci-canary-deck.htmlA complete two-slide deck on a neutral workflow (CI/CD, then a canary rollout)
examples/isometric/An isometric layered-figure generator (the SGAM cube), with lessons learned
examples/design-md/DESIGN.mdA sample DESIGN.md (Harbor) to make a theme from

Workflow

  1. Decide what the figure must show. Name the mechanism, the parts it depends on, and the sequence in which to reveal it. A sentence that says it faster beats a figure.
  2. Pick the library. A graph of parts joined by meaningful wires, revealed step by step: EdgeDiagram (templates/diagram.html). A grid of boxes, a layered stack or a left-to-right platform view, where the arrangement carries the meaning: EdgeSketch (templates/sketch.html). A presentation: templates/deck.html, with either library on its slides.
  3. Copy the template into the working directory, for example cp <skill>/templates/sketch.html ./my-figure.html. Fix the <script src> and theme paths so they point at <skill>/lib/ and <skill>/themes/, or run inline.py with --lib and --themes at the end.
  4. Lay out on a grid. Pick the viewBox, then the zones, then the boxes (equal sizes, even gaps), then the wires (see Connectors below). Put boxes that talk to each other in the same row or column, so their wire is one straight run. Give links that carry meaning an info. Read references/api.md for the options.
  5. Write the steps (EdgeDiagram). Step 0 is the resting state. Each later step adds one idea and has a short caption. Use flows for the data that moves, and dim or hide for what the step moves past.
  6. Theme. Pages link one theme, <link rel="stylesheet" href="../themes/engineering.css">; swap the name to change it. engineering for dense technical material, indigo for product and software delivery, drafting for proposals and studies read like documents. Keep each tone's meaning (references/conventions.md). For a brand's look, make a theme from its DESIGN.md: python3 <skill>/scripts/theme_from_design.py DESIGN.md -o themes/<name>.css (examples/design-md/DESIGN.md is a sample). By hand, copy a theme, keep every token name, change the values, and run scripts/check_theme.py themes/<name>.css until it passes.
  7. Build, check and look:
    python3 <skill>/scripts/inline.py my-figure.html > build/my-figure.html
    <skill>/scripts/shot.sh --check build/my-figure.html          # every figure; exit 1 on any issue
    <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-light.png light 1280
    <skill>/scripts/shot.sh --only '#my-fig' build/my-figure.html /tmp/f-dark.png dark 1280
    <skill>/scripts/shot.sh build/my-figure.html /tmp/sN.png dark 1280 'for(var i=0;i<5;i++)document.getElementById("next").click()'
    
    Fix everything --check reports. Then open the PNGs and fix what it cannot see, such as off-grid boxes, arrowheads that collide or crowded labels, and look again at width 420. Screenshots freeze packets near the start of their wires, so judge motion in a real browser.
  8. Hand over an editable copy when asked. <skill>/scripts/todrawio.sh build/my-figure.html <svg id or selector> out.drawio "Name" writes a draw.io file of one figure, in the light theme and at its last step. Say what it does not carry: motion, steps, tooltips, and filled shapes other than rects and ellipses (it prints how many it left out).
  9. Publish. The inlined file is the page: share it as a file, commit it, or, in Claude, give it to the Artifact tool (republish the same path or URL to update it).

Connectors

Wires are what a reader follows, so they must look deliberate:

  • Horizontal and vertical only. Never a diagonal and never a curve. EdgeDiagram links are ortho by default: leave route out. 'straight' is only for two ends already in line, and 'curve' only when the user asks for one. In EdgeSketch use s.arrow, s.connect and s.fan, which turn at right angles. In SVG written by hand, draw wires with H and V path commands and round only the corners.
  • One straight run when the boxes face each other. Leave out the position (t) and EdgeDiagram, or s.connect, puts both ends in line when the two boxes share a span. If the check reports a jog of a few pixels, move a box so the ends line up; don't nudge t.
  • One source feeding several boxes is a fan, not a bundle of separate wires. d.fan(id, {from: [src, 'bottom'], to: ['a', 'b', 'c']}), or s.fan(src, 'bottom', [a, b, c]), draws a trunk, a bus at right angles and a branch into each box, with a dot at every junction. Several boxes feeding one is the same fan with the lists swapped ({from: [[...], ...], to: [...]} or {into: true}).
  • Few bends, no crossings. Choose the sides so that each wire turns at most twice. Spread the wires that share a side ('auto'). Route around boxes, never through them.
  • shot.sh --check reports slanted, curved and jogging wires. Fix them like any other issue. Mark a deliberate exception, such as an isometric figure, with data-route="free".

Rules

  • Do not use other libraries. GSAP 3 from cdnjs is optional: without it, every step shows its final state.
  • Every colour comes from a token, so components never contain literal colours.
  • Every node, box or link that has info is keyboard-focusable. The SVG has role="img" and an aria-label that states what the figure claims.
  • A figure wider than a phone scrolls inside its own overflow-x: auto container, never the page.
  • Keep internal names, customer names and addresses out of pages that will be shared.

Related Skills