dela
7a22bef9e3
Extracted from the tensor-formula-viz skill and rebuilt around the idea that the geometry rules should be enforced by construction rather than restated as prose an agent has to remember. - assets/supertensor.sty: faces, stacks, index faces, shared caption lanes, meaning box, signature. Macros take a declared axis and a declared role, so equal shapes get equal edges, a x a is square, a transpose swaps the face, and contracted axes share an edge length -- without any manual alignment. - scripts/preflight.sh: decide the TikZ/CJK path before drawing. - scripts/build.sh: compile and fail on silent corruption (missing CJK glyphs, overfull boxes, undeclared roles), then export pdf/svg/png/thumb. - scripts/test.sh: build every figure as a regression test for the package. - examples/: three golden figures (TP-FFN, causal MHA, MoE top-k gather) plus an anti-pattern gallery of figures that compile cleanly and still lie. - SKILL.md + references/: lean entry point, details loaded on demand.
95 lines
4.3 KiB
Markdown
95 lines
4.3 KiB
Markdown
# 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 |
|
||
| bottom prose | `\small` | `\stmeaningbox` |
|
||
| 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.
|
||
|
||
**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.
|
||
|
||
## Signature
|
||
|
||
One centered line below the box, outside it, low-contrast gray, `\scriptsize` or smaller:
|
||
`\stsignature{<subject>}{<fit node>}` renders `<subject>@五道口纳什`. The subject must name
|
||
what this figure actually visualizes. Keep it on one line, with a small but visible gap.
|
||
|
||
## Never
|
||
|
||
Charts or metric insets not present in the primary formula. Decorative pills, banners,
|
||
shadows, repeated separators, explanatory cards.
|
||
|
||
## 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.
|