Autograd Capstone

The capstone visualisation for autograd: every node carries its forward value and its backward gradient, and every edge can be drawn twice — once in the data-flow direction (forward) and once in the gradient-flow direction (backward). The result is a single picture that says "the backward pass walks the same edges in reverse and accumulates ∂z/∂node along the way."

Where BackpropFlow animates a layer cursor across a feed-forward net and ComputationGraphViz is the typed-node primitive, AutogradCapstone is the snapshot view: forward and backward, side-by-side, on one expression.

Customize

Direction

passboth

Installation

npx shadcn@latest add https://craftbits.dev/r/autograd-capstone.json

Usage

import { AutogradCapstone } from "@craft-bits/core";
 
const nodes = [
  { id: "x",   kind: "input",  label: "x",   value: 1.5,   gradient: 1.139 },
  { id: "y",   kind: "input",  label: "y",   value: 0.5,   gradient: 0.997 },
  { id: "add", kind: "op",     label: "+",   value: 2,     gradient: 0.997 },
  { id: "sin", kind: "op",     label: "sin", value: 0.997, gradient: 2 },
  { id: "mul", kind: "op",     label: "×",   value: 1.995, gradient: 1 },
  { id: "z",   kind: "output", label: "z",   value: 1.995, gradient: 1 },
] as const;
 
const edges = [
  { from: "x",   to: "add" },
  { from: "y",   to: "add" },
  { from: "x",   to: "sin" },
  { from: "add", to: "mul" },
  { from: "sin", to: "mul" },
  { from: "mul", to: "z" },
] as const;
 
<AutogradCapstone nodes={nodes} edges={edges} />

The default direction="both" draws solid accent arrows along the forward edges and dashed warning-color arrows back along the same edges, offset perpendicularly so the two arrowheads never overlap. Every node shows its value below and its gradient above.

Understanding the component

One graph, two passes. nodes carry both value and gradient; the renderer prints value below the node and gradient above it. Edges are drawn once in the forward sense (from → to, solid accent) and once in the backward sense (to → from, dashed warning) so you can see the gradient travelling the same path in reverse.
Typed shapes for typed roles. kind: "input" and kind: "output" render as rounded squares — they hold tensor values. kind: "op" renders as a circle — it produces a value from its inputs. The output square is filled with the accent color so the reader can spot the loss / final value immediately.
Auto-layout via Kahn's algorithm. Each render computes one topological rank per node (longest-path layering). Nodes at the same rank share an x-coordinate; cycles throw with the unresolved ids in the message — autograd graphs are acyclic by contract. Same shape as ComputationGraphViz and DAGRenderer, so the spatial reading is consistent across all three.
Pair offset in "both" mode. When both passes are visible, the forward and backward lines are offset perpendicularly by 5 SVG units so the arrowheads remain readable. When direction="forward" or direction="backward", the offset collapses to zero — a single pass deserves the direct line.
Per-rank stagger on entry. Node entries and edge draws are staggered by source rank using STAGGER from @craft-bits/core/motion. SPRINGS.smooth drives the spring physics. Reduced-motion users snap to the final state — no scale-in, no path-draw, no delays.

Variants

// Forward pass only — solid accent arrows pointing toward the output, values below.
<AutogradCapstone nodes={nodes} edges={edges} direction="forward" />
 
// Backward pass only — dashed warning arrows pointing toward the inputs, gradients above.
<AutogradCapstone nodes={nodes} edges={edges} direction="backward" />
 
// Both — the capstone view. Default.
<AutogradCapstone nodes={nodes} edges={edges} direction="both" />

Props

Prop	Type	Default	Description
`nodes`	`readonly { id; label; value; gradient; kind }[]`	required	Graph nodes. `kind` is `"input"`, `"op"`, or `"output"`. Both `value` and `gradient` are required so a capstone always has something to show.
`edges`	`readonly { from; to }[]`	required	Directed dependency edges in the forward sense. Must be acyclic.
`direction`	`"forward" \| "backward" \| "both"`	`"both"`	Which pass(es) to render.
`className`	`string`	—	Merged onto the outer `<div>` via `cn()`.

Accessibility

The figure is role="figure" with aria-label="Autograd capstone visualization".
The inner <svg> is role="img" with an aria-label summarising the pass and the node sequence ("Forward and backward passes on a computation graph with 6 nodes: x, y, +, sin, ×, z.").
Color is never the only signal — backward edges use a dashed stroke pattern in addition to the warning color so users with color-vision differences can still tell the two passes apart. Forward / backward values sit on opposite sides of each node (below / above) so the orientation is unambiguous.
Motion respects prefers-reduced-motion: node entries, edge draws, and the rank-stagger reveal all collapse to instant when the user has opted out.

Credits

Extracted from: craftingattention (app/src/lessons/primitives/viz/AutogradCapstone.tsx). The original was a training-dashboard widget that consumed the project's VizComponentProps stream — a loss-curve mini-chart plus a similarity-pair heatmap, both tightly bound to the lesson framework's latest/history event arrays. For the library we re-framed the component to live up to its name: a capstone autograd visualisation that puts both the forward and backward passes on the same computation graph. The layout reuses the canonical Kahn's-algorithm topological layering shared by ComputationGraphViz and DAGRenderer, and the visual language (rounded squares for value tensors, circles for ops, accent / warning split for forward vs backward) follows the same conventions as the rest of the ML-viz family.