docs-figures

Files (10)

• SKILL.md
• starter_figures.py · assets/
• api.md · references/
• design.md · references/
• github.md · references/
• docs_figures.py · scripts/
• preview.py · scripts/
• render.py · scripts/
• ix-docs.json · styles/
• pencil.json · styles/

SKILL.md (first lines)

# Docs Figures

If this plugin is not initialized or an Agent IX command fails, read [the dev-tools setup guide](https://github.com/agent-ix/dev-tools/blob/main/setup.md) for its prerequisites and local diagnosis.

The engine lives only in this skill. A repository keeps its figure definitions
(`docs/images/figures.py`) and the generated SVGs, never a copy of the engine.
People without the plugin regenerate from a clone of `agent-ix/dev-tools`.

`<skill>` below is this skill's base directory.

## Workflow

1. **Decide each figure's claim.** One figure shows one mechanism: what moves
   along each edge, which branch is taken, what changes between options. If a
   sentence says it faster, write the sentence. See [design.md](references/design.md).
2. **Write the definitions.** If the repository has no `docs/images/figures.py`,
   copy [assets/starter_figures.py](assets/starter_figures.py) there. Each figure
   is a function returning a `Figure`; list them in `FIGURES`. API:
   [api.md](references/api.md). Besides boxes and notes it has `code()` for
   source-code panels with numbered callouts and `columns()` for column charts.
3. **Use real values.** Read numbers from the repository's own data
   (recordings, datasets, command output) in the definitions file. Never type a
   value that the repository can supply.
4. **Render:** `python3 <skill>/scripts/render.py docs/images/figures.py`
   (`python3 -m pip install fonttools` first if needed).
5. **Preview, then look:** `python3 <skill>/scripts/preview.py docs/images --out <tmp>`,
   adding `--at 1.5 4 8` for animation frames. Read every PNG. Fix clipping,
   collisions, crowded labels and low contrast before continuing.
6. **Embed** with the `<picture>` pattern in [github.md](references/github.md).
   Give each animated figure a "Show the whole diagram" toggle with its still.
7. **Gate:** `render.py docs/images/figures.py --check` exits 1 when any
   committed SVG is stale. Run it before committing.

## Rules

- A fit check that raises means the layout is wrong: widen the box or shorten
  the text. Never shrink below the style's sizes.
- Colour means role, never decoration. Keep a role's meaning fixed across a
  repository's figures and add a legend when roles repeat.
- Label arrows with what moves along them (`answers`, `0.82`, `true`).
- Each figure has a full-sentence label: the `Figure` label becomes the SVG
  `aria-label`, and Markdown `alt` text copies it word for word.
- Keep output deterministic: no clocks, randomness or unordered iteration.
  Rendering twice must produce identical bytes.
- Animate with CSS only (`lit`/`appear` windows and tokens). No script or SMIL.
  The resting state must be the complete figure, because it is the still and
  the reduced-motion view.
- Headless Chrome does not advance time inside `<img>`. Check animations with
  `preview.py --at`, which seeks inline copies.

## Styles

- `ix-docs` (default): thin coloured boxes with tinted fills, IBM Plex Sans
  Condensed titles and IBM Plex Mono labels.
- `pencil`: hand-sketched. Wobbly double-traced strokes with a subtle tremor,
  open arrowheads, pencil hatching and Kalam handwriting; graphite and coloured
  pencil on light pages, chalk on dark.

A definitions file selects a style with `STYLE = "name"`; `--style` overrides
it. Figures laid out for one style fit the other, so switching is one line.
To add a style, copy a file in `styles/` and change its fonts, sizes, palette
or renderer; keep every role key. See [api.md](references/api.md#styles).

## References

- [api.md](references/api.md): definitions-file contract, `Figure` API, animation, CLI options.
- [design.md](references/design.md): layout grid, roles, charts and animation choreography.
- [github.md](references/github.md): embedding, alt text, stills, GitHub rendering constraints and checks.

From agent-ix/dev-tools, MIT.

More from agent-ix/dev-tools