A11YSmith

Report Schema

Output Formats

A11YSmith generates reports in three formats:

  1. JSON — Canonical, schema-validated output. Used for machine consumption and dashboard import.
  2. Markdown — Human-readable report following the consultant writing style.
  3. HTML — Self-contained static report with accessible markup.

JSON Report Structure

{
  "audit_run": {
    /* AuditRun schema */
  },
  "findings": [
    /* Finding schema[] */
  ],
  "generated_at": "2026-03-16T12:00:00Z",
  "generator_version": "0.1.0"
}

Finding Sections (Human-Readable Reports)

Per the consultant writing style, every finding includes:

  1. Verdict
  2. Severity
  3. User Impact (who, task impact, AT/interaction mode)
  4. Evidence (environment, steps, actual/expected, observed output)
  5. Why It Matters
  6. Recommendation (direct fix or options with tradeoffs)
  7. Validation Steps (specific AT and browser/device combinations)
  8. Standards Mapping (Target standard, WCAG SC, precedence note)
  9. Confidence and Caveats

Schema Validation

All generated JSON is validated against Zod schemas at generation time. The generateJsonReport() function throws if any finding or audit_run fails validation.