# Accessibility review

**Review date:** October 26, 2026  
**Target:** WCAG 2.2, Levels A and AA  
**Scope:** Dashboard (`index.html`), case study (`case-study.html`), theme editor (`theme.html`), and all ten species dialogs.  
**Assessment:** The checks below describe the reviewed design before the latest hero image change. The hero now uses the replacement image with a full-area 44% black overlay and a transparent `.hero-text` wrapper with 16px padding. The global muted text color is #F5F5F5. Hero contrast needs rechecking for this updated image treatment. This is a scoped engineering review, not an independent certification or an unrestricted claim of AA conformance.

## Method

- axe-core 4.14.0 in the local Chromium preview, using `wcag2a`, `wcag2aa`, `wcag21a`, `wcag21aa`, `wcag22aa`, and best-practice rules. No accessibility rules were disabled.
- Default desktop layout at a 1280-pixel browser viewport; every species dialog was opened and scanned.
- All three pages at a 320-pixel browser viewport, with **both doubled computed text sizes and WCAG text-spacing overrides**: line height 1.5, letter spacing 0.12em, word spacing 0.16em, and paragraph spacing 2em. This text-size stress test is separate from testing actual browser zoom in other browsers.
- Keyboard and accessibility-tree inspection of skip navigation, search, tables, modal opening/closing, focus restoration, and field errors.
- Relative-luminance calculations for text, control boundaries, status symbols, and cases axe cannot determine automatically.
- Regression checks for contrast thresholds, valid/invalid saved palettes, malformed settings, and unavailable browser storage, included in `npm test`.

## Results

| Surface / state | Automated violations | Additional verification |
|---|---:|---|
| Dashboard, default desktop | 0 | 758 records loaded; 54 rules passed after the illustrative hero image was added |
| Case study, default desktop | 0 | 51 rules passed |
| Theme editor, default desktop | 0 | 44 rules passed; no rules marked incomplete |
| All 10 species dialogs, desktop | 0 each | 22 rules passed for Aasimar, 23 for each matched species |
| All 3 pages, narrow viewport + doubled text + spacing | 0 each | Page content fits the viewport; tables scroll within their own regions |
| Matched-species dialog, narrow viewport + doubled text + spacing | 0 | Content scrolls; the source link remains reachable by Tab and visible; the close control remains available |

The embedded audit frame has a 305-pixel layout viewport at the 320-pixel browser setting because of the outer scrollbar. The page's usable content width was approximately 289 pixels after the inner scrollbar. The tested pages did not require horizontal page scrolling. Data tables retain local horizontal scrolling, as allowed for content requiring a two-dimensional layout by SC 1.4.10.

### Keyboard and semantics

- Skip links move focus to each page's main landmark.
- Search results and pagination expose polite, atomic status messages. Actual spoken announcements still need confirmation with a screen reader.
- Data tables have captions and column/row header associations. Scrollable regions have accessible names and keyboard focus.
- Arrow Right scrolled the matrix region (40 pixels observed) without moving the page horizontally.
- Matrix cells include visible status text and an explanatory text alternative. Meaning no longer depends on color, icon fonts, or a mouse-only title tooltip.
- Dialogs have a name and description, open on their close button, and use native modal behavior. Tab reaches the source link; Escape dismisses the dialog and restores focus to its species trigger. Browser chrome remains reachable through normal browser navigation.
- Each theme picker and hex field has its own contextual accessible name. Invalid hex input exposes `aria-invalid` and an associated correction message. Saving an insufficient-contrast palette is blocked; focus moves to the validation heading and the active palette remains unchanged.

## Corrections made

| Issue | Correction | Relevant criteria |
|---|---|---|
| Missing bypass links and inconsistent focus visibility | Added skip links, main focus targets, and a high-contrast two-color focus ring | 2.4.1, 2.4.7 |
| Sticky headers/save bar could obscure focused controls after text enlargement | Made these elements flow with the page; kept mobile navigation available | 1.4.4, 2.4.11 |
| Low-contrast placeholder and control borders | Placeholder follows the validated muted color; control borders use validated foreground colors | 1.4.3, 1.4.11 |
| Dashboard image could weaken contrast | The current image has a full-area 44% black overlay. Contrast of this revised treatment remains to be checked. | 1.4.3 |
| Icon/hover-only matrix meanings | Added visible statuses, text alternatives, scoped headers, captions, and keyboard-scrollable regions | 1.1.1, 1.3.1, 1.4.1, 2.1.1 |
| Icon-font ligatures could be read as words or fail to load | Used system-font symbols and marked redundant symbols as decorative | 1.1.1, 4.1.2 |
| Hidden table descriptions could escape their scroll containers | Established positioned containing blocks for scroll regions | 1.4.10 |
| Cards and headings overflowed with enlarged/spaced text | Allowed wrapping and shrinking; removed restrictive input heights; disabled sticky table columns on narrow screens | 1.4.4, 1.4.10, 1.4.12 |
| Dialog content could be clipped | Enabled scrolling, reserved room for a visible Close control, and described the dialog | 1.4.4, 2.1.1, 2.4.11, 4.1.2 |
| Theme fields shared ambiguous labels; errors were not explicit | Added separate names, associated errors, persistent status feedback, and a reset action | 2.5.3, 3.3.1, 3.3.2, 3.3.3, 4.1.3 |
| A saved palette could defeat contrast requirements | Validate actual text/background pairs at 4.5:1 and functional symbols/bars at 3:1 before applying; reject unsafe legacy settings | 1.4.3, 1.4.11 |

