Xezom Accessibility documentation

01 / Overview

Accessibility review connected to the task and the code.

XA combines standards-aware accessibility review with Xezom’s Task Friction Mapping framework. It examines what someone is trying to accomplish, where the experience creates a barrier, why that barrier matters, and whether an appropriate source change can be previewed safely.

Task Friction Mapping deliberately helps reveal ADHD-related and broader neurodivergent friction that a technical checklist may miss. This includes unclear starting points, initiation barriers, competing emphasis, excessive choice, avoidable working-memory demands, and difficulty recovering context after interruption.

XA reports observable interface behavior and task consequences. It does not diagnose users, infer a neurotype, replace disabled-user research, or claim accessibility conformance.

01
Orient
Understand the current context, available paths, and what matters next.
02
Start
Recognize and begin the first useful action without unnecessary decisions.
03
Act
Complete the task without hidden state, competing emphasis, or avoidable memory burden.
04
Recover
Understand an error or detour while keeping completed work intact.
05
Resume
Return after interruption with intent, context, and the next action restored.

02 / Install

Prepare XA once inside the project you will review.

Before you begin

You need Python 3.11 or newer, an XA wheel and tester token supplied by Xezom, an application you are authorized to test, and one specific task. Do not use production customer data or private credentials.

Create an isolated environment and install the supplied wheel

python3 -m venv .venv
source .venv/bin/activate
python -m pip install /path/to/xezom_accessibility-0.2.0.dev0-py3-none-any.whl
xa --version

Prepare browser capture and invited tester access

xa setup
xa configure
xa doctor

setupInstalls XA’s Playwright-managed Chromium runtime.
configureSaves the tester token in the operating-system credential vault. It does not request an OpenAI key.
doctorChecks local capture and performs an authenticated, non-billable service health check.

03 / First review

Capture locally. Inspect first. Approve the upload second.

Start the application with its normal development command and confirm its local URL. Name one outcome rather than a broad area of the product.

Capture a task without uploading or running AI analysis

xa scan http://127.0.0.1:4173 \
  --task "Create a workspace and invite a teammate" \
  --scenario scenario.json \
  --capture-only \
  --output .xa/workspace-review

Saved locally Evidence and screenshotsAI analysis Not runUploaded NothingSource changed No

Inspect evidence.json and every screenshot. Make sure the bundle represents the intended task and contains nothing you should not share.

Analyze the saved evidence after inspection

xa analyze \
  --evidence .xa/workspace-review/evidence.json \
  --approve-evidence-upload \
  --output .xa/workspace-review/review.json

Optional source-aware review

Rendered evidence shows what happened. Explicitly named source files can help XA identify the responsible component and determine whether a controlled fix is supportable. XA does not search the entire repository for upload.

Name only source files relevant to the captured task

xa analyze \
  --evidence .xa/workspace-review/evidence.json \
  --project-root . \
  --source src/App.tsx \
  --source src/components/WorkspaceForm.tsx \
  --source src/styles/app.css \
  --approve-evidence-upload \
  --approve-source-upload \
  --output .xa/workspace-review/review.json

04 / Findings

Read the barrier, its basis, and the remediation state separately.

Each finding connects evidence, task impact, recommendation, confidence, and fixability. A confirmed barrier does not automatically mean XA can safely choose the product behavior or implement it.

Ready to fix

Enough evidence exists for a guarded preview without an unresolved product decision.

Ready after a decision

The barrier is supported, but a concrete interaction or product choice must be documented first.

Needs further validation

More evidence or testing is required before controlled remediation.

Blocked

An unavailable dependency or unsafe boundary prevents automated remediation.

wcagA supported standards-based accessibility barrier.

supplementalInclusive-design or task-friction guidance that is not independently a WCAG failure.

hybridOne confirmed root cause with both standards and task-friction effects.

05 / Remediation

Preview and approval are different actions.

A model may reason about code and propose changes. XA’s deterministic Core controls which finding owns the change, what files are affected, when validation runs, and how recovery works.

Create a guarded session for one finding

xa create-session \
  --target . \
  --report .xa/workspace-review/review.json \
  --finding XA-WCAG-001 \
  --validation-command "npm run check"

Use the session path XA prints. Paste that complete path into the commands that follow; you do not need to locate the session directory yourself.

Request a non-applied proposal from explicitly named source

xa propose \
  --session /absolute/path/to/session \
  --finding XA-WCAG-001 \
  --source src/components/WorkspaceForm.tsx \
  --approve-source-upload

xa status --session /absolute/path/to/session

At this point, product source is still unchanged.

Inspect the planned operation, patch, reasoning receipt, and validation command before approving anything.

Apply exactly one inspected finding

xa fix \
  --session /absolute/path/to/session \
  --finding XA-WCAG-001 \
  --approve

git diff
npm run check

Decision-gated findings

For a finding marked Ready after a decision, document a concrete intended behavior. A decision such as “treat the drawer as modal, focus its heading, close on Escape, contain focus, and restore the trigger” permits proposal generation only. Source upload and application remain separately approved.

Recovery

Undo one finding or recover the complete session

xa undo --session /absolute/path/to/session --finding XA-WCAG-001
xa revert --session /absolute/path/to/session --approve

Recovery refuses to overwrite overlapping newer work and preserves demonstrably independent later edits.

06 / Privacy

Local first, with explicit transitions.

Stays local by default

Capture evidence before approval
All capture-only bundles
The tester token in the OS vault
Unselected project source
Session baselines, patches, and recovery records

Sent only after approval

The displayed evidence manifest
Declared screenshots and captured states
Only explicitly named source files
The selected finding context for remediation

Never include secrets, private keys, environment files, production user data, or unrelated proprietary source. XA applies redaction and credential-file safeguards, but the developer remains responsible for reviewing the exact scope being authorized.

07 / Troubleshooting

Common interruptions, with a clear return path.

XA is not found

Activate the virtual environment where XA was installed: source .venv/bin/activate, then run xa --version.

The browser runtime is missing

Run xa setup, followed by xa doctor. XA uses Playwright-managed Chromium rather than a normal browser installation.

XA stops before uploading

This is expected when an approval flag is omitted. Inspect the manifest and copy the exact next command XA prints. Evidence and source approvals are intentionally separate.

Hosted analysis returns an error

The local evidence remains available. Run xa doctor, then retry xa analyze without repeating browser capture unless the application, task, scenario, or viewport changed.

Project validation scans XA session files

Exclude .xezom-accessibility from project-wide formatters and linters. These are private operational records, not product source. Also add .xezom-accessibility/ to .gitignore.

Undo or revert refuses to continue

XA detected overlapping newer work and will not overwrite it. Preserve the working tree and inspect the reported conflict rather than deleting the session directory.

08 / Reference

Know which commands can change source.

XA commands and whether they can modify project source
Command	Purpose	Changes source
`xa guide`	See the complete workflow and its safety boundaries.	No
`xa docs`	Read documentation bundled with the installed XA version.	No
`xa setup`	Install Playwright-managed Chromium.	No
`xa configure`	Save an invited tester token in the operating-system credential vault.	No
`xa doctor`	Check local capture and hosted-service readiness.	No
`xa scan`	Capture evidence for one named task.	No
`xa analyze`	Review saved evidence without repeating browser capture.	No
`xa create-session`	Record a baseline and selected finding.	No
`xa propose`	Generate and record a non-applied code preview.	No
`xa status`	Show guarded finding states, operations, and decisions.	No
`xa fix`	Apply one explicitly approved, previewed finding.	Yes
`xa undo`	Reverse one applied finding.	Yes
`xa revert`	Reverse every still-applied finding in a session.	Yes

Need a human?

Stop when the scope, recommendation, or data boundary is unclear.

Confusion is useful beta feedback. Start with a sanitized description; do not attach private source, evidence, or tester credentials through routine email.

Contact support