Superfig/README.md

superfig

A paper-figure toolkit for non-tensor diagrams: a LaTeX/TikZ macro package, a build pipeline that fails on silent corruption, worked examples, and an agent skill that ties them together.

It is the generic-node sibling of supertensor. Same house style, same role/cursor/warning discipline. The primitives are nodes, edges and groups, not tensor faces. Use supertensor when axis lengths and shape identities are the claim.

This repository is a child of SuperPaper, the family parent that routes paper notes to the right figure toolkit. Clone SuperPaper with --recurse-submodules for the whole family; use this directory alone when you only need node/edge figures.

SKILL.md              the skill entry point (lean; loads references on demand)
references/           grammar, layout, style, api, checklist, antipatterns
assets/superfig.sty   the macro package
scripts/preflight.sh  is the TikZ + CJK path available?
scripts/lint.py       reject source-level invariant escapes
scripts/build.sh      lint, compile, audit the log, export pdf/svg/png/thumb
scripts/test.sh       positive examples plus negative package/lint fixtures
examples/             four golden examples + an anti-pattern gallery

Quick start

./scripts/preflight.sh                          # 0 = full path, 1 = degraded, 2 = no LaTeX
./scripts/build.sh examples/pipeline.tex        # -> examples/build/pipeline.{pdf,svg,png}
./scripts/test.sh

A minimal figure:

\documentclass[border=10pt]{standalone}
\usepackage[cjk]{superfig}

\sfsetrole{input}{sfTeal}
\sfsetrole{model}{sfOrange}

\begin{document}\begin{tikzpicture}
  \sfstage{S}{one band, placed by cursor}
  \sfrow{R1}{14mm}
    \sfnode[role=input]{x}{输入 $x$}{16mm}{12mm}
    \sfconn{e1}{预处理}
    \sfnode[role=model]{f}{模型 $f_\theta$}{18mm}{12mm}
  \sfrowend
  \sflane{R1}
  \sfcaption{x}{$x$}{原始输入}
  \sfcaption{f}{$f_\theta$}{可学习参数}
\end{tikzpicture}\end{document}

See references/api.md for the full macro list.

Examples

file	shows
pipeline.tex	cursor flow; loss as a side object, not a station on the forward path
branch-architecture.tex	residual skip; a group captioned on the shared lane
state-flow.tex	time/state step; one \sfcallout on a finished band
dependency-graph.tex	dual-encoder join, fusion placed from existing anchors
antipatterns.tex	four figures that compile cleanly and still teach something false

Using it as an agent skill

SKILL.md is the entry point; the references/ files are loaded on demand. Point your agent runtime at this directory. The skill assumes scripts/ and assets/ sit beside it.

Why the build script fails on warnings

Missing character drops a CJK glyph silently. Overfull \hbox lets a label escape its lane. Package superfig Warning is an undeclared role, a single-member group, a band overflow, a second callout, or a callout hanging off a node. build.sh greps for all of them and exits non-zero.

A clean build also proves the source avoided raw TikZ drawing, a formula placed before the last row, and more than four active hues. It still cannot prove that the relationships are right; that is what references/checklist.md is for.