author-repo-diagramlisted

# Authoring a Diagram That Ships in a Repo A diagram committed to a repo is read by strangers on a surface you do not control, in a theme you cannot detect, sometimes by someone who cannot see it. Five things decide whether it works, and four of them are settled before the first shape is drawn. ## 1. You cannot make one ink work on both themes. Paint your own surface. Sweep all 256 neutral greys, maximising the *worse* of the two contrast ratios against GitHub's canvases (`#ffffff` and `#0d1117`): ``` best neutral grey: #797979 → 4.35:1 WCAG AA, normal text: 4.5:1 ``` **4.35 is the ceiling for any single ink asked to sit on both.** Coloured inks do worse than the neutral optimum, not better. So "theme-neutral ink" buys AA only at ≥24px labels, which is a poster, not a diagram. > **Every aid paints an opaque surface rect as its first element, and all contrast is > measured against that known canvas rather than against the page.** A working pair: ink `#1f2328` on surface `#f7f7f5` = 14.73:1, secondary `#57606a` = 5.96:1. The aid then reads as a deliberate card on a dark page rather than a light diagram that failed to adapt, and it survives screenshot, paste, and print. The `<picture>` + `prefers-color-scheme` route is the documented alternative and it costs **two files per aid** that must be kept in visual step — a drift bug waiting for the first revision. Take it only if something else forces it. ## 2. Two GitHub facts, both found the expensive way - **GitHub's Markd