Accessibility (WCAG 2.1 AA)

Category: Quality Attributes · Areas: ui, frontend

Description

Areas

ui, frontend

Components

Standard: WCAG 2.1 Level AA
Testing: axe-core automated checks + manual screen reader testing
Scope: All user-facing interfaces

Constraints

All interactive elements must be keyboard-navigable
Color contrast must meet AA ratios (4.5:1 text, 3:1 large text)
All non-decorative images must have alt text
Form inputs must have associated labels
Dynamic content must manage focus appropriately

When to use

Any project with user-facing web or mobile interfaces. Required for public-sector, healthcare, finance, and education. Recommended for all consumer-facing products.

Artifact Impact

Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):

ADR: target WCAG 2.1 AA standard + axe-core + manual screen-reader testing
DESIGN_SYSTEM: keyboard-navigable controls, AA contrast ratios, focus management, labeled inputs
TEST_PLAN: axe-core automated checks + manual screen-reader passes

Practices by activity

Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.

Requirements (Frame activity)

All user stories involving UI must include a11y acceptance criteria
WCAG 2.1 AA is the minimum compliance target
Accessibility is a requirement, not a nice-to-have

Design

All interactive components must be keyboard-navigable
Color contrast ratios must meet AA (4.5:1 for text, 3:1 for large text)
ARIA attributes required for custom components
Semantic heading hierarchy required (h1 > h2 > h3, no skips)
Focus order must follow visual reading order
Touch targets minimum 44x44 CSS pixels

Implementation

Use semantic HTML elements over divs with roles
All images require alt text (decorative images use alt="")
Form inputs require associated <label> elements
Focus management for modals, drawers, and dynamic content
Skip navigation link for keyboard users
aria-live regions for dynamic status updates
No tabindex values greater than 0

Testing

axe-core in CI for automated a11y checks
Screen reader testing for critical user flows (VoiceOver, NVDA)
Keyboard-only navigation testing for all interactive flows
Color contrast validation in design review
Test with browser zoom at 200%

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: concerns/a11y-wcag-aa.md
Signed: 2026-09-23T14:11:58Z
Content digest: sha256:e70f417d…ad9c336c

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-09-23T14:11:58Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/concerns/a11y-wcag-aa/",
        "digest": {
          "alg": "sha256",
          "value": "e70f417d6789000d307dcec80d7f08fbebe489a290a9714fafe75638ad9c336c"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "xb7-O4atsHNmPIV9JDPqc0UFG1LtmkzbfFkBptApg_jlKg-_jTKd5CAOryspfBMP06BBuvVhAQY4IwpFNFFxAA",
      "signed_at": "2026-09-23T14:11:58Z"
    }
  ]
}

attestation file · issuer keys