How Diagram-Design Implements Accessibility with ARIA Labels, Reduced-Motion, and Print Styles

Diagram-Design enforces accessibility through three coordinated layers: semantic ARIA labeling with unique ID namespacing for every SVG, CSS media queries that disable animations under prefers-reduced-motion, and dedicated print stylesheets that strip interactive chrome while preserving accessible metadata.

The cathrynlavery/diagram-design repository generates accessible SVG diagrams by baking WCAG-compliant markup directly into its export pipeline. Every diagram ships with machine-readable structure, respects user motion preferences, and degrades gracefully to static print output without losing semantic context.

Semantic ARIA Labeling for SVG Graphics

Role and Label Associations

In skills/diagram-design/references/output-spec.md (around line 180), the specification mandates that every exported SVG carries role="img" and an aria-labelledby attribute pointing to both a <title> and <desc> element. These elements are injected as the first children of the SVG, ensuring screen readers announce the diagram's purpose before reaching graphical markup.

<!-- Accessible SVG structure as defined in output-spec.md -->
<svg role="img" aria-labelledby="diag-1-title diag-1-desc" …>
  <title id="diag-1-title">System Architecture Overview</title>
  <desc id="diag-1-desc">Shows three layers: UI, Service, and Data, with arrows indicating flow.</desc>
  …
</svg>

Collision-Free ID Namespacing

To support multiple diagrams on a single page without invalidating HTML, the build pipeline prefixes element IDs with diagram-specific tokens. According to output-spec.md, IDs follow the pattern diagram-1-title and diagram-1-desc, preventing namespace collisions when SVGs are inlined.

Decorative Element Handling

Purely decorative SVGs—such as specimen icons—are excluded from the accessibility tree entirely. As documented in README.md (around line 184), these elements receive aria-hidden="true" instead of role and label attributes, keeping assistive technology focused on meaningful content.

Respecting User Motion Preferences

CSS Media Query Implementation

The generated stylesheets wrap all animations in @media (prefers-reduced-motion: reduce) guards. Found in the generated styles/*.css files, these rules force animation: none, transition: none, and animation-duration: 0s when the user opts for reduced motion, immediately rendering static diagrams.

/* From generated styles/*.css */
@media (prefers-reduced-motion: reduce) {
  *[data-motion-root] * {
    animation: none !important;
    transition: none !important;
    animation-duration: 0s !important;
  }
}

Live Region Announcements

When animations are disabled, control visibility changes are communicated through ARIA live regions. The skills/diagram-design/references/animation.md file (lines 87-99) specifies a role="status" region with aria-live="polite" placed inside the motion root but outside [data-motion-controls]. This ensures that hiding motion controls for reduced-motion users does not suppress state announcements.

<!-- Motion controls structure from animation.md -->
<div data-motion-root>
  <div role="status" aria-live="polite" aria-atomic="true"></div>
  <div data-motion-controls>
    <button data-motion-action="play" aria-pressed="false">Play</button>
    <button data-motion-action="pause" aria-pressed="true">Pause</button>
  </div>
</div>

Print-Optimized Accessibility

Cleaning Interactive Elements

The @media print block automatically injected into exported diagrams targets [data-motion-controls] with display: none, removing play buttons and scrubbers from physical copies. This styling convention is referenced in both README.md and animation.md as part of the print-friendly rendering pipeline.

Preserving Semantic Metadata

Unlike interactive chrome, accessible naming attributes survive the print transition. The print stylesheet explicitly retains role="img" and aria-labelledby associations, ensuring that PDF exports carry descriptive metadata for future assistive technology consumption. Decorative elements marked aria-hidden="true" remain hidden in print, maintaining visual clarity.

/* Print stylesheet excerpt */
@media print {
  [data-motion-controls] { display: none; }
  svg[role="img"] { width: 100%; height: auto; }
  /* ARIA naming remains intact */
}

Summary

• Every SVG receives role="img" with aria-labelledby pointing to prefixed <title> and <desc> elements to ensure unique identification in multi-diagram pages.
• Animations respect prefers-reduced-motion: reduce via media queries that zero out durations and disable transitions, while aria-live regions announce state changes.
• Print styles strip interactive controls via [data-motion-controls] { display: none; } but preserve ARIA labeling for accessible PDF output.
• Decorative SVGs are excluded from the accessibility tree using aria-hidden="true".

Frequently Asked Questions

How does diagram-design prevent ID collisions when multiple SVGs are embedded?

The build pipeline generates diagram-specific tokens (e.g., diagram-1-title, diagram-1-desc) that prefix every ID referenced in aria-labelledby attributes. This namespacing strategy, defined in output-spec.md, ensures multiple diagrams can coexist on the same HTML page without breaking accessibility references.

What happens to animations when a user enables reduced-motion preferences?

When the prefers-reduced-motion: reduce media query matches, the CSS sets animation: none and transition: none on all elements within [data-motion-root]. Simultaneously, motion controls are visually hidden but state changes are announced via a persistent aria-live="polite" region, maintaining context without visual movement.

Are printed diagrams still accessible to assistive technology?

Yes. The @media print stylesheet preserves role="img" and aria-labelledby attributes on SVG elements, ensuring exported PDFs retain descriptive metadata. Only interactive elements like [data-motion-controls] are hidden, while semantic content remains available to screen readers parsing the printed document.

Which source files define the accessibility standards for diagram-design outputs?

The formal specification resides in skills/diagram-design/references/output-spec.md, with implementation details in skills/diagram-design/references/animation.md and docs/adr/0001-static-by-default-single-pinned-controller.md. Generated CSS enforcing these rules appears in the styles/*.css build artifacts.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}