Repository Public
1<!--2ORIX Docs3File: docs/reports/accessibility.md4Description: Accessibility review of ORIX Docs 1.0.0 by code inspection: what the canvas and the controls expose, keyboard access, colour independence, alternative text, contrast of the token palette, and the gaps.5Author: Simon-Pierre Boucher6Contact: contact@spboucher.ai7-->8# Accessibility review910**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](../development/testing.md#xcuitest-suite)).1112Related documents: [text-engine.md, section 14](../architecture/text-engine.md#14-accessibility) and [design-system.md, accessibility conventions](../design/design-system.md#accessibility-conventions).1314## The document canvas1516The 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`.1718| Accessibility member | What the canvas returns |19|---|---|20| `isAccessibilityElement` | `true` — the canvas is one element |21| Role, role description | `textArea`, "document text" |22| Label | "Document" |23| Identifier | `document-canvas` |24| Help | "Page x of y" |25| 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 |26| Number of characters | Length of that text |27| Selected text | The selected text |28| Selected text range (get) | The selection as a range in the flat text |29| Selected text range (set) | Moves the selection; an assistive tool can place the caret and select |30| Insertion point line number | Index of the caret's paragraph |31| String for range | Substring of the flat text, clamped |32| Range for line, line for index | Per **paragraph** |33| Frame for range | The caret rectangle at the range's start, extended to its end when on the same page, in screen coordinates |34| Visible character range | The whole story |35| Notifications | `valueChanged` after a document change, `selectedTextChanged` after a selection change |3637Limits, as recorded in [text-engine.md](../architecture/text-engine.md#14-accessibility):3839* A "line" is a paragraph, not a visual line.40* The visible range is reported as the whole story, not what is on screen.41* **No attributed text**: styles, heading levels, links, tracked changes and comments are not conveyed.42* **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.43* The value cannot be set through accessibility (typing works; programmatic replacement does not).44* The flat text is rebuilt on each query, which costs time on long documents.45* Only the story being edited is exposed: while the caret is in the body, headers, footers and notes are not part of the value.4647## Labels and identifiers on controls4849Counts 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.5051| Modifier | Occurrences | Files |52|---|---:|---:|53| `accessibilityLabel` | 124 | 34 |54| `accessibilityIdentifier` | 232 | 36 |55| `accessibilityAddTraits` | 48 | 26 |56| `accessibilityElement` | 37 | 21 |57| `accessibilityHidden` | 32 | 21 |58| `accessibilityValue` | 12 | 10 |59| `accessibilityHint` | 10 | 7 |6061By 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).6263Conventions applied by the shared components ([design-system.md](../design/design-system.md#accessibility-conventions)):6465* icon-only controls (`BarButton`, `GlyphButton`, `ColorMenu`, `SwatchMenu`, inspector tab buttons) use their help text as accessibility label and as tooltip;66* 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;67* section titles in inspectors and sheets carry `.isHeader`;68* decorative images are hidden from accessibility; the ruler is hidden as a whole;69* identifiers are stable (`cmd-<command>`, `mode-<mode>`, `inspector-tab-<tab>`, `sheet-primary`, `sheet-cancel`, `status-pages`, `status-words`…).7071What 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.7273## Keyboard access7475* **Menus.** `EditorCommand` (`App/Sources/Document/Commands.swift`) defines 102 commands; according to the design system, every one is reachable from the main menu built in `App/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.76* **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.77* **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](../architecture/text-engine.md#9-keyboard-input)).78* **Sheets** answer Return and Escape.79* **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](test-results.json)).8081Not 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).8283## Independence from colour8485* **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`](../screenshots/10-track-changes.png)).86* **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`](../screenshots/11-document-comparison.png)).87* **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").88* **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.8990Comments are shown in the page by a tint only; the comment itself is listed, with its anchor text, in the Review sidebar.9192## Alternative text9394* Images carry an alternative text, edited in the Object inspector (field identifier `object-alt-text`); shapes fall back to their text.95* The auditor check `missingAltText` reports every image whose alternative text is empty ([audit.md](../architecture/audit.md#checks-and-thresholds)).96* 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](../compatibility/formats.md#summary)).97* In a tagged PDF, images and shapes are `Figure` elements with the alternative text; equations are `Figure` elements whose description is their LaTeX source ([pdf.md](../architecture/pdf.md#structure-tags)).9899The PDF tag structure is partial and **no PDF/UA conformance is claimed** ([pdf.md](../architecture/pdf.md#what-is-not-claimed)).100101## Contrast of the token palette102103WCAG 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.104105Surfaces — `chrome` (bars, sidebars, inspectors): `#F7F7FA` light, `#171922` dark; `surface`: `#FFFFFF` / `#1E2130`; `surfaceRaised`: `#FFFFFF` / `#262A3B`; `canvas` (the desk behind pages): `#E9EAF0` / `#0E1017`.106107**Light appearance**108109| Foreground token | Value | on `chrome` | on `surface` | on `canvas` |110|---|---|---:|---:|---:|111| `text` | `#16181D` | 16.61 | 17.76 | 14.79 |112| `textSecondary` | `#5B6170` | 5.80 | 6.20 | 5.16 |113| `textTertiary` | `#8A8FA3` | 3.00 | 3.21 | 2.68 |114| `accent` | `#4F46E5` | 5.88 | 6.29 | 5.24 |115| `secondary` (amber) | `#D97706` | 2.98 | 3.19 | 2.65 |116| `positive` | `#15803D` | 4.69 | 5.02 | 4.18 |117| `warning` | `#B45309` | 4.70 | 5.02 | 4.18 |118| `critical` | `#BE123C` | 5.88 | 6.29 | 5.24 |119120**Dark appearance**121122| Foreground token | Value | on `chrome` | on `surface` | on `surfaceRaised` | on `canvas` |123|---|---|---:|---:|---:|---:|124| `text` | `#ECEDF3` | 15.00 | 13.66 | 12.17 | 16.26 |125| `textSecondary` | `#9BA1B5` | 6.81 | 6.20 | 5.52 | 7.38 |126| `textTertiary` | `#6C7289` | 3.68 | 3.35 | 2.98 | 3.99 |127| `accent` | `#818CF8` | 5.87 | 5.35 | 4.77 | 6.37 |128| `secondary` (amber) | `#FBBF24` | 10.50 | 9.56 | 8.52 | 11.38 |129| `positive` | `#4ADE80` | 10.05 | 9.16 | 8.16 | 10.90 |130| `warning` | `#FBBF24` | 10.50 | 9.56 | 8.52 | 11.38 |131| `critical` | `#FB7185` | 6.51 | 5.93 | 5.28 | 7.06 |132133White 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.134135Reading the tables:136137* `text`, `textSecondary`, `accent` and `critical` are at or above 4.5:1 on every surface in both appearances.138* **`textTertiary` is 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.139* **The light-appearance amber `secondary` is at about 3:1** (2.65 to 3.19): adequate for large text and icons on white, not for small text.140* `positive` and `warning` in the light appearance pass on `chrome` and `surface` (4.69 to 5.02) and fall to 4.18 on the canvas colour.141* 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.142* `hairline` separators are between 1.09 and 1.46 against the surfaces. They are decorative dividers, not the only boundary of a control.143144Not 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`](../screenshots/16-dark-mode.png)).145146## Gaps147148| Gap | Detail |149|---|---|150| **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. |151| The XCUITest suite, which reads the canvas through its accessibility value, was not run. | [testing.md](../development/testing.md#xcuitest-suite) |152| **Tables in the canvas are exposed as text**, not as accessibility tables. | "The document canvas" above |153| 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 |154| **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` |155| **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` |156| **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](../design/design-system.md#type-ramp-orixfont) |157| Tertiary text and light-appearance amber contrast. | "Contrast" above |158| Dictation, Voice Control and Switch Control were not tried. | [text-engine.md](../architecture/text-engine.md#15-limits) |159| Full Keyboard Access through panels was not verified. | "Keyboard access" above |160| Exported PDFs: partial tag structure, no document language, no PDF/UA validation. | [pdf.md](../architecture/pdf.md#known-limits) |161| The French interface was not reviewed for the wording of accessibility labels. | [README](../../README.md#localization) |162163## What would turn this review into evidence1641651. Authorise Automation Mode and run `UITests/EditorUITests.swift`.1662. A VoiceOver session on the main tasks: open a template, type, format, insert a table and a footnote, review a tracked change, export.1673. Run Accessibility Inspector's audit on the main window and each sheet.1684. Validate a tagged PDF with a PDF/UA checker and a screen reader.169