Accessibility guidelines

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:

1. Let the user trigger an outcome
2. Tell the user what they achieved
3. 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.

• Movement outcomes can be added to a draggable entity by using a More button (...)
• Having a More button (...) does not remove the need for a drag handle icon. See design guidelines.
• If no More button (...) exists on a draggable entity, 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 only have one button for triggering actions. An entity should not have a More button (...) and a drag handle menu button (an entity should only)
• A draggable that does not have a drag handle icon because it is "implied" to be draggable (eg a card) should still have a More button (...).

Dark theme

Entire entity is draggable

More actions

Entire entity is draggable (with grouped actions)

More actions

Using drag handle button

AlizaSenior Engineer

Move Aliza

action-menu-variants example in CodeSandbox (opens in new tab)

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:

• Drag handle menu component
• inline-menu
• modal
• select

Figma (Atlassians only)

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.

• Atlassian drag and drop design guidelines
• Accessibility foundation general guidance
• Drag handle menu component
• Live region package