---
title: "Docusaurus Accessibility Conformance - Business Requirements Document"
description: "Business requirements for achieving and continuously verifying WCAG 2.1 AA accessibility conformance on the HVE-Core documentation site"
sidebar_position: 2
author: "HVE-Core Maintainers"
ms.date: 2026-06-13
ms.topic: reference
---
Version 0.1 (Draft) | Status In Progress | Owner HVE-Core Maintainers | Sponsor Core Maintainers & Repo Writers | Date 2026-06-13 | Business Unit HVE-Core (Open Source)
## Progress Tracker
| Phase | Done | Gaps | Updated |
|----------------------|---------|--------------------------------------------------------------|------------|
| Business Context | Yes | None | 2026-06-13 |
| Problem & Drivers | Yes | None | 2026-06-13 |
| Objectives & Metrics | Partial | Pre-fix baselines + full-conformance timeframe to confirm | 2026-06-13 |
| Stakeholders | Yes | None | 2026-06-13 |
| Scope | Yes | None | 2026-06-13 |
| Processes | Yes | None | 2026-06-13 |
| Requirements | Yes | Priorities set; audit-vs-identified-gaps wording open (OQ-3) | 2026-06-13 |
| Data & Reporting | Yes | None | 2026-06-13 |
| Risks & Dependencies | Yes | None | 2026-06-13 |
| Implementation | Yes | None | 2026-06-13 |
Unresolved Critical Questions: 0 | Open items for owner review: pre-fix KPI baselines, full-conformance timeframe, audit-vs-identified-gaps wording (see Section 13)
---
## Document Control
| Version | Date | Author | Summary of Changes | Approved By |
|---------|------------|----------------------|------------------------------|-------------|
| 0.1 | 2026-06-13 | HVE-Core Maintainers | Initial draft from changeset | TODO |
---
## 1. Business Context & Background
### 1.1 Overview
HVE-Core is a public, open-source project. Its documentation site (built with Docusaurus, served under `/hve-core/`) is the primary public-facing surface through which contributors and users learn the project, follow getting-started guides, and adopt its workflows. As a public OSS project, the site is expected to meet baseline accessibility standards so that people who rely on assistive technology, keyboard navigation, or low-vision settings can use the documentation without barriers.
This initiative addresses identified accessibility conformance gaps on the documentation site and, equally important, establishes automated guardrails that continuously verify accessibility so regressions are caught before they reach the public site.
### 1.2 Strategic Alignment
The deeper intent is for HVE-Core to act as a **lighthouse project**, a credible and reusable reference for how to build and continuously verify accessible documentation the right way. Compliance with WCAG 2.1 AA is the floor; demonstrable, exemplary accessibility practice that others can copy is the goal. The documentation site serves as the **pilot implementation** of a repeatable accessibility pattern intended for adoption by other HVE-Core surfaces and downstream projects.
### 1.3 Drivers & Triggers
* **Reputation / leadership (primary):** Establish HVE-Core as a lighthouse exemplar of accessible, continuously verified documentation.
* **Compliance (baseline):** Meet open-source accessibility expectations aligned to WCAG 2.1 AA, with reference to Section 508 and EN 301 549.
* **Regression prevention (trigger):** Conformance gaps existed with no automated guardrail to prevent reintroduction; the changeset introduces that guardrail.
---
## 2. Problem Statement & Business Drivers
### 2.1 Current Situation (As-Is)
The documentation site contained several WCAG 2.1 AA conformance gaps and had no automated accessibility verification in its CI pipeline. Specific gaps observed and addressed in the changeset:
* Decorative imagery exposed to screen readers (hub card icons), affecting screen-reader users (SC 1.1.1).
* Links distinguished by color alone in body content, affecting low-vision and color-vision users (SC 1.4.1).
* Missing visible focus indicators, affecting keyboard-only users (SC 2.4.7).
* Insufficient text contrast in dark mode and in local search results, affecting low-vision users (SC 1.4.3, SC 1.4.11).
* No automated accessibility gate in CI to prevent regressions.
### 2.2 Problem Statement
As a public open-source project, the HVE-Core documentation site must meet baseline accessibility expectations (WCAG 2.1 AA) so that contributors and users who rely on assistive technology, keyboard navigation, or low-vision settings are not excluded.
Today the site has conformance gaps (decorative imagery exposed to screen readers, links distinguished by color alone, missing visible focus indicators, and insufficient text contrast in dark mode and search), and there is no automated guardrail to prevent regressions.
Beyond simply being compliant, the deeper goal is for HVE-Core to serve as a lighthouse project: a credible, reusable reference for how to build and continuously verify accessible documentation the right way.
### 2.3 Impact of the Problem
| Impact Area | Description | Magnitude | Evidence / Source |
|--------------------------|---------------------------------------------------------------------------------|-----------|--------------------------------------------|
| Exclusion of users | Screen-reader, keyboard-only, and low-vision users face barriers using the docs | High | WCAG SC 1.1.1, 1.4.1, 2.4.7, 1.4.3, 1.4.11 |
| Reputation / credibility | An inaccessible OSS docs site undermines the project's leadership positioning | High | Strategic intent (lighthouse goal) |
| Regression risk | Without automated gates, fixes can silently regress on future changes | Medium | Absence of prior a11y CI guardrail |
| Compliance exposure | Falls short of WCAG 2.1 AA / Section 508 / EN 301 549 baseline expectations | Medium | Standards baseline |
---
## 3. Business Objectives & Success Metrics
**North Star:** 100% of the documentation site's page types (e.g., hub/landing, doc article, search results, homepage) are in general WCAG conformance, and the project commits to expanding from that baseline toward full conformance across all impacted area paths, including cognitive accessibility (COGA), time-based media, and the remaining WCAG success-criteria categories.
### 3.1 Objectives
| Objective ID | Statement | Category | Priority | Owner |
|--------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------|---------------------------|------------------|
| OBJ-1 | Bring 100% of the documentation site's page types into general WCAG 2.1 AA conformance, starting with the identified gaps | Compliance | Critical | Core Maintainers |
| OBJ-2 | Establish automated, continuous accessibility verification in CI to prevent regressions | Quality / Ops | Critical | Core Maintainers |
| OBJ-3 | Produce a repeatable, documented accessibility pattern other surfaces/projects can adopt | Reputation | High | Core Maintainers |
| OBJ-4 | Commit to and define a path to expand from general conformance toward full conformance across all impacted area paths (cognitive/COGA, time-based media, and remaining WCAG categories) | Reputation / Compliance | Medium (committed-future) | Core Maintainers |
### 3.2 Key Performance Indicators (KPIs)
> TODO: Confirm remaining baselines (coverage %) and the "full conformance" expansion timeframe during elicitation.
| KPI | Baseline | Target | Timeframe | Data Source | Notes |
|-----------------------------------------------|-------------------------|-----------------|----------------------------|-------------------------|---------------------------------------------------------------------------------------|
| Page types in general WCAG 2.1 AA conformance | 0 of 4 (none conformed) | 4 of 4 (100%) | At merge of this changeset | pa11y-ci CI scan | North-star metric; scope = enumerated page types (hub, doc article, search, homepage) |
| Automated a11y violations (pa11y-ci) | TODO (pre-fix count) | 0 (threshold 0) | At merge | pa11y-ci CI run | `.pa11yci` threshold = 0 |
| axe-core violations in component tests | TODO (pre-fix count) | 0 | At merge | Jest + @axe-core tests | BoxCard axe test |
| Keyboard/focus e2e checks passing | TODO (pre-fix count) | 100% pass | At merge | Playwright e2e suite | 8 e2e specs |
| Test coverage (docs components) | TODO | TODO | At merge | Jest coverage / Codecov | Codecov flag `docusaurus` |
| Impacted area paths under full conformance | 0 (general only) | All (committed) | TODO (post-release) | Conformance roadmap | Expansion commitment (cognitive, media, etc.) |
### 3.3 Non-quantitative Success Criteria (Optional)
* The accessibility pattern is documented clearly enough that another team can replicate the CI guardrail without direct support.
* Contributors can keep the docs site conformant by following the automated gates, without needing specialist accessibility knowledge for routine changes.
---
## 4. Stakeholders & Roles
### 4.1 Stakeholder Summary
| Stakeholder Group | Role / Interest | Responsibilities | Influence | Engagement Approach |
|-----------------------------|----------------------------------------|--------------------------------------------------|-----------|-----------------------------|
| Core Maintainers (Sponsor) | Own the project and sign off on "done" | Approve standards, merge, maintain CI guardrails | High | Decision-makers / approvers |
| Repo Writers / Contributors | Author docs and components | Follow accessible patterns, keep CI green | Medium | Guidance + automated gates |
| Public Users / Contributors | Consume the documentation | N/A (beneficiaries) | Low | Represented via personas |
### 4.2 Users / Business Actors
| Actor / Persona | Description | Key Goals | Pain Points | Impact of Change |
|--------------------------------|---------------------------------------|----------------------------------------|--------------------------------------------------|---------------------------------------|
| Screen-reader user | Navigates via assistive technology | Understand content without noise | Decorative icons announced as content (SC 1.1.1) | Decorative imagery hidden from AT |
| Keyboard-only user | Navigates without a pointer | See where focus is, reach all controls | No visible focus indicator (SC 2.4.7) | Visible focus outlines added |
| Low-vision / color-vision user | Relies on contrast and non-color cues | Read text, distinguish links | Color-only links, low contrast dark/search | Underlines + improved contrast |
| Contributor / Maintainer | Adds docs and components | Avoid shipping regressions | No automated a11y safety net | CI guardrails catch regressions early |
---
## 5. Scope
### 5.1 In Scope
* WCAG 2.1 AA conformance fixes for the identified gaps on the HVE-Core Docusaurus documentation site (`docs/docusaurus/`):
* Hide decorative hub-card icons from assistive technology (`aria-hidden`, empty `alt`).
* Distinguish in-content links by more than color (underlines) and add visible `focus-visible` outlines.
* Improve text contrast in dark mode and in local search results.
* Automated accessibility and quality guardrails in CI:
* Component-level accessibility tests (Jest + axe-core).
* End-to-end accessibility/keyboard/focus checks (Playwright e2e suite).
* Site-level accessibility scanning (pa11y-ci, WCAG2AA, threshold 0).
* Static accessibility linting (eslint-plugin-jsx-a11y).
* Test coverage reporting (Jest coverage uploaded to Codecov via OIDC).
* Treating the documentation site as the **pilot** implementation of a repeatable accessibility pattern.
* Producing the **documented, reusable accessibility pattern** (the guardrail recipe and its CI wiring) as a deliverable of this work, so another surface can replicate it without direct support.
### 5.2 Out of Scope
* Organization-wide accessibility programs beyond the HVE-Core documentation site.
* Rolling the pattern out to other specific surfaces/projects (future work; this BRD establishes the reusable pattern, not its downstream adoption).
* Accessibility conformance levels beyond WCAG 2.1 AA (e.g., AAA) unless explicitly added later.
* TODO: Confirm any additional explicit exclusions.
### 5.3 Boundaries & Interfaces
The initiative is bounded to the HVE-Core Docusaurus site and its CI workflow (`.github/workflows/docusaurus-tests.yml`). Interfaces include the Codecov service (coverage upload via OIDC) and the CI runner environment that executes pa11y-ci, Playwright, and Jest.
---
## 6. Current & Future Business Processes
### 6.1 As-Is Process Overview
Accessibility relied on manual attention during code review, with no automated gate. A reviewer might or might not catch an accessibility regression, and nothing prevented a non-conformant change from reaching the published site. There was no continuous signal showing whether the site remained conformant over time.
### 6.2 To-Be Process Overview
Every change to the docs site triggers automated accessibility verification in CI before merge:
1. Static accessibility linting (eslint-plugin-jsx-a11y) runs on component source.
2. Component-level accessibility tests (Jest + axe-core) run against rendered components.
3. End-to-end focus/keyboard checks (Playwright) validate interactive behavior.
4. Site-level accessibility scanning (pa11y-ci, WCAG2AA, threshold 0) runs against the rendered site.
5. Test coverage is generated and uploaded to Codecov.
Any violation fails the pipeline and blocks merge, so regressions are caught before they reach the public site and conformance is demonstrated continuously.
### 6.3 Business Rules
* The pa11y-ci accessibility threshold is 0, meaning no violations are tolerated on the scanned pages.
* CI accessibility checks must pass before a change to the docs site can merge.
* New or changed docs components should be covered by the automated accessibility checks (component axe test and/or e2e check) appropriate to their interaction surface.
---
## 7. Business Requirements
> Each requirement expresses what the business needs, not the technical implementation. Priorities and acceptance criteria are draft pending elicitation.
| BR ID | Title | Description | Objective(s) | Stakeholder(s) | Priority | Acceptance Criteria |
|--------|--------------------------------------------|---------------------------------------------------------------------------------------------------------|--------------|----------------------------------|----------|--------------------------------------------------------------------------------------------|
| BR-001 | Decorative imagery not exposed to AT | Decorative imagery on the docs site must not be announced as meaningful content by assistive technology | OBJ-1 | Screen-reader users | Critical | Decorative hub-card icons are not announced by screen readers (SC 1.1.1) |
| BR-002 | Links distinguishable beyond color | In-content links must be distinguishable without relying on color alone | OBJ-1 | Low-vision / color-vision users | Critical | Body links present a non-color visual cue (e.g., underline) (SC 1.4.1) |
| BR-003 | Visible keyboard focus indicators | Interactive elements must show a visible focus indicator when navigated by keyboard | OBJ-1 | Keyboard-only users | Critical | A visible focus indicator appears on keyboard focus across interactive controls (SC 2.4.7) |
| BR-004 | Sufficient text contrast | Text, including dark mode and search results, must meet WCAG AA contrast minimums | OBJ-1 | Low-vision users | Critical | Text and UI contrast meet SC 1.4.3 / 1.4.11 in light, dark, and search surfaces |
| BR-005 | Automated accessibility gate in CI | CI must automatically verify accessibility on the docs site and block regressions | OBJ-2 | Maintainers, contributors | Critical | CI runs accessibility checks (component, e2e, site scan) and fails on violations |
| BR-006 | Continuous coverage reporting | CI must report documentation test coverage to provide ongoing quality signal | OBJ-2 | Maintainers | High | Coverage is generated and uploaded to Codecov on docs changes |
| BR-007 | Reusable, documented accessibility pattern | The accessibility approach must be documented so other surfaces/projects can adopt it | OBJ-3 | Maintainers, downstream adopters | High | Pattern is documented sufficiently for independent replication |
---
## 8. Data & Reporting Requirements
### 8.1 Data Needs
| Data Domain | Description | Source System(s) | Consumer(s) | Quality Expectations |
|--------------------|--------------------------------------|------------------|------------------|-------------------------------|
| Accessibility scan | Violations per scanned page | pa11y-ci | Maintainers / CI | Threshold 0 (no violations) |
| Test coverage | Coverage metrics for docs components | Jest / Codecov | Maintainers | Reported on every docs change |
### 8.2 Reporting & Analytics
| Report / Insight | Purpose | Audience | Frequency | Level of Detail |
|-------------------------|------------------------------------------------|-------------|-------------------|------------------------------------|
| CI run summary | Pass/fail signal for accessibility gate per PR | Maintainers | Every docs change | Per-check pass/fail |
| Codecov coverage report | Ongoing docs test-coverage trend and PR deltas | Maintainers | Every docs change | Per-file / per-flag (`docusaurus`) |
---
## 9. Assumptions, Dependencies & Constraints
> TODO: Elicit and confirm.
### 9.1 Assumptions
| ID | Assumption | Impact if False | Owner |
|-----|--------------------------------------------------------------------------------|--------------------------------------------------------------|------------------|
| A-1 | CI runners can build the site and run headless browsers (Playwright, pa11y-ci) | Accessibility gate cannot run in CI | Core Maintainers |
| A-2 | Codecov (OIDC) remains available for coverage upload | Coverage reporting signal is lost | Core Maintainers |
| A-3 | The four enumerated page types represent the site's templates | Conformance claim does not generalize to uncovered templates | Core Maintainers |
### 9.2 Dependencies
| Dependency | Type | Criticality | Owner | Notes |
|------------------|----------|-------------|------------------|---------------------------------|
| Codecov (OIDC) | External | Medium | Core Maintainers | Coverage upload via OIDC token |
| CI runner / Node | Tooling | High | Core Maintainers | Runs pa11y-ci, Playwright, Jest |
### 9.3 Constraints
| Constraint | Category | Description | Implication |
|-------------|----------|-----------------------------------------------------|--------------------------------|
| WCAG 2.1 AA | Standard | Conformance target is AA, not AAA | Defines the bar for "done" |
| Threshold 0 | Quality | pa11y-ci tolerates zero violations on scanned pages | Any new violation blocks merge |
---
## 10. Risks & Issues
### 10.1 Risks
| Risk ID | Description | Cause | Impact | Likelihood | Severity | Mitigation | Owner | Status |
|---------|-------------------------------------------------------------|-----------------------------------------------|---------------------------------------------------|------------|----------|---------------------------------------------------------------------|------------------|--------|
| RSK-1 | Automated checks flake and falsely block merges | Timing/selector fragility in e2e or site scan | Contributor friction; pressure to weaken the gate | Medium | Medium | Stabilize selectors, add retries, keep scans deterministic | Core Maintainers | Open |
| RSK-2 | New page types added without scan coverage | Scan set not updated when templates change | Conformance claim silently stops generalizing | Medium | High | Review the pa11y-ci scan set whenever a page template is added | Core Maintainers | Open |
| RSK-3 | "General conformance" mistaken for full per-page-type audit | Wording ambiguity in KPIs | Overstated conformance posture | Medium | Medium | Distinguish identified-gap closure from full audit; track via OBJ-4 | Core Maintainers | Open |
### 10.2 Known Issues (Pre-Existing)
| Issue ID | Description | Impact | Workaround | Owner | Status |
|----------|-------------------------------------------------------------|-------------------------------------------|--------------------------------------|------------------|--------|
| ISS-1 | Pre-fix accessibility violation baselines were not captured | Cannot quantify exact before/after deltas | Track from threshold-0 state forward | Core Maintainers | Open |
---
## 11. Implementation & Change Considerations
### 11.1 Implementation Approach (High-Level)
The changeset delivers both the one-time conformance fixes (decorative-icon handling, link styling, focus indicators, contrast) and the ongoing CI guardrail infrastructure (lint, axe component tests, Playwright e2e, pa11y-ci scan, coverage upload) together, so that the site is brought to conformance and protected against regression in a single coherent effort.
### 11.2 Phasing & Milestones
| Phase | Description | Target Dates | Entry Criteria | Exit Criteria |
|---------|---------------------------------------------------------------|----------------|----------------------------------------|-----------------------------------------------------------|
| Phase 1 | Conformance fixes + automated CI accessibility guardrail | This changeset | Identified WCAG gaps and CI plan ready | Fixes merged; CI accessibility gate active at threshold 0 |
| Phase 2 | Expand from identified-gap closure toward broader conformance | Future (OBJ-4) | Phase 1 merged | Defined per-page-type conformance scope met |
### 11.3 Change Management & Training
| Audience | Change Impact | Training Needs | Channel | Timing |
|--------------|----------------------------------------------------|--------------------------------------------------------|----------------------------------|----------------|
| Contributors | Must keep the accessibility CI gate green to merge | Awareness of the gate and how to read failures | Contributing guide / PR feedback | At/after merge |
| Maintainers | Own the scan set and triage accessibility failures | Familiarity with pa11y-ci, axe, and Playwright outputs | Repo docs | Ongoing |
---
## 12. Benefits & High-Level Economics (Optional)
> Formal cost/ROI economics are not in scope for this open-source initiative; benefits are expressed qualitatively.
### 12.1 Expected Benefits
| Benefit | Type | Magnitude | Timing | Confidence |
|---------------------------------------------|-------------|-----------|------------|------------|
| Accessible docs for users with disabilities | Qualitative | High | At merge | High |
| Regression protection via automated gate | Qualitative | High | Ongoing | High |
| Reusable, documented accessibility pattern | Qualitative | Medium | Post-merge | Medium |
### 12.2 High-Level Cost Considerations
Incremental cost is limited to CI execution time for the added accessibility and coverage checks; no licensing or external spend is introduced.
---
## 13. Open Questions & Decisions
### 13.1 Open Questions
| Q ID | Question | Owner | Due Date | Status |
|------|------------------------------------------------------------------------------------------------|------------------|----------|--------|
| OQ-1 | What are the pre-fix KPI baselines (pa11y/axe/e2e) and the full-conformance timeframe (OBJ-4)? | Core Maintainers | TODO | Open |
| OQ-2 | Which pages define the canonical pa11y-ci scan set long term? | Core Maintainers | TODO | Open |
| OQ-3 | Does the north-star KPI reflect closure of identified gaps, or a full per-page-type audit? | Core Maintainers | TODO | Open |
### 13.2 Key Decisions
| Decision ID | Decision | Date | Decision Maker(s) | Rationale | Impact |
|-------------|-----------------------------------------------|------------|-------------------|----------------------------------------|------------------------|
| DEC-1 | Conformance target is WCAG 2.1 AA | 2026-06-13 | Core Maintainers | Baseline OSS accessibility expectation | Defines the "done" bar |
| DEC-2 | Docs site is the pilot for a reusable pattern | 2026-06-13 | Core Maintainers | Lighthouse exemplar goal | Shapes scope & outputs |
---
## 14. References & Appendices
### 14.1 Reference Materials
| Ref ID | Type | Title / Description | Location | Notes |
|--------|----------|-------------------------------------------|----------------------------------------------------|--------------------------------|
| REF-1 | Code | Hub card decorative icon fix | `docs/docusaurus/src/components/Cards/BoxCard.tsx` | SC 1.1.1 |
| REF-2 | Code | Link/focus/contrast styles (WI-06, WI-07) | `docs/docusaurus/src/css/custom.css` | SC 1.4.1, 2.4.7, 1.4.3, 1.4.11 |
| REF-3 | Code | Search contrast theme override | `docs/docusaurus/src/theme/SearchBar/index.jsx` | Search results contrast |
| REF-4 | Config | Site accessibility scan configuration | `docs/docusaurus/.pa11yci` | WCAG2AA, threshold 0 |
| REF-5 | Config | End-to-end test configuration | `docs/docusaurus/playwright.config.ts` | 8 e2e specs |
| REF-6 | Workflow | CI accessibility + coverage pipeline | `.github/workflows/docusaurus-tests.yml` | pa11y, Playwright, Codecov |
### 14.2 Glossary
| Term | Definition |
|-------------|-----------------------------------------------------------------------|
| WCAG 2.1 AA | Web Content Accessibility Guidelines 2.1, conformance level AA |
| axe-core | Automated accessibility testing engine used in component tests |
| pa11y-ci | Command-line accessibility scanner run in CI against rendered pages |
| Playwright | Browser automation framework used for end-to-end accessibility checks |
### 14.3 Additional Notes
The code in the changeset references work item markers WI-06 (link/focus styling) and WI-07 (search/contrast styling), which may correspond to pre-existing tracked work items.
---
Generated 2026-06-13 by BRD Builder (mode: interactive)
---
*🤖 Crafted with precision by ✨Copilot following brilliant human instruction, then carefully refined by our team of discerning human reviewers.*microsoft/hve-core
Publicmirrored from https://github.com/microsoft/hve-coreAvailable
docs/planning/brds/docusaurus-accessibility-conformance-brd.md
369lines · modepreview