Cuda Viz

cuda-viz — animated GPU/CUDA diagrams

This skill produces animated explainer diagrams in one specific, deliberate visual style (v2 dark blueprint: dashed double-border boxes, translucent fills, a single-stroke serpentine texture for activity, blue comet packets for data in motion — red = working, green = at rest, blue = in flight, chalk Archivo text). The user's audience recognizes this style across posts — consistency is the whole point. Do not freestyle visuals, colors, or motion outside the system defined here.

Two colorways exist, same anatomy and rules in both: the default dark blueprint and a light "paper" variant (white paper, ink text, pastel role hues) for embedding in light pages. Dark is the default; use light only when the user asks for it or the destination is a light-background page. See "Light colorway" below.

Where this skill lives

This skill directory IS a git repo whose remote is https://github.com/maxxfuu/cudaviz-skill (branch main). Push there and only there — never create a new repo for it, and never commit it into the repo of whatever project a diagram was authored for.

Push the skill, never the product. What belongs in this repo is the reusable craft: library primitives and fixes, design rules, API docs, scripts, and lessons learned while making a diagram. What must NEVER be committed here is the output — diagram HTML, dist/ builds, mp4s, stills. Those are deliverables and stay in the user's working directory. After finishing a diagram, ask what the session actually taught (a bug fixed in lib.js, a rule that was missing from design-rules.md, a new primitive), commit THAT, and leave the artwork behind.

Files in this skill

• assets/lib.js — the component library (global CV). Read it once per session; it's short. v0.2 adds the CUDA-glyph vocabulary: thread (squiggly-arrow), threadBlock (morphable block of threads), dataCell (value cell with texture + plate), ring (full-border sliding selector), chipLegs/edgeConnector (hardware icon trims).
• assets/theme.css — palette variables (dark default + light "paper" colorway) + player controls styling.
• assets/template.html — starting scaffold for every new diagram.
• references/design-rules.md — the visual law: palette, box anatomy, hatching, connectors, typography. Read before drawing anything.
• references/api.md — full API, timeline patterns, composition recipes, sizing norms. Read before writing code.
• examples/kernel-launch.html — canonical finished diagram (kernel launch → block scheduling → SIMT execution). Study it when structuring a new piece; it demonstrates every pattern.
• examples/grid-block-thread.html — canonical multi-act diagram (grid → blocks → threads → one-thread dot-product trace → parallel finale). Demonstrates the v0.2 vocabulary and the multi-act patterns in api.md: transform-group morphing, guarded late tracks, sliding ring highlights, deterministic churn, bounce emphasis. (Its thread/block/cell code predates the v0.2 factories and inlines them — new diagrams should call CV.thread/CV.threadBlock/CV.dataCell/CV.ring instead.)
• scripts/capture.py — keyframe stills / frame sequences / --video out.mp4.
• scripts/capture.js — Node port of capture.py (identical CLI); use where Python lacks Playwright. Node resolves modules from the SCRIPT's directory, not the cwd, so after npm i playwright in a scratch dir run it as NODE_PATH=$PWD/node_modules node …/capture.js diagram.html …. The browsers under ~/.cache/ms-playwright are shared, so only the language binding ever needs installing.
• scripts/build.py — inline the assets into a self-contained deliverable HTML.

Workflow

Layout and animation are separate problems; mixing them wastes iterations. Work in this order:

1. Plan the story. Decide the 3–6 phases the animation narrates (e.g. launch → schedule → execute → complete) and which components each phase touches. A loop is 8–15s. Decide component colors by role: red (compute) = work happening now + accent annotations, green (memory) = data at rest, neutral gray = passive structure, blue (traffic) = data in motion ONLY — when a packet lands, its blue becomes the destination's green state (the phase-change rule).

2. Static composition first. Copy template.html, place every component with the CV primitives at final coordinates, including connectors, hidden routing paths, and elements that will start invisible. Leave ≥40px channels between components — particles route through channels, never over boxes. Then capture one frame and actually look at it:

   python3 scripts/capture.py diagram.html --times 0.5 --out /tmp/check
   

   Fix spacing, alignment, and label centering now, before any motion exists.

3. Animate on the timeline. Add tracks per phase. Every track is a pure function of (p, t) — the patterns (and the three bugs this prevents) are in references/api.md. Reuse the proven verbs: particle flights, hatch-on-active, warp-row pulsing with per-component phase offsets, staged waves, windowed annotations.

