CycloneDX / CycloneDX/guides

Diagram SVGs are inconsistent across guides: naming, fonts, responsiveness, accessibility

Open
#94 1 comment 0 reactions 0 assignees View on GitHub
documentation t: MBOM t: ML-BOM
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.