Documentation for a11y — Writing Accessibility Documentation for Components

In this tutorial, you will learn about Documentation for a11y. We cover key concepts, practical examples, and best practices to help you master this topic.

Accessibility documentation for design system components must describe ARIA roles, keyboard interactions, focus behavior, contrast validation, known issues, and testing results so developers use components correctly.

What You'll Learn

You will learn how to write accessibility documentation for design system components, what sections to include, and how to keep documentation current as components change.

Why It Matters

Even the most accessible component will be used inaccessibly if developers do not know how to use it. Documentation bridges the gap between accessible design and accessible implementation.

Real-World Use

DodaKit includes an accessibility section in every component's documentation. The section covers ARIA, keyboard, focus, contrast, and testing. Documentation is reviewed as part of the component release gate.

flowchart TD
  A[Documentation] --> B[ARIA]
  A --> C[Keyboard]
  A --> D[Focus]
  A --> E[Contrast]
  A --> F[Testing]
  A --> G[Known Issues]
  B --> H[Roles, properties, states]
  C --> I[Key combinations]
  D --> J[Focus indicator, management]
  E --> K[Color pairs validated]
  F --> L[Automated, manual results]
  G --> M[Open bugs, limitations]

Documentation Sections

ARIA

List all ARIA roles, properties, and states used by the component. Explain why each is used and under what conditions.

Keyboard

Document every keyboard interaction. Include Tab, Enter, Escape, arrow keys, and any custom key bindings.

Focus

Describe the focus indicator style, focus management (trapping, returning), and any focus-related behavior.

Contrast

List all color pairs used by the component and their contrast ratios. Note any variants (hover, active, disabled).

Testing

Document the testing methods and results. Include automated, keyboard, and screen reader testing.

Known Issues

Be transparent about known accessibility issues and link to bug tracking tickets.

// Component documentation generator
class AccessibilityDocGenerator {
  constructor(componentName, version) {
    this.componentName = componentName;
    this.version = version;
    this.sections = {};
  }

  addSection(name, content) {
    this.sections[name] = {
      content: content,
      lastUpdated: new Date().toISOString().split('T')[0]
    };
  }

  generateMarkdown() {
    let md = `# ${this.componentName} — Accessibility\n\n`;
    md += `Version: ${this.version}\n\n`;

    const order = ['ARIA', 'Keyboard', 'Focus', 'Contrast', 'Testing', 'Known Issues'];
    order.forEach(section => {
      if (this.sections[section]) {
        md += `## ${section}\n\n`;
        md += `${this.sections[section].content}\n\n`;
        md += `*Last updated: ${this.sections[section].lastUpdated}*\n\n`;
      }
    });

    return md;
  }

  validate() {
    const required = ['ARIA', 'Keyboard', 'Focus', 'Contrast', 'Testing'];
    const missing = required.filter(s => !this.sections[s]);

    return {
      valid: missing.length === 0,
      missing: missing,
      totalSections: Object.keys(this.sections).length
    };
  }
}

const doc = new AccessibilityDocGenerator('Button', '2.1.0');
doc.addSection('ARIA', 'Native button element. No ARIA required. Use aria-pressed="true/false" for toggle buttons.');
doc.addSection('Keyboard', 'Enter or Space: activates the button. Tab: moves focus to the button.');
doc.addSection('Focus', 'Visible focus indicator using :focus-visible. Outline: 3px solid #005fcc. Offset: 2px.');
doc.addSection('Contrast', 'Primary: #ffffff on #005fcc = 4.8:1. Secondary: #1a1a1a on #f5f5f5 = 15.3:1.');
doc.addSection('Testing', 'axe-core: Pass. Keyboard: Pass. NVDA 2024: Pass.');
doc.addSection('Known Issues', 'Disabled button contrast: 2.8:1 on light backgrounds. Tracked in DS-234.');

console.log(doc.validate());
console.log(doc.generateMarkdown().slice(0, 300) + '...');

Expected output:

{ valid: true, missing: [], totalSections: 6 }
# Button — Accessibility

Version: 2.1.0

## ARIA

Native button element. No ARIA required. Use aria-pressed="true/false" for toggle buttons.

*Last updated: 2026-06-28*

...

Documentation Format

Use a consistent format for all components. Include code examples showing correct and incorrect usage. Show expected screen reader announcements.

<!-- Documentation template for component a11y -->
<section class="ds-doc-a11y" aria-label="Button accessibility documentation">
  <h2>Accessibility</h2>

  <h3>ARIA</h3>
  <p>Native button element. No ARIA required for basic buttons.</p>
  <p>For toggle buttons, add <code>aria-pressed="true"</code> or <code>aria-pressed="false"</code>.</p>

  <h3>Keyboard</h3>
  <table aria-label="Keyboard interactions">
    <thead>
      <tr><th scope="col">Key</th><th scope="col">Action</th></tr>
    </thead>
    <tbody>
      <tr><td>Enter or Space</td><td>Activates the button</td></tr>
      <tr><td>Tab</td><td>Moves focus to the button</td></tr>
    </tbody>
  </table>

  <h3>Focus</h3>
  <p>Focus indicator: <code>:focus-visible</code> with a 3px blue outline (#005fcc) offset by 2px.</p>

  <h3>Screen Reader Announcement</h3>
  <p><strong>Button:</strong> "Scan now, button"</p>
  <p><strong>Toggle button:</strong> "Mute notifications, toggle button, pressed"</p>

  <h3>Correct Usage</h3>
  <pre><code>&lt;button class="ds-button ds-button--primary" type="button"&gt;Scan now&lt;/button&gt;</code></pre>

  <h3>Incorrect Usage</h3>
  <pre><code>&lt;div class="ds-button" onclick="submit()"&gt;Submit&lt;/div&gt;</code></pre>
</section>

Common Mistakes

1. No Accessibility Documentation

Components without accessibility documentation will be used without accessibility considerations.

2. Documentation Without Keyboard Interactions

Developers need to know which keys to use. Include a keyboard interaction table.

3. No Contrast Information

Without documented contrast ratios, developers may change colors and break accessibility.

4. No Testing Results

Documentation should include testing results so developers trust the component's accessibility.

5. Hiding Known Issues

Be transparent about known issues. Hidden issues are discovered later when fixing is more expensive.

6. Outdated Documentation

Documentation that does not match the current component version misleads developers.

7. No Code Examples

Abstract documentation without code examples is not actionable. Show correct and incorrect usage.

Practice Questions

1. What six sections should accessibility documentation include?

ARIA, keyboard, focus, contrast, testing, and known issues.

2. Why should documentation include incorrect usage examples?

Developers may not know what patterns to avoid. Incorrect examples show what not to do.

3. How do you keep documentation current?

Include documentation review as part of the component release Process. Update documentation when the component changes.

4. Why should known issues be documented transparently?

Hidden issues are discovered later at greater cost. Transparency builds trust.

5. Challenge: Write accessibility documentation for a design system tab component. Include all six required sections with code examples.

FAQ

Mini Project

Write accessibility documentation for 3 design system components: button, text input, and accordion. Include ARIA, keyboard, focus, contrast, testing, and known issues. Use a consistent format.

What's Next

Learn about Pattern Library architecture for organizing accessible patterns. Then explore Testing Components for accessibility.