refactor: show diagrams as themed SVG images

An inline SVG put every label of both layouts, its title and its desc
into the page text, next to the prose that already says the steps: a
text dump of the Steam Deck tab read the steps three times, glued.
Each drawing is now one SVG file per layout and theme under
assets/diagrams, shown through <picture> with alt="". The figure says
its words once, in one screen-reader line and its caption.

scripts/generate_site.py

@@ -95,6 +95,7 @@ import siteentries
 import siteinputs
 import retired_files
 import siteagents
+import sitediagrams
 import sitestarlight
 import sitesteps
 from siteexports import generate_exports_page, load_export_reports
@@ -12497,6 +12498,9 @@ def _generate(args: argparse.Namespace) -> None:
         source = Path("docs_assets") / folder
         if source.is_dir():
             shutil.copytree(source, public / "assets" / dest, dirs_exist_ok=True)
+    # The diagrams and the drawn install steps, one SVG per layout and theme.
+    sitediagrams.write_diagram_files(public / sitediagrams.DIAGRAM_DIR,
+                                     {**sitediagrams.figure_files(), **sitesteps.steps_files()})
     demo_dest = public / "assets" / "demo"
     demo_dest.mkdir(parents=True, exist_ok=True)
     for name in DEMO_ASSETS:

scripts/sitediagrams.py

@@ -9,14 +9,20 @@ A page asks for a diagram with an HTML comment on a line of its own::
 
     <!-- image: install-flow -->
 
-``resolve_images`` replaces the comment with the figure. The SVG is inline
-so its text takes the page font and its colours come from the theme
-variables in ``docs_assets/extra.css``: it follows the palette toggle, which
-an ``<img>`` cannot. Presentation attributes give the same drawing a
-readable default when the SVG is opened on its own.
+``resolve_images`` replaces the comment with the figure. Each drawing is
+an SVG file shown through ``<img>``, so the page text holds its words once:
+an inline SVG put every label of both layouts, its title and its desc into
+what a screen reader, a copy, a text dump or a crawler reads, next to the
+prose that already says them. A file reads no stylesheet of the page, so it
+is written once per theme with the colours retrobios.css gives the
+``rb-d-*`` classes (``THEMES``), and the stylesheet shows the one of the
+current theme. Presentation attributes give the same drawing a readable
+default when the SVG is opened on its own.
 
