a11y.form label composite control

a11y.form-label-composite-control

Rule ID: a11y.form-label-composite-control Severity: WARN Category: a11y Target Standards: W3C Web Content Accessibility Guidelines (WCAG) 2.2 SC 1.3.1 (Info and Relationships), W3C WAI-ARIA 1.2 Grouping Controls (

/ pattern), HTML Living Standard Section 4.10.16 (The fieldset element)

---

1. Overview & Core Invariant

Warns when is directly bound to a composite multi-field control causing screen reader ambiguity

Core Invariant:

"A single must bind to exactly one discrete interactive input; composite multi-field components must use

with ."

---

2. Technical Grounding & Engine Realities

In Shadcn UI and Radix-based form architectures, generates an HTML linked via htmlFor to the single ID assigned to .

When developers bind a to a composite multi-field component (such as , , or multiple fields within one ):

1. Ambiguous Screen Reader Announcement: The screen reader announces the label only for the first input or fails to associate it properly with subsequent controls.
2. Inability to Navigate: Keyboard users cannot tell which part of the composite input the label describes.
3. Accessibility Violation: WCAG 1.3.1 requires clear programmatic grouping for related multi-field data.

Charites detects composite component naming patterns and multiple inputs under a single .

---

3. Vulnerability & Risk Taxonomy

Risk Vector	Severity	Impact
Screen Reader Control Ambiguity	MEDIUM	Users of screen readers cannot determine which discrete sub-field is labeled.
Form Autofill Fragmentation	LOW	Browser password managers and autofill engines fail to parse multi-part composite inputs.

---

4. Non-Compliant Code Patterns (Bad Examples)

TSX (Single FormLabel bound directly to composite DateRangePicker):

<FormItem>
  <FormLabel>Rentang Tanggal</FormLabel>
  <FormControl>
    <DateRangePicker fromDate={from} toDate={to} />
  </FormControl>
</FormItem>

---

5. Compliant Implementation Patterns (Good Examples)

TSX (Separated into individual FormItem controls or wrapped with fieldset):

<div className="grid grid-cols-1 sm:grid-cols-2 gap-4">
  <FormItem>
    <FormLabel>Tanggal Mulai</FormLabel>
    <FormControl><DatePicker date={from} /></FormControl>
  </FormItem>
  <FormItem>
    <FormLabel>Tanggal Selesai</FormLabel>
    <FormControl><DatePicker date={to} /></FormControl>
  </FormItem>
</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.form-label-composite-control intentional exception -->

// charites:ignore a11y.form-label-composite-control intentional exception

---

7. Configuration Reference (charites.yaml)

rules:
  a11y.form-label-composite-control:
    severity: warn # 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.