From b7de95b1ae8a11b84bc6fc1e45fae363c3f55809 Mon Sep 17 00:00:00 2001 From: Pauline Auvray Date: Tue, 10 Oct 2023 09:28:18 +0200 Subject: [PATCH] [#638] Add accessibility information in documentation --- docs/components/Banners.md | 4 +--- docs/components/Buttons.md | 6 ++--- docs/components/Cards.md | 1 + docs/components/Dialogs.md | 3 --- docs/components/FloatingActionButtons.md | 10 ++++----- docs/components/ImageTile.md | 2 ++ docs/components/Menus.md | 2 ++ docs/components/NavigationBottom.md | 4 +++- docs/components/NavigationDrawers.md | 1 - docs/components/SheetsBottom.md | 3 ++- docs/components/Tabs.md | 9 -------- docs/components/TextFields.md | 28 +----------------------- 12 files changed, 20 insertions(+), 53 deletions(-) diff --git a/docs/components/Banners.md b/docs/components/Banners.md index 191409e32..17e302c08 100644 --- a/docs/components/Banners.md +++ b/docs/components/Banners.md @@ -30,9 +30,7 @@ Only one banner should be shown at a time Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) -Users should be able to use the left phone buttons to interact with the banner. -The user should be able to hear the current state of the banner at all times. -Recommendation is available at the Orange Accessibility site +`OdsBanner` is built to support accessibility criteria and is readable by most screen readers, such as TalkBack. The use of an `OdsBannerImage` force the developer to associate a content description to the banner image. ## Implementation diff --git a/docs/components/Buttons.md b/docs/components/Buttons.md index 63979ed3b..9d736d278 100644 --- a/docs/components/Buttons.md +++ b/docs/components/Buttons.md @@ -31,9 +31,9 @@ description: Buttons allow users to take actions, and make choices, with a singl Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) -Buttons support content labeling for accessibility and are readable by most screen readers, such as -TalkBack. Text rendered in buttons is automatically provided to accessibility services. Additional -content labels are usually unnecessary. +ODS buttons support accessibility criteria and are readable by most screen readers, such as TalkBack. + +Content descriptions for icons are unnecessary in the case of buttons containing text. For other buttons types, such as `OdsIconButton`, icons content descriptions are mandatory in the APIs. ## Variants diff --git a/docs/components/Cards.md b/docs/components/Cards.md index b743e0211..a845c09f7 100644 --- a/docs/components/Cards.md +++ b/docs/components/Cards.md @@ -29,6 +29,7 @@ description: Cards contain content and actions about a single subject. Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) The contents within a card should follow their own accessibility guidelines, such as images having content descriptions set on them. +The ODS library cards APIs forces the developers to add content descriptions on card images. ## Variants diff --git a/docs/components/Dialogs.md b/docs/components/Dialogs.md index 889ec197f..18dbd6e87 100644 --- a/docs/components/Dialogs.md +++ b/docs/components/Dialogs.md @@ -32,9 +32,6 @@ Dialogs are purposefully interruptive, so they should be used sparingly. Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) -The contents within a dialog should follow their own accessibility guidelines, -such as an icon on a title having a content description. - ## Variants ### Alert dialog diff --git a/docs/components/FloatingActionButtons.md b/docs/components/FloatingActionButtons.md index a7c5f2683..1806cd241 100644 --- a/docs/components/FloatingActionButtons.md +++ b/docs/components/FloatingActionButtons.md @@ -27,11 +27,11 @@ description: A floating action button (FAB) represents the primary action of a s Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) -You should set a content description on a FAB via the -`android:contentDescription` attribute or `setContentDescription` method so that -screen readers like TalkBack are able to announce their purpose or action. Text -rendered in Extended FABs is automatically provided to accessibility services, -so additional content labels are usually unnecessary. +The `OdsFloatingActionButtonIcon` used in Floating Action Buttons APIs force the developers to set a content description to the FABs so that +screen readers like TalkBack are able to announce their purpose or action. + +Text rendered in an extended FAB is automatically provided to accessibility services, so additional content labels are usually unnecessary. +In this context you can set an empty `contentDescription`. ## Variants diff --git a/docs/components/ImageTile.md b/docs/components/ImageTile.md index bddb5f037..2720f041f 100644 --- a/docs/components/ImageTile.md +++ b/docs/components/ImageTile.md @@ -24,6 +24,8 @@ description: Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) +An image in an `OdsImageTile` should always be associated to a content description. This is the reason why the `OdsImageTileImage` forces the developer to fill a content description parameter. + ## Implementation #### Jetpack Compose diff --git a/docs/components/Menus.md b/docs/components/Menus.md index 51770e863..940606d3f 100644 --- a/docs/components/Menus.md +++ b/docs/components/Menus.md @@ -26,6 +26,8 @@ description: Menus appear from a button, action, or other control. It contains a Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) +The icons which can be displayed in a dropdown menu are always associated to a text so they don't need a content description. + ## Variants ### Dropdown menu diff --git a/docs/components/NavigationBottom.md b/docs/components/NavigationBottom.md index cbcd05094..d02eeb3dd 100644 --- a/docs/components/NavigationBottom.md +++ b/docs/components/NavigationBottom.md @@ -24,6 +24,8 @@ description: Bottom navigation bars allow movement between primary destinations Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) +Note that TalkBack already reads the bottom navigation items labels so the content descriptions of the `OdsBottomNavigationItemIcon`s can be empty. + ## Implementation ![BottomNavigation light](images/bottom_navigation_light.png) @@ -58,7 +60,7 @@ OdsBottomNavigation( icon = OdsBottomNavigationItemIcon( painter = painterResource(id = item.first), contentDescription = "" - ), // contentDescription is empty cause TalkBack already read the item's title + ), // contentDescription is empty cause TalkBack already read the item's label label = stringResource(id = item.second), selected = selectedItemIndex == index, onClick = { diff --git a/docs/components/NavigationDrawers.md b/docs/components/NavigationDrawers.md index a49e1c358..fad504c4f 100644 --- a/docs/components/NavigationDrawers.md +++ b/docs/components/NavigationDrawers.md @@ -19,7 +19,6 @@ description: The navigation drawer slides in from the left when the nav icon is - [Design System Manager - Navigation drawers](https://system.design.orange.com/0c1af118d/p/92bc26-navigation-drawers/b/146f55) - [Material Design - Navigation drawer](https://m2.material.io/components/navigation-drawer) -- Technical documentation soon available ## Accessibility diff --git a/docs/components/SheetsBottom.md b/docs/components/SheetsBottom.md index c6bfaa31d..d72081c79 100644 --- a/docs/components/SheetsBottom.md +++ b/docs/components/SheetsBottom.md @@ -24,7 +24,6 @@ Use Sheets bottom to: - [Design System Manager - Sheets](https://system.design.orange.com/0c1af118d/p/81f927-sheets-bottom/b/47b99b) - [Material Design - Sheets: bottom](https://material.io/components/sheets-bottom) -- Technical documentation soon available ## Accessibility @@ -34,6 +33,8 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o ![BottomSheet light](images/sheetbottom_light.png) ![BottomSheet dark](images/sheetbottom_dark.png) +The contents within a bottom sheet should follow their own accessibility guidelines, such as images having content descriptions set on them. + ### Jetpack Compose ```kotlin diff --git a/docs/components/Tabs.md b/docs/components/Tabs.md index 86bdc6761..57113a3f1 100644 --- a/docs/components/Tabs.md +++ b/docs/components/Tabs.md @@ -29,15 +29,6 @@ Please follow [accessibility criteria for development](https://a11y-guidelines.o The Android tab components support screen reader descriptions for tabs and badges. While optional, we strongly encourage their use. -**Content description** - -Adding a content description to the entire `TabLayout` can be done in XML with -the `android:contentDescription` attribute or programmatically like so: - -```kotlin -tabLayout.contentDescription = contentDescription -``` - ## Variants ### Fixed tabs diff --git a/docs/components/TextFields.md b/docs/components/TextFields.md index 266900fdf..f77d4ae2d 100644 --- a/docs/components/TextFields.md +++ b/docs/components/TextFields.md @@ -29,33 +29,7 @@ description: Text fields let users enter and edit text. Please follow [accessibility criteria for development](https://a11y-guidelines.orange.com/en/mobile/android/development/) Android's text field component APIs support both label text and helper text for informing the user -as to what information is requested for a text field. While optional, their use is strongly -encouraged. - -**Content description** - -When using **custom icons**, you should set a content description on them so that screen readers -like TalkBack are able to announce their purpose or action, if any. - -For the leading icon, that can be achieved via the -`app:startIconContentDescription` attribute or `setStartIconContentDescription` -method. For the trailing icon, that can be achieved via the -`app:endIconContentDescription` attribute or `setEndIconContentDescription` -method. - -When setting an **error message** that contains special characters that screen readers or other -accessibility systems are not able to read, you should set a content description via -the `app:errorContentDescription` attribute or -`setErrorContentDescription` method. That way, when the error needs to be announced, it will -announce the content description instead. - -**Custom `EditText`** - -If you are using a custom `EditText` as `TextInputLayout`'s child and your text field requires -different accessibility support than the one offered by -`TextInputLayout`, you can set a `TextInputLayout.AccessibilityDelegate` via the -`setTextInputAccessibilityDelegate` method. This method should be used in place of providing -an `AccessibilityDelegate` directly on the `EditText`. +as to what information is requested for a text field. ## Variants