Accessibility review
Nature of this document. This is a review of the source code made on 2026-11-21, with counts taken by grep and contrast ratios computed from the colour tokens. It is not a test with assistive technology and not a certification against WCAG or any other standard. No VoiceOver session with a human listener took place. The XCUITest suite, which would have driven the application through the real accessibility interface, was not run (testing.md).
Related documents: text-engine.md, section 14 and design-system.md, accessibility conventions.
The document canvas
The page area is a custom NSView, so everything NSTextView would expose had to be written. The implementation is at the end of App/Sources/Canvas/EditorCanvasView+Mouse.swift ("MARK: Accessibility"), with the notifications and the identifier in EditorCanvasView.swift.
| Accessibility member | What the canvas returns |
|---|---|
isAccessibilityElement |
true — the canvas is one element |
| Role, role description | textArea, "document text" |
| Label | "Document" |
| Identifier | document-canvas |
| Help | "Page x of y" |
| Value | The story being edited (body, or the header, footer or note the caret is in) as flat text: paragraphs in reading order, table cells included, separated by newlines; each inline object (image, equation, citation, note mark…) replaced by a space |
| Number of characters | Length of that text |
| Selected text | The selected text |
| Selected text range (get) | The selection as a range in the flat text |
| Selected text range (set) | Moves the selection; an assistive tool can place the caret and select |
| Insertion point line number | Index of the caret's paragraph |
| String for range | Substring of the flat text, clamped |
| Range for line, line for index | Per paragraph |
| Frame for range | The caret rectangle at the range's start, extended to its end when on the same page, in screen coordinates |
| Visible character range | The whole story |
| Notifications | valueChanged after a document change, selectedTextChanged after a selection change |
Limits, as recorded in text-engine.md:
- A "line" is a paragraph, not a visual line.
- The visible range is reported as the whole story, not what is on screen.
- No attributed text: styles, heading levels, links, tracked changes and comments are not conveyed.
- No child elements: tables are exposed as the text of their cells, not as accessibility tables with rows and columns; images, shapes and equations are a space in the text, and their alternative text is not exposed through the canvas.
- The value cannot be set through accessibility (typing works; programmatic replacement does not).
- The flat text is rebuilt on each query, which costs time on long documents.
- Only the story being edited is exposed: while the caret is in the body, headers, footers and notes are not part of the value.
Labels and identifiers on controls
Counts in App/Sources (59 Swift files), taken with grep -rho <word> App/Sources | wc -l. They count occurrences in the source — a shared component that sets a label counts once however many controls it produces.
| Modifier | Occurrences | Files |
|---|---|---|
accessibilityLabel |
124 | 34 |
accessibilityIdentifier |
232 | 36 |
accessibilityAddTraits |
48 | 26 |
accessibilityElement |
37 | 21 |
accessibilityHidden |
32 | 21 |
accessibilityValue |
12 | 10 |
accessibilityHint |
10 | 7 |
By folder (accessibilityLabel / accessibilityIdentifier): Sheets 41 / 79, Inspector 37 / 51, Sidebar 13 / 41, Automation 11 / 16, DesignSystem 11 / 8, Intelligence 6 / 15, App 4 / 15, Canvas 1 / 0 (the canvas sets its identifier with the AppKit setter, which this search pattern does not match), Workspace 0 / 7 (its buttons are DesignSystem components, which carry the labels).
Conventions applied by the shared components (design-system.md):
- icon-only controls (
BarButton,GlyphButton,ColorMenu,SwatchMenu, inspector tab buttons) use their help text as accessibility label and as tooltip; - state is a trait or a value: toggles add
.isSelected, collapsible groups report "Expanded" or "Collapsed", a colour swatch reports its hex value or "None", pop-ups report the current choice; - section titles in inspectors and sheets carry
.isHeader; - decorative images are hidden from accessibility; the ruler is hidden as a whole;
- identifiers are stable (
cmd-<command>,mode-<mode>,inspector-tab-<tab>,sheet-primary,sheet-cancel,status-pages,status-words…).
What this review did not do: enumerate every control on screen and confirm that each has a meaningful, correctly localised label. The counts show that the convention is applied widely; they do not prove that it is applied everywhere.
Keyboard access
- Menus.
EditorCommand(App/Sources/Document/Commands.swift) defines 102 commands; according to the design system, every one is reachable from the main menu built inApp/Sources/App/AppDelegate.swift(File, Edit, View, Insert, Format, Table and further menus). 45 commands have a keyboard shortcut, among them: bold, italic, underline (⌘B, ⌘I, ⌘U), alignment, lists, indent, the Body and Heading 1–3 styles (⌥⌘0–3), page break (⌘↩), footnote, equation, link (⌘K), comment, citation, table, track changes (⇧⌘E), the six modes (⌃⌘1–6), sidebar, inspector, ruler, zoom, find (⌘F, ⌘G, ⇧⌘G), export and export as PDF. - Standard items carry the standard shortcuts: New, Open, Save, Print, Page Setup, Undo, Redo, Cut, Copy, Paste, Paste and Match Style, Select All, Full Screen, Settings.
- In the text, the canvas handles the system key-binding commands for movement and selection by character, word, line, paragraph, page and document, deletion by character, word and line, Tab and Shift-Tab in tables and lists, and Escape to leave a header, footer, note or Focus mode (text-engine.md, section 9).
- Sheets answer Return and Escape.
- Evidence. The interaction self-test drives typing, movement, selection, shortcuts, tables, footnotes, headers and find through key events: 19 scenarios, 19 passed (test-results.json).
Not verified: full keyboard navigation of the sidebar and inspector controls (Full Keyboard Access), and focus order. Some actions have a pointer-only path alongside their menu command (dragging a column boundary or an object handle; the same values can be typed in the Table and Object inspectors).
Independence from colour
- Tracked changes. Insertions are underlined and deletions struck through, in addition to the author's colour; lines that carry a change have a change bar in the margin; the Review sidebar names each change in words ("Inserted", "Deleted", "Formatted") with its author (
10-track-changes.png). - Comparison. Rows are labelled "Modified", "Moved to block n", "Moved from block n" with an icon, and inserted and deleted words are underlined and struck through (
11-document-comparison.png). - Chrome. The selected inspector tab has a bar under it; notices carry an icon and a spoken prefix; "None" in a swatch menu is struck through; auditor findings state their severity in words ("0 errors", "5 warnings", "3 notes").
- Invalid equations are shown as their source in red monospaced text: the change of typeface and the visible source carry the information, not the colour alone.
Comments are shown in the page by a tint only; the comment itself is listed, with its anchor text, in the Review sidebar.
Alternative text
- Images carry an alternative text, edited in the Object inspector (field identifier
object-alt-text); shapes fall back to their text. - The auditor check
missingAltTextreports every image whose alternative text is empty (audit.md). - Alternative text survives the DOCX round trip (
wp:docPr descr) and HTML export, and is written as[alt text]in plain text; it is dropped by RTF (formats.md). - In a tagged PDF, images and shapes are
Figureelements with the alternative text; equations areFigureelements whose description is their LaTeX source (pdf.md).
The PDF tag structure is partial and no PDF/UA conformance is claimed (pdf.md).
Contrast of the token palette
WCAG 2 contrast ratios computed from the hex values of ORIX.Palette in App/Sources/DesignSystem/Tokens.swift (relative luminance of sRGB values; ratio = (L1 + 0.05) / (L2 + 0.05)). For reference, WCAG AA asks 4.5:1 for normal text and 3:1 for large text and for the visual information of interface components.
Surfaces — chrome (bars, sidebars, inspectors): #F7F7FA light, #171922 dark; surface: #FFFFFF / #1E2130; surfaceRaised: #FFFFFF / #262A3B; canvas (the desk behind pages): #E9EAF0 / #0E1017.
Light appearance
| Foreground token | Value | on chrome |
on surface |
on canvas |
|---|---|---|---|---|
text |
#16181D |
16.61 | 17.76 | 14.79 |
textSecondary |
#5B6170 |
5.80 | 6.20 | 5.16 |
textTertiary |
#8A8FA3 |
3.00 | 3.21 | 2.68 |
accent |
#4F46E5 |
5.88 | 6.29 | 5.24 |
secondary (amber) |
#D97706 |
2.98 | 3.19 | 2.65 |
positive |
#15803D |
4.69 | 5.02 | 4.18 |
warning |
#B45309 |
4.70 | 5.02 | 4.18 |
critical |
#BE123C |
5.88 | 6.29 | 5.24 |
Dark appearance
| Foreground token | Value | on chrome |
on surface |
on surfaceRaised |
on canvas |
|---|---|---|---|---|---|
text |
#ECEDF3 |
15.00 | 13.66 | 12.17 | 16.26 |
textSecondary |
#9BA1B5 |
6.81 | 6.20 | 5.52 | 7.38 |
textTertiary |
#6C7289 |
3.68 | 3.35 | 2.98 | 3.99 |
accent |
#818CF8 |
5.87 | 5.35 | 4.77 | 6.37 |
secondary (amber) |
#FBBF24 |
10.50 | 9.56 | 8.52 | 11.38 |
positive |
#4ADE80 |
10.05 | 9.16 | 8.16 | 10.90 |
warning |
#FBBF24 |
10.50 | 9.56 | 8.52 | 11.38 |
critical |
#FB7185 |
6.51 | 5.93 | 5.28 | 7.06 |
White text on the accent gradient used for the selected mode and prominent buttons (#7C74FF → #4F46E5 → #3730A3): 3.62, 6.29 and 9.93 at the three stops.
Reading the tables:
text,textSecondary,accentandcriticalare at or above 4.5:1 on every surface in both appearances.textTertiaryis below 4.5:1 everywhere (2.68 to 3.99) and below 3:1 on the light canvas and on the dark raised surface. Where it is used for information rather than decoration (counts, dates, field units), that text does not meet AA for normal text.- The light-appearance amber
secondaryis at about 3:1 (2.65 to 3.19): adequate for large text and icons on white, not for small text. positiveandwarningin the light appearance pass onchromeandsurface(4.69 to 5.02) and fall to 4.18 on the canvas colour.- White on the lightest stop of the accent gradient is 3.62: adequate for the semibold labels of large buttons, below 4.5:1 for small text.
hairlineseparators are between 1.09 and 1.46 against the surfaces. They are decorative dividers, not the only boundary of a control.
Not covered by these numbers: text drawn with opacity, the selection tint (accent at 26 % opacity), system colours used directly, and the document's own colours, which the author chooses. The page itself is white with the document's text colour in both appearances (16-dark-mode.png).
Gaps
| Gap | Detail |
|---|---|
| No VoiceOver session with a listener. | What is announced, in which order, and whether editing by voice-over is practical is unknown. This is the largest gap. |
| The XCUITest suite, which reads the canvas through its accessibility value, was not run. | testing.md |
| Tables in the canvas are exposed as text, not as accessibility tables. | "The document canvas" above |
| No structure in the canvas: headings, lists, links, footnote marks, tracked changes and comments are not announced as such; images and equations are a space. | "The document canvas" above |
Reduce Motion is not handled. The design tokens define two animations (0.16 s ease-out, a 0.32 s spring) and the sources call withAnimation or .animation in 13 places; none checks the system setting. |
Tokens.swift; no occurrence of accessibilityReduceMotion in App/Sources |
| Increase Contrast is not handled. The palette has one light and one dark value per token. | Tokens.swift; no occurrence of colorSchemeContrast in App/Sources |
| Dynamic Type does not apply: the chrome uses fixed sizes (10.5 to 15 pt for most text). The document itself can be zoomed. | design-system.md |
| Tertiary text and light-appearance amber contrast. | "Contrast" above |
| Dictation, Voice Control and Switch Control were not tried. | text-engine.md |
| Full Keyboard Access through panels was not verified. | "Keyboard access" above |
| Exported PDFs: partial tag structure, no document language, no PDF/UA validation. | pdf.md |
| The French interface was not reviewed for the wording of accessibility labels. | README |
What would turn this review into evidence
- Authorise Automation Mode and run
UITests/EditorUITests.swift. - A VoiceOver session on the main tasks: open a template, type, format, insert a table and a footnote, review a tracked change, export.
- Run Accessibility Inspector's audit on the main window and each sheet.
- Validate a tagged PDF with a PDF/UA checker and a screen reader.