Accessibility Annotation Kit for iOS
Accessibility annotations help capture design intent that cannot be conveyed through visual design alone. This tool can help prevent many accessibility issues before your designs are built. However, like any tool, it can also create more issues when used improperly. It’s best used by those with prior knowledge designing accessible mobile apps on iOS.
In the future, we intend to add some learning materials for those who are new to mobile accessibility.
Important Note: This kit is made specifically for iOS experiences, and it is not recommended for Android or Web platform designs. An Android OS Accessibility Annotation Kit is in development. For Web experiences, use our Web Accessibility Annotation Kit.
- Figma Community: Accessibility Annotation Kit iOS by CVS Health® Inclusive Design
- Introducing the Accessibility Annotations Kit for iOS on the CVS Tech Blog
- Follow CVS Health on the Figma Community
Included in this kit are annotation components for the following:
- Button - Major actions and features.
- Heading - Help users navigate past sections of related content.
- Title - Describes purpose of current view.
- VoiceOver Group - Identify VoiceOver Group targets and number them.
- Note - For any details that don’t fit into the other annotation categories.
Since the word “annotations” may refer to the individual components as well as the documentation itself, we use the word “stamp” to refer to the different types of components.
Pin Stamps point to parts of a design that are above, below, left, or right. This can be set using the “Stamp position” component property.
Lasso Stamps highlight an area of the design. This is useful for outlining groups of objects or interactive areas. Like Pin Stamps, labels position can be changed to reduce risk of overlapping other stamps or important parts of a design.
Details components are numbered annotations in the margins around a design that always correspond to numbers used by Pin or Lasso Stamps. The Details components can include traits, labels, values, hints, actions, and more. Not all components (for example, a single line of text) need annotation details.
Only use the Number property to attach Details to a Voiceover Group Stamp, or a Note. They should never be related to a Structure annotations (Button, Heading, or Title)
Each annotation type has its own color, icon, text label, outline, and shadow. These signifiers help to identify and differentiate them from one another as well as the designs they overlay.
In this kit, we have split all iOS elements up into two main categories:
- Interactives can be activated and will perform a resulting action.
- Informatives are inert content that has no action.
This is due to the fundamentally different ways that iOS assistive technologies such as Voice Control and VoiceOver convey the details of interactive and informative elements.
The following iOS accessibility modifiers are critical for people using assistive technologies to perceive and operate an interface.
- Label - A succinct string of text that identifies the element.
- Value - A string that contains the current value of the element.
- Hint - A succinct string that describes the result of the element’s action.
- Trait - Conveys the function or type of element to assistive technologies, which then decide how to present the element to users.
- Custom Actions - Provide multiple actions to a single interactive focus target for people using assistive technologies.
To try reduce the learning curve of annotating iOS views, we created templates for Detail components. These consist of the common use cases in iOS, such as Card and Text Fields. These templates are the general name of the components/pattern. Each template my come with predefined modifiers.
Interactive templates:
- Adjustable
- Card
- Horizontal Scroll
- Tappable
- Text Field
- Other
Interactive modifiers:
- Label
- Value
- Hint
- Trait
- Custom Actions
Informative templates:
- Image
- Other
Informative modifiers:
- Label
- Value
More in depth descriptions of these modifiers, see the Adding Interactive details and Adding Informative details sections.
When there are no templates that fit your use case, use the “Other details” component which provides no defaults.
This kit can be used in different ways, but this sequence is what we have found to be most helpful and intuitive for creating annotations that keep different assistive technologies in mind.
Identify major structural landmarks made up of a single element.
-
Titles function similar to an
<h1>on the Web, placed near the navigation area at the top. Titles get announced when the user transitions to the view. This helps users understand where they are and what to expect from an experience. -
Headings help users identify the purpose of sections, as well as navigate past sections of related content. Marking text as a Heading will add it to the VoiceOver Rotor to enable users to navigate between major sections. Not all views need a heading—it’s common to not have one.
Note: iOS currently only supports one heading level, used similarly to a
<h2>or<h3>on the Web. (The iOS accessibility API does allow for multiple heading levels, so this may change in the future.) - Buttons are major actions and features, such as: “Add to cart.” Not all Tappable controls are buttons.
Identify groups of elements that should be a single VoiceOver Group target and number them to match any associated annotation Details components (once they are added in Step 3).
Best practices for grouping information:
- Pieces of information are related concretely. Example: A shopping cart item with its price.
- Actions are related to a common subject. Example: A social media post with Like, Comment, and Share.
- Images are related to nearby text.
- There are many paragraphs without a heading between them.
- Remember that the Voiceover Group Stamp number is not a position in the focus order, but to associate the Stamp with Details.
We have provided a few different Details component templates to assist you. Not all components need annotation details.
Only attach Details to a Voiceover Group Stamp. They should never be related to a Structure Stamp (Button, Heading, or Title)
Any other types of annotations can be added using our freeform Note Stamp and Details. For example, using them to clarify where focus should land when closing a sheet.
A succinct string of text that identifies the element.
How an Interactive Label impacts assistive technology users:
- Voice Control users operate a control by speaking "Tap" followed by its Label.
- VoiceOver users perceive a control’s Label as an announcement when they focus on the interactive element/group.
Best practices:
- Label should match the visible label
- Label should not change
- Use Value for dynamic content
A string that contains the current value of the element.
How an Interactive Value impacts assistive technology users:
- Voice Control users do not perceive an interactive element’s Value. However, they will likely visually perceive the content within the control.
- VoiceOver users perceive a control’s visually related info, state, or other dynamic content. This is communicated when they focus on the interactive element/group.
Best practices:
- Should be directly tied to visible content
- Use simple and expected values to convey state
A succinct string that describes the result of the element’s action.
How Hint impacts assistive technology users:
- Voice Control users do not perceive an interactive element’s Hint.
- VoiceOver users perceive a control’s usage tips and other contextual info with Hint when they focus on the interactive element/group.
Best practices:
- Should not contain roles like “button” or “heading”
- Avoid modifying stock component’s built-in hints
- Consider the user need when creating hints for custom components
Traits convey the function or type of element to assistive technologies, which then decide how to present the element to users.
How Trait impacts assistive technology users:
- Voice Control users operate a control based on its Trait. For example, if the trait is “button” the control would be operated by speaking the word “tap” followed by the control’s Label. Or, if the trait is “adjustable” it can be operated by speaking the word “increment” followed by the Label
- VoiceOver users perceive and operate the control based on its Trait. For example, if the trait is “button” the control would be operated by double-tapping the control when focused. Or, if the trait is “adjustable” it can be incremented by swiping up.
Best practices:
- The Trait should represent the visual design and behaviors of a control, and vice versa.
- Details components already provide a Trait based on its template. Aim to use these, over something custom.
- Not all components need a Trait. Some Details components have intentionally left it out, such as Tappable.
- Hints can also provide role information.
How Custom Actions impact assistive technology users:
- Voice Control users perceive and operate the control’s other interactions with Custom Actions.
- VoiceOver users perceive and operate the control’s other interactions with Custom Actions.
Best practices:
- Use when you have multiple interactions/gestures for the same group (indicated by a Voiceover Group Stamp created in Step 2).
- A Custom Action Label for a visible control within a group should match the control’s visible label.
- A Custom Action Label for non-visible controls/gestures should be meaningful and concise.
- Set the default action to something logical.
A succinct string of text that identifies the element.
How an Informative Label impacts assistive technology users:
- Voice Control users do not use an Informative’s Label since it’s not interactive. They will likely perceive the label visually instead.
- VoiceOver users perceive all the content in Label as an announcement when they focus on the interactive element/group.
Best practices: Label should match the visible label Label should not change Use Value for dynamic content
A string that contains the current value of the element.
How an Informative Value impacts assistive technology users:
- VoiceOver users perceive the Informative element’s details & current state (or other dynamic content) with Value.
- Voice Control users do not use an Informative’s Value since it’s not interactive. They will likely perceive the Value visually instead.
- Braille users explore dynamic and important details like price in Value.
Best practices:
- Value should be reserved for those important and dynamic details.
This resource was built with organizations in mind. Styles can be easily changed to your preference. We’ve implemented Visual Regression Tests (VRTs) to help ensure that components don’t break and no data is lost when publishing your own library updates.
This resource is designed to be published as a Figma library to provide a single set of annotations for your organization or team. You can then use the kit by managing the libraries in your design files.
If you are not on a paid Figma plan, you can still use the kit by copying and pasting the components locally into your design file.
All text styles, color styles, and variables have an underscore prefix (e.g. “_Button”) so that these are not published to your organization.
All the colors and text styles used in this kit are stored locally. You can access local styles for Text, Color, and the drop shadow Effect used for annotation stamps in the right sidebar when nothing is selected, or from the style picker.
After updating Text, Color, or Effect styles, your changes should be immediately reflected anywhere this kit is used.
Note: It is highly recommended that you ensure any new colors maintain a 4.5:1 contrast ratio to help ensure everyone using the kit and reading annotations can perceive them.
For more help, visit create color, text, effect and layout grid styles on Figma.com.
Unique vector icons are used for each type of annotation and are stored as components on this page. These can be changed in the Internal library components frame on the far right side of the -- Customize this kit -- page.
Any updates will be immediately reflected anywhere this kit is used.
If you are publishing this kit as a Figma asset Library, we recommend that any updates you make to the kit components be done carefully. Customizations that are more complex than changing styles or swapping out icons, for example, may affect components in a way that causes data loss.
In other words, when you update a core Stamp or Detail component and publish those changes to the Library itself, it’s possible that any existing annotations which were created using this Kit could lose some of the data you’ve entered. For example, incremented Stamp numbers might be reset, or custom properties in the Detail components might be reset.
To help prevent this, we’ve created a Visual Regression Testing (VRT) tool for every component in the kit.
When making changes to a component, it is highly recommended you use Figma branching. This gives you the ability to compare changes between the main file and the branch.
The VRTs provide an opportunity for a human review to check that the update will not break an instance already consumed by a team. If the reflection of the VRT is not what you want consumers to receive, you are able to make corrective changes before publishing that update.
In each VRT:
- All number properties in VRTs are set to
333. - All text properties in VRTs are set to
override override... - All boolean properties in VRTs are toggled (not the default value).
- All Pin, Lasso and Detail components have been resized.
When comparing changes during a branch review, if these overrides have been unexpectedly changed between the Before view and Latest view, your changes may break existing annotations in other files.
This kit is brought to you by the CVS Health® Inclusive Design team.
- Kevin Oliveira, Sr. Accessibility Designer
- Daniel Henderson-Ede, Sr. Accessibility Designer
- Jan Maarten, Sr. Accessibility Designer
Special thanks to Julian Kittelson-Aldred and Marc Solomon and for their invaluable feedback.
Apple Pay®, Apple Fitness+℠, and Apple TV® are trademarks and/or service marks of Apple Inc. IOS is a trademark of Cisco Systems, Inc. The Accessibility Annotation Kit for iOS is an independent publication and has not been authorized, endorsed, or sponsored by Apple Inc.