SPB Git

Repository Public

accessibility.md 7.9 KB

# Accessibility

Scope: the shared UI layer (Packages/SheetUI) and the app target. Feature panels are not covered here.

# What is supported

Labels and state. Every control of the workbook window has a localized accessibility label; icon-only buttons (ToolButton, colour menus, inspector tabs, close buttons) use their tooltip text. Stateful buttons report « Activé / Désactivé » as their value and the selected trait. Colour swatches are named (« Rouge clair »), not shown as hex codes; a sheet tab reports its position (« Feuille 2 sur 5 ») and its tab colour by name. Decorative icons are hidden. Status messages, entry errors and « Aucun résultat » are posted as announcements (ORIXAccessibility.announce).

The grid (GridView+Accessibility.swift) is one custom-drawn view exposed as a table:

  • label: sheet name + « grille de la feuille »; help: the basic keys;
  • value: one sentence about the active cell: reference, column header, displayed value, formula, note, link, then the selected range with its size (or the list of ranges);
  • children: the visible non-empty cells plus the active cell, at most 600 per screen (GridView.maxAccessibilityChildren), as AXCell elements with label « B3, colonne Revenue », value, frame, row/column index, selected and focused state;
  • header detection for that label: header row of the table containing the cell, else the last frozen row, else the first (or second) row of the used range when it is text above non-text;
  • actions: press on a cell selects it and starts editing; press on the grid edits the active cell; show-menu opens the context menu; setting focus or selection on a cell element moves the selection;
  • notifications: selected cells / selected children / value changed and focused-element changed (to the active cell element) when the selection moves; value changed when contents change; layout and title changed when the sheet changes.

Keyboard. Everything in the menu bar has a command; sheet tabs are focusable (Space shows the sheet, Return renames the active one) and have menu commands: Next/Previous Sheet (⌥⌘→ / ⌥⌘←) and the new Format ▸ Sheet ▸ Rename… (⌥⌘R). Toolbar menus and buttons are standard controls reachable with Full Keyboard Access. The function browser offers « Insérer la fonction » as an accessibility action and in the context menu.

Display options (System Settings ▸ Accessibility ▸ Display):

  • Reduce Motion: the find bar appears without its slide (ORIX.Motion.respecting, isReduced). It is the only animation in SheetUI.
  • Increase Contrast: GridPalette.resolve(dark:increaseContrast:) gives darker gridlines, header separators, header text, frozen-pane line, a stronger selection fill and a thicker selection border; selected tool buttons get an outline. The grid redraws when the option changes.
  • Differentiate Without Colour: selected tool buttons and inspector tabs gain an outline and a heavier glyph. Other states already had a non-colour cue (check mark, bold active tab, icon shapes in the compatibility report, text for Edit/Point mode).

Text size. Settings ▸ Accessibility ▸ default zoom of the grid (75–200 %, step 5), applied to new windows; ⌘+ / ⌘− / ⌘0 and the status-bar menu change it per window. Chrome text uses fixed point sizes and does not follow a system text-size setting.

# Colour contrast (WCAG 2.1)

Measured by ContrastTests in Packages/SheetUI/Tests (prints the full table for both appearances; fails under 4.5:1 for text, 3:1 for glyphs and structural lines). Tokens changed in Design/Tokens.swift:

Pair Before After
textTertiary on surface / canvas / raised, light (#7A8098 → #62697F) 3.91 / 3.59 / 3.44 5.46 / 5.01 / 4.79
textTertiary on raised, dark (#7F86A0 → #8A91AB) 4.36 5.04
accent used as text, light (#0891B2 → new accentText #0A6F8C) 3.68 / 3.38 / 3.23 5.73 / 5.26 / 5.03
white label on prominent button, light (accent → new accentFill #0A6F8C) 3.68 5.73
white label on prominent button, dark (#22D3EE → accentFill #0E7490) 1.81 5.36
danger as text, light (#D4313F → #C62633) 4.87 / 4.47 / 4.28 5.64 / 5.18 / 4.95
warning as text, light (#B86A00 → #995700) 4.12 / 3.78 / 3.62 5.65 / 5.19 / 4.96
success as text, light (#12925A → #0D7A4B) 3.97 / 3.65 / 3.49 5.38 / 4.94 / 4.73
frozen-pane line on grid, light (#A9B0C4 → #858CA3) 2.17 3.35
frozen-pane line on grid, dark (#4A5273 → #626B8F) 2.42 3.54

Unchanged and passing: primary text 16–18.6:1, secondary text 5.5–8.4:1, grid text 18.6 / 16.1, header text 5.82 / 6.73, selected header 4.91 / 7.82, grid error text 4.87 / 6.71, the cyan accent as glyph or selection border 3.2–3.7 (light) and 8.7–10.7 (dark). The cyan accent itself (#0891B2 / #22D3EE) is kept for fills, glyphs and selection.

Below 3:1 on purpose: ordinary gridlines (1.24 light, 1.30 dark) and hairlines are decoration; with Increase Contrast gridlines reach 3.14:1 (light).

Not measured: colours inside feature panels, and any place where a feature uses accent as a text colour or as a button tint under white text (it should use accentText / accentFill).

# What was verified, and how

Automatically (swift test in Packages/SheetUI, 20 tests):

  • the accessibility tree of a real WorkbookView in an offscreen window, read through the system accessibility API (the same interface VoiceOver uses), with the format and the function inspector: 124 and 183 elements; 62 and 68 controls (buttons, menu buttons, pop-ups, check boxes, text fields, disclosure triangles, stepper), 0 without a label. 9 and 7 system parts (scroller pages, stepper arrows, title-bar buttons) are excluded because the system describes them;
  • the find bar's fields, buttons and four check boxes are labelled;
  • grid: header-context labels, the value sentence with formula and range, 12 cell children for a 12-cell sheet, the bound on children with thousands of visible cells, press starts editing, focus moves the selection, an empty active cell stays reachable;
  • component labels and On/Off values, the localized: variants, undo names through the catalog;
  • contrast of every pair listed above, in light and dark.

These tree tests need the process that runs them to be allowed under Privacy & Security ▸ Accessibility; they are disabled (not failed) otherwise.

By eye, on screenshots in French and English (/tmp/orix-l10n-shots/): main window light and dark, function browser, find bar, a 760 × 480 window, Settings, Help, Page Setup.

Not verified:

  • VoiceOver has not been listened to. Nobody has navigated the app with VoiceOver, so what is actually spoken, the reading order, whether the focus follows the active cell while arrowing and whether the announcements are heard are unconfirmed. The notifications are posted; their effect is not tested.
  • Apple's performAccessibilityAudit() was not run (there is no UI-test target).
  • Increase Contrast, Differentiate Without Colour and Reduce Motion were not switched on during a run; the code paths are covered by unit tests of the palette only.
  • Full Keyboard Access, Voice Control and Switch Control were not exercised.
  • Settings, Page Setup, Help and the compatibility report were not put through the tree audit (the test harness lives in the SheetUI package); their labels were added by reading the code.

# Known gaps

  • Sheet-tab actions other than show and rename (duplicate, move, colour, hide, delete) are only in the tab's context menu; Duplicate and Delete also exist in Format ▸ Sheet.
  • Column and row headers, embedded objects (charts) and the fill handle are not accessibility elements; rows and columns are selected with ⇧Space / ⌃Space, resized from the inspector.
  • A cell's header context is a heuristic and can be wrong for sheets with several tables.
  • Function summaries and formula error messages are announced in English.
Files main
Menu

Theme