Diagram SVGs are inconsistent across guides: naming, fonts, responsiveness, accessibility
- Dominant language
- CSS
- Stars
- 9
- Forks
- 12
- Avg merge
- 12h 20m
- Merged PRs (30d)
- 21
Description
## Summary
Audited all 74 SVGs used across the guide series (`git ls-files "*.svg"`). They come from at least four different authoring/export pipelines with no shared conventions, which shows up as inconsistent file naming, fonts, scaling behavior, and accessibility metadata — most visibly within `ML-BOM/en/images/` and `MBOM/en/images/Object-Model/`, which are also internally inconsistent with themselves.
## The four style families
| Family | Count | Signature | Where |
|---|---|---|---|
| Illustrator/vector export | 33 | ``, `viewBox` + `width/height="100%"` | SBOM, CBOM, HBOM, VDR_VEX, shared `images/Object-Model/*` — the closest thing to a "house style" |
| Office/draw.io export | 15 | no XML decl, `xml:space="preserve" overflow="hidden"`, huge fixed pixel canvases, draw.io default palette (`#D5E8D4`/`#82B366` etc.) | all 4 ML-BOM "anatomy" diagrams + all of MBOM's `Object-Model/*.svg` |
| Inkscape | 1 | `sodipodi`/`inkscape:version`, inch-based dimensions | ML-BOM `ml-bom-metadata-component.svg` |
| Lightweight hand-authored | 21 | small files, `viewBox`, `` present | Design-Assurance only |
## Naming
Five different conventions with no dominant standard beyond majority-kebab: kebab-case (44 files), PascalCase-hyphen (21, mostly shared `images/Object-Model/*` + CBOM), snake_case (2, SBOM only), camelCase/mixed (5). Worst case: `MBOM/en/images/Object-Model/` mixes **three** conventions in one folder — `Formula.svg` (PascalCase), `task.svg`/`workflow.svg`/`step.svg` (lowercase), `inputType.svg`/`outputType.svg`/`resourceReferenceChoice.svg` (camelCase). It's also a same-purpose, same-named sibling of the shared top-level `images/Object-Model/` folder but doesn't follow that folder's PascalCase-hyphen convention.
## Fonts
Four unrelated font stacks in use, none embedded (all rely on the renderer having the font installed): Calibri (Office/draw.io family), Consolas (the one Inkscape file), Arial/Helvetica (Illustrator + Design-Assurance), and IBM Plex Sans (an outlier appearing in just 4 MBOM files: `outputType.svg`, `relationship-event-trigger.svg`, `relationship-runtime-topology.svg`, `workflow.svg`). None of these match the actual document typeface — `templates/pdf/print.css` sets the real PDF body/mono fonts to custom `'CDX Body'`/`'CDX Mono'`, backed by Roboto and JetBrains Mono. Every diagram, including the Illustrator ones, uses a font unrelated to the surrounding prose.
## Responsiveness
Illustrator and Design-Assurance files (54 total) use `viewBox` and scale cleanly. The 16 Office/draw.io/Inkscape files (all 4 ML-BOM anatomy diagrams, all 11 MBOM Object-Model diagrams, plus the one Inkscape file) declare only fixed absolute pixel/inch dimensions with no `viewBox` — e.g. `anatomy.svg` at a native 8021×4373 px. These won't scale down responsively anywhere CSS doesn't explicitly cap them.
## Accessibility
64 of 74 SVGs (all of families 1–3) have zero `<title>`/`<desc>`. Only the 21 Design-Assurance files include them.
## Content
A few of the MBOM Object-Model diagrams (`relationship-event-trigger.svg`, `relationship-formula-workflow-component.svg`, `relationship-runtime-topology.svg`, `relationship-workflow-task.svg`) embed JSON-example text using curly/smart quotes (`"timestamp"`) instead of straight quotes — misleading since they're illustrating JSON syntax, where smart quotes aren't valid. `images/quality-dimensions.svg` also has a baked-in `fi` ligature glyph ("Confidence") from its export tool.
## Suggested path forward
This isn't a quick text fix — it needs a maintainer decision on which house style to standardize on before any diagram gets redrawn. Two candidates:
- Converge on the Illustrator/vector-export style already used for SBOM, CBOM, and the shared `images/Object-Model/*` (closest to an existing "official" look), redrawing the ML-BOM and MBOM diagrams to match, adding `viewBox` + `<title>`/`<desc>` throughout, and settling on a single naming convention (kebab-case, since it's already the majority).
- Or define a lighter documented spec (target font, palette, `viewBox` requirement, naming convention, minimum `<title>` requirement) that any future diagram — regardless of source tool — must satisfy, and retrofit incrementally.
Happy to help drive the standardization work once there's a decision on direction — willing to redraw/retrofit the affected files.
Contributor guide
Research direction
Start by reviewing the SVG inventory from `git ls-files "*.svg"` and the font definitions in `templates/pdf/print.css`, focusing on `ML-BOM/en/images/` and `MBOM/en/images/Object-Model/`. Done means a maintainer-selected house style is documented and the affected diagrams conform to its naming, font, responsiveness, and accessibility requirements.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- css
- Domain
- accessibility, design, documentation
- Issue type
- Refactor
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Needs clarification
- Newbie friendliness
- 35/100