# Accessibility Dx > Developer-Surface Accessibility - Skill: `devarispbrown/accessibility-dx` (Agent Skill, multi-file: 12 files) - Install (CLI): `npx skillmds@latest add devarispbrown/accessibility-dx` - Raw SKILL.md: https://api.skillmd.com/api/skills/devarispbrown/accessibility-dx/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: devarispbrown (https://skillmd.com/u/devarispbrown) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/devarispbrown/accessibility-dx --- # Developer-Surface Accessibility ## Mission Every developer surface is an interface that must work without color alone, animation alone, or the mouse alone. Screen readers, keyboard-only navigation, low-vision contrast, and reduced motion are supported paths, not edge cases. Audit and fix accessibility across the surfaces developers touch: terminal and CLI output, consoles and portals, documentation, charts, and error messages. An error that is only red is a defect. A spinner that is only animation is a defect. A chart whose series differ only in color is a defect. Accessibility failures are product failures. Classify them with the suite severity vocabulary and fix them before release, not after. Read `references/standards.md` for the canonical thresholds, severity vocabulary, and release gates. This skill covers the accessibility of developer surfaces. For documentation architecture and content, use the `developer-docs` skill. For doc audits use `developer-docs-auditor`; for whole-product audits use `developer-experience-auditor`. ## Developer-surface accessibility Run the audit as a fixed sequence. Skip steps whose surfaces do not exist; record every skip in the report. ### 1. Inventory the developer surfaces Enumerate every developer-facing surface in the repository: - terminal/CLI output and errors, including build tools, daemons, and scripts - consoles, portals, admin UIs, dashboards, and devtools panels - documentation pages, code blocks, and embedded diagrams - charts and data visualizations - progress indicators, spinners, and status output Record where each surface lives. A missed surface is a missed audit. ### 2. Scan terminal output for color-only signaling Run `scripts/check_cli_colors.py` against the tree as a first-pass signal. Verify, per surface: - colored output always pairs with a text marker such as ERROR, WARN, or SUCCESS - red/green never appears as the only channel distinguishing states - NO_COLOR is honored and explicit color flags exist - spinners have text labels and a final static summary line - nothing essential depends on animation Read `references/terminal-accessibility.md` for the full procedure. The script output is heuristic; confirm every finding in source before reporting. ### 3. Audit console and portal interaction Read `references/console-accessibility.md`. Verify: - every interaction is keyboard-operable with a visible focus and no traps - focus order follows reading order; dialogs trap and restore focus - forms label every control and announce errors with their field - status changes are announced through live regions - contrast meets the thresholds; motion never carries essential meaning ### 4. Audit documentation accessibility Read `references/docs-accessibility.md`. Verify: - one h1 per page, logical heading hierarchy, no skipped levels - meaningful alt text and link text; diagrams have text equivalents - admonitions and syntax highlighting never rely on color alone - tables use real table semantics with headers For documentation architecture and content, hand off to the `developer-docs` skill. ### 5. Audit charts and data visualizations Charts are developer surfaces in dashboards, docs, and reports. Verify: - every chart has a title, axis labels, series labels, and units - series are distinguishable without color (patterns, shapes, position, direct labels) - a data table or text description carries the same information as the chart - marks, labels, and backgrounds meet the contrast thresholds in light and dark themes ### 6. Measure color pairs and contrast Read `references/color-and-contrast.md`. Verify: - every text/background pair meets the ratio thresholds - no state distinction depends on a red/green pair or color alone - ratios are computed, never eyeballed ### 7. Test with a screen reader Read `references/screen-reader-testing.md`. Verify per surface: - errors are announced as text, not silence plus color - spinners and status output are announced sensibly - every console control is named, reachable, and operable by keyboard - a keyboard-only traversal completes the main flows Label every test Observed, CI-observed, or Estimated. ### 8. Render the report Use `assets/accessibility-audit-template.md`. Apply the severity vocabulary from `references/standards.md`: P0/P1 findings are release blockers and force FAIL; P2/P3 form the debt backlog; P4 is polish. Return exactly one verdict: PASS, PASS WITH DEBT, FAIL, or UNVERIFIED. A score never overrides a gate. ## CLI output contract 1. Meaning is never carried by color alone; every colored signal pairs with a text marker (ERROR, WARN, SUCCESS) on the same output. 2. Color only when the stream is a TTY; honor NO_COLOR; provide --color/--no-color flags. 3. Every spinner or progress indicator has a static text label and a final plain-text summary line; nothing essential depends on animation. 4. Errors go to stderr with a severity word, cause, and recovery; exit codes follow the documented table. 5. Piped output loses no meaning: no escape bytes, no animated-only state, no color-only distinction. ## Console and portal contract 1. Full keyboard operability with visible focus, logical order, and no traps. 2. Every control has an accessible name; forms label inputs and announce errors with their field. 3. Text/background contrast meets the thresholds in `references/color-and-contrast.md` in every theme. 4. Motion honors prefers-reduced-motion; no essential information is conveyed by animation. 5. Status changes use live regions; dialogs manage focus; tabular data uses real table semantics. ## Docs and charts contract 1. One h1 per page; heading hierarchy is logical and descriptive. 2. Meaningful link text and alt text; diagrams have text equivalents. 3. Admonitions and syntax highlighting are readable without color. 4. Charts have titles, axis and series labels, units, and a text equivalent; series are distinguishable without color. ## Required output Produce the accessibility audit report using `assets/accessibility-audit-template.md`. The report must contain: 1. **Verdict** — exactly one of PASS / PASS WITH DEBT / FAIL / UNVERIFIED 2. **Evidence** — repository/revision, environment, checks executed and not executed, with evidence labels 3. **Surface inventory** — every surface found and its status 4. **Findings table** — severity, surface, finding, evidence, acceptance test 5. **Terminal color scan** — the `scripts/check_cli_colors.py` result and per-finding confirmation 6. **Screen-reader test log** — reader, surface, what was announced, defects 7. **Prioritized backlog** — ordered fixes with acceptance tests ## Definition of done An accessibility audit is done when: - every surface in the inventory is audited or explicitly skipped in the report - `scripts/check_cli_colors.py` findings are confirmed, and each defect has a fix or a severity - no meaning anywhere depends on color alone, animation alone, or the mouse alone - contrast ratios are computed for the surfaces that exist - a screen reader test is executed, or marked not executed with an evidence label - every finding carries a severity from the canonical vocabulary and an acceptance test - the verdict is exactly one of PASS / PASS WITH DEBT / FAIL / UNVERIFIED - the report is rendered from `assets/accessibility-audit-template.md` Fix P0/P1 findings before release; report P2/P3 as debt. Hand off documentation architecture and content to the `developer-docs` skill, doc audits to `developer-docs-auditor`, and whole-product audits to `developer-experience-auditor`.