4. Verify like a reviewer. Capture stills at each phase boundary and inspect them against design-rules.md. Common regressions: labels not centered in their header band, particles crossing a component, two tracks fighting over one attribute (symptom: element visible at t=0 that shouldn't be), all components pulsing in lockstep.

5. Deliver. Build the self-contained HTML (interactive: play/pause/scrub) and, if the user wants to post it, render the mp4:

   python3 scripts/build.py diagram.html dist/diagram.html
   python3 scripts/capture.py dist/diagram.html --video dist/diagram.mp4
   

Growing the library

When a new diagram needs a primitive that doesn't exist (memory-hierarchy stack, bus with lanes, data-array tiles), compose it from box/miniBox/el following the anatomy rules, and if it's plausibly reusable, add it to lib.js as a factory function in the same style rather than leaving it inline. The library growing is expected and good — one-off visual inventions are not.

Light colorway ("paper")

Opt in with one class — <body class="cv-light"> — nothing else changes: same lib, same anatomy, same roles. The variables swap to:

Each role's main pastel is the component color (borders, serpentine, solid fills, particles); its accent is the pale wash — the light-theme equivalent of the dark theme's ~10% translucent fill — exposed as --cv-compute-accent / --cv-memory-accent / --cv-traffic-accent. (The vars exist in dark mode too, derived via color-mix, so components painted with them work in both themes.) Use the accent vars for large flat washes — plates, level tints, highlight bands — where an exact tone matters; the lib's opacity-based fills still work and land close to these tones over white.

For data-dense light frames (matrices, dense grids, small cells) add cv-vivid — <body class="cv-light cv-vivid"> — which keeps the paper, ink and washes but saturates the three role hues (red #E8503C, green #12A06B, blue #3480E8) so a lit row can actually separate from an unlit one. Pair it with a ~0.09 base fill against a ~0.85 lit fill.

Light-mode checks when verifying stills: pastel strokes carry less contrast than dark-mode strokes, so lean on fills and ink labels to carry structure; code traces automatically switch to the light editor token palette defined in theme.css. One exception to the dark-mode rules: accent-colored TEXT annotations are unreadable in pastel on paper — in light mode set annotation text in --cv-fg ink on a --cv-compute-accent wash plate instead (verified against a captured still; pastel text on white fails).

Hard rules (violating these breaks the brand)

• Colors only via the CSS variables; text is always fg-on-plate, never colored.
• No rounded corners, gradients, shadows, glows, springs, or bounces.
• Only two stroke widths: 2px outer borders, 1px everything else.
• Component inner dash is 8 8; connector dash is 8 6; don't swap them.
• Connectors and particle routes are orthogonal (elbows), never diagonal.
• Packets ride VISIBLE dashed connectors whose arrowheads point where they go — no hidden-only routes; window a visible connector in/out if it would clutter.
• The serpentine (one continuous line riding the inner border) means "active right now", not decoration; it crossfades with the inner dashes automatically.
• State changes happen IN components: cylinder levels rise/drain, cells fill or dim in place — never a symbolic dot drifting out of a component.
• Blue is only ever moving; data at rest is green; work is red (phase-change).
• Timelines are authored in story time; CV.timeline plays them 1.25× slower.
• Render videos at 1920×1080 with capture.py --scale 1.5.
• Everything is centered: a component or group (measured as ONE bounding box) sits centered both horizontally and vertically in its section, with equal breathing room on opposing sides.
• Titles get their own row: every title sits on its own row ABOVE its content, never inline with it; parallel columns share one title baseline.
• Execution cursors (code-line bars, cell rings) ease in, SLIDE between positions with ease.io, and ease out — never hard-switch. The code-line bar is centered on the text's measured ink by codeBlock — never add a fudge offset.
• Side-by-side comparisons are one color per SIDE, not per role: every cell, texture, ring, thread and label of a half wears that half's color (see design-rules.md). Neutral title/divider/connectors and blue packets excepted.
• Code traces use CV.codeBlock and the fixed --cv-code-* palette — in dark: strings #CE9178 salmon, functions #DCDCAA gold, types #4EC9B0 teal, keywords #C586C0 purple, variables #9CDCFE light blue italic, comments #6A9955 green italic. The light colorway swaps these to the light editor set in theme.css automatically — never hardcode token hexes in a diagram.
• Titles between two edges are vertically centered in the gap (contentTop).