Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Accessibility: Comply with WCAG 2 #10795

Open
personalizedrefrigerator opened this issue Jul 29, 2024 · 5 comments
Open

Accessibility: Comply with WCAG 2 #10795

personalizedrefrigerator opened this issue Jul 29, 2024 · 5 comments
Labels
accessibility Related to accessibility desktop All desktop platforms enhancement Feature requests and code enhancements high High priority issues mobile All mobile platforms

Comments

@personalizedrefrigerator
Copy link
Collaborator

personalizedrefrigerator commented Jul 29, 2024 •
edited
Loading

Summary

[ Progress: Desktop ] | [ Progress: Mobile ]

This issue tracks Joplin's progress towards compliance with the WCAG (Web Content Accessibility Guidelines) v2.2.

About the WCAG

The WCAG (Web Content Accessibility Guidelines) is a set of guidelines for improving web accessibility.

The WCAG is divided into success criteria. Each is labelled with "Level A", "Level AA", or "Level AAA". These correspond to different conformance levels.

Conformance levels

There are three different conformance levels1:

  • Level A: All Level A success criteria are satisfied.
    • This is the lowest level of conformance.
  • Level AA: All Level A and Level AA success criteria are satisfied.
  • Level AAA: All success criteria are satisfied.

According to WebAIM.org2,

Most websites should aim for Level AA conformance. Depending on the target users, some Level AAA success criteria such as Reading Level, Contrast (Enhanced), Target Size, or others may be beneficial to implement. Very few websites can claim full Level AAA conformance—not even webaim.org or the WCAG website itself!

The WCAG's definition of the different conformance levels1 confirms WebAIM's statement that Level AAA is not always achievable:

Note

It is not recommended that Level AAA conformance be required as a general policy for entire sites because it is not possible to satisfy all Level AAA success criteria for some content.

Based on the above, for now, this issue targets Level AA conformance with the WCAG.

This issue: General tasks

  • Find existing accessibility issues & link them to this task.
  • Go through the WCAG 2.2 quick reference and evaluate each task. Create issues for failures.

Notes: In this issue, different task priorities are marked differently. For example,

  • [❗] This is a task that must be completed.
    • This should be used mostly for level A tasks.
  • [🟡] This is a task that should be completed.
    • This should be used mostly for level AA tasks.
  • [🔷] This is a low priority task that may be completed.
  • [🔎] The priority of this task is unclear and requires additional research.

Note

The tasks below are a work-in-progress and based on the WCAG 2.2 spec. Completing the tasks below does not guarantee compliance with the spec.

Desktop

Note

Several relevant changes were made shortly before this issue was created:

1. Perceivable

Summary: All non-decorative components of the user interface should be described in a way perceivable to the user.

1.1.1 Non-text content (Level A)

All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for situations listed below.

To meet this requirement, all inputs controls and inputs must be labeled.

Tasks:

1.2.1. Audio-only and Video-only, 1.2.2. Captions (Prerecorded), and 1.2.3. Audio Description or Media Alternative (Prerecorded)

Joplin allows users to include prerecorded audio and video in notes. When included as a link (e.g. [link](:/resourceidhere000000000000000000)), the generated HTML video element has no associated description.

In the desktop app, we should:

  • [🔎] How can we make it easy for users to add alternative text to videos and audio elements?

Also see the spec for related tasks.

1.3 Adaptable

Summary: Content must be presentable in different ways without losing information.

1.3.1. Info and Relationships (Level A)

Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text. (Level A)

1.3.2. Meaningful Sequence (Level A)

When the sequence in which content is presented affects its meaning, a correct reading sequence can be programmatically determined. (Level A)

  • Joplin currently adjusts focus order by overriding tab and shift-tab. See SC 2.4.3.
  • [🔎] Meaningful sequences can be particularly easy to disrupt using flex-order or similar order-changing CSS. Are we using flex-order anywhere? See F1.
  • [🔎] Does this include RTL support? (Related issue).

1.3.3. Sensory Characteristics (Level A)

Instructions provided for understanding and operating content do not rely solely on sensory characteristics of components such as shape, size, visual location, orientation, or sound. (Level A)

Note: §1.4 covers color guidelines.

This task refers to instructions.
For example, "press the red button in the bottom right corner of the screen to edit" would be bad.

We should:

  • [❗] Check setting item descriptions.
  • [❗] Check the welcome notes.
  • (Different task) Check the documentation website.

1.3.4. Orientation (Level AA)

Content does not restrict its view and operation to a single display orientation, such as portrait or landscape, unless a specific display orientation is essential.

Currently, Joplin doesn't restrict devices to a single orientation. However, it may be difficult to use the desktop app on a phone-sized device in portrait mode. In particular, without moving the sidebars from "View" > "Change application layout".

  • [🔎] Does this require better by-default support for small screens? If so, a possible solution could be to minimize secondary panels (e.g. by moving them to an overflow tab) when low on space.

1.4 Distinguishable

Make it easier for users to see and hear content including separating foreground from background

