The goal of this guidance is to provide every person with a way to delightfully achieve the same outcomes in Atlassian interfaces, regardless of the technologies being used.
The core package does not enable accessible controls automatically, as there is no one pattern that works well for all situations. Instead, use these guidelines and our optional packages and Design System components to create accessible experiences.
Non Atlassian consumers are encouraged to follow this guideline and substitute our Design System components (eg @atlaskit/inline-menu) with their own components. Non Atlassian consumers are also welcome to implement accessibility in another way if they choose.
Not all people can successfully complete pointer based drag operations. Provide other ways for people using assistive technologies to achieve the same outcomes as pointer based drag and drop operations.
When building alternative flows, you need to:
- Let the user trigger an outcome
- Tell the user what they achieved
- Let the user easily continue to trigger more outcomes
Use visible and accessible controls (for example, buttons, menus, and forms) to make it easy for people using assistive technologies to trigger the same outcomes as a drag operation.
Draggable entities should have a button that can be used to trigger an inline menu containing outcomes.
- A draggable entity should almost always have a drag handle icon to clearly show the entity is draggable. See design guidelines.
- Movement outcomes should be added to an existing More button (...) on a draggable entity. Having a More button (...) does not remove the need for a drag handle icon.
- If no More button (...) exists, and movement outcomes are the only possible actions for the entity, then you can convert the drag handle icon into a drag handle menu button that triggers an inline menu with movement outcomes.
- A draggable entity should not have a More button (...) and a drag handle menu button.
This pattern works well for a lot of cases, but there are other cases where this approach is not appropriate - for those cases please be driven by what would be best for people using assistive technologies.
Simple cases
When there is only a small set of operations possible for an element, and those operations don't require any input, then we recommend that you add inline menu items for each available outcome (eg "move to top").
Complex cases
If a particular outcome requires additional input, then relevant menu items should trigger a modal containing a form to gather that additional input from the user.
Packages to help you:
If drag handles or other menus aren't available, make it possible to access more actions on focus.
All interactive elements should have a meaningful name for assistive technology.
Ensure that accessible names for buttons include the name of the element being acted on, for example, “Move task 'clean dishes' to top of backlog”.
For general guidelines on writing meaningful label text, refer to the accessibility guidelines.
For most experiences, we recommend not leveraging directional controls (arrow keys). There are a few problems with this approach:
- Directional arrow movement doesn't always make sense when you can't see the interface you are engaging with.
- Directional arrow movements require JAWS screen reader users to change screen reader mode to use it
- Directional movement does not translate well to all experiences
- Complex operations can require many keystrokes
- The approach takes a significant amount of code to get working
Instead, use accessible controls.
Use live regions to announce content changes to screen readers. Messages in live regions will be announced by screen reader.
Live regions should provide real-time feedback both during and after an interaction. Messages should contain the name of the item being moved, as well as its old and new position.
To create live region feedback for interactions, use the live region package.
import { announce } from '@atlaskit/live-region';
announce('Task "Clean dishes" moved to list "Doing" from "Todo".');Make it easy for users to continue using the same entity after an action (where applicable). To achieve this, focus should move to the original trigger element whenever possible. This prevents someone needing to navigate back to the same spot.
If the element no longer exists after the operation, choose a new element using your best judgement.
Some frameworks, such as react, will automatically restore focus to elements when they are moved in some situations. In this react example, items can be reordered within a list. When an item is moved using the menu item, focus remains on the drag handle button without us needing to do anything. react is shifting the element and ensuring that focus is maintained for us.
If your framework does not automatically restore focus for some situations, then you will need to restore focus yourself.
In this react example, the avatar can move between the two columns by dragging or by pressing the Swap team button. If the button has focus when it is selected (by pointer or by keyboard), focus is restored to it after moving.
This requires manual focus restoration because the button is moving to a new parent and will remount. The button in the new column is not the same DOM element as the original button, so focus can't be preserved automatically.
Was this page helpful?
We use this feedback to improve our documentation.