-Every figure carries two layouts, wide and narrow, and the stylesheet shows
-one: a 720-unit drawing scaled to a phone would print 9 px text.
+Every figure carries two layouts, wide and narrow, and ``<picture>`` picks
+one: a 720-unit drawing scaled to a phone would print 9 px text. The
+drawings are ``alt=""``: the figure says what they show once, in a
+screen-reader line, and the caption under them.
 """
 
 from __future__ import annotations
@@ -296,22 +302,112 @@ def grid(boxes: list[Box], per_row: int, total: float) -> tuple[float, float, li
     return total, y - gap_y + 1, out
 
 
-def svg(figure: Figure, layout: str, suffix: str) -> str:
-    """One layout of *figure* as a standalone, accessible SVG element."""
-    width, height, body = (figure.wide if layout == "wide" else figure.narrow)()
-    base = f"rb-fig-{figure.image_id}{suffix}-{layout}"
+def svg_document(width: float, height: float, title: str, desc: str, body: list[str],
+                 base: str) -> str:
+    """A drawing as a standalone, accessible SVG element."""
     return (
         f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {_n(width)} {_n(height)}" '
         f'width="{_n(width)}" height="{_n(height)}" role="img" '
-        f'aria-labelledby="{base}-t {base}-d" font-family="{FONT}" '
-        f'class="rb-diagram rb-diagram-{layout}">'
-        f'<title id="{base}-t">{escape(figure.title)}</title>'
-        f'<desc id="{base}-d">{escape(figure.desc)}</desc>'
+        f'aria-labelledby="{base}-t {base}-d" font-family="{FONT}">'
+        f'<title id="{base}-t">{escape(title)}</title>'
+        f'<desc id="{base}-d">{escape(desc)}</desc>'
         + "".join(body)
         + "</svg>"
     )
 
 
+def svg(figure: Figure, layout: str, suffix: str = "") -> str:
+    """One layout of *figure* as a standalone, accessible SVG element."""
+    width, height, body = (figure.wide if layout == "wide" else figure.narrow)()
+    return svg_document(width, height, figure.title, figure.desc, body,
+                        f"rb-fig-{figure.image_id}{suffix}-{layout}")
+
+
+# The colours retrobios.css gives a diagram, per theme: --rb-diagram-* and
+# --rb-text-secondary, then the text and background Starlight resolves
+# --sl-color-text and --sl-color-bg to (props.css: gray-2 and black, whose
+# values swap with the theme). An SVG shown through <img> reads none of them.
+THEMES: dict[str, dict[str, str]] = {
+    "dark": {"text": "#c1c3c8", "bg": "#17181c", "fill": "#252838", "stroke": "#7c82a3",
+             "accent": "#aebcff", "muted": "#a6adc8"},
+    "light": {"text": "#353841", "bg": "#ffffff", "fill": "#f5f6fa", "stroke": "#8c92ac",
+              "accent": "#3b3f7a", "muted": "#546e7a"},
+}
+# Where the files are served, under the site's public folder.
+DIAGRAM_DIR = "assets/diagrams"
+# retrobios.css shows the narrow layout below this width.
+NARROW_MEDIA = "(max-width: 37.5em)"
+
+
+def themed(document: str, theme: str) -> str:
+    """*document* with the theme's colours, the rules retrobios.css gives
+    the .rb-diagram classes on the page."""
+    c = THEMES[theme]
+    style = (
+        f"<style>svg{{color:{c['text']}}}text{{font-family:{FONT};fill:currentColor}}"
+        f".rb-d-box{{fill:{c['fill']};stroke:{c['stroke']}}}.rb-d-accent{{stroke:{c['accent']}}}"
+        f".rb-d-line{{stroke:{c['stroke']}}}.rb-d-head{{fill:{c['stroke']}}}"
+        f".rb-d-num{{fill:{c['accent']}}}.rb-d-numtext{{fill:{c['bg']}}}"
+        f".rb-d-muted{{fill:{c['muted']}}}</style>"
+    )
+    head = document.index(">") + 1
+    return document[:head] + style + document[head:]
+
+
+def _size(document: str) -> tuple[str, str]:
+    match = re.match(r'<svg [^>]*?width="([\d.]+)" height="([\d.]+)"', document)
+    if not match:
+        raise ValueError("an SVG document without its size")
+    return match.group(1), match.group(2)
+
+
+def diagram_files(stem: str, layouts: dict[str, str]) -> dict[str, str]:
+    """The files of one drawing: *layouts* maps wide and narrow to its SVG,
+    each written once per theme."""
+    return {f"{stem}-{layout}-{theme}.svg": themed(document, theme) + "\n"
+            for layout, document in layouts.items() for theme in THEMES}
+
+
+def pictures(stem: str, layouts: dict[str, str]) -> str:
+    """The drawing on the page: one <picture> per theme, the narrow layout
+    under NARROW_MEDIA. Each image is alt="", the figure says the words."""
+    (wide_w, wide_h), (narrow_w, narrow_h) = _size(layouts["wide"]), _size(layouts["narrow"])
+    out = []
+    for theme in THEMES:
+        url = markup.site_href(f"{DIAGRAM_DIR}/{stem}")
+        out.append(
+            f'<picture class="rb-diagram rb-diagram-{theme}">'
+            f'<source media="{NARROW_MEDIA}" srcset="{url}-narrow-{theme}.svg" '
+            f'width="{narrow_w}" height="{narrow_h}" />'
+            f'<img src="{url}-wide-{theme}.svg" width="{wide_w}" height="{wide_h}" alt="" '
+            'loading="lazy" decoding="async" /></picture>'
+        )
+    return "".join(out)
+
+
+def _layouts(figure: Figure) -> dict[str, str]:
+    return {layout: svg(figure, layout) for layout in ("wide", "narrow")}
+
+
+def figure_files() -> dict[str, str]:
+    """Every figure's files, by name under DIAGRAM_DIR."""
+    return {name: text for image_id in IMAGE_IDS
+            for name, text in diagram_files(image_id, _layouts(figures()[image_id])).items()}
+
+
+def write_diagram_files(directory: Path, files: dict[str, str]) -> None:
+    """*files* under *directory*, and no other SVG: a drawing renamed or
+    dropped leaves no file behind."""
+    directory.mkdir(parents=True, exist_ok=True)
+    for stale in directory.glob("*.svg"):
+        if stale.name not in files:
+            stale.unlink()
+    for name, text in sorted(files.items()):
+        path = directory / name
+        if not path.is_file() or path.read_text(encoding="utf-8") != text:
+            path.write_text(text, encoding="utf-8")
+
+
 # Data
 
 
