Skip to content

Accessibility

SciFlow targets WCAG 2.1 AA compliance. This guide covers what the editor provides out of the box and what host applications should consider when embedding it.

Principles

  1. Semantic HTML first — Native elements (<button>, <select>, <label>, <input>, <ol>, <li>) are used wherever possible instead of generic <div> or <span> elements.
  2. Every interactive element has an accessible name — All buttons and controls use aria-label values pulled from the i18n system, so labels are always localizable.
  3. Decorative elements are hidden — Icons and drag indicators use aria-hidden="true".
  4. Keyboard accessible — Drag-and-drop interactions always have a keyboard-accessible button alternative.
  5. State communicated to assistive technology — Toggle buttons use aria-pressed, navigation items use aria-current, and live regions use role="alert" or role="status".
  6. Color contrast — Muted text at 70 % opacity gives ≥ 5 : 1 contrast on light backgrounds, meeting AA requirements.

Component Patterns

Format Bar (<sciflow-formatbar>)

  • Every button has an aria-label describing its action.
  • Toggle buttons (bold, italic, etc.) use aria-pressed to indicate active state.
  • Tooltips are implemented with title and a CSS ::after pseudo-element on :focus-visible.

Outline (<sciflow-outline>)

  • Heading items use role="button" with tabindex="0" for keyboard activation.
  • Figures are focusable list items.
  • The currently active item is marked with aria-current="true".
  • An insert button provides keyboard access to cross-reference insertion (alternative to drag-and-drop).

Reference List (<sciflow-reference-list>)

  • Uses native <ol> / <li> structure for the reference list.
  • Each reference has a cite button for keyboard-based citation insertion (alternative to drag-and-drop).

Selection Editor (<sciflow-selection-editor>)

  • Uses role="form" with aria-label on sidebars.
  • All inputs are paired with <label for>.
  • Math previews use role="img" with aria-label.
  • Validation errors use role="alert" for immediate announcement.
  • Hint text uses aria-describedby on corresponding inputs.

Keyboard Navigation

The editor inherits ProseMirror's keyboard support. Key interactions:

Key Action
Tab In tables: move to next cell
Shift-Tab In tables: move to previous cell
Mod-b Toggle bold
Mod-i Toggle italic
Mod-m Insert/wrap math
Enter Split block or create new list item
Backspace / Delete At citation boundary: select citation as a unit before deleting
# + Space Convert to heading (levels 1–6 by number of #)
- / * / + + Space Start bullet list
1. + Space Start ordered list
$$ + Space Start display math

Focus Indicators

All interactive elements use a consistent :focus-visible outline:

outline: 2px solid #2563eb;
outline-offset: 2px;

i18n Integration

All aria-label values come from the translation dictionary, so switching the locale property on <sciflow-editor> updates both visible UI text and screen reader labels. When adding custom UI, use the translation function t() for all accessible names.

Translation keys live in:

  • Type definitions: packages/editor/core/src/lib/i18n/types.ts
  • English: packages/editor/core/src/lib/i18n/en.ts
  • German: packages/editor/core/src/lib/i18n/de.ts

Custom Events for Assistive Workflows

Two custom events provide keyboard-accessible alternatives to drag-and-drop:

  • sciflow-insert-cross-reference — Fired from the outline's insert button. Payload: { type, refType, id, href, text }.
  • sciflow-insert-citation — Fired from the reference list's cite button. Payload: { reference }.

Recommendations for Host Applications

  1. Don't break the Shadow DOM boundary — SciFlow's ARIA attributes are inside the shadow root. Avoid overriding them with conflicting attributes on the host element.
  2. Provide skip links — If the editor is embedded in a larger page, add a skip link so keyboard users can jump past it.
  3. Label the editor region — Add aria-label="Manuscript editor" (or equivalent) on a wrapper <section> or <main> around the editor.
  4. Test with a screen reader — VoiceOver (macOS), NVDA (Windows), or Orca (Linux) against the default feature set. Pay particular attention to citation and math node announcements.
  5. Respect prefers-reduced-motion — The editor itself does not use animations, but if your host page adds transitions around the editor, wrap them in a prefers-reduced-motion media query.