# Anti-patterns

Every figure below compiles cleanly. `build.sh` is happy with all of them. They are still
wrong, because the compiler checks TeX syntax and not whether the picture is true.

Render `examples/antipatterns.tex` and look at
`examples/build/antipatterns.png` once before your first figure.

## 1. The transpose that only changed its label

A face captioned `Kᵀ` that is still `T × d_h`. The reader looks for the contracted axis,
finds two faces of the same height, and concludes the contraction runs along the wrong
dimension. **Fix:** swap the arguments — `\ststack{KT}{...}{dh}{T}{3}`. See `geometry.md` §3.

## 2. Shards that do not tile their parent

Two shards drawn with a gap, or stretched to fill a parent whose other shards were elided.
Both assert a width that the tensor does not have. **Fix:** draw the shards in one band
and give every shard after the first `gap=0pt`, which *states* that they are adjacent
instead of arranging for it; draw an ellipsis for anything omitted. See `geometry.md` §5–6.

## 3. An index drawn as a heatmap

Expert ids or token positions rendered with a lightness ramp. The ramp is a magnitude
channel, so it says `expert 3 > expert 0`, which is meaningless. **Fix:** `\stindexface`.
See `semantics.md`.

Same family: a Boolean mask drawn with graded cells (it has one level, not three), and a
score matrix drawn as flat blocks (it has magnitude, and hiding it wastes the figure).

## 4. One pale level everywhere

A whole tensor in `role!10`. At full size it looks tasteful; at thumbnail size — which is
how it will be seen on a slide — it is a blank rectangle. **Fix:** three separated levels,
`role!30 / role!55 / role!80`. Contrast comes from lightness, not saturation.
See `style.md`.

## Not in the gallery, but just as common

- **Periodic texture.** A polynomial hash reduced mod 3 repeats every 3 rows, and the eye
  reads the resulting stripe as real structure. `pattern=dense` avoids it; if you write
  your own filler, check that rows 1, 2, 4, 5 of a tall face are not identical.
- **A label wider than its connector.** The white underlay then covers the target tensor.
  `\stlink` makes this unrepresentable: the label reserves its own width in the band and
  the arrow is drawn to whatever lands beside it. See `layout.md`.
- **A new hue for a regrouped view of the same data.** `X` and the per-expert buffers
  gathered out of `X` are the same object in a different order; a second hue claims they
  are different tensors.
- **Captions hanging at different depths** because the faces in a row have different
  heights. Use `\strow`/`\strowend`, which arms `\stlane` for you.
- **Hand-tuned offsets.** Each one is a magic number valid only for the content that was
  there when you tuned it; the figure that breaks is the *next* one, when a label grows two
  characters and lands on a face. Use the cursor. See `layout.md`.
- **A formula line placed first.** It can only be centered on a figure whose width is not
  known yet, so it ends up visibly off-center. Call `\sttopformula` after the bands.
- **A floating commentary card between two operands.** If it is not a real operation, it
  belongs in the stage subtitle or the bottom box.
- **A meaning box that repeats the shapes.** The shapes are already under every block. The
  box is for what the axes *mean* and what the operation *does*.
- **Solving crowding by shrinking type.** The type hierarchy is a hard floor; move the
  stage to another row instead.