This document defines the accessibility expectations for the repository's command-line output and Markdown documentation; it does not claim conformance for the Apple software being researched.
- Overview
- Standards Baseline
- Accessibility Architecture
- Engineering Workflow
- Known Gaps
- User Support and Reporting
- Verification and Evidence
The repository has a documented accessibility baseline but no formal conformance audit.
This contract covers project-owned command-line output, Markdown structure, and any future user-facing surface. It does not cover or certify macOS, private frameworks, target applications, or raw third-party runtime output.
Keep research usable without relying on color, pointer input, animation, or visual-only structure, and preserve user control over TCC-gated and potentially mutating experiments.
Documentation and future web or graphical surfaces should target applicable WCAG 2.2 Level AA criteria. Command-line tools use an internal baseline of plain-text readability, stable ordering, descriptive diagnostics, and keyboard-only operation.
Do not make unqualified compliance, certification, or conformance claims without a scoped audit and recorded evidence. State targets, tested surfaces, gaps, and dates precisely.
The current project-owned surfaces are macOS command-line tools and GitHub-flavored Markdown. Research involving the macOS Accessibility API is an experimental input surface, not proof of this repository's conformance.
Use ordered headings, descriptive link text, fenced commands, lists for real sets, and tables only when relationships benefit from them. Do not encode meaning through indentation or typography alone.
Current tools are invoked from the keyboard and must not require pointer input. Future interactive tools must document shortcuts and preserve standard platform input behavior.
There is no project-owned graphical focus model today. Any future UI must provide predictable focus order, visible focus, and recovery after sheets, dialogs, or asynchronous updates.
CLI labels, warnings, errors, and state changes must be descriptive and identify the affected target or operation. Future UI controls and dynamic status must expose meaningful accessible names and announcements.
CLI and documentation meaning must not depend on color. Any future UI must provide sufficient contrast, support Reduce Motion, and avoid unnecessary flashing or animation.
Keep CLI output readable as plain text without fixed-width layout assumptions beyond code blocks. Documentation should remain understandable under browser zoom and narrow layouts.
The repository currently ships no project-owned audio or video documentation. Any future media used to explain research must include an equivalent transcript or captioned alternative.
Prefer semantic Markdown and plain text, descriptive actions and errors, deterministic output, and explicit consent before TCC prompts or state mutation. Keep research probes non-interactive unless interaction is essential and documented.
Swift Testing covers reusable helper behavior, but there is no dedicated automated accessibility test suite for the current CLI and Markdown surfaces.
For accessibility-relevant changes, inspect heading order, link meaning, non-color communication, terminal readability, and whether the documented command can be completed from the keyboard.
No recurring VoiceOver or other assistive-technology test matrix is currently recorded. Add scoped evidence before claiming support for a specific assistive technology.
An accessibility-relevant change is ready when the affected surface follows this baseline, its manual checks are recorded, new gaps are listed here or in the roadmap, and no unsupported conformance claim is introduced.
- No formal WCAG audit has been completed.
- No recurring VoiceOver verification matrix exists.
- Raw framework, daemon, and unified-log output may contain inaccessible formatting outside project control.
Track concrete, issue-sized accessibility work in ROADMAP.md when a project-owned surface needs remediation. Add a dedicated test matrix if a graphical or interactive product surface is introduced.
Maintainers changing a project-owned user-facing surface are responsible for updating this document and recording the evidence for their change.
Use a GitHub issue in this repository and identify the command, document, OS version, assistive technology when relevant, expected behavior, and observed barrier. Do not include personal notifications, messages, account data, or sensitive raw captures in a public issue.
Treat loss of access, destructive behavior, or blocked keyboard operation as high priority. Preserve privacy by excluding personal notifications, messages, account data, and raw captures from issue reports.
scripts/repo-maintenance/validate-all.shThis checks repository structure and Swift behavior. It is supporting engineering evidence, not a conformance audit.
Review accessibility whenever a project-owned user-facing surface changes and before making a stronger accessibility claim. No calendar-based audit cadence is currently established.
- 2026-07-17: Established the initial CLI and Markdown accessibility baseline; no formal conformance audit was performed.