Token

Accessibility and usability expectations

A token can be static text, a link or a button, and may be removable.

Tokens must be implemented using the appropriate HTML element. When the token us static text, it must use a non-semantic element such as a <span>, when the token is a link it must use an <a> element, and when the token is a button it must use a <button> element.

The text in a token must have a minimum contrast of 4.5:1 against the token's background. In dark mode, the default token uses grey text on a dark grey background which has a contrast ratio that is below the required minimum.

Tokens that are interactive must have a visible focus style. The focus style should be a custom style rather than the browser's default focus style as the browser default can have poor colour contrast in some browsers. By default, interactive tokens use the browser's default focus style.

When a token is removable it must contain a visual cue, a close icon, to indicate it can be removed, with an appropriate text description for screen reader users.

The target size and spacing of the control for removing a token must be at least 24 by 24 CSS pixels. This is to ensure that the button is large enough to be easily activated by users with motor impairments. The small and medium variants do not meet the minimum target size and spacing requirement.

It must be possible to remove a removable token with the keyboard, in addition to the cursor.

When a static text token is removable it must contain a <button> with an accessible name that conveys which token will be removed.

When a token is a link or a button and is removable, an additional button is not provided. Instead the token is removed by focusing the token and using the "Backspace" or "Delete" keys. Instructions must be provided to screen reader users, either as part of the accessible name or using an accessible description, so they are aware of this functionality.

A token can have a leading visual, which is an icon. The icon is hidden from screen readers so must only be used for decorative purposes.

Built-in accessibility features

Tokens are a <span> by default, but a link can use an <a> and a button can use a <button> by specifying the appropriate element with the as prop.

The default colors meets the minimum contrast requirement of 4.5:1 between foreground and background colors.

Tokens that are interactive have a visible focus style.

Tokens that are removable have a close icon.

The control for removing a token meets the minimum target size of 24 by 24 CSS pixels in the large and xlarge variants.

The removable tokens have built in keyboard accessibility.

Static text tokens that are removable contain a <button> with an accessible name that conveys which token will be removed.

A Token that is a link or a button and is removable includes the instructions " (press backspace or delete to remove)" for screen reader users as part of the accessible name by default. IssueToken does not include the instruction.

Implementation requirements

If using custom colors, make sure the text in a token has a minimum contrast of 4.5:1 against the token background.

If a token has the functionality of a link (takes a user to a page) or a button (performs an action), set the appropriate semantic element by using the as prop.

When using a removable token that is a link or button, do not use the small or medium variants as the close control does not meet the minimum target size and spacing requirements of 24 by 24 CSS pixels.

If an IssueToken is a link or a button and is removable, the keyboard instructions " (press backspace or delete to remove)" must be added to the accessible name or description for screen reader users, as they are not included by default.

Only use decorative icons for the leading visual as a text description cannot be set.

How to test the component

Integration tests

• The text contrast of custom colors meets the minimum requirement of 4.5:1 between foreground and background colors
• Tokens are implemented using the appropriate HTML element.
  • A token that is a link uses an <a> element
  • A token that is a button uses a <button> element
  • A token that is text uses a <span> element
• Tokens that are removable and are a link or a button use either the large or xlarge variant. The small and medium variant's close control do not meet the minimum target size and spacing requirements.
• If an IssueToken is a link or a button and is removable, the keyboard instructions " (press backspace or delete to remove)" has been added to the accessible name or description
• A leading visual is only used for decorative purpose

Component tests

• The text contrast of default colors meet the minimum requirement of 4.5:1 between foreground and background colors
• Tokens that are interactive have a visible focus style
• When a token is removable it has a close icon
• In the large and xlarge variants of a token, the target size, including spacing of the control for removing the token, is at least 24 by 24 CSS pixels
• If a token is removable and is a <span>, then the control to remove the token is a <button> with a descriptive accessible name, and is focusable with the "Tab" key and can be activated using the "Esc" and "Space" keys
• If a Token is removable and is an <a> or a <button>,
  • a close button is not rendered, the token is removed by focusing the token and using the "Backspace" or "Delete" keys
  • the text "(press backspace or delete to remove)" in included as visibly hidden text in the link/button so it is part of the accessible name