dela
de917a2fbd
- Bracket ink is part of the fit: \st@facebody drops -inkw/-inke extreme coordinates and \stface/\ststack register them with the enclosing group/col/row fit, so a group outline can no longer be crossed by a member's bracket arms - \stlink inside \stgroup or \stcol is now a package error: sub-flow members never terminate a pending connector, so the arrow was dropped silently while the label still rendered - \stgroup requires role= (explicit role=neutral for mixed groups) and must bind at least two members or one \stcol partition; a lone stack or face inside a group is a dirty-build warning - lint: default budget is one \stcallout per figure; the allow-multiple-callouts directive relaxes it to one per band - build.sh: clean-build hint no longer names hue budget (lint owns it) - tests/group-callout.tex reworked: multi-member group with a bracketed member as a regression probe, single callout; new negative fixtures group-link, group-norole, group-single, callout-budget - api.md, checklist.md, style.md, layout.md, SKILL.md updated to match
107 lines
5.0 KiB
Markdown
107 lines
5.0 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 |
|
||
| 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 figure by default, 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 the one budgeted `\stcallout`.
|
||
|
||
## 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.
|