Report Formats

A11YSmith generates reports in four formats. Choose the format that best fits your workflow, or use --format all to generate all formats at once.

JSON Format

The JSON format is the default output. It produces a machine-readable document suitable for CI pipelines, dashboards, and programmatic analysis.

Schema Structure

• meta -- Audit metadata (timestamp, tool version, target URL or directory)
• summary -- Counts by severity (total, highest, high, medium, low)
• verdict -- Overall pass/fail/review-needed result
• findings[] -- Array of individual findings
• findings[].rule_id -- The rule that triggered the finding (e.g. web-images-alt-text)
• findings[].severity -- One of: highest, high, medium, low
• findings[].confidence -- Detection confidence: high, medium, low
• findings[].wcag_sc_ids -- WCAG 2.2 success criterion references (array)
• findings[].title -- Short title for the finding
• findings[].summary -- Human-readable description of the issue
• findings[].suggested_fix -- Recommended remediation

Markdown Format

The Markdown format produces a human-readable document with sections for the summary, a severity breakdown table, and detailed findings. It is suitable for pull request comments and documentation.

Sections

• Title and metadata
• Verdict (pass/fail/review-needed)
• Summary table with severity counts
• Findings grouped by severity, each with title, WCAG mapping, summary, and suggested fix

HTML Format

The HTML format produces a self-contained, styled report designed for sharing and review in a browser.

Features

• Dark mode support with a theme toggle
• Table of contents with anchor links
• Print-optimized styles
• Severity badges with color coding and icons
• Responsive layout for mobile and desktop
• Manual review checklist section

CSV Format

CSV export is provided by the agent ecosystem (@a11ysmith/agents) rather than the core reporter. Agent-layer CSV reporters produce spreadsheet-compatible files with one row per finding, useful for filtering, sorting, and sharing with non-technical stakeholders.

Columns

• Rule ID, Severity, WCAG SC, Location, Description, Help URL
• Help links point to Deque University (web), Microsoft (Office), or Adobe (PDF) remediation guides

Note: The core CLI --format flag supports json, markdown, html, and all. CSV output is available when using agent-generated reports.

How to Choose a Format