## Contrast cases reviewed manually

axe flags some gradients, decorative symbols, and scrolled dialog text as **incomplete**, rather than pass/fail. These cases were reviewed instead of suppressing the rules:

| Case | Measured ratio | Interpretation |
|---|---:|---|
| Case study muted text against brightest hero gradient endpoint | 5.46:1 | Exceeds 4.5:1 |
| Case study primary text against that endpoint | 8.91:1 | Exceeds 4.5:1 |
| Case study accent against that endpoint | 7.60:1 | Exceeds 4.5:1 |
| Case study control boundary against page background | 6.43:1 | Exceeds 3:1 |
| Matrix no-match symbol against default surface | 3.66:1 | Exceeds 3:1; an explicit text status also carries the meaning |
| Dashboard search placeholder against its default surface | 6.03:1 | Exceeds 4.5:1 |

The hero illustration is an absolutely positioned background layer with the accessible description “illustrative background”; it represents no dataset or result. It does not intercept pointer events, and it is hidden for forced-colors mode and printing. The replacement image now has a full-area 44% black overlay; its text wrapper has a transparent background and 16px padding. The earlier image's contrast calculation and zero-violation result do not establish contrast for this version. Saved palette validation covers the listed solid surfaces, not image pixels; recheck contrast for this revised treatment.

Decorative arrows, the scope symbol, and modal artwork are hidden from assistive technology and do not carry unique information. Dialog text retains validated foreground/background pairs when scrolling; clipping of off-screen text in a scroll container is not treated as lost content when keyboard navigation can reveal it. Native color pickers and scrollbars also depend on the browser/OS rendering.

## Remaining validation before a full conformance claim

This review does **not** establish every WCAG success criterion across all browsers and assistive technologies. Complete these human checks before advertising the whole site as AA compliant:

1. Run the complete tasks with a real screen reader, such as NVDA with Firefox/Chrome or VoiceOver with Safari. Confirm reading order, table header announcements, live results, field errors, and dialog focus/announcements.
2. Repeat keyboard, actual browser zoom at 200% and 400%, and reflow checks in the intended browser matrix, including Safari and Firefox. The tests here used Chromium and a programmatic text-size stress test.
3. Check OS high-contrast/forced-colors mode and reduced-motion preferences in an actual environment. Supporting styles were added/reviewed; those OS modes were not exercised during this session.
4. Recheck after changing content, controls, styles, dependencies, or supported browsers. Theme contrast guards cover the specified color pairs; they do not replace an accessibility evaluation of the full interface.

External websites and the source PDF's internal tagging/table structure are outside the scope of this review. The bundled SRD's reader controls and extracted-text alternative are covered by the additional checks below. No audio/video player, authentication, checkout, or timed interaction is currently part of these pages.

## SRD reference reader addition

The dashboard now opens cited pages in a native modal side panel: two-thirds of the desktop viewport and full width at 800px and below. Underlined, accent-colored evidence links include a decorative arrow and announce a dialog. Their real PDF URLs retain page fragments for modified-click and separate-reader use. Only records with a verified page have these links.

Browser checks confirmed:

- Barbarian opens rendered page 28, Bard appears after navigating to page 31, and the Human species reference opens page 86. A renamed spell opens its canonical Arcane Hand source page.
- All 599 positive records have valid page references into the checksum-verified, 364-page SRD PDF.
- Previous/next navigation, direct page entry, zoom, rapid page changes, and first/last-page boundaries work.
- Enter activates a reference; the reader focuses Close SRD. Escape closes it and returns focus to the initiating link. Opening from a species dialog preserves that dialog and returns focus to its source link.
- The desktop panel uses two-thirds of the usable layout width. On small screens it fills the usable width, accounting for scrollbar space so the left edge and controls are not clipped.
- The rendered-page reader returned zero axe violations. The enlarged-text/increased-spacing mobile test in text mode also returned zero violations; panel and text-region scroll widths matched their client widths, with no horizontal UI overflow.

The reader provides selectable PDF text and a separate, wrapping “Read page as text” view. Extraction may reorder columns or tables, so the original PDF remains one click away. Native dialog behavior, labels, status announcements, and the text alternative do not establish the original PDF as fully accessible. Real screen-reader and cross-browser validation remains necessary. axe marks some transparent PDF text/image contrast checks incomplete; those are not presented as automatic passes or suppressed.

## Repeating the checks

1. Run `npm install`, `npm test`, and `npm run serve`.
2. Open `/scripts/a11y-audit.html` on the local server. This is a development tool, not a public dashboard feature; axe is a development dependency.
3. Select each page, interact with its controls/dialogs, and run the audit again. Use the spacing and text-size options and a narrow browser viewport.
4. Review **both violations and incomplete results**, then repeat the keyboard and assistive-technology tasks above. An automated zero is not a conformance certificate.

Reference: [W3C's WCAG 2.2 quick reference](https://www.w3.org/WAI/WCAG22/quickref/).
