SuperTensor/references/style.md

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.