# Gmira A11Y
> Use when auditing a built page for contrast, keyboard operation, semantics, and canvas fallback. Also use when text sits on a colored or image background and nobody measured it, when the focus outline was removed, when tab order jumps around the screen, when a div is being used as a button, when a canvas or WebGL layer carries text or controls, when a form field has no label, or when reduced motion only slows an animation down. Runs at audit time and not during design, because an accessibility reminder while designing produces timid underdesigned output. Ships a runnable DOM audit that computes contrast from computed styles rather than eyeballing it.
- Skill: `othmanadi/gmira-a11y` (Agent Skill)
- Install (CLI): `npx skillmds@latest add othmanadi/gmira-a11y`
- Raw SKILL.md: https://api.skillmd.com/api/skills/othmanadi/gmira-a11y/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Web & Frontend
- Author: othmanadi (https://skillmd.com/u/othmanadi)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/othmanadi/gmira-a11y
---
# A11y
Contrast, semantics, keyboard, canvas fallback. Measured, on the built page.
Load `../gmira/references/DOCTRINE.md` first. This skill owns gate G3 and the readability half
of G8.
## Why this is an audit skill and not a design reminder
The doctrine puts this check here on purpose. Reminded about accessibility while designing, a model
talks itself into safe, timid, underdesigned output: smaller claims, flatter color, less commitment,
all in the name of a rule nobody measured. So the build skills say nothing about it and this one
says all of it, after the page exists, with numbers.
Do not import this checklist into a build skill. Run it here.
## What automated tooling does and does not cover
`@axe-core/playwright` is worth running and it finds roughly the machine-checkable half: missing
labels, bad roles, duplicate ids, contrast on plain backgrounds. It does not find focus order
disagreeing with visual order, a canvas carrying the page's only headline, an error message that
names a problem but no recovery, or a control that is reachable but not operable. Those are below.
```bash
pnpm add -D @axe-core/playwright
```
## 1. Contrast, measured
Floors, from the doctrine: **body and placeholder text 4.5:1**, **large text 3:1**, **controls,
icons, and focus indicators 3:1 against adjacent colors**. Large means 24px or larger, or 18.66px at
weight 700 or heavier.
Two rules that get broken constantly: placeholder text is body text and needs 4.5:1, and on colored
surfaces secondary text is tinted from that hue or the foreground, **never gray**. Gray on color is
both a contrast failure and the reason the surface looks unfinished.
```
INCORRECT secondary text #6B6B6B on a #0F2D1E surface, because "gray reads as muted".
Measured: 2.8:1. It reads as a rendering fault, not as hierarchy.
CORRECT tint the secondary from the surface hue: #6E9A85 on #0F2D1E measures 4.7:1
and still reads as the quieter of the two.
```
The walker resolves the real background through ancestors and composites alpha, which is the part
eyeballing and most quick scripts get wrong:
```js
(() => {
const f = c => { c /= 255; return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4 };
const lum = ([r, g, b]) => 0.2126 * f(r) + 0.7152 * f(g) + 0.0722 * f(b);
const parse = s => (s.match(/[\d.]+/g) || []).map(Number);
const over = (fg, bg) => { const a = fg[3] ?? 1; return [0, 1, 2].map(i => fg[i] * a + bg[i] * (1 - a)) };
const ratio = (a, b) => { const l1 = lum(a), l2 = lum(b);
return (Math.max(l1, l2) + 0.05) / (Math.min(l1, l2) + 0.05) };
const bgOf = el => { // walk up, composite every translucent layer
const stack = []; let e = el;
while (e) {
const c = parse(getComputedStyle(e).backgroundColor);
if (c.length >= 3 && (c[3] ?? 1) > 0) { stack.push(c); if ((c[3] ?? 1) === 1) break }
e = e.parentElement;
}
return stack.reverse().reduce((acc, c) => over(c, acc), [255, 255, 255]);
};
const out = [];
for (const el of document.querySelectorAll('body *')) {
const s = getComputedStyle(el);
if (s.display === 'none' || s.visibility === 'hidden' || parseFloat(s.opacity) === 0) continue;
const own = [...el.childNodes].some(n => n.nodeType === 3 && n.textContent.trim().length > 1);
if (!own) continue;
const size = parseFloat(s.fontSize), weight = parseInt(s.fontWeight, 10) || 400;
const large = size >= 24 || (size >= 18.66 && weight >= 700);
const bg = bgOf(el);
const r = ratio(over(parse(s.color), bg), bg);
const need = large ? 3 : 4.5;
if (r < need) out.push({ ratio: +r.toFixed(2), need, size, text: el.textContent.trim().slice(0, 40), el });
}
for (const el of document.querySelectorAll('input[placeholder], textarea[placeholder]')) {
const bg = bgOf(el);
const r = ratio(over(parse(getComputedStyle(el, '::placeholder').color), bg), bg);
if (r < 4.5) out.push({ ratio: +r.toFixed(2), need: 4.5, text: 'placeholder: ' + el.placeholder, el });
}
console.table(out); return out.length;
})()
```
Two cases the walker cannot resolve, so check them by eye with a color picker: text over an image or
a video, and text over a canvas. For those, sample the darkest and lightest pixels under the text
and measure against both. Text over a moving background needs a scrim, a solid plate, or a different
place to live.
## 2. Focus order matches visual order
Tab order follows DOM order. When the visual layout is reordered with `order`, `grid-area`, `row-reverse`,
or absolute positioning, they come apart and the keyboard walks the page in a sequence nobody sees.
```js
(() => {
const sel = 'a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"]), [contenteditable="true"]';
const nodes = [...document.querySelectorAll(sel)]
.filter(e => e.offsetParent !== null && !e.disabled && !e.closest('[inert],[aria-hidden="true"]'));
const positive = nodes.filter(e => (parseInt(e.getAttribute('tabindex'), 10) || 0) > 0);
const jumps = [];
for (let i = 1; i < nodes.length; i++) {
const a = nodes[i - 1].getBoundingClientRect(), b = nodes[i].getBoundingClientRect();
if (b.top < a.top - 8 || (Math.abs(b.top - a.top) <= 8 && b.left < a.left - 8))
jumps.push({ from: nodes[i - 1].textContent.trim().slice(0, 24), to: nodes[i].textContent.trim().slice(0, 24) });
}
console.table(jumps);
if (positive.length) console.warn('positive tabindex found, that is the finding by itself', positive);
return jumps.length;
})()
```
Any `tabindex` above 0 is a finding on its own: it jumps ahead of every natural element on the page
and the order becomes unmaintainable. Use 0 or -1 only.
Also confirm focus is never trapped and never lost. Open every overlay, tab to the end, and check
that focus cycles inside it and returns to the trigger on close. After a route change, focus moves
to the new page's heading or main, it does not stay on a button that no longer exists.
## 3. Every interactive element reachable and operable
The common failure is a `div` with a click handler: reachable by mouse, invisible to the keyboard.
```js
[...document.querySelectorAll('div,span,li,td,article,section')]
.filter(e => getComputedStyle(e).cursor === 'pointer' &&
!e.closest('a,button,label,summary,select,[role="button"],[role="link"],[tabindex]'))
```
Every hit is either converted to a real `button` or `a`, or given `tabindex="0"`, a role, and a
keydown handler for Enter and Space. The first option is right almost every time.
Operable means the whole interaction works from the keyboard, not just that focus can land on it:
menus open with Enter and close with Escape, sliders move with arrows, drag-and-drop has a
non-pointer path, a custom select is navigable with arrows and typeahead, and Escape dismisses every
overlay.
## 4. The skip link
One link, first in the tab order, visible once focused.
```html
Skip to content
...
```
`tabindex="-1"` on the target is required: without it, Chrome and Safari move the scroll position
but not the focus, so the next Tab goes back into the nav.
```js
const skip = document.querySelector('body a[href^="#"]');
console.log(skip?.getAttribute('href'), !!document.querySelector(skip?.getAttribute('href') || '#none'));
```
## 5. ARIA for the things that need it, and nothing else
The first rule of ARIA is not using ARIA. A `role="button"` on a `