Accessibility ability reference

Which accessibility findings cost the most points

Every rule the audit runs has a fixed severity, and the severity sets the penalty: 10 for critical, 6 for serious, 3 for moderate and 1 for minor. Six rules are critical: an image with no alt attribute, an image button with no alt, an image-map area with no alt, a form field with no label, a button with no accessible name, and a viewport tag that blocks zoom (user-scalable=no, or a maximum-scale below 2). Fix those first, because a single one moves the score more than several minor findings together.

The fix_ability field tells the agent whether it can act on a finding itself. Image alt findings point at wppilot/update-image-alt. Empty headings, skipped heading levels, a missing h1 and a table without header cells point at wppilot/update-post, because those live in post content. Everything else (a missing lang attribute, no title tag, duplicate ids, broken ARIA references, a positive tabindex, an iframe with no title) carries no fix ability, which usually means the markup comes from the theme, a builder widget or another plugin and has to be fixed there.

Because the audit reads one served page, a finding in the header, footer or navigation is likely to repeat on every page that template prints. Spot-check one other page that uses the same template, then report it once as a theme issue rather than auditing every URL and counting it each time.

How the decorative guess decides an image is probably decoration

wppilot/audit-media-alt marks an image as likely decorative for one of three reasons, and gives the reason in plain words: it is 32 by 32 pixels or smaller; its file name or title contains a word such as spacer, divider, separator, background, texture, gradient, overlay or ornament; or it is a thin strip at least eight times wider than tall, or the reverse. Anything else gets likely: false.

The guess only reads names and dimensions. A small logo, a product thumbnail called background-shot.jpg or a chart cropped into a banner can all trip it, so the agent should still open the picture with wppilot/get-media-image before storing an empty alt. Text that appears inside an image belongs in its alt, and a linked image should name where the link goes rather than describe the picture.

When an image preview cannot be produced

wppilot/get-media-image takes max_size between 128 and 1568 pixels (1024 when omitted) and a format of auto, jpeg, webp or png. To stay under 750,000 bytes it first tries quality 82, then quality 60, then the same at three quarters and half the requested size. The errors it can return each point at a different cause:

• kit_a11y_image_type: the attachment is not a raster image. For an SVG, read its markup instead of asking for a preview.
• kit_a11y_image_no_file: the file is not on this server, which is what offloaded media looks like. Check the image in the media library by eye.
• kit_a11y_image_too_large: even the half-size, lower-quality attempt was over the limit. Ask again with a smaller max_size.
• kit_a11y_image_encode: the preview could not be written or read back, or the site converted it to a format vision models do not accept. Try another format value.
• kit_a11y_image_forbidden and kit_a11y_image_not_found: the connected user cannot view that attachment, or the id is wrong.

Why corrected alt text can still fail the next audit

wppilot/update-image-alt changes the alt stored on the attachment. An image block already placed in a post keeps the alt that was written into the block when it was inserted, so a page can show the same image-alt finding after a successful bulk write. Re-audit the page: whatever image findings remain are in post content, and that post has to be edited (or the image reinserted) before the page changes.

Under the Read Only safety profile the three reads stay available and the alt write is withheld. The write is not marked destructive, so the confirmation gate does not stop it unless the site owner has added a confirmation rule for it. A supported undo restores the captured attachment alt metadata, including its earlier absence, and checks the stored result. A rendered block or theme may carry its own alt attribute, so inspect the page separately.

A request to try on staging: audit /services/, fix every image alt finding, then re-audit. The agent reads the attachment_ids from the findings, previews each image, writes the batch, and audits again. Compare the two scores and finding lists, then open the page with a screen reader or the browser's accessibility tree to confirm the new alt is the one being announced.