Contribution Guidelines — Accessibility Requirements for Contributions

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

Accessibility contribution guidelines require new components to include accessibility documentation, pass automated tests, demonstrate keyboard operability, meet contrast requirements, and undergo screen reader review before acceptance.

What You'll Learn

You will learn how to write accessibility contribution guidelines for a design system, what requirements contributors must meet, and how to review contributions for accessibility.

Why It Matters

Without clear contribution guidelines, contributors may add inaccessible components to the design system. Guidelines set the standard and make accessibility a requirement not a suggestion.

Real-World Use

DodaKit's contribution guidelines include a mandatory accessibility checklist. Contributors must complete the checklist before their Pull Request is reviewed. Incomplete checklists are returned.

flowchart TD
  A[Contribution] --> B[Proposal]
  B --> C[Design Review]
  C --> D[Development]
  D --> E[Accessibility Checklist]
  E --> F[Automated Tests Pass]
  F --> G[Manual Review]
  G --> H[Release]
  E --> E1[Documentation complete]
  E --> E2[Color contrast validated]
  E --> E3[Keyboard tested]
  E --> E4[Screen reader tested]

Accessibility Checklist

Every contribution must complete an accessibility checklist. The checklist covers: semantic HTML usage, ARIA correctness, keyboard operability, focus management, color contrast, screen reader testing, and documentation.

Review Process

Accessibility review is part of the pull request process. A reviewer with accessibility expertise checks the component against the checklist. Components that fail are returned with specific feedback.

// Contribution accessibility checklist
class ContributionChecklist {
  constructor(contributorName, componentName) {
    this.contributor = contributorName;
    this.component = componentName;
    this.date = new Date().toISOString().split('T')[0];
    this.items = {
      'semanticHTML': { label: 'Uses semantic HTML elements where possible', completed: false },
      'ariaCorrect': { label: 'ARIA attributes are correct and match WAI-ARIA practices', completed: false },
      'keyboardOperable': { label: 'Full keyboard operability verified', completed: false },
      'focusVisible': { label: 'Visible focus indicator on all interactive elements', completed: false },
      'focusManagement': { label: 'Focus management implemented (trap, return)', completed: false },
      'contrastPass': { label: 'All color pairs meet WCAG AA 4.5:1 minimum', completed: false },
      'screenReaderTested': { label: 'Tested with NVDA or VoiceOver', completed: false },
      'documentationComplete': { label: 'Accessibility documentation written (ARIA, keyboard, focus, contrast, testing)', completed: false },
      'codeCommentsClean': { label: 'No inline code comments (accessibility notes go in docs)', completed: false },
      'testAdded': { label: 'Automated accessibility tests added to CI', completed: false }
    };
  }

  completeItem(itemName) {
    if (this.items[itemName]) {
      this.items[itemName].completed = true;
      return { item: itemName, status: 'completed' };
    }
    return { item: itemName, status: 'not found' };
  }

  getProgress() {
    const total = Object.keys(this.items).length;
    const done = Object.values(this.items).filter(i => i.completed).length;
    return {
      total: total,
      completed: done,
      remaining: total - done,
      percentage: Math.round(done / total * 100) + '%',
      ready: done === total,
      missingItems: Object.entries(this.items)
        .filter(([key, val]) => !val.completed)
        .map(([key, val]) => val.label)
    };
  }

  generateReport() {
    const progress = this.getProgress();
    const status = progress.ready ? 'READY FOR REVIEW' : 'INCOMPLETE';

    return `
## Accessibility Checklist — ${this.component}
**Contributor:** ${this.contributor}
**Date:** ${this.date}
**Status:** ${status}

| # | Requirement | Status |
|---|------------|--------|
${Object.entries(this.items).map(([key, item], i) =>
  `| ${i + 1} | ${item.label} | ${item.completed ? 'PASS' : 'FAIL'} |`
).join('\n')}

**Progress:** ${progress.completed}/${progress.total} (${progress.percentage})

${progress.ready ? 'All checks passed. Proceed to accessibility review.' : `Missing: ${progress.missingItems.join(', ')}`}
`;
  }
}

const checklist = new ContributionChecklist('A. Developer', 'TabPanel');
checklist.completeItem('semanticHTML');
checklist.completeItem('ariaCorrect');
checklist.completeItem('keyboardOperable');
checklist.completeItem('focusVisible');
console.log(checklist.getProgress());
console.log(checklist.generateReport());

Expected output:

{ total: 10, completed: 4, remaining: 6, percentage: '40%', ready: false, missingItems: ['Focus management implemented (trap, return)', 'All color pairs meet WCAG AA 4.5:1 minimum', 'Tested with NVDA or VoiceOver', 'Accessibility documentation written (ARIA, keyboard, focus, contrast, testing)', 'No inline code comments (accessibility notes go in docs)', 'Automated accessibility tests added to CI'] }

