Gov a11y enforcer

gov-a11y-enforcer

Governance skill for generating accessible civic-portal form components. Enforces WCAG 2.1 Level AA as the hard pass/fail baseline, flags WCAG 2.2 Level AA additions as recommendations, and mandates USWDS design tokens for color-contrast compliance.

---

When to apply this skill

Apply whenever you are asked to produce, edit, or review a form UI component for a government, civic, or public-service context. Typical surfaces include:

• Permit applications (building, business, event, land-use)
• Benefit intake and eligibility screening
• Procurement bid and vendor registration forms
• License applications and renewals
• Public records / FOIA request forms
• Citizen feedback, complaint, and service-request intake
• Tax filing and fee payment forms
• Any multi-step civic form or complex public data intake

If the user's request is ambiguous (e.g., "build me a form"), ask whether the form is for a public-sector or regulated context before deciding whether these rules apply. Do not silently skip these rules on a civic form just because the user did not say "accessible."

---

Regulatory basis (why these rules exist)

• Section 508 of the Rehabilitation Act (Revised Standards, 2017 refresh) incorporates WCAG 2.0 Level AA by reference for federal agencies and federal contractors.
• DOJ ADA Title II final rule (April 24, 2024, effective June 24, 2024) sets WCAG 2.1 Level AA as the technical standard for state and local government digital content and mobile apps. Compliance dates were extended by the DOJ Interim Final Rule of April 20, 2026: April 26, 2027 for entities with population ≥ 50,000, and April 26, 2028 for smaller entities and special districts.
• 21st Century IDEA requires federal websites to use the U.S. Web Design System (USWDS), which is the anchor for this skill's color-token rules.

Because the ADA Title II standard is 2.1 AA and Section 508 remains at 2.0 AA, this skill enforces 2.1 AA as the hard pass/fail floor (which is a strict superset of 2.0 AA). WCAG 2.2 AA additions are surfaced as recommendations rather than blockers.

---

Framework and output

Output all UI components in React (JSX) using semantic HTML. The accessibility rules defined here — ARIA attributes, keyboard operation, focus management, semantic role selection, contrast tokens, and error-handling patterns — are framework-agnostic and must be applied regardless of the target JavaScript framework. If the user requests Angular, Vue, Svelte, or plain HTML, translate the JSX examples faithfully; do not weaken the rules.

Every code block you produce for a civic form must be followed by an audit checklist in the format defined in references/checklist-template.md. The checklist maps each rule you satisfied to its exact WCAG Success Criterion number. This is the artifact a compliance officer or accessibility auditor will grep against — treat it as non-optional output, not a nice-to-have.

---

Non-negotiable rules (WCAG 2.1 AA hard pass/fail)

These rules MUST be satisfied on every civic form component you generate. If a user request would force you to violate one of these, do not comply — invoke the Anti-Pattern Interception Protocol below.

1. Semantic HTML for interactive elements — SC 4.1.2 Name, Role, Value

Use <button>, <input>, <select>, <textarea>, <a> for their intended purposes. Never generate <div> or <span> with click handlers, role="button", or role="checkbox" when a native element exists. Native elements come with keyboard operation, focus management, screen-reader semantics, and form participation for free — custom implementations reliably miss at least one of these.

2. Programmatic label association — SC 1.3.1 Info and Relationships, SC 3.3.2 Labels or Instructions

Every input has a <label> bound by htmlFor/id. Placeholder text is not a label; it disappears on focus, has insufficient contrast by default, and is invisible to some assistive technologies. Instructions ("Enter your 9-digit permit number") appear before the field, not after it, so screen-reader users hear them before focusing the input.

{/* CORRECT */}
<label htmlFor="permit-number">Permit number</label>
<p id="permit-number-hint">Enter the 9-digit number from your application receipt.</p>
<input
  id="permit-number"
  name="permitNumber"
  type="text"
  inputMode="numeric"
  aria-describedby="permit-number-hint"
  required
/>

