SPB Git

Repository Public

accessibility.md 14.2 KB

# 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 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.
  • 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 missingAltText reports 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 Figure elements with the alternative text; equations are Figure elements 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, accent and critical are at or above 4.5:1 on every surface in both appearances.
  • 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.
  • 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.
  • 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.
  • 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.
  • hairline separators 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

  1. Authorise Automation Mode and run UITests/EditorUITests.swift.
  2. A VoiceOver session on the main tasks: open a template, type, format, insert a table and a footnote, review a tracked change, export.
  3. Run Accessibility Inspector's audit on the main window and each sheet.
  4. Validate a tagged PDF with a PDF/UA checker and a screen reader.
Files main
Menu

Theme