## Accessibility Checklist — TabPanel
**Contributor:** A. Developer
**Date:** 2026-06-28
**Status:** INCOMPLETE

| # | Requirement | Status |
|---|------------|--------|
| 1 | Uses semantic HTML elements where possible | PASS |
| 2 | ARIA attributes are correct and match WAI-ARIA practices | PASS |
| 3 | Full keyboard operability verified | PASS |
| 4 | Visible focus indicator on all interactive elements | PASS |
| 5 | Focus management implemented (trap, return) | FAIL |
| 6 | All color pairs meet WCAG AA 4.5:1 minimum | FAIL |
| 7 | Tested with NVDA or VoiceOver | FAIL |
| 8 | Accessibility documentation written | FAIL |
| 9 | No inline code comments | FAIL |
| 10 | Automated accessibility tests added to CI | FAIL |

**Progress:** 4/10 (40%)

Missing: Focus management implemented (trap, return), All color pairs meet WCAG AA 4.5:1 minimum, Tested with NVDA or VoiceOver, Accessibility documentation written, No inline code comments, Automated accessibility tests added to CI

Documentation Requirements

Contributors must provide accessibility documentation for their component. The documentation must cover ARIA, keyboard, focus, contrast, testing results, and known issues.

Enforcement

Pull requests that do not meet accessibility requirements should not be merged. The accessibility checklist is a hard gate in the contribution process.

<!-- Contribution guidelines a11y section -->
<section aria-labelledby="contribution-a11y">
  <h2 id="contribution-a11y">Accessibility Requirements for Contributions</h2>

  <p>All components contributed to this design system must meet these accessibility requirements:</p>

  <h3>Required</h3>
  <ul>
    <li>Use semantic HTML elements. Only add ARIA when no native element exists.</li>
    <li>All interactive elements must be keyboard operable.</li>
    <li>Visible focus indicator on all interactive elements using <code>:focus-visible</code>.</li>
    <li>Color pairs must meet WCAG AA (4.5:1 for text, 3:1 for large text).</li>
    <li>Test with NVDA on Windows or VoiceOver on macOS.</li>
    <li>Write accessibility documentation.</li>
    <li>Add automated accessibility tests.</li>
  </ul>

  <h3>Review Process</h3>
  <ol>
    <li>Complete the accessibility checklist in the PR template.</li>
    <li>Automated CI tests run axe-core checks.</li>
    <li>Accessibility reviewer verifies checklist items.</li>
    <li>PR merged only after all checks pass.</li>
  </ol>

  <h3>Resources</h3>
  <ul>
    <li>WAI-ARIA Authoring Practices</li>
    <li>Design system focus indicator tokens</li>
    <li>Accessible color token reference</li>
    <li>Keyboard testing guide</li>
  </ul>
</section>

Common Mistakes

1. No Accessibility Requirements in Guidelines

If guidelines do not mention accessibility, contributors will not consider it.

2. Checklist Not Enforced

A checklist that is optional will be skipped. Make the checklist a hard requirement.

3. No Accessibility Reviewer

Without a designated accessibility reviewer, checklist items may be rubber-stamped.

4. Guidelines Too Vague

"Make it accessible" is not useful. Be specific about ARIA, keyboard, focus, contrast, and testing requirements.

5. No Examples

Provide examples of compliant and non-compliant contributions.

6. No Testing Resources

Contributors may not know how to test for accessibility. Provide guides and tools.

7. No Feedback Process

When a contribution fails accessibility review, provide specific, actionable feedback about what to fix.

Practice Questions

1. What are the 10 items in the accessibility contribution checklist?

Semantic HTML, ARIA correctness, keyboard operability, focus visible, focus management, contrast pass, screen reader tested, documentation complete, no inline code comments, test added.

2. Why should the checklist be enforced in the PR process?

An optional checklist will be ignored. Enforcement ensures all contributions meet accessibility standards.

3. Who should review accessibility contributions?

A designated accessibility reviewer or team member with accessibility expertise.

4. What should feedback include when a contribution fails accessibility review?

Specific, actionable items about what to fix. Point to documentation and examples.

5. Challenge: Write accessibility contribution guidelines for a design system. Include a 10-item checklist, review process, and resources for contributors.

FAQ

Mini Project

Create an accessibility contribution guide for a design system. Include a 10-item checklist, review process, testing resources, and code examples of compliant and non-compliant components.

What's Next

Complete the Design System Project where you will apply everything from this module to build an accessible design system component library.