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

> Discover how DiagramDesign implements accessibility with ARIA labels, reduced-motion, and print styles. Learn to create inclusive, user-friendly designs for all.

- Repository: [Cathryn Lavery/diagram-design](https://github.com/cathrynlavery/diagram-design)
- Tags: deep-dive
- Published: 2026-08-15

---

**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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```html
<!-- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```css
/* 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```html
<!-- 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`](https://github.com/cathrynlavery/diagram-design/blob/main/README.md) and [`animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/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.

```css
/* 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`](https://github.com/cathrynlavery/diagram-design/blob/main/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`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/output-spec.md), with implementation details in [`skills/diagram-design/references/animation.md`](https://github.com/cathrynlavery/diagram-design/blob/main/skills/diagram-design/references/animation.md) and [`docs/adr/0001-static-by-default-single-pinned-controller.md`](https://github.com/cathrynlavery/diagram-design/blob/main/docs/adr/0001-static-by-default-single-pinned-controller.md). Generated CSS enforcing these rules appears in the `styles/*.css` build artifacts.