3. Field grouping — SC 1.3.1 Info and Relationships

Related inputs (address components, multi-part dates, radio groups, checkbox groups) are wrapped in <fieldset> with a <legend>. The legend gives screen-reader users the group's purpose when they focus any input inside it.

4. Input purpose identification — SC 1.3.5 Identify Input Purpose

Apply the autocomplete attribute to fields collecting personal data: name, given-name, family-name, email, tel, street-address, postal-code, country, bday, organization. This lets browsers autofill from stored user data, which is a cognitive-accessibility accommodation, not just a convenience.

5. Error identification, suggestion, and prevention — SC 3.3.1, SC 3.3.3, SC 3.3.4

• Identify errors in text, not color alone. Wire aria-invalid="true" and aria-describedby pointing to the error message element.
• Suggest the correction, not just "invalid input." "Enter a date on or after today" beats "Invalid date."
• Prevent irreversible submission on legal, financial, or data-consequential forms (permit filings, benefit applications, procurement bids, tax payments). Include a review step showing all entered data before final submit, plus a confirmation action.

6. Focus visibility — SC 2.4.7 Focus Visible

Never emit outline: none, outline: 0, or outline: hidden without an equivalent replacement focus indicator. Use :focus-visible with a visible outline or box-shadow that has non-text contrast of at least 3:1 against adjacent colors.

7. Contrast via USWDS tokens — SC 1.4.3 Contrast (Minimum), SC 1.4.11 Non-text Contrast

Do not emit raw hex, RGB, or named CSS colors on text, borders, focus rings, or form controls. Use USWDS color tokens and apply the magic-number rule: the grade delta between foreground and background must be ≥ 50 for body text (achieves 4.5:1), ≥ 40 for large text (achieves 3:1), and ≥ 50 for form-field borders and focus indicators (achieves the 3:1 non-text minimum with margin).

Full token map and safe pairings in references/uswds-tokens.md.

8. Status messages via live regions — SC 4.1.3 Status Messages

Async validation feedback (e.g., "Permit number verified," "Address not found"), inline success confirmations, and non-blocking error notices must be announced through an aria-live region. Use aria-live="polite" for non-urgent updates, aria-live="assertive" only for blocking errors that require immediate user action.

9. Keyboard operation — SC 2.1.1 Keyboard, SC 2.1.2 No Keyboard Trap

All form functionality is operable via keyboard alone. Every custom interactive control must expose Tab-order navigation, Enter/Space activation for buttons, and appropriate arrow-key patterns for composite widgets (radio groups, tabs, combobox). Never trap focus inside a modal without an Escape handler and a documented exit path.

10. Descriptive headings and labels — SC 2.4.6 Headings and Labels

Section headings and field labels describe purpose or topic. "Applicant information" beats "Section 1." Use a single <h1> per page and step down heading levels without skipping.

---

Recommended rules (WCAG 2.2 AA — flag but do not block)

Add these to the checklist as "Recommended (2.2 AA)" rows. Do not fail generation if the user's spec conflicts, but note the gap.

• SC 2.4.11 Focus Not Obscured (Minimum) — sticky headers/footers must not fully cover the focused field
• SC 2.5.7 Dragging Movements — any drag interaction has a single-pointer alternative (see anti-pattern protocol)
• SC 2.5.8 Target Size (Minimum) — touch targets ≥ 24×24 CSS pixels; prefer 44×44 for primary actions on mobile
• SC 3.2.6 Consistent Help — help link/button appears in the same relative position across steps
• SC 3.3.7 Redundant Entry — do not re-ask for data already entered earlier in the session; prefill or reference
• SC 3.3.8 Accessible Authentication (Minimum) — no cognitive-function-test CAPTCHAs

---

Anti-Pattern Interception Protocol

When the user requests a form interaction that can be achieved using native HTML but they've specified a non-semantic custom implementation, you MUST intercept the request rather than generate the requested code as-asked or generate it with a warning appended.