Color for distinguishing content (§1.4.1, A):

  • [🔎] Check color contrast between neighboring content.
    • Add a high-contrast theme for the markdown editor?

Audio control (§1.4.2, A)

If any audio on a Web page plays automatically for more than 3 seconds, either a mechanism is available to pause or stop the audio, or a mechanism is available to control audio volume independently from the overall system volume level.

At present, all audio should be user-created (and only auto-play if this is set by the user in HTML). Additionally, audio included with [](:/resourceidhere) has Electron-provided controls.

Minimum contrast (§1.4.3, AA):

  • [🟡] Improve color contrast of "Conflicts" in the sidebar with the default theme. (Currently uses 3.32:1 contrast).
  • [🟡] Improve the color contrast of "All notes" in the sidebar. (Currently has 3.35:1 contrast).
    • When active, "All notes" has sufficient contrast. This might be sufficient, given §1.4.3's "incidental" exception.
  • [🟡] Improve color contrast of setting item descriptions -- Desktop: Fix errors found by automated accessibility testing #11246
  • [🟡] Improve link URL contrast (currently has 3.81:1 contrast).
  • [🟡] Improve notebook list scrollbar contrast in the default light theme.
    • Current contrast is 1.22:1 when not active, 1.6:1 when active.

Note: It might not be necessary to improve contrast of inactive buttons (despite having low contrast). See discussion and "incidental" in §1.4.3.

Resize text (§1.4.4, AA):

  • Joplin supports zoom with ctrl-+ and ctrl--
  • [❗] Zooming to 200% causes items (e.g. toolbar items) to be offscreen (F69)

Avoid images of text unless customizable/essential (§1.4.5, AA):

  • For the most part, Joplin doesn't seem to rely on images of text. However, the welcome notes does include SubNotebooks.png, which includes text that isn't presented elsewhere.

Note: See the WCAG spec for §1.4.6-1.4.9 (all level AAA).

1.4.10: Reflow (AA)

Content can be presented without loss of information or functionality, and without requiring scrolling in two dimensions for:

  • Vertical scrolling content at a width equivalent to 320 CSS pixels;
  • Horizontal scrolling content at a height equivalent to 256 CSS pixels;

Except for parts of the content which require two-dimensional layout for usage or meaning.

  • [🟡] By default, a width of 320 CSS pixels shows only the notebooks list and part of the note list (everything else is hidden). Fix this.
  • Height of 256 CSS pixels:
    • [❗] Some buttons in the multi-note selection menu can't be accessed (clipped).

1.4.11: Non-text contrast (AA)

The visual presentation of the following have a contrast ratio of at least 3:1 against adjacent color(s):

  • User Interface Components: Visual information required to identify user interface components and states, except for inactive components or where the appearance of the component is determined by the user agent and not modified by the author;
  • Graphical Objects: Parts of graphics required to understand the content, except when a particular presentation of graphics is essential to the information being conveyed.
  • [🔎] Check user interface components (non-text) in the desktop app for contrast in the default theme.

1.4.12: Text spacing (AA)

Users should be able to override Joplin's styles (through OS accessibility settings?) in the following ways and still use the app:

  • Set line spacing to at least 1.5 times the font size.
  • Set spacing following paragraphs to at least 2 times the font size.
  • Set word spacing to at least 0.16 times the font size.

In particular, content should not be clipped.

  • [🔎] How can this be done with Joplin (if at all)? Is Joplin still usable in this case?

1.4.13: Content on Hover or Focus (AA)

When content (e.g. tooltips) can be shown by hovering with the mouse pointer, it should also be possible to show them with a keyboard.

At present, this isn't possible with most title= tooltips (at least on Linux). However, the WCAG includes an exception that might be relevant here:

Exception: The visual presentation of the additional content is controlled by the user agent and is not modified by the author.

As an Electron app, however, Joplin is the user agent, and so this might not apply.

  • [🟡] Currently, most tooltips can only be shown by hovering.

2. Operable

User interface components and navigation must be operable.

2.1.1. Keyboard (A)

All functionality of the content is operable through a keyboard interface without requiring specific timings for individual keystrokes, except where the underlying function requires input that depends on the path of the user's movement and not just the endpoints. (Level A)

2.1.2. No Keyboard Trap (A)

