Skip to content

Accessibility (a11y)

The a11y package defines semantic types for accessibility findings tied to WCAG success criteria and projects them into the domain-neutral Finding.

Issue

Issue is an accessibility finding for a specific WCAG success criterion at a location in a rendered page.

Field Type Notes
ID string Stable identifier
Title string Short human-readable summary
Description string Detailed explanation
Criterion string WCAG success-criterion identifier, e.g. "1.4.3"
Level ConformanceLevel WCAG conformance level of the criterion
Impact Impact User-facing impact of the issue
HelpURL string Link to guidance for resolving the issue
Location *findingspec.Location Where it was observed — see Location
Remediation *findingspec.Remediation How to fix, incl. an AgentPrompt
Status findingspec.Status Lifecycle state
DetectedAt *time.Time When observed

ConformanceLevel

ConformanceLevel is a WCAG conformance level.

Constant Value
LevelA A
LevelAA AA
LevelAAA AAA

Impact

Impact is the user-facing impact of an accessibility issue, following the common minor/moderate/serious/critical scale used by tools such as axe-core.

Constant Value
ImpactMinor minor
ImpactModerate moderate
ImpactSerious serious
ImpactCritical critical

Impact.Severity() maps an accessibility impact onto the shared severity scale:

Impact Severity
critical SeverityCritical
serious SeverityHigh
moderate SeverityMedium
minor SeverityLow
(empty / unknown) SeverityInformational

Projection to Finding

ToFinding() projects the issue into a domain-neutral findingspec.Finding in the a11y domain:

  • sets Domain to findingspec.DomainA11y;
  • maps Impact to Severity via Impact.Severity();
  • derives RuleID from the criterion and level — when both are present it becomes "WCAG <criterion> (<level>)", e.g. "WCAG 1.4.3 (AA)"; when the level is empty the raw Criterion is used;
  • adds a References entry titled "WCAG guidance" for a non-empty HelpURL.
issue := a11y.Issue{
    ID:        "a11y-001",
    Title:     "Text has insufficient color contrast",
    Criterion: "1.4.3",
    Level:     a11y.LevelAA,
    Impact:    a11y.ImpactSerious,
    HelpURL:   "https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html",
    Location: &findingspec.Location{
        URL:      "https://example.com/pricing",
        Selector: ".cta-button",
    },
}

f := issue.ToFinding()
f.Domain   // "a11y"
f.RuleID   // "WCAG 1.4.3 (AA)"
f.Severity // "high"

See also