a11y.dialog missing aria

a11y.dialog-missing-aria

Rule ID: a11y.dialog-missing-aria Severity: ERROR Category: a11y Target Standards: W3C Web Content Accessibility Guidelines (WCAG) 2.2 SC 4.1.2 (Name, Role, Value), W3C WAI-ARIA 1.2 Dialog (Modal) Pattern Specification, W3C WAI-ARIA Authoring Practices Guide (APG)

---

1. Overview & Core Invariant

Enforces that custom modal dialogs declare aria-modal="true" and have an accessible name

Core Invariant:

"Any element with role="dialog" or role="alertdialog" must specify aria-modal="true" and declare an accessible name via aria-labelledby or aria-label."

---

2. Technical Grounding & Engine Realities

In web applications, declaring role="dialog" on a

establishes the container as an accessible dialog in the accessibility tree.

However, role="dialog" alone is insufficient without two mandatory attributes:

1. Modal Boundary (aria-modal="true"): Without aria-modal="true", screen readers treat the dialog as a non-modal popup, allowing reading cursor navigation to bleed into background page elements behind the backdrop.
2. Accessible Name (aria-labelledby or aria-label): Screen readers announce "dialog" but cannot state what the dialog is about (e.g. "Konfirmasi Hapus Data") if aria-labelledby or aria-label is omitted.

Charites inspects custom dialog nodes to verify both boundary demarcation and accessible naming.

---

3. Vulnerability & Risk Taxonomy

Risk Vector	Severity	Impact
Screen Reader Background Bleed	HIGH	Screen readers navigate into background DOM elements behind the dialog overlay.
Unnamed Modal Context	HIGH	Assistive technologies announce an unnamed generic dialog without purpose or context.

---

4. Non-Compliant Code Patterns (Bad Examples)

TSX (Custom dialog missing aria-modal and accessible name):

<div role="dialog" className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
  <div className="bg-background p-6 rounded-xl">
    <h2>Konfirmasi Tindakan</h2>
    <p>Apakah Anda ingin melanjutkan?</p>
  </div>
</div>

---

5. Compliant Implementation Patterns (Good Examples)

TSX (Compliant custom modal dialog with aria-modal and aria-labelledby):

<div role="dialog" aria-modal="true" aria-labelledby="dialog-title" className="fixed inset-0 z-50 flex items-center justify-center bg-black/50">
  <div className="bg-background p-6 rounded-xl">
    <h2 id="dialog-title" className="text-lg font-semibold">Konfirmasi Tindakan</h2>
    <p className="text-sm text-muted-foreground mt-2">Apakah Anda ingin melanjutkan?</p>
  </div>
</div>

---

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.dialog-missing-aria intentional exception -->

// charites:ignore a11y.dialog-missing-aria intentional exception

---

7. Configuration Reference (charites.yaml)

rules:
  a11y.dialog-missing-aria:
    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.