@@ -667,18 +763,20 @@ _INLINE_ESCAPES = str.maketrans({"_": "&#95;", "*": "&#42;", "`": "&#96;", "[":
 def figure_html(image_id: str, occurrence: int = 1, inline: bool = False) -> str:
     figure = figures()[image_id]
     suffix = "" if occurrence == 1 else f"-{occurrence}"
-    drawings = svg(figure, "wide", suffix) + svg(figure, "narrow", suffix)
+    drawings = pictures(image_id, _layouts(figure))
+    said = f'<span class="sr-only">{escape(figure.desc)}</span>'
     caption = escape(figure.caption)
     anchor = f"rb-fig-{image_id}{suffix}"
     if inline:
         html = (
             f'<span class="rb-figure rb-figure-inline" id="{anchor}" {markup.search_exclude()}>'
-            f'{drawings}<span class="rb-figure-caption">{caption}</span></span>'
+            f'{drawings} {said} <span class="rb-figure-caption">{caption}</span></span>'
         )
         return html.translate(_INLINE_ESCAPES)
     return (
         f'<figure class="rb-figure" id="{anchor}" {markup.search_exclude()}>\n'
         f"{drawings}\n"
+        f"{said}\n"
         f"<figcaption>{caption}</figcaption>\n"
         "</figure>"
     )

scripts/sitesteps.py

@@ -3,12 +3,14 @@
 Two things per tab, both drawn from data:
 
 - The steps that differ by system, opening a terminal and pasting the line,
-  as an inline SVG: one card per step, a pictogram and a short caption,
-  drawn with sitediagrams' primitives so it takes the theme's colours in
-  light and dark. The text steps above it (platforms/_guides.yml,
-  terminals) stay the accessible source. The SVG says the same in its title
-  and desc. The pictograms are generic shapes (a menu, a search field, a
-  window, keys, a mouse, the power symbol), no vendor's interface or logo.
+  as a drawing: one card per step, a pictogram and a short caption, drawn
+  with sitediagrams' primitives and shown as its SVG files, one per layout
+  and theme (sitediagrams.pictures). The text steps above it
+  (platforms/_guides.yml, terminals) are the one text source: the images
+  are alt="", so the page reads the steps once. The files say the same in
+  their title and desc, for one opened on its own. The pictograms are
+  generic shapes (a menu, a search field, a window, keys, a mouse, the
+  power symbol), no vendor's interface or logo.
 - The installer demo recorded for that place (scripts/make_demo.py): the
   full-screen interface on a handheld under "On the device", the terminal
   recording under the others but Windows. No Windows recording is
@@ -23,7 +25,6 @@ from xml.sax.saxutils import escape
 
 import sitemarkup as markup
 from sitediagrams import (
-    FONT,
     MONO_STYLE,
     NARROW,
     STROKE,
@@ -35,6 +36,9 @@ from sitediagrams import (
     _n,
     _rect,
     _text,
+    diagram_files,
+    pictures,
+    svg_document,
     wrap,
 )
 
@@ -92,7 +96,7 @@ def demo_variant(tab: str) -> str:
 
 
 def description(tab: str) -> str:
-    """The steps in words: the SVG's desc."""
+    """The steps in words: the desc of the SVG files."""
     return " ".join(f"{index}. {step.caption}." for index, step in
                     enumerate(STEPS[tab][1], start=1))
 
@@ -234,25 +238,29 @@ def _narrow(steps: tuple[Step, ...]) -> tuple[float, float, list[str]]:
 def _svg(tab: str, layout: str) -> str:
     title, steps = STEPS[tab]
     width, height, body = (_wide if layout == "wide" else _narrow)(steps)
-    base = f"rb-steps-{tab}-{layout}"
-    return (
-        f'<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 {_n(width)} {_n(height)}" '
-        f'width="{_n(width)}" height="{_n(height)}" role="img" '
-        f'aria-labelledby="{base}-t {base}-d" font-family="{FONT}" '
-        f'class="rb-diagram rb-diagram-{layout}">'
-        f'<title id="{base}-t">{escape(title)}</title>'
-        f'<desc id="{base}-d">{escape(description(tab))}</desc>'
-        + "".join(body) + "</svg>"
-    )
+    return svg_document(width, height, title, description(tab), body, f"rb-steps-{tab}-{layout}")
+
+
+def _layouts(tab: str) -> dict[str, str]:
+    return {layout: _svg(tab, layout) for layout in ("wide", "narrow")}
+
+
+def stem(tab: str) -> str:
+    return f"steps-{tab}"
+
+
+def steps_files() -> dict[str, str]:
+    """Every tab's drawing files, by name under sitediagrams.DIAGRAM_DIR."""
+    return {name: text for tab in STEPS for name, text in diagram_files(stem(tab), _layouts(tab)).items()}
 
 
 def steps_figure(tab: str) -> list[str]:
-    """The figure of a tab's steps, both layouts, or nothing for a tab with
-    no drawing."""
+    """The figure of a tab's steps, both layouts in both themes, or nothing
+    for a tab with no drawing. The steps above it say its words."""
     if tab not in STEPS:
         return []
     return [f'<figure class="rb-figure rb-steps" {markup.search_exclude()}>',
-            _svg(tab, "wide") + _svg(tab, "narrow"), "</figure>", ""]
+            pictures(stem(tab), _layouts(tab)), "</figure>", ""]
 
 
 def tab_demo(tab: str) -> list[str]: