How to use a11y Companion

Run a review from first check to Canvas Record.

The widget keeps the active work on the canvas. Use this guide to understand what each control changes, what the file retains, and when the evidence is incomplete.

Widget anatomy

Read the surface from top to bottom.

The widget keeps current work visible and moves retained evidence into four commands. Use the live state beside this guide; its controls are the same controls shown in the product and Scenario Lab.

01
Filter
Find one checklist decision without changing its state.
02
Progress
Read checklist completion and signed sections together.
03
Inspect
Open Contrast without leaving the review surface.
04
Evidence
Return to saved Targets, Text, or Tokens results.
05
Record
Refresh the page-owned summary when the evidence is ready.

Open the full Scenario Lab

Live product state

Complete a first review

One pass establishes checklist progress, measured evidence, and a handoff record.

Place the widgetKeep one instance on the page you are reviewing.
Review the checklistChoose a template, filter the list, and check items as decisions are made.
Measure the pageCheck contrast, then run Targets, Text, and Tokens where they apply.
Leave a recordSign complete sections and choose Record to create the page-owned handoff frame.

Read the control surface

Contrast opens and closes an inspector. The four commands below it select retained audit evidence or refresh the Canvas Record.

Widget control behavior
Control	Action	Retained state
Contrast	Measures the selected text and surface pair. Watch follows canvas changes.	Latest pair and Watch owner
Targets	Checks target dimensions and groups repeated size failures.	Latest result for this page
Text	Checks readable text measurements and groups repeated typography causes.	Latest result for this page
Tokens	Reviews variable-backed text and surface pairs by collection and mode.	Latest result for this page
Record	Creates or refreshes the page-owned handoff frame.	One Canvas Record per page

Inspect contrast

Measure one supported color pair or keep Watch active while you inspect nearby layers.

Check

Select a text or paint layer, then choose Check. Swap reverses the measured pair without changing the canvas.

Watch

Watch refreshes when the selection, relevant paints, linked styles, or page changes. The owner name remains visible while it runs.

Vision

Vision previews four color-perception states. It is a simulation and does not change the WCAG ratio.

Run page audits without losing scale

Targets, Text, and Tokens retain one current result per page and audit type. A new run replaces only that matching result.

Choose a command.If saved evidence exists, the widget opens it. Otherwise the audit starts.
Review grouped causes.The card shows up to three representative examples while counts cover every affected use in the completed scan.
Open or annotate a layer.Jump reveals one example. Annotate writes only the examples shown and discloses hidden findings.
Rerun or clear deliberately.Run audit refreshes the selected type. Clear removes that type and its widget-owned annotations only.

CompleteThe full bounded scan finished.

PartialA scan cap or selection scope limits coverage.

Not applicableThe page has no evidence for that audit type.

Sign a section after the decisions are current

A section can be signed after all of its checks are complete. The compact chip shows the reviewer; its tooltip carries the full timestamp.

Current

The section fingerprint still matches the checks that the reviewer approved.

Stale

A later checklist change invalidated the prior decision. Review the section and sign it again.

Create one Canvas Record per page

Record creates a native, editable Figma frame or refreshes the frame already owned by this widget. It never creates a duplicate during migration.

Action requiredA blocking audit or contrast failure remains.

Review requiredReview items, stale sign-offs, missing audits, or partial evidence remain.

In progressChecklist work, sign-offs, or a supported contrast check are incomplete.

Ready for handoffChecklist, sign-offs, contrast, and applicable page evidence are current.

Move the same evidence into the next tool

Portable exports use the same page-scoped data as the Canvas Record.

Export formats and common uses
Format	Use it for
Markdown	Review notes, pull requests, and issue descriptions
CSV	Sorting findings or joining them with a tracking sheet
JSON	Automation and typed downstream tooling
SVG	Editable evidence for decks and design reviews
PDF	A fixed handoff snapshot
Clipboard	A fast text handoff without opening another panel

Use properties for configuration

Primary work stays on the widget. The property menu holds choices that change the whole review surface.

Widget property reference
Property	Effect
Checklist template	Changes the visible checklist without deleting progress.
WCAG filter	Filters by conformance level or WCAG 2.2 additions.
Language	Changes widget labels, guidance, and checklist copy.
Theme	Changes the widget only. Canvas Records keep one canonical palette.
Accent color	Applies a contrast-safe product accent to the widget.
Export format	Provides secondary portable outputs outside the main workflow.

Read the coverage before the verdict

Large files stay responsive because every scan is bounded and every bounded result says what it covered.

2,000 nodes: Maximum traversal for page and selection scans.
800 pairs: Maximum token text and surface pairs evaluated in one run.
3 rows: Representative examples visible in the widget card.
6 examples: Representative examples retained in synced page evidence.

Partial scans and selection-only evidence cannot produce Ready for handoff. Run the capped-scan scenario to inspect the exact state contract.

Resolve the common edge cases

Watch says it is active but the pair does not change.: Select a non-widget canvas layer. Closing and reopening Contrast ends any stale local session before you start Watch again.
The card shows three rows but the count is larger.: The rows are representative examples. Use the affected-use count for scope, then refine the selection or jump through the shown causes.
An audit ran on more than the selected object.: If the selection has nothing useful to scan, the widget falls back to the current page and reports that scope.
Tokens says not applicable.: The page has no local variable-backed text and surface pair in scope. The state is recorded without inventing a failure.
The section sign-off became stale.: A checklist decision changed after sign-off. Review the section, then sign it again.