If keyboard focus can be moved to a component of the page using a keyboard interface, then focus can be moved away from that component using only a keyboard interface, and, if it requires more than unmodified arrow or tab keys or other standard exit methods, the user is advised of the method for moving focus away. (Level A)

  • [❗] CodeMirror 6 editor, Rich Text Editor: Inform the user that esc before tab or shift-tab escapes the focus trap.
    • Alternatively, let ctrl-m escape focus and inform the user of this. One possible method could be to add a menubar item with associated keyboard shortcut.
    • It's also possible to escape the focus trap using the arrow keys. However, we've received feedback that this can make the editor more difficult to use (though we've also received feedback that it's useful). Perhaps this behavior should be reverted?
  • [🔷] CodeMirror 6 editor: Move the focus when pressing shift-tab at the beginning of the editor, without need for a leading esc modifier.
  • [❗] Make the CodeMirror 6-based markdown editor the default (Desktop: Resolves #9450: Make the beta markdown editor the default #10796).
    • The CodeMirror 5 editor traps focus.
  • [❗] Rich Text Editor & CodeMirror: Allow escaping focus with keys that don't rely on specific timings (ctrl-m seems to be a standard way of switching focus. See, for example, VSCode.).
    • §2.1 includes the "without specific timings" requirement.

2.1.3. Keyboard (No Exception) (AAA):

Equivalent to §2.1.1, but removes exceptions.

2.1.4. Character Key Shortcuts (A)

If there are unmodified keyboard shortcuts implemented with just a letter/punctuation/special character, then at least one of the following must be true:

  • It can be turned off.
  • The shortcut can be remapped to some other combination.
  • The shortcut is specific to a user interface component and is active only when it has focus.

Joplin doesn't seem to have character key shortcuts.

2.2. Provide users enough time to read and use content

§2.2.1: This section seems to be mostly concerned with auto-log-out/locking. I don't believe that Joplin puts a time limit on any activities.

2.2.2. Pause, Stop, Hide

For moving, blinking, scrolling, or auto-updating information, all of the following are true: (Level A)

This includes:

Auto-updating: For any auto-updating information that (1) starts automatically and (2) is presented in parallel with other content, there is a mechanism for the user to pause, stop, or hide it or to control the frequency of the update unless the auto-updating is part of an activity where it is essential.

  • [🟡] Provide a way to hide synchronization status while keeping the sidebar open. (Issue Add a button to hide the synchronisation panel #8611)
    • Currently, it is possible to hide the sync status button by hiding the sidebar. However, this also involves hiding the note list. There should be a way to hide the sync status animation without hiding the sidebar.

§2.2.3-2.2.6 (Level AAA): Concerned with interruptions and timing.

2.3. Seizures: Don't design content in a way that is known to cause seizures

§2.3.1 Three Flashes or Below Threshold: Web pages do not contain anything that flashes more than three times in any one second period, or the flash is below the general flash and red flash thresholds. (Level A)

  • [🔎] Is it possible to cause the UI to flash more than three times? (Check cases involving dark mode transitioning to light mode and switching notes with resources that need to load).
  • §2.3.2 (Level AAA) seems to be equivalent to §2.3.1, but removes the "flash is below the general flash and red flash thresholds" exception.

2.4. Navigable

Provide ways to help users navigate, find content, and determine where they are.

2.4.1. Bypass Blocks (Level A)

A mechanism is available to bypass blocks of content that are repeated on multiple Web pages.

Joplin currently has menu items and keyboard shortcuts to jump focus to the note list, sidebar, note title, and note editor (Go > Focus > ...).

2.4.2. Page Titled (Level A)

Web pages have titles that describe topic or purpose.

  • [🔎] Research whether Joplin needs to change its title to match the current note.
    • Joplin currently does change its title when switching to settings or some other non-note screen.

2.4.3. Focus Order (Level A)

If a Web page can be navigated sequentially and the navigation sequences affect meaning or operation, focusable components receive focus in an order that preserves meaning and operability.
— https://www.w3.org/WAI/WCAG22/quickref/?versions=2.1&showtechniques=243#focus-order

Related (§2.4.3): #10817

2.4.4. Link Purpose (In Context) (Level A)

The purpose of each link can be determined from the link text alone or from the link text together with its programmatically determined link context, except where the purpose of the link would be ambiguous to users in general.
— https://www.w3.org/WAI/WCAG22/quickref/#link-purpose-in-context

2.4.5. Multiple Ways (Level AA)

More than one way is available to locate a Web page within a set of Web pages except where the Web Page is the result of, or a step in, a process.

  • Most (all?) screens that can be accessed through menus can be accessed through GotoAnything.
  • It's possible to access the full settings screen through menus, GotoAnything, and ctrl-,.
    • It may not be possible, however, to access individual settings tabs in multiple different ways. Are these tabs considered "part of the settings page"?

2.4.6. Headings and Labels (Level AA)

Headings and labels describe topic or purpose.

  • [🔷] [🔎] Headings: Joplin currently doesn't use a <h1>/etc. tag for the "NOTEBOOKS" heading. This heading, however, seems descriptive.

2.4.7. Focus Visible (Level AA)

Any keyboard operable user interface has a mode of operation where the keyboard focus indicator is visible.

2.4.9. Link Purpose (Link Only) (Level AAA)

A mechanism is available to allow the purpose of each link to be identified from link text alone, except where the purpose of the link would be ambiguous to users in general.

Based on the "sufficient techniques" section and the "ambiguous to users in general", this seems to be primarily targeted at screen reader users (e.g. when cycling through the links available on a page). To meet this, we might start by:

  • [🔷] Adding and visually hiding extended link text in the "Note attachments" screen.
  • [🔷] Adding and visually hiding extended link text for the "location" link on the note properties screen.

Also to research:

  • [🔎] When navigating with a screen reader, is it possible to tell what the plugin screen header links do?

2.4.10. Section Headings (Level AAA)

Section headings are used to organize the content.

Note 1: "Heading" is used in its general sense and includes titles and other ways to add a heading to different types of content.

Note 2: This success criterion covers sections within writing, not user interface components. User Interface components are covered under Success Criterion 4.1.2.

Given the second note above, this section likely applies mostly to Joplin's welcome notes and settings screen. At present, the welcome notes use headings.

2.4.11. Focus Not Obscured (Minimum) (Level AA)

When a user interface component receives keyboard focus, the component is not entirely hidden due to author-created content.

  • Note 1: Where content in a configurable interface can be repositioned by the user, then only the initial positions of user-movable content are considered for testing and conformance of this Success Criterion.
  • Note 2: Content opened by the user may obscure the component receiving focus. If the user can reveal the focused component without advancing the keyboard focus, the component with focus is not considered hidden due to author-created content.

2.4.12. Focus Not Obscured (Enhanced) (Level AAA)

When a user interface component receives keyboard focus, no part of the component is hidden by author-created content.

2.4.12 is equivalent to 2.4.11, but removes exceptions. See the task list for § 2.4.11.

2.4.13. Focus Appearance (Level AAA)

When the keyboard focus indicator is visible, an area of the focus indicator meets all the following:

  • is at least as large as the area of a 2 CSS pixel thick perimeter of the unfocused component or sub-component, and
  • has a contrast ratio of at least 3:1 between the same pixels in the focused and unfocused states.
  • [🔷] Increase focus indicator thickness to 2 CSS pixels (it's currently 1 CSS pixel).
  • [🔷] [🔎] Check the focus indicator contrast against existing user interface components, particularly links in the warning banner.

See also §2.4.7.

2.5.1. Pointer Gestures (Level A)

All functionality that uses multipoint or path-based gestures for operation can be operated with a single pointer without a path-based gesture, unless a multipoint or path-based gesture is essential.

  • Drag and drop for notes -- it seems to be possible to access all related functionality in other ways.
    • Joplin currently also supports reordering notes with alt+arrow keys.
    • Dragging, then dropping, a note into the editor inserts a Markdown link. Right-clicking on the note and selecting "copy Markdown link", then pasting this link into the editor, can achive the same effect.
    • Notes can be moved to different notebooks by right-clicking, then selecting "move to notebook".
  • [❗] Support moving notebooks without drag and drop (context menu) -- Desktop: Accessibility: Add "Move to" context menu action for notebooks #11039

2.5.2. Pointer Cancellation (Level A)

For functionality that can be operated using a single pointer, at least one of the following is true:

  • No Down-Event: The down-event of the pointer is not used to execute any part of the function;

  • Abort or Undo: Completion of the function is on the up-event, and a mechanism is available to abort the function before completion or to undo the function after completion;

  • Up Reversal: The up-event reverses any outcome of the preceding down-event;

  • Essential: Completing the function on the down-event is essential.

  • Note dragging: Dragging the note back to its original location cancels the action.

  • Notebook dragging: Dragging a notebook back to its original location (before lifting the pointer) cancels the action.

  • [🟡] Clicking on a dialog's dimmed background seems to only be cancellable by dragging the pointer outside the main Joplin window.

    • Clicking and dragging the dialog's dimmed backdrop into the main dialog content still causes the dialog to close.

Note

A search for mousedown and pointerdown in Joplin's GitHub repository results in very few matches:

This suggests (but does not imply) that Joplin desktop doesn't directly handle pointer down events.

2.5.3. Label in Name (Level A)

For user interface components with labels that include text or images of text, the name contains the text that is presented visually.

  • [❗] [🔎] Check for F96 in all controls with a visible label (verify that no visible text is excluded from the label, perhaps using a screen reader).

2.5.4. Motion Actuation (Level A)

Functionality that can be operated by device motion or user motion can also be operated by user interface components and responding to the motion can be disabled to prevent accidental actuation, except when:

  • Supported Interface: The motion is used to operate functionality through an accessibility supported interface;
  • Essential: The motion is essential for the function and doing so would invalidate the activity.

Joplin for desktop seems to not have functionality that can be activated by device motion (e.g. accelerometer).

2.5.5. Target Size (Enhanced) (Level AAA)

The size of the target for pointer inputs is at least 44 by 44 CSS pixels except when:

  • Equivalent: The target is available through an equivalent link or control on the same page that is at least 44 by 44 CSS pixels;
  • Inline: The target is in a sentence or block of text;
  • User Agent Control: The size of the target is determined by the user agent and is not modified by the author;
  • Essential: A particular presentation of the target is essential to the information being conveyed.

A non-exhaustive list of items that would need adjustment to implement this:

  • [🔷] Toolbar buttons (most are 26 px by 26px) (including "toggle sort order" and "reverse sort order")
  • [🔷] Expand/collapse buttons for folders (24 px x30 px)
  • [🔷] New notebook button (currently 32 px x 32 px)
  • [🔷] Note list items (height is currently 34 px)
  • [🔷] Sidebar items (height is currently 30 px)

2.5.6. Concurrent Input Mechanisms (Level AAA)

Web content does not restrict use of input modalities available on a platform except where the restriction is essential, required to ensure the security of the content, or required to respect user settings.

  • [🔷] [🔎] Based on F98 and the examples section, this section seems specific to intentionally disabled input modalities after detecting the presence of another (e.g. disabling the touchscreen after keyboard interaction). Does Joplin desktop (or any of its dependencies) do this?

2.5.7. Dragging Movements (Level AA)

All functionality that uses a dragging movement for operation can be achieved by a single pointer without dragging, unless dragging is essential or the functionality is determined by the user agent and not modified by the author.

Based on the description of §2.5.1, satisfying 2.5.1 seems to imply that 2.5.7 is also satisfied.

Note that the extended description of this section states:

This requirement is separate from keyboard accessibility because people using a touch screen device may not use a physical keyboard.

...and later...

Success Criteria 2.1.1 Keyboard and 2.1.3 Keyboard (No Exception) require dragging features to be keyboard accessible. However, achieving keyboard equivalence for a dragging operation does not automatically meet this Success Criterion. It is possible to create an interface that works with dragging and keyboard controls that does not work using only clicks or taps.

For now, see the checklist for §2.5.1.

2.5.8. Target Size (Minimum) (Level AA)

The size of the target for pointer inputs is at least 24 by 24 CSS pixels, except where:

  • Spacing: Undersized targets (those less than 24 by 24 CSS pixels) are positioned so that if a 24 CSS pixel diameter circle is centered on the bounding box of each, the circles do not intersect another target or the circle for another undersized target;
  • Equivalent: The function can be achieved through a different control on the same page that meets this criterion;
  • Inline: The target is in a sentence or its size is otherwise constrained by the line-height of non-target text;
  • User agent control: The size of the target is determined by the user agent and is not modified by the author;
  • Essential: A particular presentation of the target is essential or is legally required for the information being conveyed.
  • Markdown toolbar buttons are 26 by 26 CSS pixels.

To change:

  • Reverse sort order is 18 px x 26 px
    • This function can also be accessed from view > sort notes by > reverse sort order.
  • Settings checkboxes are 14 px x 14 px. However, 1) checkbox labels are larger and can also be clicked, 2) the "spacing" requirement should be satisfied due to spacing between setting controls.
  • [🟡] Note list item checkboxes are 14px x 14px and are contained in a clickable container. Provide an alternate way to toggle to-dos or increase the checkbox size.
  • [🟡] Scrollbars have 7px width (issue report).

3.1.1. Language of Page (Level A)

The default human language of each Web page can be programmatically determined.

For HTML, H57 recommends using the lang attribute. Among other reasons, this is so that

  • Speech synthesizers that support multiple languages will be able to orient and adapt to the pronunciation and syntax that are specific to the language of the page, speaking the text in the appropriate accent with proper pronunciation.

3.1.2. Language of Parts (Level AA)

The human language of each passage or phrase in the content can be programmatically determined except for proper names, technical terms, words of indeterminate language, and words or phrases that have become part of the vernacular of the immediately surrounding text.

  • [🟡] Some (or most) of Joplin's supported UI languages aren't complete translations and fall back to the default English locale in places. Wrap these places with lang="en".
    • I'm not sure how feasible this is — many localized strings are included in places that can't easily be marked as a different language from the surrounding text (not easy to set HTML props on the container based on failed/successful localization).

3.1.3. Unusual words (Level AAA)

A mechanism is available for identifying specific definitions of words or phrases used in an unusual or restricted way, including idioms and jargon.

  • [🔷] Joplin's UI uses technical terms in some locations, particularly in settings. It may make sense to link these terms to sections of Joplin's documentation. Examples of terms that could be explained include:
    • "End-to-end encryption" in settings.
    • "Master password".
    • "Disabled keys".
    • "Stylesheet".
    • "Markdown renderer".
    • Names of Markdown plugins.
    • "Proxy"

3.1.4. Abbreviations (Level AAA)

A mechanism for identifying the expanded form or meaning of abbreviations is available.

The WCAG's section on understanding SC 3.1.4. suggests:

  • Providing the full form of an abbreviation the first time it appears in a document. For example "PDF (Portable Document Format)", or using the <abbr> element.

  • Linking to the definition of all instances of an abbreviation.

  • Providing a glossary.

  • [🔷] In settings > Markdown, define "WYSIWYG" or replace it with "Rich Text".

  • [🔷] In settings > Markdown, define PDF.

  • [🔷] Define "JEX" when used in settings descriptions.

  • [🔷] Search dialog "regexp".

3.1.5. Reading Level (Level AAA)

When text requires reading ability more advanced than the lower secondary education level after removal of proper names and titles, supplemental content, or a version that does not require reading ability more advanced than the lower secondary education level, is available.

The WCAG defines "lower secondary education level" as

the two or three year period of education that begins after completion of six years of school and ends nine years after the beginning of primary education

The WCAG suggests:

  • Text summaries written at lower secondary education level.
  • Illustrations.
  • Making text easier to read.

This section focuses on the desktop app's accessibility. As such, this is likely to apply mostly to the settings screen.

  • [🔷] [🔎] Evaluate text in Joplin's settings screen and make it easier to read/understand.

3.1.6. Pronunciation

A mechanism is available for identifying specific pronunciation of words where meaning of the words, in context, is ambiguous without knowing the pronunciation.

  • [🔷] [🔎] Evaluate Joplin's UI text and determine whether any words have pronunciations that cannot be inferred from context, where different pronunciations would have different meanings (see "Understanding SC 3.1.6" for details).

3.2 - Predictable

Make Web pages appear and operate in predictable ways.

3.2.1. On Focus (Level A)

When any user interface component receives focus, it does not initiate a change of context.

Note

The WCAG defines "changes of context" to be:

major changes that, if made without user awareness, can disorient users who are not able to view the entire page simultaneously

It includes "focus" and "content that changes the meaning of the web page" as examples.

  • [🔎] Check for focus causing changes in context.

3.2.2. On Input (Level A)

Changing the setting of any user interface component does not automatically cause a change of context unless the user has been advised of the behavior before using the component.

3.3.3. Error Suggestion (Level AA)

If an input error is automatically detected and suggestions for correction are known, then the suggestions are provided to the user, unless it would jeopardize the security or purpose of the content.

  • [🟡] Display an error (and allow users to correct it) if an invalid date is entered in the note properties dialog.
  • [🟡] Display a warning if the user enters an invalid location in the note properties dialog.
  • [🟡] Display a warning in the color picker dialog in the Rich Text Editor when invalid color components are entered.
    • Currently, the invalid input is highlighted in red and marked with aria-invalid="true". This might be sufficient.
  • [🟡] Master password dialog: Inform the user when the password and the password repeat don't match.
    • Currently, the "submit" button is disabled, but there's no explanation for why.
  • [🟡] Built-in backup plugin: Inform the user when password and "confirm password" don't match. (Requires upstream contributions and possibly plugin API changes).

3.3.4. Error Prevention (Legal, Financial, Data) (Level AA)

For Web pages that cause legal commitments or financial transactions for the user to occur, that modify or delete user-controllable data in data storage systems, or that submit user test responses, at least one of the following is true:

  • Reversible: Submissions are reversible.
  • Checked: Data entered by the user is checked for input errors and the user is provided an opportunity to correct them.
  • Confirmed: A mechanism is available for reviewing, confirming, and correcting information before finalizing the submission.

This guideline is described as applying to systems that "modify or delete user-controllable data in data storage systems". Joplin manages user data. Checking whether Joplin complies with this guideline might involve:

  • [🔎] Are there any actions that aren't reversible (or don't provide users an opportunity to correct/confirm)?

3.3.5. Help (Level AAA)

Context-sensitive help is available.

This success criterion suggests, for example,

3.3.6. Error Prevention (All) (Level AAA)

For Web pages that require the user to submit information, at least one of the following is true:

  • Reversible: Submissions are reversible.
  • Checked: Data entered by the user is checked for input errors and the user is provided an opportunity to correct them.
  • Confirmed: A mechanism is available for reviewing, confirming, and correcting information before finalizing the submission.

This is equivalent to SC 3.3.4, but applies to a larger set of applications.

3.3.7. Redundant Entry (Level A)

Information previously entered by or provided to the user that is required to be entered again in the same process is either:

  • auto-populated, or
  • available for the user to select.

Except when:

  • re-entering the information is essential,
  • the information is required to ensure the security of the content, or
  • previously entered information is no longer valid.

The success criterion's extended description also states:

This Success Criterion does not add a requirement to store information between sessions. A process is defined on the basis of an activity and is not applicable when a user returns after closing a session or navigating away. However, a process can run across different domains, so if a check-out process includes a 3rd party payment provider, that would be in scope.

I'm unaware of cases where Joplin requests data re-entry (except in the case of passwords). The success criterion does include search as an example, however. As such,

  • [❗] Pre-populate the Rich Text editor search dialog with the global search content.
    • Search-entry pre-population is currently only done in the Markdown editor.

3.3.8. Accessible Authentication (Minimum) (Level AA)

A cognitive function test (such as remembering a password or solving a puzzle) is not required for any step in an authentication process unless that step provides at least one of the following:

  • Alternative: Another authentication method that does not rely on a cognitive function test.
  • Mechanism: A mechanism is available to assist the user in completing the cognitive function test.
  • Object Recognition: The cognitive function test is to recognize objects.
  • Personal Content: The cognitive function test is to identify non-text content the user provided to the Web site.

The guidelines also state that supporting password manager input and allowing copy/paste to reduce re-typing satisfy this criterion.

  • Joplin's password inputs should all support pasting from other locations. However, I'm unsure whether direct entry using a password manager is supported.

3.3.9. Accessible Authentication (Enhanced) (Level AAA)

The WCAG states:

This criterion is the same as Accessible Authentication (Minimum) but without the exceptions for objects and user-provided content.

Joplin should allow pasting passwords from password managers or other applications when signing in to sync targets that authenticate through the app. Sync targets that authenticate through a web browser (e.g. Joplin Cloud) should also allow using the user's password manager.

§4 - Robust

Content must be robust enough that it can be interpreted by a wide variety of user agents, including assistive technologies.

4.1.2. Name, Role, Value (Level A)

For all user interface components (including but not limited to: form elements, links and components generated by scripts), the name and role can be programmatically determined; states, properties, and values that can be set by the user can be programmatically set; and notification of changes to these items is available to user agents, including assistive technologies.

Note 1: This success criterion is primarily for Web authors who develop or script their own user interface components. For example, standard HTML controls already meet this success criterion when used according to specification.

At present, most ARIA-related tasks are listed under SC 1.3.1. In addition to those, issues include:

4.1.3. Status Messages (Level AA)

In content implemented using markup languages, status messages can be programmatically determined through role or properties such that they can be presented to the user by assistive technologies without receiving focus.

Several status messages need appropriate accessibility information to be exposed:

  • [🟡] Sync status message.
  • [🟡] Error messages in settings.
  • [🟡] Importing/exporting modal.
  • [🟡] Top-of-screen error banner (for sync & decryption errors).

Mobile

Prior accessibility work and related issues: #10122, #10253, #8715

General notes:

Uncategorized issues:

  • Screen reader: When closing the voice typing dialog, focus jumps to the "back" button at the top of the screen.
  • Screen reader: It seems difficult to act on selected items (e.g. select items, then duplicate) with a screen reader.
  • Screen reader: It seems difficult to navigate to/from the Markdown toolbar using a screen reader.
  • Screen reader: After activating items on the Markdown toolbar, there's no feedback to indicate that an action was completed. (E.g. after clicking "Header 5", it seems unclear whether a header was added/removed and where).
  • Screen reader: Missing regions.
    • To-do: Check whether it's possible to add navigation/main/... regions with React Native — the supported accessibility roles seem much more limited than what's available on web.

Important

For now, most of this evaluation focuses on mobile/Android. For keyboard accessibility (unless TalkBack is enabled), React Native has significant issues with its built-in TextInput component. As such, these sections may also include web-related information.

1.1. Text alternatives

1.1.1. Non-text Content (A)

All non-text content that is presented to the user has a text alternative that serves the equivalent purpose, except for the situations listed below.

  • Controls, Input: If non-text content is a control or accepts user input, then it has a name that describes its purpose. (Refer to Success Criterion 4.1.2 for additional requirements for controls and content that accepts user input.)
    [ ...other exceptions... ]
  • Decoration, Formatting, Invisible: If non-text content is pure decoration, is used only for visual formatting, or is not presented to users, then it is implemented in a way that it can be ignored by assistive technology.

1.2.1 - 1.2.3. Audio and Video (A)

  • [🔷] Prerecorded audio and video would be user-created (attached as files in notes). While users are currently able to provide their own audio/video transcripts, it may make sense to include an "accessibility check" button that checks for unlabelled audo/video/images. (I think OneNote has this).

Note: §1.2.4-1.2.9 are all related to audio/video recordings/streams, which is not included in Joplin mobile by default.

1.3.1. Info and Relationships (A)

Information, structure, and relationships conveyed through presentation can be programmatically determined or are available in text.

Note

If it's not possible to convey certain relationships/structure with React Native, it may be permissible to describe the structure in text:

Some technologies do not provide a means to programmatically determine some types of information and relationships. In that case then there should be a text description of the information and relationships. For instance, "all required fields are marked with an asterisk (*)". The text description should be near the information it is describing (when the page is linearized), such as in the parent element or in the adjacent element.
— https://www.w3.org/WAI/WCAG22/Understanding/info-and-relationships.html

Important

After adding/updating accessbilityRoles, be sure to check that the change improves screen reader accessibility on at least one platform and doesn't degrade screen reader support on other platforms.

Other structure information:

  • [❗] Fix checkbox not marked as checked on web (accessibilityState is ignored on web).

...

  • To-do

2.2. Provide users enough time to read and use content

Notes on accessibility testing

Screen reader testing

For items related to screen reader accessibility, I'm testing primarily with the following screen readers:

  • Linux: Orca
  • Windows: NVDA
  • MacOS: VoiceOver
  • iOS: VoiceOver
    • Note: Enabling VoiceOver globally in MacOS also enables it for the iOS simulator
  • Android: TalkBack

Mobile: Finding contrast issues

On Android, the Accessibility Scanner may also be helpful in identifying and fixing certain accessibility issues (e.g. contrast, unlabeled content).

