Libration Accessibility

The handbook for the accessibility plugin: from installation and widget customization to audit reports, the accessibility statement and AI tools. All settings live in WordPress under Settings → Accessibility.

Installation

1. Upload the plugin ZIP under Plugins → Add New → Upload Plugin — or copy the libration-accessibility folder to /wp-content/plugins/.
2. Activate the plugin in the plugin list. You'll find a direct Settings link right there.
3. Done — the assistive widget appears in the bottom-right corner of your site immediately. All core fixes (skip links, focus indicator, ARIA landmarks) are active out of the box.

Activate your license Pro

You'll find your license key in your order e-mail and in your account.

1. Open Settings → Accessibility → License.
2. Enter the key (format LIB-XXXX-XXXX-XXXX) and click Activate.
3. Your plan (Pro, Pro AI or Agency) is displayed and all included features unlock — one key for everything, including the AI features.

Agency licenses can be activated on up to 25 websites; the License tab and your account show which sites are in use. “Detach license from this website” frees up a seat — handy when moving client projects.

Widget: visitor features

The widget offers visitors ten display modes and four sliders — all preferences are stored in the visitor's browser for 30 days (no tracking, nothing sent to any server):

In the Widget tab you can disable feature groups individually (e.g. grayscale, contrast modes, font sliders, link underlining) to keep the panel lean.

Floating button

Everything lives under Widget → Floating button:

You can also disable the button entirely and place the panel yourself — see Embedding.

Appearance & theme

Design coupling via CSS variables

For developers: instead of fixed colors you can hook the widget into your theme's CSS custom properties. It then follows every design change automatically — dark mode included.

Accent color

In the accent color field, simply enter the variable instead of a hex value:

var(--primary)   or short:   --primary

Panel background and text color

Set the panel theme to Custom variables and enter the variable names your theme defines, e.g.:

:root { --site-bg: #ffffff; --site-text: #1d1d1f; }
@media (prefers-color-scheme: dark) {
  :root { --site-bg: #1c1b22; --site-text: #f4f4f5; }
}

The widget adopts background: var(--site-bg) and color: var(--site-text) and derives all secondary colors (tile backgrounds, dividers, borders) automatically via color-mix(). If your site switches to dark mode via media query or class, the widget follows without any extra configuration.

Gutenberg block

Search the block editor for “Accessibility panel” (Widgets category). The block renders the same panel as the floating button — ideal for footers, popups or a dedicated accessibility page. Title, title visibility and reset button are configured in the block sidebar.

Shortcode

The panel anywhere you like — including theme files via do_shortcode():

[libration_accessibility]

[libration_accessibility title="Need help?" show_title="1" show_reset="0"]

Elementor

If Elementor is active, the widget “Libration Accessibility – Accessibility” automatically appears in the Elementor panel (General category, keywords “accessibility”, “a11y”). Drag & drop it anywhere; title, title visibility and reset button are set directly in the widget options.

WPBakery

If WPBakery (Visual Composer) is active, you'll find the element “Libration Accessibility – Accessibility” in the element catalog under Content — with the same three options as block and shortcode.

Accessibility statement Pro

The Statement tab generates a complete accessibility statement according to the European Accessibility Act as a WordPress page:

1. Enter organisation, contact e-mail and optionally a phone number.
2. Choose the compliance status — partially conformant is the usual, honest state.
3. Add known limitations (e.g. “Older PDF documents are not yet accessible”).
4. Pick a language — all 29 plugin languages are available (German and English editorially maintained, more to follow).
5. Create page — the statement is published as a page; on changes just save again and the page is updated.

External scan

The External scan tab has your site checked from the outside: a real browser on the Libration server opens the selected pages and measures them with axe-core. That finds problems invisible in the admin – and supplies the measurements the contrast assistant builds on.

Which pages get checked

Checking only the home page says little: most problems live in templates that appear on subpages – forms, listings, product views, checkout. The plugin therefore proposes one page per template type and explains why. Remove what does not fit and add your own addresses; addresses on other domains are rejected.

Quota

What counts is pages checked per month, not runs: Free 5, Pro and Pro AI 100, Agency 500. A single run covers at most 25 pages.

History

Every run is recorded and compared with the previous one – what is new, what grew, what is fixed. Without that comparison a repeated scan on an unchanged site would look identical to the old one, and you could not tell whether anything happened at all. Individual runs can be deleted.

Monthly, automatically Pro

The scan can run on its own and mails you – but only when something got worse. The first run and improvements trigger nothing. Accessibility is a state, not a project: a theme update can bring back problems you had fixed.

Contrast assistant

Colour contrast was long considered something a plugin cannot fix – PHP does not know an element's colour, it only emerges in the browser from cascade, inheritance and theme variables. But that is exactly what the external scan measures: axe-core reports foreground and background colour per finding, the achieved and required ratio, font size and weight.

How the suggestion is calculated

From that the plugin computes the smallest change that reaches the required value: only the lightness of the text colour moves, hue and saturation stay. Your brand remains recognisable instead of collapsing into black on white. If the same selector appears on several pages over different backgrounds, a colour is sought that satisfies all of them.

When the text is not the problem

White text on a too-light surface cannot sensibly be darkened – it would turn grey, and grey text on a coloured surface is almost always the wrong answer. In such cases the plugin names the required background colour, again preserving hue, and can apply it. It distinguishes whether only the element is affected (a button, say) or a whole section – the latter asks for explicit confirmation, because it is visible in the layout. The page's base colour (body, html) stays excluded; that belongs in the theme.

Approval and delivery

Nothing happens automatically. Each correction shows before and after as a colour swatch, the old and new contrast ratio, and a link that highlights the spot in the front end. Approved corrections are delivered as CSS in the page head – server-side, no JavaScript – and can be withdrawn at any time. Append ?libration-no-contrast to any address to see the page unchanged for comparison.

A correction list to hand over

Whatever cannot be solved by a rule – surfaces with a gradient or image, spots on several different backgrounds – goes into a downloadable correction list: a printable document with every finding, split into text colours, surfaces and manual work, with links into the front end and a ready CSS block including the reasoning as comments. Meant for handing to an agency or developer.

Audit report & PDF

The Audit tab bundles three tools:

• Overview — statistics on images without alt text, checklist progress and overall status. This is also where you generate the PDF audit report Pro: a print-optimised documentation of your efforts (summary, active measures, full checklist, image list) that you save as PDF via the print dialog.
• Image analysis — a detailed list of all images without alt text, with preview, usage locations and a direct edit link. Free shows the first 50 images; Pro audits without limits and exports to CSV.
• WCAG checklist — 27 criteria based on WCAG 2.1 AA in five categories, with progress bar and save function. Your self-assessment feeds into the PDF report.

AI features Pro AI

The AI features run on Libration servers in Germany and unlock through your license. Quotas per plan: see Plans.

Automatic alt texts

• On upload: the “Generate alt texts on upload” switch — new images are described asynchronously.
• Backfill your library: “Scan media library” counts images without alt text, “Generate now” works through them with a progress bar. Existing alt texts are never touched.
• Language: follows the site language, adjustable in the AI tab.

Easy language & AI read-aloud

Both are part of the Pro AI plan and unlock automatically through your license as soon as they become available for your account — the AI tab shows the status.

Backend options

Plans at a glance

Pricing and checkout: libration.io/#pricing · Management: Account

What Libration Accessibility cannot fix – and how to do it yourself

Libration Accessibility works on the surface of your website: it adds skip links, a visible focus indicator and ARIA landmarks, corrects known HTML patterns on the server, finds images without alt text and gives visitors controls for typography, contrast and read-aloud. That covers a large share of the technical checkpoints — but not all of them. Seven areas stay in your hands because they depend on content, design or third-party code. A tool that intervened automatically there would have to guess, and a wrongly guessed label or a re-sorted page is worse for users than no correction at all.

Each of the following sections gives the reason, a step-by-step procedure and the place in WordPress where you do the work.

1. Colour contrast (WCAG 1.4.3, 1.4.11)

Why a plugin cannot fix this: contrast always comes from two colours — the text and whatever sits behind it. That background is often not a plain colour value but a photo, a gradient, a semi-transparent panel or an overlay. A plugin could only override colours globally; your brand would be gone and new failures would appear elsewhere. The contrast modes in the widget help visitors who switch them on — the default view of your site has to meet the values on its own.

These are the required ratios:

How to do it:

1. Measure: enter foreground and background colour in the WebAIM Contrast Checker. It is quicker right on the page — right-click → Inspect, then click the colour swatch in the Styles pane: Chrome, Edge and Firefox show the contrast ratio in the colour picker, including the line where 4.5:1 is reached.
2. Adjust lightness only, keep the hue: switch the colour to HSL and lower the L value step by step (for dark text on a light background), until the ratio is met. That keeps the brand recognisable — a too-light corporate blue becomes a darker corporate blue, not a different blue.
3. Enter the new colour centrally, not on individual blocks: with block themes under Appearance → Editor → Styles → Colors → Palette, with classic themes under Appearance → Customize → Colors.
4. If you maintain a child theme, the values belong in theme.json under settings.color.palette. They then apply in the editor and on the front end alike and survive parent-theme updates.
5. Do not forget states: hover, focus, disabled buttons, placeholder text in forms, captions. For text on photos, an opaque box or an overlay from roughly 50% opacity helps — a text shadow does not.
6. After the change, re-measure a handful of typical pages: home, one post, a form, the footer. The footer fails most often, because that is where light text sits on a mid-grey background.

Where Libration Accessibility helps: the External scan tab measures contrast on the audited pages, lists the findings with their colour values and highlights them on the front end so you can trace them back to your theme. The fix itself happens in the theme.

2. Captions and audio description (WCAG 1.2.2, 1.2.3)

Why a plugin cannot fix this: captions are content, not technology. They need speaker attribution, a decision about which sounds matter and punctuation that carries the meaning. Automatic captions reliably fail on names, technical terms, accents and numbers, which is why they do not count as captions in an audit. Audio description describes what can be seen but not heard — only someone who knows the point of the video can decide that.

How to do it:

1. On YouTube, use the automatic version as a draft, then correct it: YouTube Studio → Subtitles → language → Duplicate and edit, read through, publish. Afterwards the player shows “English” instead of “English (auto-generated)” — that is how you know the reviewed version is live.
2. On Vimeo: Video → Settings → Captions → upload file, set language and label, enable it.
3. Write your own caption file: a WebVTT file is a plain text file with the extension .vtt. Timestamps, blank line, text — that is all it takes:

   WEBVTT
   
   00:00:00.500 --> 00:00:04.000
   Welcome to our tour.
   
   00:00:04.100 --> 00:00:07.800
   [doorbell]
   Narrator: This is where the entrance begins.

   An SRT file looks almost identical: a sequential number before each timestamp, a comma instead of a full stop for milliseconds, and no WEBVTT on the first line.
4. For self-hosted videos, reference the file inside the video element:

   <video controls src="tour.mp4">
     <track kind="captions" src="tour-en.vtt" srclang="en" label="English" default>
   </video>

   WordPress does not accept .vtt uploads in every configuration. If the media library refuses the file, place it next to the video via FTP and reference it with the full path.
5. Offer a transcript below the video as ordinary text: running text with speaker names and a description of the important visuals. For audio-only recordings that satisfies the requirement completely; for video it covers a good part of the audio description — and it is searchable on top.
6. Real audio description: either link a second version of the video with a descriptive audio track or — much cheaper — narrate the video from the start so that everything important is also said out loud (“in the chart, the value rises from 20 to 60”).

Where in WordPress: captions for embedded videos are maintained at the respective service, not in WordPress. Self-hosted videos go into the media library; add the track element using the Custom HTML block rather than the video block. The transcript fits nicely into the Details block — expandable and usable without JavaScript.

3. Meaningful link text and headings (WCAG 2.4.4, 2.4.6)

Why a plugin cannot fix this: only you know where a link goes and what role a sentence plays in the outline. An automated tool would have to guess the link text from its surroundings, and a wrongly guessed link text is worse than “click here”, because it sends people in the wrong direction. Heading levels are meaning, not font size: automatic renumbering would misrepresent the structure of your page.

How to do it:

1. Link text names the destination, even out of context: “View pricing” instead of “click here”, “Open the contact form” instead of “more”. Screen readers can read out all links on a page as a list — there is no surrounding context there.
2. If the layout demands a short word, add the description on the link: <a href="/pricing/" aria-label="View pricing">More</a>. The visible word must be part of the label, otherwise voice-control users cannot address the link.
3. Same link text, same destination. Three “Read more” links pointing at three different posts are a failure — append the post title.
4. If a link leads to a file, say so in the text: “Price list (PDF, 1.2 MB)”. If it opens a new window, say that too.
5. Exactly one h1 per page, usually the page title. Check whether your theme also outputs the site name as an h1; if so, one of the two has to move to a lower level.
6. No skipping downwards: h1 → h2 → h3. An h4 must not follow an h2. Going back up is fine, so an h3 may well be followed by another h2.
7. Do not use headings for looks. If you just want large, bold text, take a paragraph and set size and weight under Typography. Conversely, a real subheading stays a heading even when it is meant to look small.

Where in WordPress: in the block editor, open the List View at the top left and switch to the Outline tab (document overview). It shows the complete heading structure and flags incorrect levels. You change the level in the heading block's toolbar (H2, H3, …) or in the block sidebar. In Elementor and WPBakery the level sits in the options of the heading widget — the place where it is most often chosen by size alone.

4. Keyboard operability of your own and third-party components (WCAG 2.1.1, 4.1.2)

Why a plugin cannot fix this: a slider, accordion or popup built from div elements with click handlers has no role, no state and no keyboard support. From the outside there is no way to tell what such a div is supposed to be — guessed roles lead to wrong announcements in screen readers, and patching into third-party JavaScript breaks with the next update. So this is where you test yourself and decide what stays.

The test procedure, about ten minutes per page type: click into the browser's address bar and put the mouse aside. From then on use only Tab (forward), Shift+Tab (back), Enter and Space (activate), Escape (close) and the arrow keys (inside menus, tabs, sliders).

This has to work:

• Every control is reachable with Tab — including slider arrows, filters, accordion headers and the close button.
• The focus is visible at all times. If it disappears, someone set outline: none without defining a replacement.
• Enter and Space trigger whatever a mouse click triggers.
• Modals and popups close with Escape, and the focus returns to the element that opened them.
• No focus trap: you can Tab your way out of every region. Conversely, focus must not enter hidden content — off-screen slides and closed menus need display: none, hidden or inert, not just opacity: 0.
• Motion that runs automatically for more than five seconds can be paused (auto-play sliders, tickers).

If a component fails:

1. Check its settings first: many sliders, menus and popups have a “keyboard navigation” or “accessibility” option that is off by default.
2. Report the bug to the vendor, with reproduction steps, browser and expected behaviour. For plugins from wordpress.org, the public support forum is the right place, so other site owners find it.
3. If no fix is in sight, replace the component. A slider with three images works just as well as three images stacked below each other — accessible, faster and maintenance-free.
4. If you build it yourself, use native elements: button for actions, a href for destinations, details and summary for disclosure widgets, label for form fields. They come with focus, keyboard support and role. div plus onclick comes with none of that and needs three extra lines of ARIA.

Where in WordPress: your own markup belongs in the Custom HTML block or in the child theme. Libration Accessibility helps with testing: the Tab order tab numbers all focusable elements on the front end for logged-in administrators. If the numbering jumps, the order is wrong; if an element has no number at all, it cannot be reached by keyboard.

5. Meaningful sequence and focus order (WCAG 1.3.2, 2.4.3)

Why a plugin cannot fix this: screen readers and the keyboard follow the order in the source code, not what the eye sees. Which order was intended is written nowhere in the code — only the person who built the page knows. A tool that re-sorted the source code after the fact would break layout and scripts.

How to do it:

1. Basic rule: the order in the source code follows the visible order. If you want to rearrange content, actually move the blocks instead of shifting them with CSS.
2. These CSS properties reorder things visually without touching the source: order in flex and grid layouts, flex-direction: row-reverse and column-reverse, grid-template-areas, position: absolute and float. The most common case in WordPress is the theme or block option “reverse columns on mobile”.
3. A test without extra tools: switch off the page CSS. In Firefox via View → Page Style → No Style. In Chrome and Edge via the developer tools, Elements tab: select the stylesheet links in the head and hide them with the H key. Then read the page top to bottom — if the order makes sense, you are fine.
4. Second test: Tab through the page and watch the focus. If it jumps from top right to bottom left and back up, the source order differs from the visible one.
5. Do not use positive tabindex values. tabindex="1" and higher tears elements out of the natural order; only 0 and -1 are useful.
6. When something new opens — a modal, an off-canvas menu, a search field — move the focus into it and back again on closing. Without that, the focus sits invisibly behind the overlay and the next Tab press leads nowhere.

Where in WordPress: change the block order in the List View by dragging or with the arrows in the block toolbar; in columns and group blocks, move the columns themselves. Options for reversing on mobile sit in the Customizer or in the settings of the layout block. The Libration Accessibility skip link helps people jump past long navigations — it does not repair a wrong order inside your content.

6. Form error messages (WCAG 3.3.1, 3.3.3)

Why a plugin cannot fix this: markup, validation logic and message texts come from your form plugin, and the errors only appear on submit, often loaded in via Ajax. From the outside there is no way to tell which message belongs to which field — and even if there were: what a message has to say in order to help is an editorial decision.

How to do it:

1. The message names the field and the expectation in words: “Please enter an e-mail address” or “Please enter the date as DD/MM/YYYY” instead of “Invalid input”.
2. Never rely on colour alone. A red border by itself is invisible to many users — it takes text, ideally plus an icon.
3. Tie the message to the field: give the error text an id, point the field's aria-describedby at it and add aria-invalid="true". The screen reader then reads the error out together with the field.
4. Output a summary above the form with in-page links to the affected fields, and move the focus there (container with tabindex="-1", then focus()). Messages that load in later need a region with role="alert" so they are announced.
5. Mark required fields in the label, not with an asterisk alone — and if you use an asterisk, explain it above the form.
6. Use real label elements, not placeholders inside the field. Placeholders vanish as soon as someone types and are a common contrast failure.

Where in WordPress: maintain the texts in your form plugin's settings: Contact Form 7 under Contact form → Messages tab, WPForms under Settings → Validation (global) and per field in the advanced options, Gravity Forms in the Form settings and per field under “Custom validation message”, Fluent Forms under Global settings → Validation messages. The fastest way to see whether your plugin links things up properly: submit the form empty, then Tab into the first field and check whether the error is read out. If the link is missing, that is a case for vendor support — or for switching plugins.

7. PDF and Office documents

Why a plugin cannot fix this: a PDF is a separate file format with its own structure. Libration Accessibility sees the HTML page the download is linked from, not the contents of the file. Scanned documents contain no text at all, only an image — there, nothing short of fresh text recognition or a rebuilt document helps. Legally, linked documents still count as part of your site.

How to do it — in Word:

1. Work with real styles: “Heading 1”, “Heading 2”, “List Paragraph”. Text that is merely bold and larger is not a heading, however much it looks like one.
2. Set alt text: right-click an image → Alt Text. Mark purely decorative images as decorative.
3. Set the document language under Review → Language → Set Proofing Language. Mark quotations in other languages separately.
4. Tables: enable Table Design → Header Row and set Layout → Repeat Header Rows. No merged cells, no tables used for layout.
5. No empty paragraphs for spacing, no manual line breaks inside running text. Fill in title and author in the document properties.
6. Run Review → Check Accessibility and work through the findings.
7. Export: File → Export → Create PDF/XPS → Options, then enable “Document structure tags for accessibility”. Do not go through “Print → PDF” — that discards all tags.

In InDesign: give paragraph styles export tags (Paragraph Style Options → Export Tagging), define the reading order in the Articles panel, maintain alt text via Object → Object Export Options and export as Adobe PDF (Interactive) or choose PDF/UA-1 in the Advanced section. Afterwards, verify in Acrobat Pro via Accessibility → Full Check and correct the tag tree.

The alternative that is almost always better: offer the content as an HTML page as well. A price list, a registration form or a menu as a normal WordPress page is readable on a phone, findable by search and accessible without extra effort. The PDF stays around for printing.

Where in WordPress: documents live in the Media library; the link text with format and size is written on the linking page. Older documents you cannot rework right away belong in the list of known limitations in the Statement tab — together with a note on how users can obtain the content in another form.

Staying on top of it

Accessibility is not a project with an end date, it is a routine. Four occasions are enough:

Keep your self-assessment in the WCAG checklist current and generate a fresh PDF audit report after larger changes. That documents what you checked and decided, and when — which is exactly what gets asked for if anyone ever does.

/wp-content/plugins/libration-accessibility/assets/frontend.js
/wp-content/plugins/libration-accessibility/assets/frontend.css
/wp-content/plugins/libration-accessibility/assets/libration-tts.js
/wp-content/plugins/libration-accessibility/assets/libration-easy-lang.js

Support

Questions, bugs, feature requests? Write to support@librationtools.io — Pro customers get priority. Please include your WordPress and plugin versions (see plugin list) and a short description of what you expected versus what you saw.