qa-form-a11y
Consolidated form accessibility skill. Owns labels, aria, fieldset legend, error announcement, required-field indication, focus order, password show/hide. Replaces qa-detect-form-a11y plus a11y-portio
SKILL.mdskills/qa-form-a11y/SKILL.md
GitHubqa-form-a11y — Consolidated Form Accessibility Skill
Single skill owning ALL form-related accessibility findings. No other skill emits a11y findings on form elements.
What it checks (6 issue types)
| issueType | severity | catches |
|---|---|---|
fieldWithoutLabel |
high | Input/textarea/select with no label, aria-label, aria-labelledby, title, or placeholder |
errorNotAnnounced |
high | Error container missing role="alert" or aria-live — screen readers don't announce |
requiredNotIndicated |
medium | Required field (by required attr OR by red border on load) with no visible asterisk AND no aria-required="true" — covers both explicit-required and color-only-required fields |
fieldsetNoLegend |
medium | <fieldset> without <legend> — radio/checkbox group label invisible |
focusOrderMismatch |
medium | Tab focus order does not match visual top-to-bottom order |
passwordNoToggle |
medium | Password field has no show/hide toggle nearby |
Self-skip
Single passive browser_evaluate. Returns [] if no forms / inputs / errors found.
Probe (browser_evaluate)
() => {
const sel = el => (el.tagName.toLowerCase() + (el.id ? `#${el.id}` : '')).slice(0,120);
const bb = el => { const r = el.getBoundingClientRect(); return { x: Math.round(r.left), y: Math.round(r.top), w: Math.round(r.width), h: Math.round(r.height) }; };
const out = [];
const skipTypes = new Set(['hidden','submit','reset','button','image','checkbox','radio']);
// Detect floating/contextual labels used by UI component libraries.
// These libraries position a <label> visually inside the input (looks like placeholder),
// which floats up on focus. The label IS there — just not always linked via for/id.
// Without this check, every MUI / Ant Design / Chakra / Vuetify input fires a false positive.
const hasContextualLabel = el => {
// 1. MUI: <FormControl class="MuiFormControl-root"><label class="MuiFormLabel-root">...</label>...<input>
const muiControl = el.closest('.MuiFormControl-root, .MuiTextField-root, .MuiInputBase-root');
if (muiControl) {
const lbl = muiControl.closest('.MuiFormControl-root, .MuiTextField-root');
if (lbl) {
const label = lbl.querySelector('.MuiFormLabel-root, .MuiInputLabel-root');
if (label && label.innerText.trim()) return true;
}
}
// 2. Ant Design: <Form.Item><label class="ant-form-item-label">...</label>...<input>
const antItem = el.closest('.ant-form-item');
if (antItem && antItem.querySelector('.ant-form-item-label label, .ant-form-item-label')) return true;
// 3. Chakra UI: <FormControl class="chakra-form-control"><FormLabel class="chakra-form__label">
const chakra = el.closest('.chakra-form-control');
if (chakra && chakra.querySelector('.chakra-form__label')) return true;
// 4. Vuetify: <v-text-field> renders <label class="v-label">
const vuetify = el.closest('.v-input, .v-field');
if (vuetify && vuetify.querySelector('.v-label, .v-field-label')) return true;
// 5. Angular Material: <mat-form-field><mat-label> or <label class="mdc-floating-label">
const matField = el.closest('mat-form-field, .mat-mdc-form-field, .mat-form-field');
if (matField && matField.querySelector('mat-label, .mdc-floating-label, .mat-mdc-floating-label')) return true;
// 6. Bootstrap 5 floating labels: <div class="form-floating"><input><label>
const bsFloat = el.closest('.form-floating');
if (bsFloat && bsFloat.querySelector('label')) return true;
// 7. PrimeReact / PrimeFaces: <span class="p-float-label"><input><label>
const prime = el.closest('.p-float-label, .p-inputwrapper');
if (prime && prime.querySelector('label')) return true;
// 8. Quasar: <q-input> renders <label class="q-field__label">
const quasar = el.closest('.q-field, .q-input');
if (quasar && quasar.querySelector('.q-field__label')) return true;
// 9. Generic: any wrapping element with a <label> that has text
const genericWrap = el.closest('.form-group, .form-field, .field, .input-wrapper, .input-group');
if (genericWrap) {
const lbl = genericWrap.querySelector('label');
if (lbl && lbl.innerText.trim()) return true;
}
return false;
};
// Proximity label: a VISIBLE short text sitting immediately beside the field in the same
// container (e.g. "Records Per Page: <select>"). It's not linked via for/aria, so a screen
// reader still misses it — but a sighted user clearly sees the label, so this is NOT a
// high "field has NO label" defect. Suppresses the false positive on labelled-by-proximity
// controls (records-per-page selects, inline filters) while still flagging truly bare fields.
const visText = n => { const t = (n.innerText != null ? n.innerText : n.textContent || '').trim(); return t.length >= 2 && t.length <= 40 ? t : ''; };
const hasProximityLabel = el => {
// (a) a preceding ELEMENT sibling with short visible text
let prev = el.previousElementSibling;
for (let i = 0; prev && i < 3; i++, prev = prev.previousElementSibling) { if (prev.offsetParent !== null && visText(prev)) return true; }
// (b) a short text NODE before the field inside the same parent ("Records Per Page: <select>")
const par = el.parentElement;
if (par) {
for (const node of par.childNodes) { if (node === el) break; if (node.nodeType === 3) { const t = node.textContent.trim(); if (t.length >= 2 && t.length <= 40) return true; } }
// (c) climb one wrapper (e.g. <gf-input>) and re-check its preceding sibling
let pp = par.previousElementSibling;
for (let i = 0; pp && i < 2; i++, pp = pp.previousElementSibling) { if (pp.offsetParent !== null && visText(pp)) return true; }
}
return false;
};
// Inline reddish-border helpers (r dominant: r≥150, r>g+50, r>b+50, alpha≥0.3)
const parseColor = s => { const m = s && s.match(/rgba?\((\d+)\s*,\s*(\d+)\s*,\s*(\d+)(?:[\s,]+([\d.]+))?/); return m ? { r:+m[1], g:+m[2], b:+m[3], a:m[4]!==undefined?+m[4]:1 } : null; };
const isReddish = s => { const c = parseColor(s); return !!(c && c.a >= 0.3 && c.r >= 150 && c.r > c.g + 50 && c.r > c.b + 50); };
const fieldBorderColor = el => { const cs = getComputedStyle(el); return cs.borderTopColor || cs.borderBottomColor || cs.borderLeftColor || cs.borderRightColor || ''; };
// Helper: is this <select> a "Records Per Page" / "Rows per page" / page-size selector?
// Pattern signatures (any ONE qualifies):
// (a) ≤ 6 numeric options whose values look like page sizes (5, 10, 15, 20, 25, 30, 50, 100…)
// (b) name/id/class contains "page-size", "pageSize", "perPage", "rows-per", "records-per"
// (c) the visible text within ~150 chars of the select's location contains "per page"
// (case-insensitive) — covers "Records Per Page", "Rows per page", "Items per page", etc.
// Page-size selectors are universally understood from context; requiring a <label for>
// association is noise the user has explicitly called out (Departments page, 2026-06-11).
const PAGE_SIZE_VALUES = new Set([5, 10, 15, 20, 25, 30, 40, 50, 75, 100, 150, 200, 250, 500, 1000]);
const isPageSizeSelect = (el) => {
if (el.tagName !== 'SELECT') return false;
// (a) numeric-only options that look like page sizes
const opts = [...el.options || []];
if (opts.length > 0 && opts.length <= 6) {
const allNumericPageSizes = opts.every(o => {
const v = parseInt((o.value || o.text || '').trim(), 10);
return !Number.isNaN(v) && PAGE_SIZE_VALUES.has(v);
});
if (allNumericPageSizes) return true;
}
// (b) name/id/class hints
const hint = ((el.name || '') + ' ' + (el.id || '') + ' ' + (el.className && typeof el.className === 'string' ? el.className : '')).toLowerCase();
if (/page[-_]?size|per[-_]?page|rows[-_]?per|records[-_]?per|items[-_]?per/.test(hint)) return true;
// (c) parent / ancestor text contains "per page" / "rows per page" within 150 chars
let scope = el.parentElement;
for (let i = 0; scope && i < 3; i++, scope = scope.parentElement) {
const t = (scope.innerText || '').trim().toLowerCase();
if (t.length > 0 && t.length <= 200 && /per\s+page|page\s*size|rows\s+per|records\s+per|items\s+per|show\s+\d|show\s+per/.test(t)) return true;
}
return false;
};
// Shared full-visibility check used by fieldWithoutLabel and other checks below.
// An element must be:
// (a) non-zero dimensions
// (b) inside the viewport bounds — not below/above/left/right of the visible area
// (c) not hidden by an ancestor (display:none / visibility:hidden / opacity:0)
// (d) not clipped inside an overflow:hidden ancestor that puts it out of view
// Without (b) and (c), ghost elements rendered off-screen by framework components
// (PrimeNG paginator jump-to-page input, hidden Angular form fields, off-canvas drawers)
// produce annotations that appear in empty space below/outside page content.
const vw = window.innerWidth, vh = window.innerHeight;
const isVisibleInViewport = el => {
const r = el.getBoundingClientRect();
if (r.width === 0 || r.height === 0) return false;
// Entirely outside viewport in any direction
if (r.right <= 0 || r.bottom <= 0 || r.left >= vw || r.top >= vh) return false;
// Ancestor visibility walk
let node = el.parentElement;
while (node && node !== document.documentElement) {
const s = getComputedStyle(node);
if (s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0') return false;
// Clipped by overflow:hidden ancestor — check if element is outside ancestor's rect
if (s.overflow === 'hidden' || s.overflowY === 'hidden' || s.overflowX === 'hidden') {
const pr = node.getBoundingClientRect();
if (r.bottom <= pr.top || r.top >= pr.bottom || r.right <= pr.left || r.left >= pr.right) return false;
}
node = node.parentElement;
}
return true;
};
// Dashboard/report period-filter selects (e.g. "This Year", "Last Month", "All Time").
// These <select> elements live outside <form> tags in dashboards/reports and are entirely
// self-described by their option values — requiring a <label> is noise.
const PERIOD_KEYWORDS = /this\s+year|last\s+year|this\s+month|last\s+month|this\s+week|last\s+week|this\s+quarter|last\s+quarter|all\s+time|today|yesterday|ytd|mtd|year|month|week|quarter/i;
const isDashboardFilter = el => {
if (el.tagName !== 'SELECT') return false;
// Must NOT be inside a <form> — dashboard filters are standalone controls
if (el.closest('form')) return false;
// Check option texts for period/date keywords
const opts = [...(el.options || [])];
const optText = opts.map(o => o.text || o.value || '').join(' ');
if (PERIOD_KEYWORDS.test(optText)) return true;
// Check the select's own value / id / name / class
const hint = [el.value, el.id, el.name, typeof el.className === 'string' ? el.className : ''].join(' ');
if (PERIOD_KEYWORDS.test(hint)) return true;
// Check id/name for generic filter signals (period, date-range, year, timeframe)
if (/period|date[-_]?range|timeframe|year|month|fiscal/i.test(el.id + ' ' + el.name)) return true;
return false;
};
// 1. fieldWithoutLabel
for (const el of document.querySelectorAll('input, textarea, select')) {
if (out.length >= 16) break;
if (el.type && skipTypes.has(el.type)) continue;
// Use full visibility check — not just zero-dimensions.
// Catches ghost inputs positioned below viewport (PrimeNG paginator jump-to-page,
// hidden Angular reactive form fields, off-canvas inputs) that have non-zero BBox
// but are never visible to the user. Without this, annotations appear in empty space.
if (!isVisibleInViewport(el)) continue;
// Search/filter inputs are self-descriptive — their placeholder IS their label in context.
// type="search" and inputs whose placeholder or surrounding text contains search-related
// words are a well-understood pattern; requiring a <label> would be noise for list-page filters.
if (el.type === 'search') continue;
// Page-size selectors (records per page / rows per page) are universally understood
// from option values + surrounding text; requiring a <label for> is noise.
if (isPageSizeSelect(el)) continue;
// Dashboard period/date-range filter selects ("This Year", "Last Month", etc.) outside forms
// are self-described by their option values — skip them.
if (isDashboardFilter(el)) continue;
const ph = (el.placeholder || el.getAttribute('placeholder') || '').trim().toLowerCase();
if (/search|filter|find|lookup|query|zoek|recherche/i.test(ph)) continue;
// Also check if the nearest visible text node or sibling says "search" — covers Angular inputs
// where placeholder is rendered via attribute binding and reads back as '' on el.placeholder.
const nearText = (() => {
const par = el.parentElement;
if (!par) return '';
// check placeholder attribute directly (covers Angular [placeholder] binding)
const attrPh = el.getAttribute('placeholder') || '';
if (/search|filter|find|lookup|query/i.test(attrPh)) return attrPh;
// check mat-label / label sibling text
const lbl = par.querySelector('label, mat-label, .mat-mdc-floating-label, .mdc-floating-label');
return lbl ? (lbl.innerText || lbl.textContent || '') : '';
})();
if (/search|filter|find|lookup|query/i.test(nearText)) continue;
const lbByText = el.getAttribute('aria-labelledby') ? (document.getElementById(el.getAttribute('aria-labelledby'))?.textContent?.trim() || '') : '';
const labelled = (el.labels && el.labels.length > 0) ||
(el.getAttribute('aria-label') || '').trim() ||
lbByText ||
el.title ||
el.placeholder ||
el.getAttribute('placeholder') ||
hasContextualLabel(el) ||
hasProximityLabel(el);
if (!labelled) {
out.push({ issueType:'fieldWithoutLabel', severity:'high', selector:sel(el),
description:'Form field has no label, aria-label, aria-labelledby, title, or placeholder', bbox: bb(el) });
}
}
// 2. errorNotAnnounced
for (const e of document.querySelectorAll('.error, .invalid-feedback, .field-error, .error-message, .form-error, [class*="error-msg"]')) {
if (out.length >= 20) break;
if (!isVisibleInViewport(e)) continue;
const role = e.getAttribute('role');
const ariaLive = e.getAttribute('aria-live');
if (role !== 'alert' && role !== 'status' && !ariaLive) {
out.push({ issueType:'errorNotAnnounced', severity:'high', selector:sel(e),
description:`Error container ${sel(e)} missing role="alert" or aria-live — screen readers won't announce the error`, bbox: bb(e) });
}
}
// 3. requiredNotIndicated
// Part A: field has required attr but is missing visual asterisk or aria-required
for (const input of document.querySelectorAll('input[required], textarea[required], select[required]')) {
if (out.length >= 24) break;
if (input.type === 'hidden') continue;
if (!isVisibleInViewport(input)) continue;
const hasAriaRequired = input.getAttribute('aria-required') === 'true';
const label = (input.labels && input.labels[0]) || input.closest('label') || (input.id && document.querySelector(`label[for="${input.id}"]`));
const labelText = label ? label.innerText : '';
const hasAsterisk = /\*|\(required\)/i.test(labelText);
if (!hasAriaRequired && !hasAsterisk) {
out.push({ issueType:'requiredNotIndicated', severity:'medium', selector:sel(input),
description:`Required field ${sel(input)} has no visual asterisk AND no aria-required — users can't tell it's required`, bbox: bb(input) });
}
}
// Part B: field uses red border as the ONLY required indicator (no required attr, no aria-required, no asterisk)
// Covers forms that rely solely on color to communicate required state (WCAG 1.4.1).
// Example: Issue Budget "Title" field — red border on load, no * and no required attribute.
for (const input of document.querySelectorAll('input, textarea, select')) {
if (out.length >= 28) break;
if (input.type === 'hidden') continue;
if (!isVisibleInViewport(input)) continue;
if (input.disabled || input.readOnly) continue;
// Skip fields already covered by Part A
if (input.hasAttribute('required') || input.getAttribute('aria-required') === 'true') continue;
const value = (input.value || '').trim();
if (value.length > 0) continue;
const cls = (input.className || '').toString();
if (/\bng-touched\b|\btouched\b|\bdirty\b/.test(cls)) continue;
// Check for reddish border on the input or its component container
let hasRedBorder = isReddish(fieldBorderColor(input));
if (!hasRedBorder) {
const ctr = input.closest('mat-form-field, .mat-mdc-form-field, .mat-form-field-wrapper, .form-group, .form-field, .field');
if (ctr) {
const ccs = getComputedStyle(ctr);
hasRedBorder = isReddish(fieldBorderColor(ctr)) || isReddish(ccs.outlineColor);
}
}
if (!hasRedBorder) continue;
out.push({ issueType: 'requiredNotIndicated', severity: 'medium', selector: sel(input),
description: `Field appears required (red border on load) but has no required attribute, no aria-required="true", and no text marker — screen-reader users and colorblind users have no signal this field is mandatory`,
bbox: bb(input) });
}
// 4. fieldsetNoLegend
for (const fs of document.querySelectorAll('fieldset')) {
if (out.length >= 28) break;
if (!isVisibleInViewport(fs)) continue;
const legend = fs.querySelector(':scope > legend');
if (!legend || !legend.innerText.trim()) {
out.push({ issueType:'fieldsetNoLegend', severity:'medium', selector:sel(fs),
description:`Fieldset ${sel(fs)} has no <legend> — radio/checkbox groups lack a screen-reader-announced group label`, bbox: bb(fs) });
}
}
// 5. passwordNoToggle
for (const pwd of document.querySelectorAll('input[type="password"]')) {
if (out.length >= 30) break;
if (!isVisibleInViewport(pwd)) continue;
const parent = pwd.closest('div, fieldset, form');
const toggle = parent && parent.querySelector('[aria-label*="show" i], [aria-label*="hide" i], [data-testid*="toggle"]');
if (!toggle) {
out.push({ issueType:'passwordNoToggle', severity:'medium', selector:sel(pwd),
description:'Password field has no show/hide toggle button', bbox: bb(pwd) });
}
}
// 6. focusOrderMismatch
const focusables = [...document.querySelectorAll(
'input:not([disabled]):not([type="hidden"]), select:not([disabled]), textarea:not([disabled]), button:not([disabled]), a[href], [tabindex]:not([tabindex="-1"])'
)].filter(el => { const r = el.getBoundingClientRect(); return r.width > 0 && r.height > 0; }).slice(0, 10);
if (focusables.length >= 3) {
let violations = 0;
for (let i = 1; i < focusables.length; i++) {
const prev = focusables[i-1].getBoundingClientRect();
const curr = focusables[i].getBoundingClientRect();
if (curr.top + 8 < prev.top) violations++;
}
if (violations >= 2) {
out.push({ issueType:'focusOrderMismatch', severity:'medium', selector:'form',
description:`Tab focus order does not match visual top-to-bottom — ${violations} elements appear above their DOM-previous sibling`,
bbox: { x:0, y:0, w:200, h:80 } });
}
}
return out;
}
Migration
[detectors]
qa-form-a11y = true # NEW
qa-detect-form-a11y = false # REPLACED entirely
# qa-detect-forms retains the structural checks (formNoSubmit, inputHeightTooSmall, formFieldNotFullWidth) → moved to qa-form-structure