Footnotes

  1. https://www.w3.org/WAI/WCAG22/Understanding/conformance#conf-req1 ↩ ↩2

  2. https://webaim.org/standards/wcag/#current ↩
@personalizedrefrigerator personalizedrefrigerator added enhancement Feature requests and code enhancements mobile All mobile platforms desktop All desktop platforms high High priority issues accessibility Related to accessibility labels Jul 29, 2024
@personalizedrefrigerator personalizedrefrigerator changed the title Accessibility metaissue: Comply with WCAG 2.0 Accessibility: Comply with WCAG 2 Jul 29, 2024
This was referenced Jul 29, 2024
Merged
Merged
Open
Merged
Merged
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Aug 3, 2024
@personalizedrefrigerator
Desktop: Accessibility: Improve Markdown editor toolbar focus handling
4b606ea 
This pull request improves focus handling in the **Markdown editor**'s
toolbar. See laurent22#10795.
Merged
Merged
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Aug 28, 2024
@personalizedrefrigerator
Desktop: Accessibility: Improve note list accessibility
8c25ff1 
See laurent22#10795
This was referenced Aug 29, 2024
Merged
Merged
This was referenced Sep 13, 2024
Merged
Merged
Merged
Merged
Merged
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Oct 7, 2024
@personalizedrefrigerator
Improving sidebar ARIA information
c434a17 
See laurent22#10795
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Oct 18, 2024
@personalizedrefrigerator
Desktop: Improve keyboard shortcuts screen accessibility
bb151cd 
Related: laurent22#10795
Merged
@rkingett
Copy link

rkingett commented Oct 28, 2024 •
edited
Loading

I am loving this! I am not sure what the desktop app is programmed in, but I am worried there is an over reliance on ARIA where native controls and functions could be used, such as, the below for example regarding links.

I genuinely do not think links need an ARIALABEL if link text/titles are descriptive enough.

But I am beyond excited to see this progress so will watch closely! If I knew what the mobile apps and desktop apps were made in, I could better advise but this is a great start!

@tomasz1986
Copy link

I am worried there is an over reliance on ARIA where native controls and functions could be used, such as, the below for example regarding links.

The general rule is that if you have to use things like role=img, then this likely means that the element itself should just be a simple img (and not div or similar). You can find this ARIA overuse on many websites with <nav role="navigation>, which is completely useless and only adds bloat.

@personalizedrefrigerator
Copy link
Collaborator Author

I genuinely do not think links need an ARIALABEL if link text/titles are descriptive enough.

Thank you for the feedback!

There are cases where links/buttons in Joplin have no text content but have a title attribute. According to w3.org,

The title attribute can also be used to identify form controls. This approach is generally less reliable and not recommended because some screen readers and assistive technologies do not interpret the title attribute as a replacement for the label element, possibly because the title attribute is often used to provide non-essential information.

Based on this, aria-label is being added in some cases where a button/link has no text content, even if it already has a title.

Related links:

If I knew what the mobile apps and desktop apps were made in, I could better advise but this is a great start!

The desktop app is built with Electron and React. The mobile app is built with React Native.

@personalizedrefrigerator
Copy link
Collaborator Author

The general rule is that if you have to use things like role=img, then this likely means that the element itself should just be a simple img (and not div or similar).

Thank you for the feedback!

Currently, Joplin does use role="img" for its font icons. For example, Joplin uses FontAwesome <i> webfont icons. For this type of icon, ARIA 24 recommends:

Some low vision users need user stylesheets, scripts, or extensions to override the fonts on a page to perceive text content. However, they need to be able to perceive icon fonts that are meaningful, such as a star signifying a favorite, or an email icon in a link.

The key is for the author to semantically markup icon fonts with role="img". Then the user's font replacement selector can hook into that semantic and exclude role="img". This results in those icon fonts being shown.

An alternative to webfont+role=img could be to use SVG icons (e.g. with FontAwesome SVG). However, this would likely require significant code changes.

@tomasz1986
Copy link

Yeah, icon fonts are not good for accessibility since they are basically a hack to display images instead of text (as should be expected with fonts normally), so they have issues with screen readers, and they also cause problems when the user wants (or needs due to a particular disability) to use their own font for the whole application or website. SVG icons are much better in this aspect, but as you've said, implementing them would require a major rewrite of the code 🙁.

This was referenced Nov 15, 2024
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
Merged
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Nov 22, 2024
@personalizedrefrigerator
Editor: Announce changes made by Markup commands
a61c571 
This commit announces changes (e.g. "added block code") made by most
Markdown commands. Currently:
- This is done on both mobile and desktop.
- The goal is to give screen reader users a brief description of how an
  action changed the document.
- It's possible that this change will be more annoying than useful (more
  content read by the screen reader?)

Related to laurent22#10795.
This was referenced Nov 26, 2024
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
accessibility Related to accessibility desktop All desktop platforms enhancement Feature requests and code enhancements high High priority issues mobile All mobile platforms
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
3 participants
@tomasz1986 @rkingett @personalizedrefrigerator