Warm-ink SVG figures
Produces original vector figures (architecture plates, mechanism diagrams, small charts) in one design language: white ground, one warm taupe for all structure, a few saturated signal colors used semantically, tracked-caps labels, and Computer-Modern math. Figures are authored in TikZ and exported to SVG, with a matching PDF and a PNG preview.
Draw original figures only. Never trace or re-create a published figure; take facts from
primary sources and design the picture yourself. For a full typeset document around the
figure, use the warm-ink-technical-pdf skill; it shares the same mlink.sty.
The design language
- One taupe, one ink. Every line, arrow, bracket, box outline and label is
mkTaupe. Words and key numerals aremkInk(a warm near-black). No pure black lines, no outer frames, no shadows, no gradients, no tinted backgrounds. - Color means something. Assign one saturated hue per concept (5 or 6 at most per figure)
and reuse it everywhere that concept appears: the shape, its label, its term in the
equation. Reserve
mkRedfor the single thing the reader must not miss. - Three voices of text. Tracked small caps sans (
\mkL) names things. Italic serif (\mkN) explains. Computer-Modern math (\mkM,\mkD,\mkF) carries quantities. - Light strokes. .3bp hairlines for leaders, .5bp default, .75bp only for emphasis. Small solid triangular arrowheads, butt caps, 2.5 to 3bp corner radius.
- Tensors look like data. A vector is a strip of viridis cells (
\mkstrip) whose length scales with the square root of its dimension, with the dimension as a tiny tag. Matrices are viridis grids. Viridis is never used for categories. - Zoom, do not cram. Show the whole system small, then zoom into one unit, then into one
mechanism. Each level is a dashed rounded group whose label interrupts its top edge
(
\mkgroup), numbered 1, 2, 3. Join levels with dotted wedge leaders when the wedge crosses nothing; otherwise refer to the panel by number. - Two kinds of box. Filled muted blocks with white text (
mk solid) for the one to three major compute units. Thin outlined white boxes (mk box) for small operations. Add and multiply are 8bp circles on the wire (mk plus,mk times). - Hero numerals. The three to seven numbers worth remembering are set large in math
over a tiny caps label (
\mkstat), usually as a strip along the bottom. - Air. Keep 10 to 14bp between lanes, at least 3bp between any text and any line, and snap elements to shared lanes so wires run straight.
Workflow
- Facts first. Look up every number in a primary source and keep a list with sources. Mark anything decorative (random strip contents, sample tokens) as illustrative in a footer line inside the figure.
- Storyboard. Choose the zoom levels and panels, then assign concept colors before drawing anything.
- Lay out in bp. Use
[mk canvas]so one unit is 1bp. A full plate is 600 wide; a column figure is 322 wide. Start with\mkpaper(bounding box plus white ground), decide lane y-values, then place nodes on them. Keep the body infig-<name>.tikzand\inputit from a small wrapper so a document can reuse it. - Compile and look.
xelatex -interaction=nonstopmode -halt-on-error fig.tex, thenpdftoppm -r 130 -png fig.pdf prevand read the PNG. Fix every collision, then render a 220dpi crop of the densest area and check again. Expect at least two rounds. - Export the SVG.
pdftocairo -svg fig.pdf fig.svg. Then prove it:rsvg-convert -w 1400 -b '#202020' fig.svg -o check.pngand readcheck.png. The dark backdrop shows at once if the white ground is missing or anything failed to convert. Also exportpdftoppm -r 220 -png -singlefile fig.pdf figas a preview. - Deliver the SVG first, with the PDF and PNG beside it, and say where the facts came from and what is illustrative.
SVG notes: text is converted to outlines, so the file looks identical everywhere and needs
no fonts, but the words are not editable as text. The file carries a viewBox, so it
scales cleanly. For a transparent SVG, replace \mkpaper with a plain \useasboundingbox.
Setup: save this as mlink.sty next to your .tex
% mlink.sty -- "warm ink" design system: colors, type and TikZ vocabulary.
% Compile with XeLaTeX (or LuaLaTeX). Usage: \usepackage{mlink}
\NeedsTeXFormat{LaTeX2e}
\ProvidesPackage{mlink}[2026/11/13 v1.1 warm-ink design system, core]
\RequirePackage{amsmath}
\RequirePackage{fontspec}
\RequirePackage{unicode-math}
\RequirePackage{xcolor}
\RequirePackage{tikz}
\usetikzlibrary{arrows.meta,calc,positioning,fit,backgrounds,decorations.pathreplacing}
% ---------------------------------------------------------------- 1. COLOR
% Neutrals: a warm near-black for words, one taupe for all structure.
\definecolor{mkInk}{HTML}{231F20} % body text, key numerals
\definecolor{mkTaupe}{HTML}{948979} % every structural line, arrow, label
\definecolor{mkTaupeDk}{HTML}{6F665A} % small text that must stay legible
\definecolor{mkTaupeLt}{HTML}{C3BBB1} % inactive / background marks
\definecolor{mkTaupePl}{HTML}{E6E1DA} % callout fills, table bands
\definecolor{mkPaper}{HTML}{F6F3EE} % panel wash
\definecolor{mkCream}{HTML}{EFE5D1} % highlight wash
\definecolor{mkCode}{HTML}{FEFDF8} % code background
% Signals: saturated, used one-per-concept and repeated in math + caption.
\definecolor{mkRed}{HTML}{ED1C24}
\definecolor{mkOrange}{HTML}{F26522}
\definecolor{mkGold}{HTML}{D9A441}
\definecolor{mkGreen}{HTML}{0EA14B}
\definecolor{mkTeal}{HTML}{27A299}
\definecolor{mkCyan}{HTML}{00AEEF}
\definecolor{mkBlue}{HTML}{1B78B5}
\definecolor{mkIndigo}{HTML}{4A54AB}
\definecolor{mkPurple}{HTML}{7F3F98}
\definecolor{mkMagenta}{HTML}{EC008C}
\definecolor{mkSlate}{HTML}{3B576E}
% Muted solids for filled compute blocks (white text sits on these).
\definecolor{mkSage}{HTML}{7FA77F}
\definecolor{mkSteel}{HTML}{566B84}
% Viridis, 10 stops: the only colormap. Use for tensors, never for categories.
\definecolor{mkV0}{HTML}{440154}\definecolor{mkV1}{HTML}{482878}
\definecolor{mkV2}{HTML}{3E4A89}\definecolor{mkV3}{HTML}{31688E}
\definecolor{mkV4}{HTML}{26828E}\definecolor{mkV5}{HTML}{1F9E89}
\definecolor{mkV6}{HTML}{35B779}\definecolor{mkV7}{HTML}{6DCD59}
\definecolor{mkV8}{HTML}{B4DE2C}\definecolor{mkV9}{HTML}{FDE725}
% ---------------------------------------------------------------- 2. TYPE
% Humanist serif for prose, grotesque sans for labels, Computer-Modern-style
% math on purpose: the contrast makes equations read as "the math layer".
\defaultfontfeatures{Ligatures=TeX}
\IfFontExistsTF{TeX Gyre Pagella}{\setmainfont{TeX Gyre Pagella}}{}
\IfFontExistsTF{Inter}{%
\setsansfont{Inter}[Scale=0.88]%
\newfontfamily\mkSemi{Inter SemiBold}[Scale=0.88]%
\newfontfamily\mkBold{Inter Bold}[Scale=0.88]%
}{%
\setsansfont{TeX Gyre Heros}[Scale=0.9]%
\newfontfamily\mkSemi{TeX Gyre Heros Bold}[Scale=0.9]%
\newfontfamily\mkBold{TeX Gyre Heros Bold}[Scale=0.9]%
}
\IfFontExistsTF{DejaVu Sans Mono}{\setmonofont{DejaVu Sans Mono}[Scale=0.8]}{}
\setmathfont{Latin Modern Math}
% Text atoms. Optional argument is a color.
\newcommand\mkL[2][mkTaupe]{{\mkSemi\fontsize{5.8}{7.2}\selectfont
\addfontfeature{LetterSpace=7}\color{#1}\MakeUppercase{#2}}} % LABEL
\newcommand\mkT[2][mkInk]{{\mkSemi\fontsize{7}{8.6}\selectfont\color{#1}#2}} % Name
\newcommand\mkN[2][mkTaupeDk]{{\rmfamily\itshape\fontsize{6.6}{8.2}\selectfont\color{#1}#2}} % note
\newcommand\mkD[2][mkTaupe]{{\fontsize{5.9}{7}\selectfont\color{#1}$#2$}} % 128x64
\newcommand\mkF[2][mkTaupeDk]{{\fontsize{6.8}{8.2}\selectfont\color{#1}$#2$}} % small formula
\newcommand\mkM[2][mkInk]{{\fontsize{8}{9.6}\selectfont\color{#1}$#2$}} % math
\newcommand\mkBig[2][mkInk]{{\fontsize{15}{16}\selectfont\color{#1}$#2$}} % hero numeral
% ---------------------------------------------------------------- 3. TIKZ
\tikzset{
mk canvas/.style={x=1bp,y=1bp,line cap=butt,line join=miter,
every node/.style={inner sep=0pt,outer sep=0pt}},
% strokes: .3 hairline / .5 default / .75 emphasis / 1.1 hero
mk line/.style={draw=mkTaupe,line width=.5bp},
mk hair/.style={draw=mkTaupe,line width=.3bp},
mk arrow/.style={mk line,-{Triangle[length=3.3bp,width=2.9bp]},shorten >=.5bp},
mk flow/.style={mk arrow,rounded corners=3.5bp},
mk leader/.style={draw=mkTaupe,line width=.3bp,dash pattern=on .7bp off 1.1bp},
mk dash/.style={draw=mkTaupe,line width=.4bp,dash pattern=on 2.1bp off 2.1bp},
mk tone/.style={draw=#1,-{Triangle[length=3.3bp,width=2.9bp,fill=#1]}},
% boxes
mk box/.style={draw=mkTaupe,line width=.5bp,rounded corners=2.5bp,fill=white,
inner xsep=4bp,inner ysep=3bp,align=center},
mk solid/.style={fill=#1,draw=none,rounded corners=3bp,text=white,
inner xsep=5bp,inner ysep=4bp,align=center},
mk tint/.style={fill=#1!9,draw=#1,line width=.5bp,rounded corners=2.5bp,
inner xsep=4bp,inner ysep=3bp,align=center},
mk chip/.style={fill=#1,rounded corners=1.4bp,text=white,inner xsep=2.6bp,
inner ysep=1.9bp,font=\mkSemi\fontsize{6.2}{7}\selectfont},
mk tag/.style={fill=#1,rounded corners=1bp,text=white,inner xsep=2bp,
inner ysep=1.2bp,font=\mkBold\fontsize{4.4}{5}\selectfont},
% operators on a wire
mk op/.style={circle,draw=mkTaupe,line width=.5bp,fill=white,minimum size=8.4bp},
mk plus/.style={mk op,path picture={\draw[mkTaupe,line width=.5bp]
(path picture bounding box.west)--(path picture bounding box.east)
(path picture bounding box.south)--(path picture bounding box.north);}},
mk times/.style={mk op,path picture={\draw[mkTaupe,line width=.5bp]
(path picture bounding box.south west)--(path picture bounding box.north east)
(path picture bounding box.north west)--(path picture bounding box.south east);}},
mk brace/.style={draw=mkTaupe,line width=.4bp,decorate,
decoration={brace,amplitude=2.6bp,raise=1.5bp}},
}
% Dashed group with a label that interrupts the top edge.
% \mkgroup[color]{name}{x1,y1}{x2,y2}{Label}
\newcommand\mkgroup[5][mkTaupe]{%
\draw[mk dash,draw=#1,rounded corners=5bp] (#3) rectangle (#4);
\path (#3) rectangle (#4) node[pos=0] (#2-sw) {} node[pos=1] (#2-ne) {};
\node[anchor=west,fill=white,inner xsep=3bp,inner ysep=1bp]
at ($(#2-sw|-#2-ne)+(9bp,0)$) {\mkL[#1]{#5}};}
% Tensor strip: a row of viridis cells, length proportional to sqrt(dim).
% \mkstrip{name}{x}{y}{dim}{seed} (x = left edge, y = vertical centre)
\newlength\mkcw \setlength\mkcw{2.2bp} % cell width
\newlength\mkch \setlength\mkch{8bp} % cell height
\newcommand\mkstripscale{0.74}
\newcommand\mkstrip[5]{%
\pgfmathtruncatemacro\mk@n{max(2,round(\mkstripscale*4*sqrt(\the\numexpr#4/16\relax)*1bp/\mkcw))}%
\pgfmathsetseed{#5}%
\foreach \mk@i in {1,...,\mk@n}{%
\pgfmathtruncatemacro\mk@c{min(9,max(0,round(4.4+2.1*rand+1.9*rand*rand*rand)))}%
\fill[mkV\mk@c] ($(#2,#3)+({(\mk@i-1)*\mkcw},-.5\mkch)$) rectangle ++(\mkcw+.05bp,\mkch);}%
\node[anchor=west,minimum width=\mk@n\mkcw,minimum height=\mkch] (#1) at (#2,#3) {};}
% Stat: hero numeral over a small label. \mkstat{x}{y}{671\text{B}}{total parameters}
\newcommand\mkstat[4]{%
\node[anchor=base west] at (#1,#2) {\mkBig{#3}};
\node[anchor=base west] at ($(#1,#2)+(0,-9.5bp)$) {\mkL{#4}};}
% White ground + bounding box. Put first in every figure so the SVG is opaque.
% \mkpaper{x1,y1}{x2,y2}
\newcommand\mkpaper[2]{\useasboundingbox (#1) rectangle (#2);\fill[white] (#1) rectangle (#2);}
\endinput
Figure skeleton
\documentclass{article}
\usepackage{mlink}
\usepackage[active,tightpage]{preview}\setlength\PreviewBorder{0bp}
\begin{document}\begin{preview}
\begin{tikzpicture}[mk canvas]
\mkpaper{-8,-8}{308,130} % bounding box + white ground; every coordinate is in bp
\mkgroup{blk}{0,0}{300,120}{Residual block}
\mkstrip{x}{14}{84}{1024}{7}
\node[anchor=south] at ($(x.north)+(0,3)$) {\mkM{x}};
\node[anchor=north] at ($(x.south)+(0,-3)$) {\mkD{1024}};
\node[mk box] (n) at (92,84) {\mkL[mkTaupeDk]{Norm}};
\node[mk solid=mkBlue,minimum width=70bp,minimum height=22bp] (f) at (160,84) {\mkT[white]{Attention}};
\node[mk plus] (p) at (226,84) {};
\draw[mk arrow] (x.east)--(n.west);
\draw[mk arrow] (n.east)--(f.west);
\draw[mk arrow] (f.east)--(p.west);
\fill[mkTaupe] (50,84) circle (1.3);
\draw[mk flow] (50,84)--(50,56)--(226,56)--(p.south);
\node[anchor=north west] at (56,53) {\mkL{skip connection}};
\draw[mk arrow] (p.east)--(252,84);
\mkstrip{y}{255}{84}{1024}{9}
\mkstat{14}{22}{4{\times}}{fewer cache bytes}
\node[anchor=base west] at (120,22) {\mkN{Notes are italic serif; labels are tracked caps.}};
\end{tikzpicture}
\end{preview}\end{document}
Vocabulary:
| Need | Use |
|---|---|
| Bounding box and white ground | \mkpaper{x1,y1}{x2,y2} (first line of the picture) |
| Name of a thing, caps label | \mkL[color]{text} |
| Mixed-case name, usually inside a solid block | \mkT[white]{text} |
| Explanatory note | \mkN{text} |
| Quantity, formula, dimension tag | \mkM[color]{..}, \mkF{..}, \mkD{..} |
| Wire, wire with corners, dotted leader | mk arrow, mk flow, mk leader |
| Small op, major unit, tinted box | mk box, mk solid=<color>, mk tint=<color> |
| Token or category chip, tiny flag | mk chip=<color>, mk tag=<color> |
| Add, multiply | mk plus, mk times |
| Tensor strip | \mkstrip{name}{x}{y}{dim}{seed} (x is the left edge, y the centre) |
| Panel | \mkgroup{name}{x1,y1}{x2,y2}{Label} |
| Brace | \draw[mk brace] (a)--(b); (bulges to the left of the direction of travel) |
| Hero numeral | \mkstat{x}{y}{671\text{B}}{total parameters} |
To highlight a strip, outline it: \draw[mkRed,line width=.6bp] ($(s.south west)+(-1.6,-1.6)$) rectangle ($(s.north east)+(1.6,1.6)$);
A viridis grid is two nested \foreach loops filling 5bp cells with mkV0 to mkV9; seed
with \pgfmathsetseed so the picture is reproducible.
Pitfalls
- TeX arithmetic overflows above 16383.99. Never put a larger literal in a coordinate or
pgfmath expression.
\mkstripis safe up to dimensions of about 250,000. - Use XeLaTeX. LuaLaTeX also works where
luaotfloadis installed. Thestandaloneclass can fail on LuaLaTeX; thepreviewwrapper in the skeleton always works. - Missing fonts fall back automatically (Inter to TeX Gyre Heros). Do not hard-code fonts.
- Without
\mkpaperthe SVG is transparent and unreadable on dark pages. - A leader that crosses text or another panel is worse than no leader.
- If the figure will be shown below about 80% of its drawn size, raise label sizes so nothing lands under 5pt.
Checklist before delivering
- Every number traced to a source; illustrative content labeled in the figure.
- Each concept has exactly one color, and that color appears in its label or equation too.
- No text touches a line; no two labels overlap; wires are straight on their lanes.
- Panels are numbered in reading order.
- SVG rendered on a dark backdrop and inspected; PDF and PNG exported beside it.