Accessibility support

Current status: Bio Tooltips is designed to support WCAG 2.2 Level AA conforming implementations when used according to this guidance. Representative components and interaction states are covered by automated accessibility scans, browser-based keyboard tests, and browser-based layout and user-preference checks. This testing is not a full WCAG conformance evaluation, and the project does not currently claim that the package, documentation site, or a host application conforms to WCAG.

Scope

The current assessment covers the library-owned core, gene, and chemical tooltip behavior exercised by the repository's local test fixtures. It includes the shipped themes, common trigger elements, nested and pinned panels, asynchronous states, and selected responsive and user-preference conditions.

It does not cover the surrounding markup, content, styles, or configuration supplied by a host application. Optional third-party visualizations, custom renderers, and combinations of browsers and assistive technologies not listed in the verification record are also outside the assessment. A host application needs its own complete evaluation before making a WCAG conformance claim.

The documentation website is assessed separately (Scope B) in the repository's accessibility evaluation record; the two scopes are not conflated, and neither scope proves the other.

Using the library accessibly

Bio Tooltips preserves the semantics of the host element and adds keyboard and focus behavior when a tooltip is initialized. Prefer a native <button type="button"> for an action that opens a tooltip, and a native <a href="…"> when the trigger is also navigation. A <span> trigger is supported and is enhanced with an appropriate button role and keyboard behavior by the library.

Keep the trigger text meaningful, provide aria-label or visible context when a symbol is ambiguous, and avoid placing interactive controls inside a tooltip that is presented only as a description. Interactive content belongs in a dialog or popover pattern with a clear close action. Host styles must preserve visible focus indicators and sufficient contrast; avoid clipping the tooltip or setting overflow: hidden on an ancestor that contains it. Gene details also expose a text alternative when optional visual rendering is unavailable.

Keyboard users open span and button triggers with Enter or Space; a link trigger retains navigation on Enter and opens its dialog with ArrowDown. Once open, Tab reaches the pin and close controls, and Shift+Tab from the dialog entry returns to the trigger. Forward Tab from the last panel control resumes after its trigger in page order. Escape closes the deepest relevant panel, including a pinned panel; focus returns to its trigger only when focus was inside the dismissed panel. Hover and focus previews do not move focus, and these non-modal dialogs do not trap focus. Collapsed sections become hidden and inert while collapsed so their controls are not reachable by Tab. Copy and summary controls expose their result through a status message.

Top-level drawers replace the visible × control with a native button labelled Close and a 48px touch target. It closes on tap or can be dragged downward to dismiss; dragging is optional. Wide-screen popovers retain the existing × close button. Reduced-motion settings remove the handle's snap and drawer transition animations.

The shipped styles include light and dark themes and respond to reduced-motion and forced-colors preferences. Applications should still test their surrounding layout at 320 CSS pixels, with text spacing overrides, at 200% text resizing, and at 400% desktop browser zoom. A narrower viewport is not a substitute for actual browser zoom.

The automated checks cover representative gene and chemical fixtures with WCAG 2.0/2.1/2.2 A and AA axe rules, keyboard behavior, lifecycle cleanup, and browser console errors. They do not establish full WCAG conformance or replace manual testing. Before release, manually verify the experience with NVDA and VoiceOver, keyboard-only navigation in supported browsers, actual 200% text resizing and 400% desktop browser zoom, high contrast/forced colors, and the application’s own host styles. The automated viewport and media emulation checks are programmatic simulations; they do not establish actual browser zoom behavior.

References: Web Content Accessibility Guidelines (WCAG) 2.2 and the ARIA Authoring Practices Guide tooltip pattern.

Running the checks

Run npm ci, npx playwright install chromium, then npm run test:a11y. The script builds the package and uses local gene/chemical fixtures with development-only axe-core. No live provider requests are required. Unit coverage runs separately with npm test -- --run.

The visual browser checks assert panel and page reflow at 320 CSS pixels, then apply WCAG text-spacing values and double computed text sizes. They also check focus indicators, close-button target sizes, reduced-motion transitions, and forced-colors panel boundaries. These checks cover representative fixtures; inspect actual browser zoom, content overlap, all supported operating systems, and your application’s styles manually.

The gene-model header includes a compact Show exon data button whose controlled region contains the selected transcript identity, strand, and exon numbers and coordinates. Its label changes to Hide exon data when open, it exposes its state with aria-expanded, the region updates with the transcript selector, and the data opens automatically if D3 cannot render. Individual SVG exons retain pointer previews without adding hundreds of keyboard stops.

Short descriptive previews use role="tooltip" and aria-describedby; interactive parent and searchable child panels use named role="dialog" containers. Host applications should supply meaningful trigger text, preserve native link/button semantics, and avoid overriding the library’s focus and hidden-state styles. Optional third-party visualizations and custom renderers need their own accessibility assessment.

WCAG 2.2 Level AA evaluation

A full WCAG 2.2 A/AA evaluation matrix for both scopes (library behavior and documentation website), with per-criterion evidence, tooling limits, the defects found and fixed (including six documentation-site contrast defects and a non-keyboard-focusable scrollable ideogram region), the five WCAG conformance requirements, and the conformance recommendation is recorded in the repository's accessibility evaluation record. The remaining checks that require a human with assistive technology or real OS/browser settings are itemized in the manual accessibility checklist.

Because those manual checks are not yet complete, the project retains the "designed to support" wording above rather than making a formal conformance claim.

Reporting an accessibility barrier

If you encounter an accessibility problem, open a GitHub issue with the package version, browser and operating system, assistive technology if applicable, a minimal example, and the behavior you expected. Please do not include private or sensitive data.

Verification record

Validated 2026-09-18 in headless Chromium 151.0.7922.34 (Playwright 1.52, axe-core 4.13.0 pinned, Node 24.19.0) with local TP53 and aspirin records. The library browser suite exercises span/button/link activation, logical Tab exit, nested search and dismissal, pinning, transcript changes, copy success/failure, delayed responses, request errors, empty results, and cleanup/reinitialization, with axe scans of open gene and chemical panels across the five shipped themes plus nested and pinned states. The visual suite asserts 320 CSS pixel reflow, WCAG text-spacing values, doubled text sizes, reduced-motion transitions, forced-colors panel boundaries, and focus indicators. The unit suite contains 126 passing tests across 31 files. Production, declaration, and documentation builds pass.

The documentation site was scanned with the same axe configuration across all page templates in both themes, the interactive demos in open and closed states, the mobile menu, and 320 CSS pixel reflow. Six contrast defects in the VitePress default theme as shipped (light code-block background, the code language label in both themes, one shiki token color, and the hero brand button) were found and fixed in docs/.vitepress/theme/a11y.css; the post-fix scan is clean. Two best-practice observations remain documented: the VitePress home layout places hero content outside any landmark, and the generated api/modules.html page has no <h1>. The site has no search feature (VitePress local search is not configured). See the repository's accessibility evaluation record for full details.

Development dependency review found zero runtime vulnerabilities and eight existing development-tool findings (three moderate, five high); these predate the axe-core addition. Registry verification checked 498 package signatures and 89 attestations.