Silently generating the code and warning at the bottom does not work — developers ship the code and ignore the warning. Refusing outright also does not work — developers uninstall the skill. The correct behavior is intercept, cite, reroute.

Protocol

Execute these three steps, in order:

1. Halt and Flag. Immediately state that the requested pattern violates Section 508 / WCAG standards. Use a blockquote for visibility:

   Compliance Intercept: The requested pattern introduces high-risk accessibility regressions.

2. Cite the SC. Name the exact WCAG Success Criterion the requested pattern would violate (e.g., "SC 2.1.1 Keyboard," "SC 4.1.2 Name, Role, Value"). One line per SC, no vague hand-waving.

3. Provide the Native Alternative. Generate the code using semantic, accessible HTML that delivers the same functional outcome. Follow it with the standard audit checklist.

The catalog of specific anti-patterns and their native rewrites is in references/anti-patterns.md. Load that file the first time you hit an interception in a session.

Rule text (for consistent behavior)

ANTI-PATTERN INTERCEPTION RULE: If the user requests a custom UI component for a form interaction that can be achieved using native HTML elements (e.g., requesting a div-based checkbox, a custom drag-and-drop file upload, a non-semantic dropdown, or a drag-to-reorder without keyboard support), you MUST refuse to generate the custom component. Instead, you will output:

1. A blockquote stating: "Compliance Intercept: The requested pattern introduces high-risk accessibility regressions."
2. The exact WCAG Success Criteria the custom component typically violates.
3. The code for the native, accessible HTML alternative (e.g., <input type="checkbox">, <input type="file">, or native <select>).

---

Required output format

Every code generation response for a civic form ends with the audit checklist. Format:

### Accessibility audit checklist

| Rule | SC | Standard | How satisfied | How to verify |
|------|----|----|---------------|--------|
| Programmatic label | 1.3.1 | 2.1 AA | `<label htmlFor="permit-address">` bound to `<input id="permit-address">` | Inspect DOM / axe-core |
| Non-text contrast | 1.4.11 | 2.1 AA | Field border `gray-60` on `gray-0` background (Δ60 ≥ 50) | USWDS token map |
| Keyboard operation | 2.1.1 | 2.1 AA | Native `<button>` and `<input>` — no custom handlers | Tab through form |
| Error identification | 3.3.1 | 2.1 AA | `aria-invalid="true"` + `aria-describedby` to error `<div>` | Screen reader test |
| Target size | 2.5.8 | 2.2 AA (rec) | Buttons 44×44 CSS px | Chrome DevTools |

Every row includes the SC number. This is what a compliance officer or auditor will search for. See references/checklist-template.md for the full template and a filled example.

---

What this skill does not do

Set expectations honestly — this is a governance skill for generation, not a replacement for downstream tooling:

• It does not replace automated testing (axe-core, pa11y, Lighthouse). Ship those in CI. This skill reduces the rate at which they find defects.
• It does not replace manual keyboard testing or screen-reader QA. Some SC (e.g., 2.4.3 Focus Order, 1.3.2 Meaningful Sequence) require human judgment on the rendered artifact.
• It does not compute exact contrast ratios. It prevents the class of errors by mandating tokens whose ratios are pre-verified.
• It does not audit existing production code — it prevents new violations at generation time.

State this framing when relevant so users do not overtrust the checklist.

---

Reference files

Load only the file you need for the current step. Do not load all four preemptively.

• references/wcag-form-sc-map.md — Full SC lookup: rule → SC number → why it matters → WCAG.org link. Load when you need to look up an SC you have not memorized.
• references/uswds-tokens.md — USWDS color token cheatsheet, magic-number table, and safe token pairings. Load whenever you emit any color on text, borders, or focus indicators.
• references/anti-patterns.md — Intercept and Reroute catalog: common non-semantic patterns and their native rewrites. Load the first time you hit an interception case in a session.
• references/checklist-template.md — Full audit checklist template with a filled example. Load if you are unsure how to format the audit row for a specific rule.