Disability User Stories

Disability-Centered User Stories

"As a user, I want the site to be accessible" is not a user story. It is a wish. — TetraLogical

"Automated scans reliably flag only 13% of WCAG 2.1 AA success criteria." — Accessible.org

Stories that say "accessible" are not testable. Stories that name the assistive technology, the persona, and the experience are. This skill generates user stories, acceptance criteria, and BDD scenarios that center the disability experience rather than the code implementation.

1. Why Disability-Centered Stories

Accessibility stories fail when they describe code attributes instead of human experiences. Two symptoms:

Vague stories nobody can test:

• "As a user, I want the site to be accessible." (No persona, no AT, no outcome)
• "As a disabled user, I want to use the site." (Disability is not monolithic)
• "As a developer, I want to add aria-labels to all buttons." (This is a task, not a story)

Code-focused acceptance criteria that miss the point:

The criterion is what the human experiences, not what the code does.

Sources: TetraLogical, Section 508

2. Persona Frameworks

Three established frameworks provide ready-made personas. Use them directly or as templates for project-specific personas.

W3C WAI Personas (9 personas)

Source: W3C WAI User Stories

GOV.UK Accessibility Personas (7 personas)

Simulated Chrome browser profiles for empathy testing. Teams run 50-minute sessions where each member adopts a persona and attempts real user tasks.

Critical caveat from GDS: "A simulation is never a true representation of an impairment. It's only a tool trying to make some things roughly as difficult for someone without that impairment."

Sources: GDS Persona Profiles, GOV.UK Accessibility Personas

Microsoft Inclusive Design Persona Spectrum

Disability as a mismatch between person and environment, not an inherent deficit. Solutions for permanent disabilities cascade benefits to temporary and situational contexts.

This spectrum expands the "who benefits" framing and builds organizational buy-in: keyboard accessibility benefits the one-armed user, the broken-arm user, AND the parent holding a baby.

Source: Microsoft Inclusive Design

Full persona details: references/persona-catalog.md

3. Story Template

As a [persona name] who [specific disability/AT context],
I want to [specific interaction with the feature],
So that [human outcome -- what they can accomplish].

Every slot matters:

• Persona slot: Must name the specific disability or AT. "As a user" is never acceptable for an accessibility story.
• Goal slot: Describes an interaction, not a technical implementation.
• Benefit slot: States the human outcome, not a WCAG reference.

Full template with persona context, acceptance criteria sections, WCAG references, and BDD scenarios: references/story-templates.md

4. Example Stories by Disability Type

Blind (Screen Reader Users)

• "As a screen reader user, I want to hear the text equivalent for each image button so that I will know what function it performs."
• "As a screen reader user, I want to know the column and row headers for each table cell so that I can understand the meaning of the data."
• "As a screen reader user, I want to know the page language so that my screen reader uses the correct pronunciation."

Keyboard-Only Users

• "As a keyboard-only user, I want to know where I am on the screen so that I can perform an action or navigate."
• "As a keyboard-only user, I want to be able to navigate content without getting stuck so that I can complete my task."
• "As a keyboard-only user, I want to be able to skip repeated navigation so that I can reach the main content quickly."

Low Vision

• "As a user with limited vision, I want to be able to zoom to 200% without losing content so that I can read text at a comfortable size."
• "As a user who sees better with high contrast, I want sufficient contrast between text and its background so that I can read content."

Cognitive / Learning Disabilities

• "As a user who struggles to comprehend a lot of content at once, I want descriptive headings so that I can understand the type of content in each section."
• "As a user who has limited attention, I want to stop all moving or blinking content so that I can focus on reading."
• "As a user who has trouble following detailed instructions, I want to easily understand what is required in each form field so that I can complete the form."

Deaf / Hard of Hearing

• "As a user without hearing, I want captions on multimedia so that I can understand the audio content."
• "As a user with limited hearing, I want to be able to easily turn off auto-playing audio so that it does not interfere with my hearing aid."

Motor / Limited Manipulation

• "As a user with limited ability to use a keyboard and mouse, I want time outs to allow me sufficient time so that I can complete tasks at my own pace."
• "As a voice input user, I want to be able to use my dictation software to control the interface so that I can work hands-free."

Photosensitive

• "As a user with photoepileptic seizures, I want to navigate content without it triggering a medical response so that I can use the web safely."

Source: Section 508 Sample User Stories

5. Acceptance Criteria Patterns

Three-Level Model

Acceptance criteria should be defined at three levels to ensure nothing falls through the cracks (per Cerovac):

Page level:

• Valid HTML; unique, descriptive page title; language attribute set; landmark regions defined

Container level:

• Section headings present and hierarchical; heading text describes section content; related form fields grouped with fieldset/legend

Component level:

• Interactive element has accessible name; role communicated to AT; state changes announced; keyboard interaction matches expected behavior

AT Verification, Not Code Attributes

Acceptance criteria must specify what the user experiences:

### Perceivable (what is announced/visible)
- [ ] Screen reader announces [specific text] when [trigger]
- [ ] Focus indicator is visible when [component] receives focus
- [ ] Color is not the only means of conveying [information]

### Understandable (what makes sense)
- [ ] Error messages state what went wrong AND how to fix it
- [ ] Instructions are provided before the user needs them

### Robust (what holds up)
- [ ] Works with [specific AT: NVDA+Firefox, VoiceOver+Safari, JAWS+Chrome]
- [ ] No keyboard traps
- [ ] Focus returns to [trigger element] when [component] is dismissed

The Coles Supermarket Model

Australian supermarket Coles developed 10 Accessibility Acceptance Criteria covering the most commonly failing WCAG success criteria. Key insight: 10 high-impact criteria beat 50 ignored ones. A focused set drives more actual improvement than a comprehensive checklist teams skip.

The 10 criteria: Keyboard, Content on Hover, Page Title, Visible Focus, Semantic Markup, Form Control Labeling, Screen Reader announcements, Zoom and Resize, Alt Text, Orientation and Reflow.

Source: CANAXESS / Coles AACs

Full patterns and templates: references/acceptance-criteria-patterns.md

6. BDD / Given-When-Then for Accessibility

When to Use Gherkin

Use Gherkin for scenarios describing user behavior: keyboard navigation, screen reader interaction, visual feedback, form behavior.

Do NOT use Gherkin for technical validation requiring source code inspection (checking ARIA attributes, validating HTML). Use axe-core, Pa11y, or Lighthouse for those.

Rule of thumb: If the test describes what a user does and perceives, use Gherkin. If it requires looking at markup, use automated tools. Combine both.

Source: Hassell Inclusion

Examples

Skip Navigation:

Given I am on the homepage
When I press Tab as the first keyboard action
Then a "Skip to content" link becomes visible
When I activate the skip link
Then the main content area has keyboard focus

Form Validation:

Given I am a screen reader user
When I submit a form with validation errors
Then focus moves to the first field in error state
And my screen reader announces the error message and how to fix it

Dialog/Modal:

Given I am a screen reader user
When I activate a button that opens a dialog
Then keyboard focus moves to the dialog
And I can navigate within the dialog using Tab
And I cannot Tab to content behind the dialog
When I press Escape
Then the dialog closes
And focus returns to the button that opened it

Dynamic Content:

Given I am a screen reader user
When I click a button that loads content asynchronously
Then I hear an announcement that content is loading
When the content finishes loading
Then I hear a confirmation that new content is available

What NOT to Write in Gherkin

These require code inspection, not user behavior testing:

• "Then each anchor tag has the href attribute"
• "Then the page has exactly one h1 element"
• "Then all images have non-empty alt attributes"
• "Then ARIA landmarks are correctly defined"

Sources: Hassell Inclusion, accessibility-gherkin GitHub

7. Shift-Left Integration

Accessibility acceptance criteria belong in the story before development starts, not in a QA phase after. Fixing accessibility post-release costs 10-100x more than building it in. (IAPM)

Definition of Done

A team's Definition of Done should include four accessibility gates (per Accessibility for Teams):

1. Automated accessibility testing passed -- axe, WAVE, Lighthouse, or Pa11y (use multiple tools; each catches different issues)
2. Manual WCAG review completed -- a screen reader user can test ~2/3 of WCAG 2.1 success criteria using a screen reader alone
3. Accessibility statement updated -- if the feature has known limitations, document them
4. Content style guide followed -- plain language, descriptive link text, proper alt text, meaningful headings

Sprint Planning

• Estimate accessibility work as part of the story, not a separate task
• Include keyboard testing and screen reader testing in the test plan
• Identify which WCAG criteria the story touches

Design Review

• Review mockups for color contrast, focus states, keyboard interaction patterns
• Annotate designs with heading levels, landmark regions, reading order
• Define all component states (hover, focus, active, disabled, error, loading)

8. Anti-Patterns

Vague "Accessible" Stories

Testing Attributes, Not Experiences

Missing the Spectrum

Writing stories only for permanent disabilities misses 80%+ of the affected population. Use Microsoft's persona spectrum: permanent -> temporary -> situational. Every accessibility improvement benefits users across the spectrum.

9. Cross-References

• at-experience-verification -- what screen readers, keyboard, and voice control users actually experience; "what bad sounds like" examples
• testing-strategy -- three-tier testing model (automated, keyboard, screen reader); acceptance criteria templates
• cognitive-neurodivergent-experience -- sensory overload, predictability, anxiety patterns for neurodivergent users
• accessible-content-writing -- link text, error messages, alt text, plain language quality
• form-a11y -- form labeling, error handling, validation patterns
• focus-management -- modal focus trapping, SPA route changes, focus restoration

For detailed reference material:

• references/persona-catalog.md -- full persona details from all three frameworks
• references/story-templates.md -- complete story-to-criteria templates with worked examples
• references/acceptance-criteria-patterns.md -- three-level model, Coles AACs, AT verification patterns
• references/sources.yaml -- provenance for all cited sources