Residual Connection Viz

A single-glance picture of the residual / skip connection that powers ResNets and Transformer blocks. Input x enters a transformation block (F(x) by default — could be an attention sub-block, an FFN, or a ResNet bottleneck) and also travels along a dashed arc that bows over the top of the block. A + node at the right adds the two signals together before they leave as y. Flip the toggle to drop the skip arc and the sum so the picture collapses to a plain input → block → output chain — exactly what the same network looks like without residuals.

Installation

npx shadcn@latest add https://craftbits.dev/r/residual-connection-viz.json

Usage

import { ResidualConnectionViz } from "@craft-bits/core";
 
<ResidualConnectionViz />

Drive the toggle from outside:

const [enabled, setEnabled] = useState(true);
 
<ResidualConnectionViz
  enabled={enabled}
  onEnabledChange={setEnabled}
/>

Rename the block to teach a specific sub-block:

<ResidualConnectionViz blockLabel="Attention" />
<ResidualConnectionViz blockLabel="FFN" />

Hide the formula caption for a pure shape diagram:

<ResidualConnectionViz showFormula={false} />

Understanding the component

1. Two paths, one sum. The input x enters a transformation block whose output is F(x), and travels in parallel along a curved skip path. A + node at the right adds the two signals together before they leave as y. The formula y = F(x) + x is what the diagram is drawing.
2. enabled is a binary toggle. When false, the skip arc and the sum node fade out, the formula caption collapses to y = F(x), and the picture becomes a plain input → block → output chain. Controlled (enabled + onEnabledChange) and uncontrolled (defaultEnabled) follow the standard Radix pair.
3. Skip path is purely decorative. The arc is a cubic Bézier from just past the input node to just before the sum node, dashed and rendered in the accent colour so it reads as an added path rather than the main flow.
4. SPRINGS.smooth for the toggle. The skip arc, the skip label, and the sum node animate opacity (the sum node also scales) with SPRINGS.smooth from @craft-bits/core/motion. prefers-reduced-motion: reduce collapses every spring to an instant swap.
5. The formula is the caption. Live text below the diagram echoes the state — y = F(x) + x when enabled, y = F(x) when disabled, using the current blockLabel. Hide it with showFormula={false} for a pure shape diagram.

Props

Accessibility

• The root is role="figure" with aria-labelledby pointing at a visually hidden heading and aria-describedby at a visually hidden aria-live="polite" summary.
• The summary announces the current state and block label whenever the toggle flips ("Residual connection enabled. Output is F(x) plus the input.").
• The toggle button carries aria-pressed reflecting enabled and a descriptive aria-label ("Enable residual" / "Disable residual").
• Colour is never the only signal — the formula caption, the live summary, and the toggle label all spell the state in text.
• prefers-reduced-motion: reduce collapses every spring to an instant swap.

Credits

• Extracted from: craftingattention (app/src/lessons/primitives/viz/ResidualConnectionViz.tsx). The source was a multi-mode lesson widget — Explore / Predict mode strip, a six-round question bank about vanishing gradients, a layer-stack bar chart that ran a fake LCG-driven gradient simulation across up to twenty layers, a LabeledSlider and TogglePill control set, narration text, score dots and a DoneCard. The library version drops the simulation, the modes, the questions, the chrome and the curriculum-specific copy, and keeps only the concept the title promises: an input branching into a block and a skip arc that sum back together, with a toggle to drop the residual.