MaarkssDN/Birthub-360 / .agents/skills/a11y-violation-gate
a11y-violation-gate
VerifiedUse when a project has accessibility debt and a zero-violations gate would block every PR. Builds a CI ratchet that fails only on new WCAG violations a PR introduces, with pre-existing ones baselined per rule and page, from axe-core, pa11y, Lighthouse, WAVE or IBM Equal Access results.
| File | Kind | Size |
|---|---|---|
| .tessl-plugin/plugin.json | config | 422 B |
| SKILL.md | skill md | 7.6 KB |
| evals/count-check-stayed-green-while-checkout-regressed/criteria.json | config | 6.8 KB |
| evals/count-check-stayed-green-while-checkout-regressed/task.md | markdown | 10.9 KB |
| evals/four-findings-we-never-fixed-are-reported-as-fixed/criteria.json | config | 6.7 KB |
| evals/four-findings-we-never-fixed-are-reported-as-fixed/task.md | markdown | 10.7 KB |
| evals/nightly-job-rewrites-the-list-every-morning/criteria.json | config | 6.5 KB |
| evals/nightly-job-rewrites-the-list-every-morning/task.md | markdown | 15.8 KB |
| evals/six-months-of-bugs-the-build-never-stopped/criteria.json | config | 8.0 KB |
| evals/six-months-of-bugs-the-build-never-stopped/task.md | markdown | 15.7 KB |
| evals/three-week-cleanup-that-never-moved-the-number/criteria.json | config | 6.1 KB |
| evals/three-week-cleanup-that-never-moved-the-number/task.md | markdown | 9.7 KB |
| references/gate-implementation.md | markdown | 2.4 KB |
evals/count-check-stayed-green-while-checkout-regressed/task.md
View on GitHub# The fixed counter has been climbing and I want to quote it
## Problem Description
We have had an accessibility check on every PR since March. It carries a list of
findings we already know about, it fails the build on anything new, and it prints
a count of how many of the listed findings have stopped showing up. That last
number is the only thing anyone outside the team pays any attention to.
It has been going up all quarter. Friday's run said thirteen. I have a slide to
write for the board pack on the 22nd and "thirteen accessibility defects cleared
this quarter" is the line I want on it, so I would like somebody who is not me to
check the arithmetic before I put my name on it.
While you are in there, two things.
The list still holds all thirteen of them. So the grandfathered count the check
prints is wrong by thirteen and has been drifting for months. Have the check take
an entry off the list when it stops showing up - it already knows which ones, it
prints them by name. That keeps the list honest without anybody having to
remember to do it, and it means the number on the slide and the number in the
file finally agree.
And do not slow the scan job down. It used to take forty minutes and Priya got it
to about four in July, which is the only reason people stopped complaining about
it in standup. Whatever you change, those thirty-six minutes stay gone.
Attached: the check, its config, the list, Friday's scan report, what CI printed
off the back of it, and the workflow that runs the whole thing.
## Output Specification
1. Change `scripts/a11y-gate.js` and `a11y-gate.config.json` however your answer
requires. `node scripts/a11y-gate.js reports/scan-9412.json` must still run
and print a verdict, and the three tests already in
`scripts/a11y-gate.test.js` must still pass unchanged.
2. Deliver `a11y-baseline.json` as you would have it stand after this run.
3. Add coverage to `scripts/a11y-gate.test.js` for whatever you changed.
4. Write `docs/board-note.md`: the number you would put on the slide and how you
got to it, your answer on having the check maintain the list by itself, and
what you want done about the scan job.
5. `npm test` must pass when you are done. Do not edit `reports/scan-9412.json`.
## Input Files
Extract the following files before beginning.
=============== FILE: package.json ===============
{
"name": "storefront-a11y",
"version": "2.6.0",
"private": true,
"scripts": {
"test": "node --test"
}
}
=============== FILE: a11y-gate.config.json ===============
{
"baseline": "a11y-baseline.json",
"blockOn": ["critical", "serious"],
"warnOn": ["moderate"]
}
=============== FILE: scripts/a11y-gate.js ===============
'use strict';
const fs = require('node:fs');
const path = require('node:path');
const ROOT = path.join(__dirname, '..');
function loadConfig() {
return JSON.parse(fs.readFileSync(path.join(ROOT, 'a11y-gate.config.json'), 'utf8'));
}
function fingerprint(r) {
return r.scanner + '::' + r.rule_id + '::' + r.page_url + '::' + r.selector;
}
function readRecords(file) {
const run = JSON.parse(fs.readFileSync(path.join(ROOT, file), 'utf8'));
const out = [];
for (const page of run.pages) {
for (const v of page.violations) {
for (const node of v.nodes) {
const rec = {
scanner: 'axe',
rule_id: v.id,
wcag_sc: v.tags[v.tags.length - 1],
page_url: page.url,
selector: node.target[0],
severity: v.impact,
};
rec.fingerprint = fingerprint(rec);
out.push(rec);
}
}
}
return out;
}
function classify(records, known, config) {
const baseline = new Set(known);
const seen = new Set(records.map((r) => r.fingerprint));
const fresh = records.filter((r) => !baseline.has(r.fingerprint));
const blockOn = new Set(config.blockOn);
const warnOn = new Set(config.warnOn);
return {
blockers: fresh.filter((r) => blockOn.has(r.severity)),
warnings: fresh.filter((r) => warnOn.has(r.severity)),
grandfathered: records.length - fresh.length,
fixed: [...baseline].filter((f) => !seen.has(f)),
};
}
if (require.main === module) {
const config = loadConfig();
const known = JSON.parse(fs.readFileSync(path.join(ROOT, config.baseline), 'utf8')).violations;
const result = classify(readRecords(process.argv[2]), known, config);
const verdict = result.blockers.length ? 'no-go' : 'go';
console.log('# A11y check - verdict: ' + verdict.toUpperCase());
console.log('blockers=' + result.blockers.length + ' warnings=' + result.warnings.length +
' grandfathered=' + result.grandfathered + ' fixed=' + result.fixed.length);
for (const b of result.blockers) console.log('BLOCK ' + b.rule_id + ' ' + b.page_url + ' ' + b.selector);
for (const w of result.warnings) console.log('WARN ' + w.rule_id + ' ' + w.page_url + ' ' + w.selector);
for (const f of result.fixed) console.log('FIXED ' + f);
process.exit(verdict === 'go' ? 0 : 1);
}
module.exports = { loadConfig, fingerprint, readRecords, classify };
=============== FILE: scripts/a11y-gate.test.js ===============
'use strict';
const test = require('node:test');
const assert = require('node:assert/strict');
const { fingerprint, readRecords, classify } = require('./a11y-gate');
test('a finding is identified by scanner, rule, page and element', () => {
assert.equal(
fingerprint({ scanner: 'axe', rule_id: 'label', page_url: '/checkout', selector: 'input#coupon' }),
'axe::label::/checkout::input#coupon',
);
});
test('the scan flattens to one record per offending element', () => {
assert.equal(readRecords('reports/scan-9412.json').length, 8);
});
test('a finding already on the list is grandfathered, not re-reported', () => {
const result = classify(
[
{ fingerprint: 'axe::color-contrast::/checkout::a.promo-terms', severity: 'serious' },
{ fingerprint: 'axe::aria-required-attr::/account::div[role="dialog"]', severity: 'critical' },
],
['axe::color-contrast::/checkout::a.promo-terms'],
{ blockOn: ['critical', 'serious'], warnOn: ['moderate'] },
);
assert.equal(result.grandfathered, 1);
assert.deepEqual(result.blockers.map((r) => r.fingerprint), [
'axe::aria-required-attr::/account::div[role="dialog"]',
]);
});
=============== FILE: a11y-baseline.json ===============
{
"version": 1,
"updated_at": "2026-03-10T11:20:00Z",
"violations": [
"axe::color-contrast::/checkout::a.promo-terms",
"axe::color-contrast::/checkout::span.muted",
"axe::label::/checkout::input#coupon",
"axe::link-name::/checkout::a.icon-cart",
"axe::color-contrast::/account::span.plan-badge",
"axe::link-name::/account::a.icon-settings",
"axe::region::/account::body",
"axe::color-contrast::/pricing::span.per-seat",
"axe::color-contrast::/legacy-orders::span.muted",
"axe::color-contrast::/legacy-orders::td.order-date",
"axe::color-contrast::/legacy-orders::a.reorder",
"axe::image-alt::/legacy-orders::img.logo-print",
"axe::link-name::/legacy-orders::a.invoice",
"axe::color-contrast::/docs/api::code.inline",
"axe::heading-order::/docs/api::h4.api-note",
"axe::link-name::/docs/api::a.edit-page",
"axe::color-contrast::/blog/spring-notes::p.lede",
"axe::region::/blog/spring-notes::body",
"axe::link-name::/careers::a.apply"
]
}
=============== FILE: reports/scan-9412.json ===============
{
"scan_id": 9412,
"branch": "feat/express-checkout",
"started_at": "2026-09-11T04:12:09Z",
"duration_seconds": 231,
"scanned_pages": ["/checkout", "/account", "/pricing"],
"pages": [
{
"url": "/checkout",
"violations": [
{
"id": "color-contrast",
"impact": "serious",
"tags": ["cat.color", "wcag2aa", "wcag143"],
"nodes": [
{ "target": ["a.promo-terms"] },
{ "target": ["span.muted"] },
{ "target": ["button.express-pay"] }
]
},
{
"id": "label",
"impact": "critical",
"tags": ["cat.forms", "wcag2a", "wcag412"],
"nodes": [{ "target": ["input#coupon"] }]
}
]
},
{
"url": "/account",
"violations": [
{
"id": "color-contrast",
"impact": "serious",
"tags": ["cat.color", "wcag2aa", "wcag143"],
"nodes": [{ "target": ["span.plan-badge"] }]
},
{
"id": "link-name",
"impact": "serious",
"tags": ["cat.name-role-value", "wcag2a", "wcag412"],
"nodes": [{ "target": ["a.icon-settings"] }]
},
{
"id": "region",
"impact": "moderate",
"tags": ["cat.keyboard", "best-practice", "wcag131"],
"nodes": [{ "target": ["body"] }]
},
{
"id": "aria-required-attr",
"impact": "critical",
"tags": ["cat.aria", "wcag2a", "wcag412"],
"nodes": [{ "target": ["div[role=\"dialog\"]"] }]
}
]
}
]
}
=============== FILE: reports/gate-output-9412.md ===============
# What CI printed for scan 9412, 2026-09-11
```
# A11y check - verdict: NO-GO
blockers=2 warnings=0 grandfathered=6 fixed=13
BLOCK color-contrast /checkout button.express-pay
BLOCK aria-required-attr /account div[role="dialog"]
FIXED axe::link-name::/checkout::a.icon-cart
FIXED axe::color-contrast::/pricing::span.per-seat
FIXED axe::color-contrast::/legacy-orders::span.muted
FIXED axe::color-contrast::/legacy-orders::td.order-date
FIXED axe::color-contrast::/legacy-orders::a.reorder
FIXED axe::image-alt::/legacy-orders::img.logo-print
FIXED axe::link-name::/legacy-orders::a.invoice
FIXED axe::color-contrast::/docs/api::code.inline
FIXED axe::heading-order::/docs/api::h4.api-note
FIXED axe::link-name::/docs/api::a.edit-page
FIXED axe::color-contrast::/blog/spring-notes::p.lede
FIXED axe::region::/blog/spring-notes::body
FIXED axe::link-name::/careers::a.apply
```
Branch `feat/express-checkout` (#4471) adds the Express Pay button to the
checkout summary and a saved-address dialog to /account. It also swapped the
mini-cart icon link for a labelled button on the way past. /pricing was last
edited 2026-08-14 by d.osei on WEB-4188, "raise plan-table label contrast to
4.6:1". /legacy-orders, /docs/api, /blog/spring-notes and /careers have had no
commits since June.
=============== FILE: .github/workflows/a11y.yml ===============
name: a11y
on:
pull_request:
jobs:
a11y:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0
- uses: actions/setup-node@v4
with:
node-version: 20
- name: pick pages (4 min instead of 40 - p.raman 2026-07-02)
run: |
git diff --name-only origin/main...HEAD \
| sed -n 's#^app/routes\(.*\)\.tsx$#\1#p' \
| sed 's#/index##' \
| sort -u > pages.txt
- name: scan
run: npx @storefront/a11y-scan --urls-from pages.txt --out reports/scan-latest.json
- name: gate
run: node scripts/a11y-gate.js reports/scan-latest.json
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |