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.

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

Accessibility: Comply with WCAG 2 #10795

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

Accessibility: Comply with WCAG 2 #10795

personalizedrefrigerator opened this issue Jul 29, 2024 · 0 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

Summary

[ Progress: Desktop ] | [ Progress: Mobile ]

This issue tracks general accessibility issues in Joplin mobile and desktop and its progress on WCAG 2.2 compliance.

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 is a task that should be completed.
  • [🔷] 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

Recent relevant changes: #9982, b108bf7, dd5240d, 4827d0b

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

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

Also:

1.3.2. Meaningful Sequence

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

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

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?

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).
  • [🟡] Improve link URL contrast (currently has 3.81:1 contrast).

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

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

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.
  • [🔷] 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.

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.

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

  • [❗] Don't skip focusable elements on tab. Instead, use grouping (and/or intelligent use of Up/Down arrow keys?)
  • [❗] Fix focus isn't moved to certain screens when opened (e.g. focus is lost after opening the note history screen). See F85.

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.
  • Does this apply to settings tabs?

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:

    • 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.
  • 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.

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).

To-do

  • [🔎] Evaluate §3-4.

Mobile

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

General notes:

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 primarially 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, unlabelled 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
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Aug 3, 2024
This pull request improves focus handling in the **Markdown editor**'s
toolbar. See laurent22#10795.
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Aug 28, 2024
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Oct 7, 2024
personalizedrefrigerator added a commit to personalizedrefrigerator/joplin that referenced this issue Oct 18, 2024
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
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
Development

No branches or pull requests

1 participant