Hacktoberfest 2026: le issue che i maintainer hanno segnato per ottobre, aperte e adatte ai principianti. Sfoglia le issue Hacktoberfest

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

Aperta
  • Qualcosa non va?
#94 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
35/100
Tipo di issue
Refactoring
Chiarezza
Da chiarire
Stato di attività
Attiva
Stack tecnologico
css
Ambito
accessibility, design, documentation

Direzione di ricerca

Inizia esaminando l’inventario SVG ottenuto con git ls-files "*.svg" e le definizioni dei font in templates/pdf/print.css, concentrandoti su ML-BOM/en/images/ e MBOM/en/images/Object-Model/. Il lavoro è completato quando è documentato uno stile del progetto scelto da un maintainer e i diagrammi interessati ne rispettano i requisiti di denominazione, font, responsività e accessibilità.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

documentation t: MBOM t: ML-BOM

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 <!DOCTYPE svg PUBLIC "…SVG 1.1…">, 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, <title> 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.

Lingua principale
CSS
Stelle
10
Fork
13
Nessuna PR unita negli ultimi 30g

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di CycloneDX/guides

Tutte le issue di CycloneDX/guides

Issue simili

Altre issue su Accessibility

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.