[#638] Add accessibility information in documentation

Orange-OpenSource · Oct 13, 2023 · b7de95b · b7de95b
1 parent 17bba32
commit b7de95b
Show file tree

Hide file tree

Showing 12 changed files with 20 additions and 53 deletions.
diff --git 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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