40 KiB

Czysty Bezpośredni odnośnik Wina Historia

layout
page

Maintaining Accessibility

::: info Help improve the accessibility of Funkwhale!

Test the component examples below. Did you find a bug? A missing hint? Some component feature doesn't work as expected with your setup?

Get in touch on the Funkwhale forum, Matrix chat, Mattermost room and code forge.

:::

::: tip Recommended tools...

...for automated testing

See The W3C Web Accessibility Initiative's Web Accessibility Evaluation Tools List for a comprehensive and well-curated list of advanced tools, especially for automated testing. These tools typically catch less than half the accessibility issues.

...for manual testing

Screen readers

See the MDN guide on Accessibility tooling and assistive technology for an overview of screen readers you can install, including Orca (on Linux), VoiceOver(on Macintosh), TalkBack (on Android) or NVDA (on Windows).

Other assistive technology

MDN has a list of additional tooling that users typically use to access web apps such as Funkwhale. If you are using a braille keyboard, trackballs, joysticks, a touchpad, a screen magnifier, or voice commands, your critical feedback is very valuable to make funkwhale accessible.

Your browser's Developer Tools

If you use a desktop, laptop or tablet with a keyboard, you can usually open a pane or window with helpful tools by pressing F12 (or Fn+F12). Find the Accessibility tab and follow the instructions there. In addition, the Inspector tab helps you understand the hierarchical structure of the component's DOM nodes.

{width=180}

:::

Components:

TOC

Form fields

Using forms: Complete example

Using the Input component: A11y checklist
Using the Pills component: A11y checklist
Using the Select component: A11y checklist
Using the Slider component: A11y checklist
Using the Textarea component: A11y checklist
Using the Toggle component: A11y checklist

::: details Criterion 1.3.1d - Info and relationships - Form fields

Goal

Form fields must be properly labeled and grouped to ensure users can understand their purpose and relationship.

How to test

Use a screen reader to navigate through the form
Check that each form control announces its label and purpose
For groups of related controls (radio buttons, checkboxes), verify they are properly grouped and have a group label

Expected outcome

Each form control announces its label
Related controls are grouped with a common label
Required fields are clearly indicated
Error messages are associated with their fields

Learn more: Practical guide - Deep dive :::

::: details Criterion 1.3.5 - Identify input purpose

Goal

Form fields collecting user information should have their purpose programmatically identified to support autocomplete and other assistive features.

How to test

Check the HTML of input fields using browser developer tools
Look for appropriate autocomplete attributes
Try using browser autofill features

Expected outcome

Input fields have appropriate autocomplete attributes
Browser autofill correctly identifies field purposes
Screen readers announce the purpose of each field

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.5.3 - Label in name

Goal

Visual labels must match their programmatic names.

How to test

Compare visible labels to aria-label values
Use screen reader to check announced names
Try voice activation using visible labels

Expected outcome

Visible labels match programmatic names
Screen reader announces correct labels
Voice commands using visible text work

Learn more: Practical guide - Deep dive :::

::: details Criterion 3.3.1 - Error Identification

Goal

Form errors must be clearly identified and described to users.

How to test

Submit form with invalid data
Check how errors are displayed
Use screen reader to verify error announcements

Expected outcome

Errors are clearly marked visually
Error messages are associated with their fields
Screen reader announces errors when they occur

Learn more: Practical guide - Deep dive :::

::: details Criterion 3.3.2 - Labels or Instructions

Goal

Form fields must have clear labels and instructions.

How to test

Review all form fields for visible labels
Check for instructions about required format
Verify label associations in the code

Expected outcome

All fields have visible labels
Required formats are clearly indicated
Labels are properly associated with controls

Learn more: Practical guide - Deep dive :::

::: details Criterion 3.3.3 - Error Suggestion

Goal

Error messages should suggest how to fix the problem.

How to test

Trigger various form errors
Review error message content
Verify suggestions are helpful and clear

Expected outcome

Error messages explain what went wrong
Suggestions for correction are provided
Language is clear and helpful

Learn more: Practical guide - Deep dive :::

::: details Criterion 3.3.4 - Error Prevention for important information

Goal

When providing important or sensitive data, users need to be able to review and correct information before final submission, or review and revert erroneous submissions in hindsight.

How to test

Complete form with important information
Check for review step before submission
Verify ability to correct information

Expected outcome

Data can be reviewed before submission
Changes can be made during review
Submissions can be reversed if needed

Learn more: Practical guide - Deep dive :::

Alert

Using this component: A11y checklist - Accessible Alert example

::: details Criterion 4.1.2 - Name, Role, Value

Goal

UI components must communicate their name, role, and value to assistive technologies.

How to test

Use a screen reader to interact with both alert variants
Check that the alert type (status vs. alert) is properly announced
Verify that the alert content is read when it appears

Expected outcome

Screen reader announces the alert's role ('status' or 'alert')
Alert content is automatically announced when it appears
Users understand the difference between status and alert roles

Learn more: Practical guide - Deep dive :::

::: details Criterion 4.1.3 - Status Messages

Goal

Status messages must be programmatically determined and announced without receiving focus.

How to test

Trigger different types of alerts
Use screen reader to verify automatic announcements
Check that focus remains unchanged when alerts appear

Expected outcome

Status changes are announced automatically
Alerts don't disrupt user's focus
Different types of status messages are properly differentiated

Learn more: Practical guide - Deep dive :::

Button

Using this component: A11y checklist - Accessible Button example

::: details Criterion 1.1.1 Non-text content

Goal

Buttons with icons must provide text alternatives that describe their purpose.

How to test

Use a screen reader on the button with icons but no visible text
Verify the announced label matches the button's function

Expected outcome

Screen reader announces label for the icon-only button
The announced label clearly indicates the button's purpose

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.1.1 - Keyboard accessible

Goal

All button functionality must be operable with a keyboard.

How to test

Tab to focus a button
Press Enter or Space repeatedly

Expected outcome

Button is focusable with Tab
Both Enter and Space activate the button
The first button triggers an action
The second button toggles between on and off

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.4.7 - Focus visible

Goal

Button must have a visible focus indicator when navigating with keyboard.

How to test

Use Tab key to navigate to the button
Check if focus indicator is clearly visible
Verify focus indicator has sufficient contrast

Expected outcome

Focus indicator is clearly visible
Focus state has sufficient contrast with background
Focus indicator persists while button has focus

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.5.8 - Target size (minimum)

Goal

Button must be large enough to be easily activated.

How to test

Check button dimensions
Try activating on touch devices
Verify spacing between adjacent buttons

Expected outcome

Button target area is at least 24x24px
Sufficient spacing between interactive elements
Easy to activate without hitting adjacent elements

Learn more: Practical guide - Deep dive :::

::: details Criterion 4.1.2 - Name, Role, Value

Goal

Button must communicate its name, role, and state to assistive technologies.

How to test

Use screen reader to focus on button
Check if button role is announced
Verify button label is announced
Test if state changes (pressed, disabled) are announced

Expected outcome

Screen reader announces "button" role
Button's label is clearly announced
State changes are properly communicated

Learn more: Practical guide - Deep dive :::

Card

Using this component: A11y checklist - Accessible Card example

::: details Criterion 1.1.1 Non-text content

Goal

Images that convey information must have a text alternative

How to test

Use your screen reader on the image in the first card above

Expected outcome

The screen reader announces the image's alternative text: 'Colorful whales communicating in a network'

Learn more: Practical guide - Deep dive :::

::: details Criterion 1.3.1c - Info and relationships - Headings

Goal

Where visual headings are used to communicate the structure of a page, they must also be communicated in a way that supports assistive technology users to access this structure.

How to test

Right-click on any heading and select the 'Inspect' option, or use a screen reader

Expected outcome

The Card title is marked up as a heading (<h6>)

Learn more: Practical guide - Deep dive :::

::: details Criterion 1.4.3 - Contrast minimum

Goal

There should be enough contrast between a background and the foreground content so that users can easily distinguish them.

How to test

Use a contrast checker tool to compare background and the foreground colors on text

Expected outcome

Text, including text in images, must have a contrast ratio of at least 4.5:1 against its background color. Large text can be 3:1.

Learn more: Practical guide - Deep dive

:::

::: details Criterion 1.4.11 - Non-text contrast

Goal

Visual elements used to indicate state or boundaries must have sufficient contrast.

How to test

Activate :hover and :focus states on the second card ("Link")
Use contrast checking tools to compare different interactive states
Use contrast checking tools to compare the icon color in the first card with its surrounding background color
Repeat in high contrast mode

Expected outcome

Interactive states are clearly visible (3:1 contrast)
Icon is clearly visible (3:1 contrast)
Visual boundaries remain perceivable in high contrast mode

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.1.1 - Keyboard accessible

Goal

All functionality must be available using only a keyboard.

How to test

Navigate through cards using Tab key
Activate interactive elements using Enter (Inline link, Action link, Link card) or Space (Tag Button)
Verify all actions can be performed

Expected outcome

All interactive elements are focusable
Actions can be triggered with keyboard; no functionality requires mouse interaction

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.4.3 - Focus order

Goal

Interactive elements must receive focus in an order that preserves meaning and operability.

How to test

Tab through card elements
Check if order matches visual layout

Expected outcome

Focus moves logically through card content
Focus sequence matches visual layout
Focus movement is predictable

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.4.7 - Focus visible

Goal

Keyboard focus indicator must be clearly visible.

How to test

Tab through interactive elements
Check contrast of focus indicators

Expected outcome

Focus indicator is clearly visible; current focus location is always apparent
Focus state has sufficient contrast (3:1)

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.5.2 - Pointer cancellation

Goal

Users must be able to cancel or undo pointer interactions with the card.

How to test

Start clicking/touching the link card but drag away before releasing
Start clicking/touching the link card but press Escape away before releasing

Expected outcome

No actions triggered when pressing a mouse button
Dragging away and pressing Enter cancel a click

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.5.3 - Label in name

Goal

Visible labels must match their programmatic names for interactive elements within the card.

How to test

Use screen reader to check announced names
Compare with visible text labels
Try voice activation using visible labels

Expected outcome

Screen reader announces same text as visible labels
Programmatic names contain visible text
Voice commands using visible text work

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.5.8 - Target size (minimum)

Goal

Interactive elements must be large enough to be easily activated.

How to test

Measure clickable areas
Try scrolling on touch devices by clicking on non-interactive surfaces
Check spacing between targets

Expected outcome

Interactive elements are at least 24x24px
There is sufficient spacing between targets so that users can scroll on touch devices
Easy to activate on touch devices

Learn more: Practical guide - Deep dive :::

Header

Using this component: A11y checklist - Accessible Header example

::: details Criterion 2.4.3 - Focus order

Goal

Interactive elements must receive focus in an order that preserves meaning and operability.

How to test

Tab through action controls at the start of the header (next to the heading)
Check if order matches visual layout

Expected outcome

Focus moves logically through actions and section content
Focus sequence matches visual layout and movement is predictable

Learn more: Practical guide - Deep dive :::

See Heading

See Section

Heading

Using this component: A11y checklist - Accessible Heading example

::: details Criterion 1.3.1c - Info and relationships - Headings

Goal

Headings must be properly structured and marked up to communicate document hierarchy.

How to test

Use a screen reader's heading navigation feature
Check heading levels in the browser's developer tools
Use a document outline tool

Expected outcome

Headings are marked with appropriate h1-h6 tags
Heading levels follow a logical hierarchy
Screen readers announce the correct heading level

Learn more: Practical guide - Deep dive :::

Input

Using this component: A11y checklist - Accessible Input example

See Form fields.

Layout

Using this component: A11y checklist - Accessible Layout example

::: details Criterion 2.4.3 - Focus order

Goal

Interactive elements must receive focus in an order that preserves meaning and operability.

How to test

Tab through elements in each layout
Check if order matches visual layout

Expected outcome

Focus moves logically through buttons
Focus sequence matches visual layout and movement is predictable

Learn more: Practical guide - Deep dive :::

Link

Using this component: A11y checklist - Accessible Link example

::: details Criterion 1.1.1 Non-text content

Goal

Links with icons must provide text alternatives that describe their purpose.

How to test

Use a screen reader on links with icons but no visible text
Verify the announced label matches the link's destination

Expected outcome

Screen reader announces meaningful labels for icon-only links
The announced label clearly indicates where the link leads

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.1.1 - Keyboard accessible

Goal

All link functionality must be operable through a keyboard interface.

How to test

Tab to reach the link
Try to activate using Enter key

Expected outcome

Link is focusable with Tab
Enter activates the link

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.4.7 - Focus visible

Goal

Link must have a visible focus indicator when navigating with keyboard.

How to test

Use Tab key to navigate to the link
Check if focus indicator is clearly visible and has sufficient contrast

Expected outcome

Focus indicator is clearly visible and has sufficient contrast with background

Learn more: Practical guide - Deep dive :::

::: details Criterion 4.1.2 - Name, Role, Value

Goal

Link must communicate its name, role, and state to assistive technologies.

How to test

Use screen reader to focus on link
Check if link role is announced
Verify link destination is clear

Expected outcome

Screen reader announces "link" role
Link's destination is clearly conveyed
State changes are properly communicated

Learn more: Practical guide - Deep dive :::

Loader

Using this component: A11y checklist - Accessible Loader example

Using this component: A11y checklist - Accessible Modal example

::: details Criterion 1.4.13 - Content on Hover or Focus

Goal

Modal content must be dismissible, hoverable, and persistent.

How to test

Try to dismiss modal without moving focus
Move cursor over modal content
Check if content remains visible when needed

Expected outcome

Can dismiss modal with Escape key
Can move cursor over content without issues
Content remains visible until deliberately dismissed

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.1.2 - No Keyboard Trap

Goal

Users must be able to navigate to and from all modal content using keyboard.

How to test

Open modal and navigate through all controls
Try to exit modal using keyboard
Verify focus handling when modal closes

Expected outcome

Can navigate through all modal content
Can exit modal with keyboard (Escape key)
Focus returns to trigger element after closing

Learn more: Practical guide - Deep dive :::

::: details Criterion 2.4.3 - Focus order

Goal

When a modal opens, focus should move into it and be trapped within until it closes.

How to test

Open the modal using both mouse and keyboard
Try tabbing through all focusable elements
Try to move focus outside the modal while it's open

Expected outcome

Focus moves to modal when opened
Focus is trapped within modal
Focus returns to trigger element when closed

Learn more: Practical guide - Deep dive :::

::: details Criterion 4.1.2 - Name, Role, Value

Goal

The modal's role, state, and name must be properly communicated to assistive technologies.

How to test

Use a screen reader when opening/closing modal
Check ARIA attributes in your browser's developer tools

Expected outcome

Screen reader announces modal role
Modal state (open/closed) is announced
Modal title is announced

Learn more: Practical guide - Deep dive :::

Nav

Using this component: A11y checklist - Accessible Nav example

::: details Criterion 1.3.1 - Info and relationships

Goal

Ensure that the structure and relationships within the Nav component, especially when used as tabs, are programmatically determinable and presented in a way that preserves meaning.

How to test

Inspect the Nav component above using browser developer tools and accessibility inspectors as well as screen readers. If used as tabs, verify the following: - The main container (<Layout>) has role="tablist". - Individual tab elements (<Button>) have role="tab". - Each tab has an id and an aria-controls attribute pointing to its corresponding tab panel's id. - Each tab panel (<slot>) has role="tabpanel" and an aria-labelledby attribute pointing to its corresponding tab's id. - aria-posinset and aria-setsize are correctly calculated and applied to each tab to convey its position within the set. - The span with class falseTitle uses aria-hidden="true" to hide duplicated or visually formatted text from screen readers.

Expected outcome

Assistive technologies accurately announce the Nav component's structure, including tab lists, tabs, and their relationships to tab panels.
Each tab title is only read out once by screen readers.

Learn more: Practical guide: 1.3.1 - Deep dive: Info and relationships :::

::: details Criterion 2.1.1 - Keyboard Accessible

Goal

Ensure that all functionality of the Nav component, particularly when used as tabs, is operable via a keyboard interface without requiring specific timings for individual keystrokes. Users should be able to navigate between tabs using standard keyboard interactions.

How to test

Navigate to the Nav component using the Tab key.
If used as tabs, once a tab is focused:
- Press ArrowRight or ArrowDown to move focus to the next tab.
- Press ArrowLeft or ArrowUp to move focus to the previous tab.
- Press Home to move focus to the first tab.
- Press End to move focus to the last tab.
- Play around.
Ensure that the tablist updates accordingly, and tab panel content associated with the selected tab is displayed.

Expected outcome

Users can tab into and out of the tablist.
Arrow keys move between tabs and wrap around ("roving").
The currently focused tab is clearly indicated visually.
Activating a tab displays its associated content.

Learn more: Practical guide: 2.1.1 - Deep dive: Keyboard Accessible :::

::: details Criterion 2.4.8 - Location

Goal

Users should be able to determine their location within navigation.

How to test

Check for current location indicators:

Screen readers should announce aria-current="page" for active navigation links.
If used as tabs, screen readers should announce aria-selected="true" for the active tab.
Sighted users can visually identify the active item (e.g., an orange line indicating the active tab or a highlighted nav-item).
The target is highlighted.

Expected outcome

The current location is clearly and consistently indicated for both sighted and assistive technology users.
Screen readers accurately announce the current page/tab status.
The navigation hierarchy and active state are easily understood.

Learn more: Practical guide: 2.4.8 - Deep dive: Location :::

::: details Criterion 4.1.2 - Name, Role, Value

Goal

Verify that all interactive components within the Nav component communicate their name, role, and state to assistive technologies.

How to test

Inspect the component using browser developer tools and accessibility inspectors.
If used as tabs, verify the following:
- The role="tab" is correctly applied to tab elements.
- The aria-selected attribute accurately reflects the active state of a tab (true for the selected tab, absent for unselected tabs).
For all interactive elements (tabs and links), confirm that they have accessible (machine-readable) names.

Expected outcome

Screen readers announce the correct roles for tabs and links.
The accessible names for all interactive elements are clear and accurately convey their purpose.
The state of tabs - selected, focused, current - is communicated to assistive technologies.

Learn more: Practical guide: 4.1.2 - Deep dive: Name, Role, Value :::