A11y Issue

How it works in practice

An audit of a dashboard🎛️DashboardData & AnalyticsAn analytics dashboardView reference → turns up an issue: the primary "Save" button shows white text on a pale-green fill at a contrast ratio of 2.8:1, failing WCAG success criterion 1.4.3 Contrast (Minimum), which requires 4.5:1 for normal text. The issue is logged against that guideline with a severity of "serious", because the button is on the core path. It also points at the shared button component, so darkening the fill token once resolves the issue everywhere the component appears, rather than screen by screen.

The W3C's Understanding Documents sit behind every criterion reference in a well-formed issue. For each success criterion they set out the intent of the rule, a set of sufficient techniques that are accepted ways to satisfy it, and a list of documented failures — concrete patterns that definitively fail the criterion. When an issue cites SC 1.4.3, the Understanding Document for that criterion is where the 4.5:1 threshold and the accepted remediation techniques are grounded, and where the large-text exception that defines the boundary of "normal text" is set out.

Accessibility issue vs. its neighbours

• Accessibility audit: the audit is the investigation🔍InvestigationEngineeringAn investigation into an issue or incidentView reference → that surfaces the issue; the issue is one finding within it. Issues only exist as the output of testing.
• Accessibility guideline: the guideline is the rule in the abstract; the issue is a concrete breach of it. Every well-formed issue names the guideline it violates.
• Bug🐛BugProduct SpecificationA defect or unexpected behaviourView reference →: a bug is any defect against intended behaviour; an accessibility issue is specifically a failure against an accessibility standard, scored on a severity that reflects user impact for people with disabilities. An accessibility issue is a bug with a standards reference attached.

Deque University's ARIA and JavaScript course works the same standards reference down to the component level. It maps common interactive patterns — dialogs, live regions, menus, tab panels, carousels — to the specific ARIA authoring requirements each one must satisfy, framing them as named requirements tied to WCAG success criteria rather than general advice. That pins down the point this entity makes: an accessibility issue is a failure against a particular rule on a particular component, not a vague quality concern.

In the graph

In the Unified Product Graph, an accessibility issue is born from an audit through a11y_audit_discovers_a11y_issueA11y AuditdiscoversA11y Issuehierarchy, which keeps every issue traceable to the test that found it and the standard above that test. The fix is located through a11y_issue_affects_design_componentA11y IssueaffectsDesign Componentcross-domain, binding the failure to the exact component that needs changing. That second edge is what turns an audit list into a remediation plan: fixing one shared component can clear many issues at once, and the graph shows precisely which.