a11y.error not announced

a11y.error-not-announced

Rule ID: a11y.error-not-announced Severity: ERROR Category: a11y Target Standards: WCAG 2.2 Success Criterion 3.3.1 (Error Identification - Level A), WCAG 2.2 Success Criterion 1.3.1 (Info and Relationships - Level A), WAI-ARIA 1.2 Form Validation Authoring Practices

---

1. Overview & Core Invariant

Ensures form controls with aria-invalid are programmatically linked to error messages via aria-describedby (WCAG 3.3.1)

Core Invariant:

"Form input controls (, , <textarea>) declaring 'aria-invalid' must provide an 'aria-describedby' attribute linking to the error message element ID."

---

2. Technical Grounding & Engine Realities

When form validation fails, declaring aria-invalid prompts screen readers to announce that the field contains an error.

However, if the control lacks aria-describedby referencing the error description container:

1. Blind Error State: Screen reader users are informed that their input is invalid, but are left completely unaware of why or what format is expected.
2. Inaccessible Visual Feedback: Visual error banners with text-destructive are visible to sighted users but completely disconnected in the accessibility tree.
3. Severe WCAG 3.3.1 Level A Non-Compliance: Automatic audit failure in enterprise accessibility and European Accessibility Act (EAA) reviews.

Charites verifies that any input with active or dynamic aria-invalid includes an accompanying aria-describedby.

---

3. Vulnerability & Risk Taxonomy

Risk Vector	Severity	Impact
Unannounced Form Validation Errors	HIGH	Screen reader users cannot determine why form submission failed or how to correct invalid inputs.
WCAG 3.3.1 Level A Non-Compliance	HIGH	Immediate compliance failure during accessibility audits.

---

4. Non-Compliant Code Patterns (Bad Examples)

TSX (Dynamic aria-invalid without aria-describedby to the error text):

<input id="email" aria-invalid={!!errors.email} className="border-destructive" />

ASTRO (Static aria-invalid without programmatic error connection):

<input id="username" aria-invalid="true" class="border-red-500" />

---

5. Compliant Implementation Patterns (Good Examples)

TSX (Input wired to error message ID via aria-describedby):

<input id="email" aria-invalid={!!errors.email} aria-describedby={errors.email ? "email-error" : undefined} className="border-destructive" />

ASTRO (Input linked to error container with role='alert'):

<input id="username" aria-invalid="true" aria-describedby="username-error" class="border-red-500" />

---

6. How to Suppress (Ignore Directives)

If this pattern is required for an intentional exception, suppress the diagnostic using the canonical Charites Rule ID:

<!-- charites:ignore a11y.error-not-announced intentional exception -->

// charites:ignore a11y.error-not-announced intentional exception

---

7. Configuration Reference (charites.yaml)

rules:
  a11y.error-not-announced:
    severity: error # error | warn | info | off

---

8. Architectural Domain & Verification Reference

• Domain Architecture & Analysis Pipeline: See the a11y Category Guide.
• 1-SSOT Golden Tri-Corpus Test Matrix: See the Verification Harness on the Master Home page.
• Rule Catalog Index: See Master Wiki Home.