# House style

The package ships these defaults; this file explains what you must still decide and what
you must not undo.

## Canvas

White background, natural `standalone` crop. No forced 16:9. No title by default. The top
holds at most two compact formula lines: the primary chain and, only if essential, one
companion definition.

Each stage is one horizontal algebraic row with a shared visual baseline. Use the fewest
stages that preserve the primary path. No unrelated branches, no dashboard panels.

## Type hierarchy

| element | size | macro / style |
|---|---|---|
| formula | `\large` | `\stformula` |
| stage label | `\small\bfseries`, muted | `st stage` |
| operator | `\Large` | `st op` |
| symbol | `\small` | `\stcaption` arg 2 |
| shape | `\scriptsize`, muted | `\stcaption` arg 3 |
| side card | `\scriptsize\bfseries` title, `\scriptsize` body | `\stcallout`, same tier as `st note` |
| bottom prose | `\small` | `\stmeaningbox` |
| optional signature | `\scriptsize`, low contrast | `\stsignature` |

Never shrink below this to make something fit — see `layout.md`.

## Faces

Separate tiles with a small white gutter and 0.5–1 pt corner rounding (`\st@tile` does
this). Thin neutral brackets, `black!55`–`black!70` outer borders. No saturated
tensor-colored outlines, no continuous spreadsheet grid.

The one exception is `\stgroup`, whose outline is drawn at `role!65`: there the outline
*is* the object being named, so the hue is doing semantic work rather than decorating a
face that already has its own fill.

**Encode support before magnitude.** Every known zero stays white/unfilled; every shown
nonzero gets color. A diagonal matrix must read instantly as colored diagonal cells on a
white field. `pattern=diag/band/lower/upper/causal/data` fill exactly the structural
support.

## Color

Palette (already defined): `stTeal #4F8FA5`, `stOrange #EE995B`, `stCoral #C95B5B`,
`stViolet #8A74B5`, `stGray #85898F`. Muted, mid-chroma, paper-like. Do not add saturated
primaries.

- One semantic color per tensor role, held across every stage: `\stsetrole{q}{stTeal}`.
  Macros take a **role**, never a color.
- At most four active hue families per algebraic row, plus neutral gray. Vary lightness or
  reuse the related input/output family before spending a new hue.
- If sign matters: hue for sign, intensity for magnitude.
- Contrast comes from **lightness separation, not saturation**. Levels are `role!30`,
  `role!55`, `role!80` (`\stlevelpct`); white is reserved for zero/absence. Do not render
  a whole tensor in `role!5`–`role!15` pastel.
- Illustrative dense tensors use two or three **non-periodic** levels. `pattern=dense`
  composes coprime moduli to avoid this; a polynomial hash mod 3 makes rows 1, 2, 4, 5
  identical and the eye reads that stripe as structure in the data. No checkerboards, no
  regular stripes, no symmetric motifs unless they encode real structure.

## Bottom box

One full-width, low-contrast box, one reading column, three fixed-label rows:

- **Axes** — what each dimension means.
- **Objects** — semantic kind / domain / range (see `semantics.md`).
- **Mechanism** — at most two essential mappings, contractions, broadcasts or boundaries.

Narrow bold label rail, left-aligned ragged-right `\small` content, 8–10 pt inner padding,
0.4–0.6 em row gaps. Rail labels localize with the package option (`zh` default, `en`).
Keep each row compact: prefer symbol semantics over numeric configuration. When it is too
long, **remove content** — never add cards, columns or smaller type. Pass `{}` to omit a row.

## Side cards

`\stcallout` is the only sanctioned floating text card, and it is deliberately narrow in
scope: one per band, hung off the right edge of a *finished* band, never between two
operands. When the text outgrows the height of its band, it is not an aside — move it into
the **Mechanism** row of `\stmeaningbox` instead of widening or shrinking the card.

## Optional signature

Add a centered line only when the user or house template requests it. Keep it below the
box, outside it, low-contrast gray and on one line. `\stsignature{<subject>}{<fit node>}`
renders only the subject. Do not append an author, handle or brand identity.

## Never

Charts or metric insets not present in the primary formula. Decorative pills, banners,
shadows, repeated separators, explanatory cards other than one `\stcallout` per band.

## Reference image

`assets/kimi-matrix-style-reference.png` — inspect it with an image viewer before drawing
when entry-level matrix blocks are central or Kimi-like styling is requested. Use it only
to calibrate tile spacing, rounding, neutral brackets, restrained hue, lightness separation
and structural whitespace. Do not copy its content, and do not embed it in the output.

## Language

Chinese figures use concise Chinese labels with standard English terms where helpful
(`softmax`, `All-Reduce`, `gather` stay in English). Switch the whole figure at once —
`\usepackage[en]{supertensor}` plus English stage headings and box text — never mix.