woodcut

Explanatory figures for technical writing, as data.

Woodcut is a figure grammar plus a set of zero-dependency web components. You describe a diagram as JSON; the components draw it and give every figure the same interaction chrome:

  1. Hover cards — any box or arrow can explain itself.
  2. Expand — fullscreen with zoom from 10% to 600%, fit, cmd-scroll zoom, drag to pan, Esc, and a collapsible detail rail.
  3. Variants — one figure, several renditions, one dropdown.
  4. Replay — scenarios step through the diagram on a numbered dial, with an event log. A play control animates at the reader’s command; reduced motion gets the final frame.
  5. Narrated walkthroughs — a scenario step can carry a title, a sentence or two, and a record of what the system holds now. A narration panel tells the story with the diagram. The reader clicks or presses the arrow keys; the active arrow draws itself.

The taste lives in GRAMMAR.md. The components enforce it, so every figure in every post reads the same way.

See the figure catalog → One worked example of every diagram type, and one narrated walkthrough. Hover a box, expand a figure, replay a scenario.

Status

Early. Five diagram types ship today: block diagram, state machine, flowchart, swimlane, and sequence — all on the one shared frame.

npm install @arjunkhera/woodcut

Or copy packages/woodcut/src/ — the components are plain files with no build step.

Use it in a page

<link rel="stylesheet" href="woodcut/src/tokens.css">
<script type="module" src="woodcut/src/index.js"></script>

<wc-state-machine>
  <script type="application/json">{ ...figure data... }</script>
</wc-state-machine>

The figure catalog shows one worked example of every diagram type. Its source is docs/index.html. To run it locally:

python3 -m http.server 8080

Then open http://localhost:8080/docs/.

Theme it

The components read CSS variables and ship with a neutral theme (src/tokens.css). Override the --wc-* variables to skin every figure at once. themes/quiet-editorial.css is a complete worked example, including a dark mode.

Let an agent draw

The figure skill teaches a coding agent to pick the right diagram type, emit correct data, and self-check against the grammar:

npx skills add github.com/Arjunkhera/woodcut --skill figure

License

MIT.

This site is open source. Improve this page.