Skip to content

Use accessible STIX 2.1 SVG icons in documentation - #140

Open
Kevinwochan wants to merge 4 commits into
oasis-open:mainfrom
Kevinwochan:codex/stix-2.1-svg-doc-icons
Open

Use accessible STIX 2.1 SVG icons in documentation#140
Kevinwochan wants to merge 4 commits into
oasis-open:mainfrom
Kevinwochan:codex/stix-2.1-svg-doc-icons

Conversation

@Kevinwochan

@Kevinwochan Kevinwochan commented Jul 29, 2026

Copy link
Copy Markdown

Summary

  • add accessible SVG equivalents for the 26 documentation icon assets while retaining the historical PNG files for compatibility
  • add 24 filled, persistently labeled tiles for documentation contexts where the artwork is the only visible type identifier
  • use labeled tiles in example type cells, relationship selectors, and 148 nested relationship-diagram nodes
  • retain glyph-only icons beside printed object names in introductory tables and walkthrough headings to avoid redundant labels
  • render TLP levels as colored STIX marking tags with original scope pictograms and complete adjacent labels
  • improve alternative text for the relationship overview
  • add a dependency-free audit and run it in CI

The SVG artwork comes from the STIX 2.1 Community SVG Icons project. The labeled tiles are byte-identical to canonical source commit 14fd9b4f24df5adafbf5392e73a4a51f4214abc5; the flat compatibility SVGs preserve the historical 77-by-77 intrinsic dimensions. They are provided under this repository's BSD 3-Clause license.

The labels are deterministic vector paths rather than SVG text, so rendering does not depend on installed fonts. TLP scope pictograms are original, non-normative community artwork; the applicable FIRST color and literal uppercase label remain authoritative. Consumers must also expose the complete marking name through native visible and accessible text. Labeled TLP tiles are intended for display at 96 CSS pixels or larger.

Rendered impact

The updated examples retain the TLP name, official color, and illustrative scope pictogram in screenshots and exported documents:

Documentation examples using labeled STIX icons and colored TLP marking tags

Validation

  • ./audit-icon-references.sh
    • validated 26 SVG/PNG compatibility pairs
    • validated 24 labeled SVG tiles
    • found 25 glyph-only SVG references where native labels remain adjacent
    • found 198 labeled SVG references
    • found 148 nested relationship-diagram references
  • all 24 labeled assets are byte-identical to canonical commit 14fd9b4f24df5adafbf5392e73a4a51f4214abc5
  • the four TLP compatibility wrappers match canonical inner geometry and metadata exactly, differing only by their intentional 77-by-77 intrinsic size
  • all imported SVGs parse successfully with xmllint
  • redesigned TLP wrappers and labeled tiles render successfully at their intended 77 px and 96 px dimensions
  • labeled assets contain path[data-label] and no SVG text or font dependency
  • git diff --check main...HEAD

@CLAassistant

CLAassistant commented Jul 29, 2026

Copy link
Copy Markdown

CLA assistant check
All committers have signed the CLA.

@Kevinwochan
Kevinwochan marked this pull request as ready for review July 30, 2026 14:33
@Kevinwochan

Copy link
Copy Markdown
Author

@ejratl @adulau This PR is ready for review. It replaces ambiguous documentation PNG usage with accessible SVG and labeled variants, including refined TLP markings. Reference audits, XML validation, canonical byte comparisons, rendering checks, and the CLA all pass. When you have time, a maintainer review would be appreciated.

@Kevinwochan

Copy link
Copy Markdown
Author

@chrisr3d Friendly follow-up on this PR. It remains ready for review and cleanly mergeable; the CLA, reference audit, XML validation, canonical comparisons, and rendering checks all pass. I’m happy to adjust the implementation if needed. Could you advise whether this repository is currently accepting contributions?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants