svelte-a11y-panel

A configurable, open-source accessibility panel for Svelte 5 apps. Lets users adjust your site for their needs without any server-side setup.

Originally built for Care Culture's public website, then extracted into a standalone package.

What it does

Adds an accessibility widget that lets site visitors adjust your site for their needs:

• Profiles: Epilepsy Safe, Low Vision, Cognitive, ADHD, Blindness
• Readable Experience: font size, line height, letter spacing, readable/dyslexia fonts, text magnifier
• Visual: dark/high contrast, monochrome, saturation, custom colour overrides
• Orientation: reading guide, reading mask, hide images/emoji, stop animations, cursor size, focus/hover highlights
• Cognitive: text-to-speech, voice navigation, keyboard shortcuts, link navigator, virtual keyboard

The panel UI renders in a Shadow DOM — fully isolated from your site's CSS.

Note: The accessibility effects actively reach into your page (injecting CSS, appending overlays, muting audio). That is the point. See Host page effects below.

Documentation

Full docs and live demo: https://a11y.clmartin.dev

Requirements

• Svelte 5 (runes)
• SvelteKit 2+ (or a Vite project)
• Node 18+

Installation

pnpm add svelte-a11y-panel
# or
npm install svelte-a11y-panel

Quick start

Add PanelMount and AccessibilityButton to your root layout:

<!-- src/routes/+layout.svelte -->
<script>
  import { PanelMount, AccessibilityButton } from 'svelte-a11y-panel';
  let { children } = $props();
</script>

<PanelMount config={{
  accentColor: '#2563eb',
  statement: {
    orgName: 'Your Organisation',
    email: '[email protected]',
    assessmentDate: 'January 2026',
  }
}} />

<AccessibilityButton accentColor="#2563eb" />

{@render children()}

PanelMount renders nothing visible — it sets up the panel in a Shadow DOM. AccessibilityButton is a fixed-position floating button (bottom-right) that opens and closes the panel.

Setup CLI (optional)

Prefer a guided setup? Run from the root of your SvelteKit project:

npx svelte-a11y-panel init

The CLI detects your layout file and adds a configured PanelMount with your brand colour, org name, and contact email pre-filled.

Configuration

Pass a config object to PanelMount:

<PanelMount config={myConfig} />

Option	Type	Default	Description
accentColor	string	'#2563eb'	Colour for buttons, toggles, focus rings, and host-page overlays
uiFontFamily	string	'system-ui, sans-serif'	Font for the panel UI and all overlays
dyslexiaFontUrl	string	jsDelivr CDN	WOFF2 URL for the OpenDyslexic font
storageKey	string	'a11y-panel-state'	localStorage key for persisted state
positionKey	string	'a11y-panel-pos'	sessionStorage key for dragged panel position
statement.orgName	string	''	Organisation name in accessibility statement
statement.email	string	''	Contact email in accessibility statement
statement.conformanceStatus	string	WCAG 2.1 AA string	Conformance statement text
statement.limitations	string[]	[]	Known limitations to list
statement.assessmentDate	string	''	Date string for the statement

Security note

Config values (accentColor, dyslexiaFontUrl) are interpolated into a CSS stylesheet injected into the Shadow DOM. Do not set these from untrusted user input or unvalidated CMS fields. Treat config as a build-time constant, not a runtime user setting.

Theming the panel

The panel renders inside a Shadow DOM — your page's CSS (including custom properties on :root) cannot reach it. Theming is done through config:

• Accent colour (buttons, toggles, focus rings, overlays) — accentColor
• Font (panel UI and all overlays) — uiFontFamily

<PanelMount config={{
  accentColor: '#7c3aed',
  uiFontFamily: "'Inter', system-ui, sans-serif",
}} />

AccessibilityButton props

Prop	Type	Default	Description
accentColor	string	'#2563eb'	Background colour of the button
label	string	'Accessibility options'	Accessible label for screen readers
class	string	''	Additional CSS classes

Custom trigger button

AccessibilityButton is intentionally simple. Build your own trigger using the state functions directly:

<script>
  import { openPanel, closePanel, getOpen } from 'svelte-a11y-panel';
  let buttonEl = $state(null);
</script>

<button
  bind:this={buttonEl}
  onclick={() => getOpen() ? closePanel() : openPanel(buttonEl)}
  aria-expanded={getOpen()}
  aria-controls="a11y-panel"
  aria-label="Accessibility options"
>
  Accessibility settings
</button>

openPanel(element) takes your trigger element so the panel can return focus to it when closed. getOpen() is a reactive getter backed by Svelte 5 $state.

Host page effects

When users enable features, the panel actively modifies your page:

Feature	What it does to your page
Font size / contrast / filters	Injects <style id="a11y-panel-host-styles"> into <head>
Reading guide / mask / magnifier	Appends overlay <div>s to <body>
Mute sounds	Sets .muted = true on all <audio> and <video> elements
Hide emoji	Wraps emoji text nodes in <span data-a11y-panel-emoji>
Link navigator	Appends a <dialog> to <body>
Virtual keyboard	Appends a keyboard <div> to <body>, dispatches synthetic KeyboardEvents
Text-to-speech	Attaches a click listener to document, uses window.speechSynthesis
Voice navigation	Uses window.SpeechRecognition, calls window.scrollBy / history
Navigation keys	Attaches a keydown listener to document
State persistence	Saves to localStorage under config.storageKey

All effects are fully reversed when the user turns them off or the panel is unmounted.

Browser support

Feature	Support
Panel UI	All modern browsers
Text-to-speech	All modern browsers
Voice navigation	Chrome / Edge only (Web Speech Recognition API)
Virtual keyboard	All modern browsers

Custom accessibility statement

Pass a customStatement snippet to PanelMount to replace the default statement content entirely:

<PanelMount config={myConfig}>
  {#snippet customStatement()}
    <h2>Our Accessibility Statement</h2>
    <p>We are committed to making our site accessible to everyone.</p>
    <p>Contact us at <a href="mailto:[email protected]">[email protected]</a>.</p>
  {/snippet}
</PanelMount>

When customStatement is provided, the default statement is replaced entirely by your content. The back button and statement header are still rendered.

Content Security Policy (CSP)

If your site uses a strict CSP, you will need to allow the following:

Feature	CSP directive required
Host-page style injection	style-src 'unsafe-inline' (or a nonce)
OpenDyslexic font (if using dyslexia mode)	font-src cdn.jsdelivr.net
Self-hosted font	font-src 'self' (set dyslexiaFontUrl to your own URL)

If 'unsafe-inline' is blocked, the panel UI still works — only host-page style overrides (font changes, contrast filters, cursor overrides) will be silent no-ops.

Privacy and permissions

Voice navigation uses the browser's SpeechRecognition API, which requires microphone permission. The browser will prompt the user the first time they enable voice navigation. Speech is processed entirely in the browser — no audio data is sent to any server.

Text-to-speech reads aloud the text content of any element the user clicks. On pages with sensitive information, users should be aware that reading aloud may expose content to bystanders.

localStorage stores the user's accessibility preferences (toggle states, font size, colours). No personally identifiable information is stored.

CDN font: When dyslexia mode is enabled, a request is made to cdn.jsdelivr.net. To avoid this, provide your own font URL via dyslexiaFontUrl.

License

MIT — see LICENSE