Superfig/SKILL.md

name, description

name

description

superfig

Create or refine clean paper-style figures for non-tensor concepts — architecture and block diagrams, pipelines and data flow, state/time flows, dependency graphs, and conceptual mechanism diagrams. Use whenever a paper idea should be explained with clear nodes, edges, grouping, captions, and a short meaning box in a muted slide-ready style, or the user runs $superfig. Not for tensor/matrix/shape semantics (use supertensor), stepwise rewrite figures (use superderive), full paper notes (use superpaper), or plotting numeric data.

superfig

Turn one paper claim or mechanism into one dense, slide-ready figure with three zones:

1. Top — idea. The compact claim or formula. Optional; call it after the drawing.
2. Middle — structure. Semantic nodes, directed edges, grouped composites, and captions.
3. Bottom — meaning. What the idea is, what the objects are, what the mechanism does.

assets/superfig.sty enforces the house style and the common cursor/role discipline. Draw with \sfnode / \sfconn / \sfarrow / \sfgroup; do not hand-roll TikZ rectangles and arrows unless the linter explicitly allows it.

When to use

• Architecture, block diagram, pipeline, data flow, dependency graph, state or time flow.
• A conceptual mechanism that is not a tensor shape: nodes, arrows, containment, lanes.
• A figure that should look like supertensor in palette and text hierarchy.

Do not use for tensor faces, axes, contractions, sharding or broadcasting; route those to supertensor. Do not use for loss curves, benchmark bars, scatter plots, or dashboards.

Workflow

1. Preflight. ./scripts/preflight.sh. Exit 0 = TikZ+CJK path. Exit 1 = degraded (say so). Exit 2 = no LaTeX; read references/fallback.md and name the lost guarantees.
2. Reduce the paper to one primary claim. Drop parallel objectives, optional modules, diagnostics and secondary paths unless the user asks for them.
3. Build a semantics ledger before drawing:
   • nodes — each block is one semantic object: kind, domain/range, owner, lifecycle.
   • edges — each arrow is data flow, control flow, dependency, or causality; never decoration.
   • groups — an outline only when it names a real composite object. See references/grammar.md.
4. Choose the smallest grammar that exposes the mechanism:
   • one object = \sfnode[role=..., level=...]{name}{label}{width}{height}
   • horizontal flow = \sfstage + \sfrow … \sfrowend
   • horizontal connector with label = \sfconn{name}{label}
   • fixed/branching edge = \sfarrow[options]{from}{to} or \sfarrowlabel
   • composite = \sfgroup[role=...]{name}{(member1)(member2)}{} then \sfcaption
   • a whole-band aside = \sfcallout
   • bottom explanation = \sfmeaningbox Full macro list: references/api.md. Worked figures: examples/.
5. Build and audit. ./scripts/build.sh fig.tex runs lint, TeX checks, and exports. Then run references/checklist.md against the PNG full-size and thumbnail. Redraw on any mandatory violation.

Non-negotiables

• Semantics — one node, one object. An edge says one relationship. A group is a real composite, not a decorative border.
• Layout — use the cursor in flow rows; use at={<coord>} only when the topology is genuinely non-linear. Never hand-tune a neighbor against a magic offset.
• Style — muted palette, one hue per role, at most four active hues plus gray, three separated lightness levels, no saturated primaries, no dashboard clutter.
• Build — Missing character, overfull/underfull boxes, and Package superfig Warning are build failures, not cosmetic warnings.

references/antipatterns.md shows the common ways a clean compile still tells the reader something false.

Output

Default to editable TikZ. scripts/build.sh emits PDF, SVG, white-background PNG, transparent PNG and a 360 px thumbnail. Deliver the PNG preview, a one-paragraph mechanism explanation, and the .tex source plus vector artifact.

• Chinese figures: \usepackage[cjk]{superfig} (XeLaTeX + portable Fandol). Keep standard English terms where natural (softmax, logits, gather).
• English figures: \usepackage[en]{superfig} — same geometry, English meaning-box rails.
• Keep math in LaTeX, not raw Unicode.
• Add \sfsignature{<subject>}{<box>} only when the user or house template asks for it.

Iterating

When the user asks for a change, do not restart the figure. Edit the role/ledger or the one macro call that owns the offending object, rebuild, and re-audit. If a fix requires shrinking type, closing the gutter, or covering another object, move the stage to another row instead. Ask before dropping an object or edge the user named.