From 5feb51d6a618bfbfb4830ba8e3f33b9af59af316 Mon Sep 17 00:00:00 2001 From: Alessandro Senese Date: Fri, 26 Jul 2024 01:08:27 +0100 Subject: [PATCH] Move guidelines checklist outside versioning (#216) * move outside versioning * rename file * custom autogenerate sidebar * specify custom sidebar --- .../checklist/bottom-sheet-drawer.md | 4 + .../checklist/bottom-tab-navigator.md | 4 + .../checklist/bottomsheet.excalidraw | 0 website/{docs => }/checklist/bottomsheet.png | Bin website/{docs => }/checklist/button.md | 4 + website/{docs => }/checklist/button.png | Bin .../{docs => }/checklist/buttons.excalidraw | 0 website/checklist/carousel.md | 5 + website/{docs => }/checklist/focus.excalidraw | 0 website/{docs => }/checklist/focus.gif | 0 website/{docs => }/checklist/focus.md | 4 + .../{docs => }/checklist/form-disabled.png | Bin website/{docs => }/checklist/form-error.png | Bin website/{docs => }/checklist/form-focused.png | Bin .../{docs => }/checklist/form-selected.png | Bin website/{docs => }/checklist/form.excalidraw | 0 website/{docs => }/checklist/forms.md | 4 + website/{docs => }/checklist/grid.excalidraw | 0 website/{docs => }/checklist/grid.png | Bin .../{docs => }/checklist/headers.excalidraw | 0 website/{docs => }/checklist/headers.png | Bin website/{docs => }/checklist/headings.md | 4 + .../checklist.md => checklist/index.md} | 1 + website/{docs => }/checklist/list-grids.md | 4 + .../{docs => }/checklist/tabbar.excalidraw | 0 website/{docs => }/checklist/tabbar.png | Bin website/{docs => }/checklist/text.excalidraw | 0 website/{docs => }/checklist/text.gif | 0 website/{docs => }/checklist/text.md | 4 + website/{docs => }/checklist/timed-actions.md | 4 + website/docs/checklist/carousel.md | 1 - website/docs/guidelines/accessibility-hint.md | 23 --- website/docs/guidelines/grouping.md | 1 - website/docusaurus.config.ts | 56 +++++--- .../guidelines/accessibility-hint.md | 11 +- .../guidelines/accessibility-label.md | 1 + .../guidelines/accessibility-role.md | 1 + .../guidelines/accessibility-states.md | 1 + .../guidelines/android-list-feature.gif | 0 website/{docs => }/guidelines/animations.md | 1 + website/{docs => }/guidelines/bottomsheet.md | 1 + website/{docs => }/guidelines/carousel.md | 1 + website/{docs => }/guidelines/contrast.md | 1 + .../guidelines/email-field-with-error.png | 0 website/{docs => }/guidelines/focus.md | 1 + website/{docs => }/guidelines/forms.md | 1 + website/guidelines/grouping.md | 5 + website/{docs => }/guidelines/headers.md | 1 + .../guidelines.md => guidelines/index.md} | 2 +- website/{docs => }/guidelines/lists-grids.md | 1 + website/{docs => }/guidelines/minimum-size.md | 1 + website/{docs => }/guidelines/next-key.jpg | Bin website/{docs => }/guidelines/pour.md | 1 + website/{docs => }/guidelines/text.md | 1 + .../{docs => }/guidelines/timed-actions.md | 1 + .../type-of-accessibility-issues.md | 1 + website/sidebars.ts | 54 ++++++- .../versioned_docs/version-0.7.x/checklist.md | 92 ------------ .../version-0.7.x/guidelines/_category_.json | 4 - .../guidelines/accessibility-label.md | 132 ------------------ .../guidelines/accessibility-role.md | 49 ------- .../version-0.7.x/guidelines/animations.md | 27 ---- .../version-0.7.x/guidelines/bottomsheet.md | 23 --- .../version-0.7.x/guidelines/carousel.md | 45 ------ .../version-0.7.x/guidelines/contrast.md | 30 ---- .../version-0.7.x/guidelines/focus.md | 43 ------ .../version-0.7.x/guidelines/forms.md | 105 -------------- .../version-0.7.x/guidelines/guidelines.md | 19 --- .../version-0.7.x/guidelines/headers.md | 29 ---- .../version-0.7.x/guidelines/lists-grids.md | 22 --- .../version-0.7.x/guidelines/minimum-size.md | 30 ---- .../guidelines/predictable-consistent.md | 6 - .../version-0.7.x/guidelines/text.md | 92 ------------ .../version-0.7.x/guidelines/timed-actions.md | 28 ---- 74 files changed, 158 insertions(+), 829 deletions(-) rename website/{docs => }/checklist/bottom-sheet-drawer.md (97%) rename website/{docs => }/checklist/bottom-tab-navigator.md (98%) rename website/{docs => }/checklist/bottomsheet.excalidraw (100%) rename website/{docs => }/checklist/bottomsheet.png (100%) rename website/{docs => }/checklist/button.md (98%) rename website/{docs => }/checklist/button.png (100%) rename website/{docs => }/checklist/buttons.excalidraw (100%) create mode 100644 website/checklist/carousel.md rename website/{docs => }/checklist/focus.excalidraw (100%) rename website/{docs => }/checklist/focus.gif (100%) rename website/{docs => }/checklist/focus.md (94%) rename website/{docs => }/checklist/form-disabled.png (100%) rename website/{docs => }/checklist/form-error.png (100%) rename website/{docs => }/checklist/form-focused.png (100%) rename website/{docs => }/checklist/form-selected.png (100%) rename website/{docs => }/checklist/form.excalidraw (100%) rename website/{docs => }/checklist/forms.md (98%) rename website/{docs => }/checklist/grid.excalidraw (100%) rename website/{docs => }/checklist/grid.png (100%) rename website/{docs => }/checklist/headers.excalidraw (100%) rename website/{docs => }/checklist/headers.png (100%) rename website/{docs => }/checklist/headings.md (94%) rename website/{docs/checklist/checklist.md => checklist/index.md} (97%) rename website/{docs => }/checklist/list-grids.md (95%) rename website/{docs => }/checklist/tabbar.excalidraw (100%) rename website/{docs => }/checklist/tabbar.png (100%) rename website/{docs => }/checklist/text.excalidraw (100%) rename website/{docs => }/checklist/text.gif (100%) rename website/{docs => }/checklist/text.md (97%) rename website/{docs => }/checklist/timed-actions.md (96%) delete mode 100644 website/docs/checklist/carousel.md delete mode 100644 website/docs/guidelines/accessibility-hint.md delete mode 100644 website/docs/guidelines/grouping.md rename website/{versioned_docs/version-0.7.x => }/guidelines/accessibility-hint.md (86%) rename website/{docs => }/guidelines/accessibility-label.md (99%) rename website/{docs => }/guidelines/accessibility-role.md (98%) rename website/{docs => }/guidelines/accessibility-states.md (99%) rename website/{docs => }/guidelines/android-list-feature.gif (100%) rename website/{docs => }/guidelines/animations.md (98%) rename website/{docs => }/guidelines/bottomsheet.md (98%) rename website/{docs => }/guidelines/carousel.md (98%) rename website/{docs => }/guidelines/contrast.md (99%) rename website/{docs => }/guidelines/email-field-with-error.png (100%) rename website/{docs => }/guidelines/focus.md (98%) rename website/{docs => }/guidelines/forms.md (99%) create mode 100644 website/guidelines/grouping.md rename website/{docs => }/guidelines/headers.md (99%) rename website/{docs/guidelines/guidelines.md => guidelines/index.md} (97%) rename website/{docs => }/guidelines/lists-grids.md (98%) rename website/{docs => }/guidelines/minimum-size.md (98%) rename website/{docs => }/guidelines/next-key.jpg (100%) rename website/{docs => }/guidelines/pour.md (99%) rename website/{docs => }/guidelines/text.md (99%) rename website/{docs => }/guidelines/timed-actions.md (98%) rename website/{docs => }/guidelines/type-of-accessibility-issues.md (99%) delete mode 100644 website/versioned_docs/version-0.7.x/checklist.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/_category_.json delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/accessibility-label.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/accessibility-role.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/animations.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/bottomsheet.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/carousel.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/contrast.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/focus.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/forms.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/guidelines.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/headers.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/lists-grids.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/minimum-size.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/predictable-consistent.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/text.md delete mode 100644 website/versioned_docs/version-0.7.x/guidelines/timed-actions.md diff --git a/website/docs/checklist/bottom-sheet-drawer.md b/website/checklist/bottom-sheet-drawer.md similarity index 97% rename from website/docs/checklist/bottom-sheet-drawer.md rename to website/checklist/bottom-sheet-drawer.md index a9ded83d..85a3e8fe 100644 --- a/website/docs/checklist/bottom-sheet-drawer.md +++ b/website/checklist/bottom-sheet-drawer.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import BottomSheet from './bottomsheet.png'; # BottomSheet & Drawers diff --git a/website/docs/checklist/bottom-tab-navigator.md b/website/checklist/bottom-tab-navigator.md similarity index 98% rename from website/docs/checklist/bottom-tab-navigator.md rename to website/checklist/bottom-tab-navigator.md index 660b0460..aa315cf3 100644 --- a/website/docs/checklist/bottom-tab-navigator.md +++ b/website/checklist/bottom-tab-navigator.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import TabBar from './tabbar.png'; # Bottom Tab Navigator diff --git a/website/docs/checklist/bottomsheet.excalidraw b/website/checklist/bottomsheet.excalidraw similarity index 100% rename from website/docs/checklist/bottomsheet.excalidraw rename to website/checklist/bottomsheet.excalidraw diff --git a/website/docs/checklist/bottomsheet.png b/website/checklist/bottomsheet.png similarity index 100% rename from website/docs/checklist/bottomsheet.png rename to website/checklist/bottomsheet.png diff --git a/website/docs/checklist/button.md b/website/checklist/button.md similarity index 98% rename from website/docs/checklist/button.md rename to website/checklist/button.md index 49815c5e..c8e52bea 100644 --- a/website/docs/checklist/button.md +++ b/website/checklist/button.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import Button from './button.png'; # Button diff --git a/website/docs/checklist/button.png b/website/checklist/button.png similarity index 100% rename from website/docs/checklist/button.png rename to website/checklist/button.png diff --git a/website/docs/checklist/buttons.excalidraw b/website/checklist/buttons.excalidraw similarity index 100% rename from website/docs/checklist/buttons.excalidraw rename to website/checklist/buttons.excalidraw diff --git a/website/checklist/carousel.md b/website/checklist/carousel.md new file mode 100644 index 00000000..1a65523d --- /dev/null +++ b/website/checklist/carousel.md @@ -0,0 +1,5 @@ +--- +displayed_sidebar: checklist +--- + +# Carousel diff --git a/website/docs/checklist/focus.excalidraw b/website/checklist/focus.excalidraw similarity index 100% rename from website/docs/checklist/focus.excalidraw rename to website/checklist/focus.excalidraw diff --git a/website/docs/checklist/focus.gif b/website/checklist/focus.gif similarity index 100% rename from website/docs/checklist/focus.gif rename to website/checklist/focus.gif diff --git a/website/docs/checklist/focus.md b/website/checklist/focus.md similarity index 94% rename from website/docs/checklist/focus.md rename to website/checklist/focus.md index a9858ccc..16a2c731 100644 --- a/website/docs/checklist/focus.md +++ b/website/checklist/focus.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import Focus from './focus.gif'; # Focus diff --git a/website/docs/checklist/form-disabled.png b/website/checklist/form-disabled.png similarity index 100% rename from website/docs/checklist/form-disabled.png rename to website/checklist/form-disabled.png diff --git a/website/docs/checklist/form-error.png b/website/checklist/form-error.png similarity index 100% rename from website/docs/checklist/form-error.png rename to website/checklist/form-error.png diff --git a/website/docs/checklist/form-focused.png b/website/checklist/form-focused.png similarity index 100% rename from website/docs/checklist/form-focused.png rename to website/checklist/form-focused.png diff --git a/website/docs/checklist/form-selected.png b/website/checklist/form-selected.png similarity index 100% rename from website/docs/checklist/form-selected.png rename to website/checklist/form-selected.png diff --git a/website/docs/checklist/form.excalidraw b/website/checklist/form.excalidraw similarity index 100% rename from website/docs/checklist/form.excalidraw rename to website/checklist/form.excalidraw diff --git a/website/docs/checklist/forms.md b/website/checklist/forms.md similarity index 98% rename from website/docs/checklist/forms.md rename to website/checklist/forms.md index 317dc6c4..abc7a686 100644 --- a/website/docs/checklist/forms.md +++ b/website/checklist/forms.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import FormDisabled from './form-disabled.png'; import FormError from './form-error.png'; import FormFocused from './form-focused.png'; diff --git a/website/docs/checklist/grid.excalidraw b/website/checklist/grid.excalidraw similarity index 100% rename from website/docs/checklist/grid.excalidraw rename to website/checklist/grid.excalidraw diff --git a/website/docs/checklist/grid.png b/website/checklist/grid.png similarity index 100% rename from website/docs/checklist/grid.png rename to website/checklist/grid.png diff --git a/website/docs/checklist/headers.excalidraw b/website/checklist/headers.excalidraw similarity index 100% rename from website/docs/checklist/headers.excalidraw rename to website/checklist/headers.excalidraw diff --git a/website/docs/checklist/headers.png b/website/checklist/headers.png similarity index 100% rename from website/docs/checklist/headers.png rename to website/checklist/headers.png diff --git a/website/docs/checklist/headings.md b/website/checklist/headings.md similarity index 94% rename from website/docs/checklist/headings.md rename to website/checklist/headings.md index 29525431..810d1d44 100644 --- a/website/docs/checklist/headings.md +++ b/website/checklist/headings.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import Headers from './headers.png'; # Headings diff --git a/website/docs/checklist/checklist.md b/website/checklist/index.md similarity index 97% rename from website/docs/checklist/checklist.md rename to website/checklist/index.md index f6c1f3b9..a98cdb2c 100644 --- a/website/docs/checklist/checklist.md +++ b/website/checklist/index.md @@ -1,5 +1,6 @@ --- sidebar_position: 0 +displayed_sidebar: checklist --- # Accessibility Checklist diff --git a/website/docs/checklist/list-grids.md b/website/checklist/list-grids.md similarity index 95% rename from website/docs/checklist/list-grids.md rename to website/checklist/list-grids.md index 74860939..98c397a4 100644 --- a/website/docs/checklist/list-grids.md +++ b/website/checklist/list-grids.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import Grid from './grid.png'; # List & Grids diff --git a/website/docs/checklist/tabbar.excalidraw b/website/checklist/tabbar.excalidraw similarity index 100% rename from website/docs/checklist/tabbar.excalidraw rename to website/checklist/tabbar.excalidraw diff --git a/website/docs/checklist/tabbar.png b/website/checklist/tabbar.png similarity index 100% rename from website/docs/checklist/tabbar.png rename to website/checklist/tabbar.png diff --git a/website/docs/checklist/text.excalidraw b/website/checklist/text.excalidraw similarity index 100% rename from website/docs/checklist/text.excalidraw rename to website/checklist/text.excalidraw diff --git a/website/docs/checklist/text.gif b/website/checklist/text.gif similarity index 100% rename from website/docs/checklist/text.gif rename to website/checklist/text.gif diff --git a/website/docs/checklist/text.md b/website/checklist/text.md similarity index 97% rename from website/docs/checklist/text.md rename to website/checklist/text.md index fd3947da..a33820e6 100644 --- a/website/docs/checklist/text.md +++ b/website/checklist/text.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + import Text from './text.gif'; # Text diff --git a/website/docs/checklist/timed-actions.md b/website/checklist/timed-actions.md similarity index 96% rename from website/docs/checklist/timed-actions.md rename to website/checklist/timed-actions.md index ea43d915..3c19488b 100644 --- a/website/docs/checklist/timed-actions.md +++ b/website/checklist/timed-actions.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: checklist +--- + # Timed Actions | User | I Can | diff --git a/website/docs/checklist/carousel.md b/website/docs/checklist/carousel.md deleted file mode 100644 index 2631ae81..00000000 --- a/website/docs/checklist/carousel.md +++ /dev/null @@ -1 +0,0 @@ -# Carousel diff --git a/website/docs/guidelines/accessibility-hint.md b/website/docs/guidelines/accessibility-hint.md deleted file mode 100644 index 54a5fa92..00000000 --- a/website/docs/guidelines/accessibility-hint.md +++ /dev/null @@ -1,23 +0,0 @@ -# Accessibility Hint - -Accessibility hint helps users understand the element's purpose when the accessibility label alone is not enough. -For example: - -```jsx - - lib - Like - - -``` -In the example announcing only "Like" might be not enough for a screen reader user, so we've added the extra information: "Likes the song." - -:::danger - -The field is optional and should only be used if the label itself is not self-explanatory, don't overload a screen reader user with too much information. - -::: diff --git a/website/docs/guidelines/grouping.md b/website/docs/guidelines/grouping.md deleted file mode 100644 index 12e5efbc..00000000 --- a/website/docs/guidelines/grouping.md +++ /dev/null @@ -1 +0,0 @@ -# Grouping diff --git a/website/docusaurus.config.ts b/website/docusaurus.config.ts index f5f39552..ac496d3b 100644 --- a/website/docusaurus.config.ts +++ b/website/docusaurus.config.ts @@ -139,24 +139,39 @@ const config: Config = { ...defaultPresets, }, ], - // [ - // '@docusaurus/plugin-content-docs', - // { - // id: 'guidelines', - // path: '../docs/guidelines', - // routeBasePath: 'guidelines', - // ...defaultPresets, - // }, - // ], - // [ - // '@docusaurus/plugin-content-docs', - // { - // id: 'checklist', - // path: '../docs/checklist', - // routeBasePath: '/checklist/', - // ...defaultPresets, - // }, - // ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'guidelines', + path: 'guidelines', + routeBasePath: 'guidelines', + async sidebarItemsGenerator({ + defaultSidebarItemsGenerator, + numberPrefixParser, + item, + version, + docs, + categoriesMetadata, + isCategoryIndex, + }) { + // Example: return an hardcoded list of static sidebar items + return [ + { type: 'doc', id: 'bottomsheet' }, + { type: 'doc', id: 'bottomsheet' }, + ]; + }, + ...defaultPresets, + }, + ], + [ + '@docusaurus/plugin-content-docs', + { + id: 'checklist', + path: 'checklist', + routeBasePath: '/checklist/', + ...defaultPresets, + }, + ], ], themeConfig: { docs: { @@ -176,17 +191,14 @@ const config: Config = { to: '/docs/', }, { - type: 'docsVersion', - to: 'docs/guidelines', position: 'left', label: 'Guidelines', to: '/guidelines/', }, { - type: 'docsVersion', label: 'Checklist', position: 'left', - to: 'docs/checklist', + to: '/checklist/', }, { label: 'Packages', diff --git a/website/versioned_docs/version-0.7.x/guidelines/accessibility-hint.md b/website/guidelines/accessibility-hint.md similarity index 86% rename from website/versioned_docs/version-0.7.x/guidelines/accessibility-hint.md rename to website/guidelines/accessibility-hint.md index 54a5fa92..ce0eae5c 100644 --- a/website/versioned_docs/version-0.7.x/guidelines/accessibility-hint.md +++ b/website/guidelines/accessibility-hint.md @@ -1,3 +1,7 @@ +--- +displayed_sidebar: guidelines +--- + # Accessibility Hint Accessibility hint helps users understand the element's purpose when the accessibility label alone is not enough. @@ -8,12 +12,15 @@ For example: accessible={true} accessibilityLabel="Like" accessibilityHint="Likes the song" - onPress={onPress}> - lib + onPress={onPress} +> + + lib Like ``` + In the example announcing only "Like" might be not enough for a screen reader user, so we've added the extra information: "Likes the song." :::danger diff --git a/website/docs/guidelines/accessibility-label.md b/website/guidelines/accessibility-label.md similarity index 99% rename from website/docs/guidelines/accessibility-label.md rename to website/guidelines/accessibility-label.md index f59c3695..ae550487 100644 --- a/website/docs/guidelines/accessibility-label.md +++ b/website/guidelines/accessibility-label.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Understandable ama_affected_users: Visual ama_success_criterion: 4.1.2@https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html +displayed_sidebar: guidelines --- # Accessibility Label diff --git a/website/docs/guidelines/accessibility-role.md b/website/guidelines/accessibility-role.md similarity index 98% rename from website/docs/guidelines/accessibility-role.md rename to website/guidelines/accessibility-role.md index 2a922a29..a576ce13 100644 --- a/website/docs/guidelines/accessibility-role.md +++ b/website/guidelines/accessibility-role.md @@ -3,6 +3,7 @@ ama_severity: Critical ama_category: Operable ama_affected_users: Visual, Motor ama_success_criterion: 4.1.2@https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html +displayed_sidebar: guidelines --- # Accessibility Role diff --git a/website/docs/guidelines/accessibility-states.md b/website/guidelines/accessibility-states.md similarity index 99% rename from website/docs/guidelines/accessibility-states.md rename to website/guidelines/accessibility-states.md index 08bb721b..51d57d16 100644 --- a/website/docs/guidelines/accessibility-states.md +++ b/website/guidelines/accessibility-states.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Understandable ama_affected_users: Visual ama_success_criterion: 4.1.2@https://www.w3.org/WAI/WCAG21/Understanding/name-role-value.html +displayed_sidebar: guidelines --- # Accessibility States diff --git a/website/docs/guidelines/android-list-feature.gif b/website/guidelines/android-list-feature.gif similarity index 100% rename from website/docs/guidelines/android-list-feature.gif rename to website/guidelines/android-list-feature.gif diff --git a/website/docs/guidelines/animations.md b/website/guidelines/animations.md similarity index 98% rename from website/docs/guidelines/animations.md rename to website/guidelines/animations.md index ff89c49d..d9ad74a5 100644 --- a/website/docs/guidelines/animations.md +++ b/website/guidelines/animations.md @@ -3,6 +3,7 @@ ama_severity: Critical ama_category: Operable ama_affected_users: Cognitive ama_success_criterion: 2.3.3@https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html +displayed_sidebar: guidelines --- # Animations diff --git a/website/docs/guidelines/bottomsheet.md b/website/guidelines/bottomsheet.md similarity index 98% rename from website/docs/guidelines/bottomsheet.md rename to website/guidelines/bottomsheet.md index 53792888..d35cadb3 100644 --- a/website/docs/guidelines/bottomsheet.md +++ b/website/guidelines/bottomsheet.md @@ -3,6 +3,7 @@ ama_severity: Critical ama_category: Operable ama_affected_users: Visual, Motor, Cognitive ama_success_criterion: 2.3.3@https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html +displayed_sidebar: guidelines --- # BottomSheet & Drawer diff --git a/website/docs/guidelines/carousel.md b/website/guidelines/carousel.md similarity index 98% rename from website/docs/guidelines/carousel.md rename to website/guidelines/carousel.md index 3e95a5fd..cb67c042 100644 --- a/website/docs/guidelines/carousel.md +++ b/website/guidelines/carousel.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Operable ama_affected_users: Visual, Motor ama_success_criterion: 2.3.3@https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html +displayed_sidebar: guidelines --- # Carousel diff --git a/website/docs/guidelines/contrast.md b/website/guidelines/contrast.md similarity index 99% rename from website/docs/guidelines/contrast.md rename to website/guidelines/contrast.md index 4e69483f..11146d99 100644 --- a/website/docs/guidelines/contrast.md +++ b/website/guidelines/contrast.md @@ -3,6 +3,7 @@ ama_severity: Critical ama_category: Perceivable ama_affected_users: Vision ama_success_criterion: 1.4.3@https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum +displayed_sidebar: guidelines --- # Contrast diff --git a/website/docs/guidelines/email-field-with-error.png b/website/guidelines/email-field-with-error.png similarity index 100% rename from website/docs/guidelines/email-field-with-error.png rename to website/guidelines/email-field-with-error.png diff --git a/website/docs/guidelines/focus.md b/website/guidelines/focus.md similarity index 98% rename from website/docs/guidelines/focus.md rename to website/guidelines/focus.md index 48ac320f..8534c626 100644 --- a/website/docs/guidelines/focus.md +++ b/website/guidelines/focus.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Operable ama_affected_users: Visual, Mobility, Cognitive ama_success_criterion: 2.4.3@https://www.w3.org/WAI/WCAG21/Understanding/focus-order +displayed_sidebar: guidelines --- # Focus diff --git a/website/docs/guidelines/forms.md b/website/guidelines/forms.md similarity index 99% rename from website/docs/guidelines/forms.md rename to website/guidelines/forms.md index 2b6fc74d..2d1267c8 100644 --- a/website/docs/guidelines/forms.md +++ b/website/guidelines/forms.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Operable ama_affected_users: Visual, Mobility, Cognitive ama_success_criterion: 3.3@https://www.w3.org/WAI/WCAG21/Understanding/input-assistance +displayed_sidebar: guidelines --- import EmailFieldWithError from './email-field-with-error.png'; diff --git a/website/guidelines/grouping.md b/website/guidelines/grouping.md new file mode 100644 index 00000000..1ab4cc4c --- /dev/null +++ b/website/guidelines/grouping.md @@ -0,0 +1,5 @@ +--- +displayed_sidebar: guidelines +--- + +# Grouping diff --git a/website/docs/guidelines/headers.md b/website/guidelines/headers.md similarity index 99% rename from website/docs/guidelines/headers.md rename to website/guidelines/headers.md index 31ecb891..da739914 100644 --- a/website/docs/guidelines/headers.md +++ b/website/guidelines/headers.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Operable ama_affected_users: Visual, Mobility ama_success_criterion: 2.4.6@https://www.w3.org/WAI/WCAG21/Understanding/headings-and-labels +displayed_sidebar: guidelines --- import AndroidListFeature from './android-list-feature.gif'; diff --git a/website/docs/guidelines/guidelines.md b/website/guidelines/index.md similarity index 97% rename from website/docs/guidelines/guidelines.md rename to website/guidelines/index.md index 384906ba..da65f2ef 100644 --- a/website/docs/guidelines/guidelines.md +++ b/website/guidelines/index.md @@ -1,5 +1,5 @@ --- -sidebar_position: 1 +displayed_sidebar: guidelines --- # Mobile Accessibility Guidelines diff --git a/website/docs/guidelines/lists-grids.md b/website/guidelines/lists-grids.md similarity index 98% rename from website/docs/guidelines/lists-grids.md rename to website/guidelines/lists-grids.md index 9b45babc..08deb010 100644 --- a/website/docs/guidelines/lists-grids.md +++ b/website/guidelines/lists-grids.md @@ -2,6 +2,7 @@ ama_severity: Serious ama_category: Perceivable ama_affected_users: Visual, Mobility +displayed_sidebar: guidelines --- # Lists & Grids diff --git a/website/docs/guidelines/minimum-size.md b/website/guidelines/minimum-size.md similarity index 98% rename from website/docs/guidelines/minimum-size.md rename to website/guidelines/minimum-size.md index 94df5a15..5a33fbf9 100644 --- a/website/docs/guidelines/minimum-size.md +++ b/website/guidelines/minimum-size.md @@ -2,6 +2,7 @@ ama_severity: Serious ama_category: Operable ama_affected_users: Visual, Mobility +displayed_sidebar: guidelines --- # Minimum Size diff --git a/website/docs/guidelines/next-key.jpg b/website/guidelines/next-key.jpg similarity index 100% rename from website/docs/guidelines/next-key.jpg rename to website/guidelines/next-key.jpg diff --git a/website/docs/guidelines/pour.md b/website/guidelines/pour.md similarity index 99% rename from website/docs/guidelines/pour.md rename to website/guidelines/pour.md index 381cb212..c51d2f7f 100644 --- a/website/docs/guidelines/pour.md +++ b/website/guidelines/pour.md @@ -1,5 +1,6 @@ --- sidebar_position: 1 +displayed_sidebar: guidelines --- # POUR - Accessibility Principles diff --git a/website/docs/guidelines/text.md b/website/guidelines/text.md similarity index 99% rename from website/docs/guidelines/text.md rename to website/guidelines/text.md index 5bce219a..98366362 100644 --- a/website/docs/guidelines/text.md +++ b/website/guidelines/text.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Perceivable ama_affected_users: Visual, Mobility ama_success_criterion: 2.1@https://www.w3.org/WAI/WCAG21/Understanding/distinguishable +displayed_sidebar: guidelines --- # Text diff --git a/website/docs/guidelines/timed-actions.md b/website/guidelines/timed-actions.md similarity index 98% rename from website/docs/guidelines/timed-actions.md rename to website/guidelines/timed-actions.md index 605f31ff..2185ac98 100644 --- a/website/docs/guidelines/timed-actions.md +++ b/website/guidelines/timed-actions.md @@ -3,6 +3,7 @@ ama_severity: Serious ama_category: Perceivable ama_affected_users: Visual, Mobility ama_success_criterion: 2.2.1@https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable +displayed_sidebar: guidelines --- # Timed actions diff --git a/website/docs/guidelines/type-of-accessibility-issues.md b/website/guidelines/type-of-accessibility-issues.md similarity index 99% rename from website/docs/guidelines/type-of-accessibility-issues.md rename to website/guidelines/type-of-accessibility-issues.md index d6cef31f..f2608581 100644 --- a/website/docs/guidelines/type-of-accessibility-issues.md +++ b/website/guidelines/type-of-accessibility-issues.md @@ -1,5 +1,6 @@ --- sidebar_position: 2 +displayed_sidebar: guidelines --- # Type of Accessibility Issues diff --git a/website/sidebars.ts b/website/sidebars.ts index 50eb8a39..a76f05e9 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -1,9 +1,57 @@ import type { SidebarsConfig } from '@docusaurus/plugin-content-docs'; +const SIDEBAR_POSITION_REGEX = /sidebar_position:\s?(\d+)/; +/** + * Looks like Docusaurus has an issue autogenerating docs for multi doc instance + * https://stackoverflow.com/questions/77528478/sidebar-wont-autogenerate-with-docs-multi-instances-on-docusaurus + */ +function capitalizeFirstLetter(string) { + return string.charAt(0).toUpperCase() + string.slice(1); +} + +function autoGenerate(path) { + const fs = require('fs'); + const files = fs.readdirSync(path); + + return files + .map(file => { + if (!file.endsWith('.md')) { + return null; + } + + const name = file.replace('.md', ''); + const content = fs.readFileSync(`${path}/${file}`, { + encoding: 'utf8', + flag: 'r', + }); + const position = content.match(SIDEBAR_POSITION_REGEX)?.[1]; + + return { + type: 'link', + label: capitalizeFirstLetter(name.replace('-', ' ')), + href: name, + autoAddBaseUrl: true, + position: parseInt(position ?? 0), + }; + }) + .filter(Boolean) + .sort((a, b) => { + // sort by position + if (a.position === b.position) { + return 0; + } + + return a.position > b.position ? -1 : 1; + }) + .map(({ position, ...rest }) => { + return rest; + }); +} + /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars: SidebarsConfig = { docs: [ - { type: 'autogenerated', dirName: 'ama' }, + ...autoGenerate('docs/ama'), { type: 'category', label: 'Packages', @@ -56,8 +104,8 @@ const sidebars: SidebarsConfig = { ], }, ], - guidelines: [{ type: 'autogenerated', dirName: 'guidelines' }], - checklist: [{ type: 'autogenerated', dirName: 'checklist' }], + guidelines: [autoGenerate('guidelines')], + checklist: [autoGenerate('checklist')], }; export default sidebars; diff --git a/website/versioned_docs/version-0.7.x/checklist.md b/website/versioned_docs/version-0.7.x/checklist.md deleted file mode 100644 index 15e1825d..00000000 --- a/website/versioned_docs/version-0.7.x/checklist.md +++ /dev/null @@ -1,92 +0,0 @@ -# Accessibility Checklist - -The checklist is based on the [Guidelines](./guidelines) and is focused on the testing side of accessibility. - -:::note -Addressing the issues called out in this checklist will help improve the experience for everyone who uses the app, -but it won't guarantee that the app will be 100% accessible! -::: - -## Feature - -- [ ] Are you able to use it by using Screen Curtains (iOS) or setting to 0 the screen luminosity? - -## Order - -- [ ] [Are you able to logically scroll through the entire screen/modal/drawer/bottom sheet](./guidelines/focus)? - -## Components - -**What is this thing? Does the screen reader announce:** - -- [ ] [Role](./guidelines/accessibility-role) (ex. button) -- [ ] [Name](./guidelines/accessibility-label) (ex. "Submit") -- [ ] State (ex. disabled, checked, expanded, etc...) - -**What happens when I click the thing?** - -- [ ] Is it clear what will happen if you click the thing? - -[**Hint**](./guidelines/accessibility-hint)? - -- [ ] Is the label enough? - -[**Predictable/Consistent**](guidelines/predictable-consistent) - -- [ ] Is the appearance consistent across the app? -- [ ] Is the behaviour consistent across the app? - -[**Size*](guidelines/minimum-size)* - -- [ ] Has a minimum size of 44/48px? - -**NOTE**: [hitSlop does not guarantee a minimum size](guidelines/minimum-size#hitslop-vs-min-size) - -### [Animations](./guidelines/animations) - -- [ ] Ensure animations are subtle and do not flash too much. -- [ ] Are translation animations disabled if the user has chosen reduce motion from the device settings? - -### BottomTabNavigator - -- [ ] Does the screen reader announce the element as: _selected status_ **BUTTON TITLE**, **index** of **total**, tab, _double-tap to activate_? - -Example: -- selected Home, 1 of 5 -- Account, 5 of 5 - -### Button - -- [ ] Does the screen reader announce the element as: **BUTTON TITLE**, _button_, _double-tap to activate_? - -### [Focus](./guidelines/focus) - -- [ ] Does the first element/header of the screen receive the focus automatically when navigating to a new screen/modal? -- -### [Form](./guidelines/forms) - -- [ ] Can you navigate through the various fields using the corresponding keyboard "next" key? -- [ ] Can you submit the form using the "enter" key? -- [ ] Invalid fields: Is the error read with the text once the latter gets the focus? -- [ ] Is the label announced when a [TextInput](./components/textinput) is selected? - -### [Headings](./guidelines/headers) - -- [ ] Is there at least one heading in the Screen/Modal/Drawer/Bottom sheet? -- [ ] Is the section title announced as "header"? -- [ ] Does a header get automatically focused when the screen/modal/drawer/bottom sheet appears? - -### [Lists & Grids](./guidelines/lists-grids) - -- [ ] Does TalkBack announce "in list/grid" and/or "out of list/grid"? -- [ ] If there is a filtering: Does the screen reader automatically announce how many items the list is showing? - -### [Text](./guidelines/text) - -- [ ] Is the text readable with a font size scaled up to 300%? -- [ ] If the text is uppercase, does the screen reader read it correctly or does it spell the words? -- [ ] Are you able to focus all the links within a Text? - -### [Time limits](./guidelines/timed-actions) - -- [ ] Does the user have enough time to read an auto-hiding message? diff --git a/website/versioned_docs/version-0.7.x/guidelines/_category_.json b/website/versioned_docs/version-0.7.x/guidelines/_category_.json deleted file mode 100644 index 6a01f3e9..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/_category_.json +++ /dev/null @@ -1,4 +0,0 @@ -{ - "label": "Guidelines", - "position": 4 - } diff --git a/website/versioned_docs/version-0.7.x/guidelines/accessibility-label.md b/website/versioned_docs/version-0.7.x/guidelines/accessibility-label.md deleted file mode 100644 index ce180398..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/accessibility-label.md +++ /dev/null @@ -1,132 +0,0 @@ -import { Must } from '@site/src/components'; - -# Accessibility Label - -The [accessibilityLabel](https://reactnative.dev/docs/accessibility#accessibilitylabel) is the text that assistive technology reads when the component is focused and AMA requires it by tappable elements. - -## No Accessibility Label - -### The problem - -Let's consider the following example: - -```jsx - - Contact us - -``` - -When testing the button with both VoiceOver and TalkBack, they both read: - -> button, Contact us, double-tap to activate - -Because the component has no `accessibilityLabel`, only the `accessibilityRole` is announced; they read the inner text, if any, and in this case: **Contact us**. Finally, the last part tells the user that the component can be interacted with by performing a double-tap. - -
- -**What's happen if no text is available?** - -```jsx - - - -``` - -When testing the button with both VoiceOver and TalkBack, they both read: - -> button, double-tap to activate - -Here the assistive technology only reads the role and the action that can be performed with the component. So there is a complete lack of helpful information about what we're going to trigger. - -### Let's fix it - -```jsx -// 1. - - Contact us - - -// 2. - - - -``` - -When testing with the assistive technology, this happens: - -> Contact us button, double-tap to activate -> Go back button, double-tap to activate - -The `accessibilityLabel` is announced first, then the __role__ and the action that can be performed at the end. - -For this reason, AMA requires that tappable elements have the `accessibilityLabel` defined. - -## All CAPS Accessibility Label - -All CAPS accessibility labels affect how and what a screen reader reads, so a non-CAPS one should always be provided. - -### No inflection - -Both Talkback and VoiceOver reads the words with the same flat tone, which becomes more noticeable with long sentences. - -### Wrong spelling - -Some words could be misinterpreted, causing the screen readers to read a word as separate characters. - -#### Example: `ADD TO THE CART` - -```jsx -... -``` - -This is how the different screen readers handle the uppercase label: - -| Voice Over | Talkback | -|--------------------|-----------------| -| A-D-D to the cart | Add to the cart | - -In this case, VoiceOver does the spelling of the word `ADD` while talkback reads it correctly. -The remaining words are read correctly by both screen readers. - -#### Example: `CONTACT US` - -| Voice Over | Talkback | -|--------------|--------------| -| Contact U.S. | Contact U.S. | - -The word `CONTACT` is read correctly, but both screen readers spell the word `US` as it is interpreted as `U.S.` for `United States. - -A similar issue happens if a sentence contains the word **IT**, for example. - -## AMA dev runtime errors - -### NO_ACCESSIBILITY_LABEL - -This error is used when a pressable element has no [accessibilityLabel](https://reactnative.dev/docs/accessibility#accessibilitylabel) defined. - -:::note - -This rule is mandatory and cannot be turned off! -::: - -### NO_UPPERCASE_TEXT - -This is used when a component has the `accessibilityLabel` prop in all caps. - -:::tip - -Is it possible to specify a list of allowed all caps accessibility labels, [more info here](../guidelines/guidelines.md) -::: - -## Related AMA components - -- [ExpandablePressable](../components/expandablepressable) -- [Pressable](../components/pressable) -- [TouchableOpacity](../components/touchableopacity) -- [TouchableWithoutFeedback](../components/TouchableWithoutFeedback) - -## External resources - -Some helpful resources about accessibility and all caps. - -- http://ux.stackexchange.com/questions/67454/how-does-capitalization-affect-readability diff --git a/website/versioned_docs/version-0.7.x/guidelines/accessibility-role.md b/website/versioned_docs/version-0.7.x/guidelines/accessibility-role.md deleted file mode 100644 index f9dacdce..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/accessibility-role.md +++ /dev/null @@ -1,49 +0,0 @@ -import { Must } from '@site/src/components'; - -# Accessibility Role - -The [accessibilityRole](https://reactnative.dev/docs/accessibility#accessibilityrole) communicates the purpose of a component to the assistive technology user and so AMA requires it by tappable elements. - -The lack of a value causes affects the Screen Reader behaviour: - -- VoiceOver only reads the component `accessibilityLabel` and `accessibilityHint`, if specified, or any text inside the component -- TalkBack, besides reading the component `accessibilityLabel` and `accessibilityHint`, if specified, or any text inside the component, also adds "double-tap" to activate. - -## Example - -Let's consider the following example: - -```jsx -Contact us -``` - -| VoiceOver | TalkBack | -|------------|------------------------------------| -| Contact us | Contact us, double-tap to activate | - -In both cases, the user has no clue about the nature of the component the screen reader landed and/or if any action could be triggered and what could be the outcome of interacting with it. - -## The roles - -React Native provides an extensive list of [accessibility roles](https://reactnative.dev/docs/accessibility#accessibilityrole), but not all of them are native to both iOS and Android platform. -For example `checkbox` is a native component on Android but not on iOS. - -For those cases AMA automatically uses the correct role for the running platform. - -## AMA dev runtime errors - -### NO_ACCESSIBILITY_ROLE - -This error is used when a pressable element has no [accessibilityRole](https://reactnative.dev/docs/accessibility#accessibilityrole) defined. - -:::note - -This rule is mandatory and cannot be turned off! -::: - -## Related AMA components - -- [ExpandablePressable](../components/expandablepressable) -- [Pressable](../components/pressable) -- [TouchableOpacity](../components/touchableopacity) -- [TouchableWithoutFeedback](../components/TouchableWithoutFeedback) diff --git a/website/versioned_docs/version-0.7.x/guidelines/animations.md b/website/versioned_docs/version-0.7.x/guidelines/animations.md deleted file mode 100644 index 68cd3229..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/animations.md +++ /dev/null @@ -1,27 +0,0 @@ -# Animations - -> Success Criterion 2.3.3 Animation from Interactions (Level AAA): Motion animation triggered by interaction can be disabled, unless the animation is essential[^1] to the functionality or the information being conveyed. -> -> https://www.w3.org/WAI/WCAG21/Understanding/animation-from-interactions.html - -Some people might turn off animation on the device because moving content can distract them, or they might be adversely affected by animations or other reasons. - -Our app animations, unless essential[^1], should respect the [Reduce Motion] (https://reactnative.dev/docs/accessibilityinfo) preference and therefore disable any [motion animation](https://www.w3.org/TR/WCAG21/#dfn-motion-animation) -when the option is turned on. -So, - -- gifs and videos should not autoplay -- navigation motion should be disabled -- any motion triggered by an interaction with the app - -## Related AMA components & hooks - -- [AnimatedContainer](../components/animatedcontainer) -- [BottomSheet](../components/bottomsheet) -- [useAMAContext](../hooks/useAMAContext) -- [useAnimation](../hooks/useAnimation) -- [useAnimationDuration](../hooks/useanimationduration) -- [useReanimatedTiming](../hooks/useReanimatedTiming) - - -[^1]: Basic content scrolling is considered an essential function and is excluded from this requirement. diff --git a/website/versioned_docs/version-0.7.x/guidelines/bottomsheet.md b/website/versioned_docs/version-0.7.x/guidelines/bottomsheet.md deleted file mode 100644 index 5da482b4..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/bottomsheet.md +++ /dev/null @@ -1,23 +0,0 @@ -# BottomSheet & Drawer - -When dealing with Drawers/BottomSheets, we need to take care of: - -1. Handling the focus -1. Can be dismissed -1. Focus stays inside it - -### 1. Handling the focus - -When opening a modal window or drawer, the focus must be placed on or inside it; otherwise, the user remains in the active control and might not be aware or be able to reach the new content. - -### 2. Can be dismissed - -The drawer/bottom sheet should either have a close button or be dismissable by tapping on its overlay layer. - -### 3. The focus stays inside it - -Make sure that the user cannot focus on any element underneath the drawer/bottom sheet; the user should only be able to cycle between the drawer/bottom sheet content. - -## Related AMA components - -- [BottomSheet](../components/bottomsheet) diff --git a/website/versioned_docs/version-0.7.x/guidelines/carousel.md b/website/versioned_docs/version-0.7.x/guidelines/carousel.md deleted file mode 100644 index 6fd6f7c8..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/carousel.md +++ /dev/null @@ -1,45 +0,0 @@ -# Carousel - -When dealing with Carousel, we need to make sure that the user is able to navigate through its items. -The navigation is generally done by swiping one finger up or done: - -- 1 finger swipe up: go to the next item -- 1 finger swipe down: go to the previous item - -To do this in React Native we need to: - -- use the [accessibility role](./accessibility-role) **adjustable** -- set `accessibilityActions={[{ name: 'increment' }, { name: 'decrement' }]}` -- handle **onAccessibilityAction** to change the index - -## Example - -```jsx - - { - const value = event.nativeEvent.actionName === 'increment' ? 1 : -1; - const newIndex = carouselIndexForScreenReader.current + value; - - carouselIndexForScreenReader.current = clamp( - newIndex, - 0, - data.length - 1, - ); - flatList.current?.scrollToIndex({ - index: carouselIndexForScreenReader.current, - }); - }} -/> - -``` diff --git a/website/versioned_docs/version-0.7.x/guidelines/contrast.md b/website/versioned_docs/version-0.7.x/guidelines/contrast.md deleted file mode 100644 index 44619783..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/contrast.md +++ /dev/null @@ -1,30 +0,0 @@ -import { Must, ShouldNot } from '@site/src/components'; - -# Contrast - -AMA performs a contrast check between the component background and its children for tappable elements like Pressable, Button, etc. -The check is performed on the component children and sub children up to a depth level of [5](../introduction/config-file.md#constants). - -The [minimum contrast](#contrast_failed) ratio expected is at least `4.5:1`, and by default, this is a mandatory requirement. While the [enhanced contrast](#contrast_failed_aaa) of at least `7:1` is a suggestion and therefore prints only a warning if it fails. - -:::tip - -Both Log level type and max depth level can be customised, [here for more info](../introduction/config-file.md) -::: - -## AMA dev runtime errors - -### CONTRAST_FAILED - -This error is used when the contrast check between a component background and its children foreground one fails to reach the [AA accessibility level](https://www.w3.org/TR/WCAG21/#contrast-minimum). - -### CONTRAST_FAILED_AAA - -This code is used when the contrast check does not pass the [AAA level](https://www.w3.org/TR/WCAG21/#contrast-enhanced). - -## Related AMA components - -- [ExpandablePressable](../components/expandablepressable) -- [Pressable](../components/pressable) -- [TouchableOpacity](../components/touchableopacity) -- [TouchableWithoutFeedback](../components/TouchableWithoutFeedback) diff --git a/website/versioned_docs/version-0.7.x/guidelines/focus.md b/website/versioned_docs/version-0.7.x/guidelines/focus.md deleted file mode 100644 index 2eb2eef5..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/focus.md +++ /dev/null @@ -1,43 +0,0 @@ -# Focus - -## Order Matters - -It's crucial to ensure screen readers and other assistive technologies can navigate your app in a logical order, making sure that content is separate with meaningful titles. - -## Screen navigation - -When navigating to a new screen, make sure that the focus always starts from the "same" position; it could be the first element of the screen or the first header[^1]; whatever you choose, make sure that it is consistent across all the screens/modals of your app. - -:::tip - -The built-in [``](../components/Text) has the `autofocus` property that automatically sets the focus when it gets rendered for the first time. - -::: - -## Drawer / BottomSheet navigation - -When dealing with Drawers/BottomSheets, we need to take care of: - -1. Handling the focus -1. Can be dismissed -1. Focus stays inside it - -### 1. Handling the focus - -When opening a modal window or drawer, the focus must be placed on or inside it; otherwise, the user remains in the active control and might not be aware or be able to reach the new content. - -### 2. Can be dismissed - -The drawer/bottom sheet should either have a close button or be dismissable by tapping on its overlay layer. - -### 3. The focus stays inside it - -Make sure that the user cannot focus on any element underneath the drawer/bottom sheet; the user should only be able to cycle between the drawer/bottom sheet content. - -## Related AMA components - -- [AutofocusContainer](../components/autofocuscontainer) -- [BottomSheet](../components/bottomsheet) -- [Text](../components/text) - -[^1]: According to this study: [https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/](https://www.gatsbyjs.com/blog/2019-07-11-user-testing-accessible-client-routing/) the solution that worked better for the mast majority was: _Shift focus to a heading_ diff --git a/website/versioned_docs/version-0.7.x/guidelines/forms.md b/website/versioned_docs/version-0.7.x/guidelines/forms.md deleted file mode 100644 index 67a546e2..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/forms.md +++ /dev/null @@ -1,105 +0,0 @@ -import { MustNot } from '@site/src/components'; - -# Forms - -## Labels - -:::danger MUST - -All form controls must be labelled. - -::: - -Labels describe the purpose and function of form elements; and are critical for users who cannot determine this by looking at the form. - -- All form controls, such as text fields, checkboxes, radio buttons, etc., must each have a unique label -- Placeholders must not be used as a substitute for a label; as they are only visible if the field is empty - -### Hide it - -For some form controls, such as text fields, the label should not be focusable individually, as it would provide redundant information, but the Text field must provide an `accessibilityLabel` instead. - -```jsx -Enter your email address - -``` - -:::tip - -The built-in [TextInput](../components/TextInput) automatically hides the label from the screen readers. - -::: - -:::danger - -If the field is required the accessibility label should not end with an asterisk, but a required message should be provided instead. - -::: - -```jsx -Enter your email address* - -``` -::: - -## Errors - -If the field has an error, then this should be read as part of the field label/hint itself and should not be focused as an isolated component: - -This is because if we keep the information in a separate component, the user won't be aware of the error unless it does swipe to select the next element. -Also, some users might forget the error, forcing them to swipe left and right to figure out that. - -## Focus on the next field - -When on TextInput, the user should be able to access the next field or submit the form using the specific keyboard button; please don't force them to swipe to do that. - - -:::tip - -The built-in [TextInput](../components/TextInput) automatically handles the `returnKeyLabel` property and its action. - -::: - -## Keyboard trap - -The user **must** be able to navigate to all the interactive elements on the screen and navigate away from them at any moment without becoming trapped. - -For example, if the user decides to navigate away from an input field, it must be allowed to do so; even if the field contains invalid data, it doesn't matter in no way the focus should be programmatically forced back to that field! - -## Form submission - -The user should be able to submit a form using the **done** button on the keyboard if a text input has it. - -Also, an error message should be displayed and autofocused when it fails to let the screen reader know about the issue. -Alternatively, the first failed field should be autofocused if no message is available. - -## AMA dev runtime errors - -### NO_FORM_LABEL - -This error is used when no label has been provided for the [TextInput](../components/TextInput) component. - -### NO_FORM_ERROR - -This error is used when no error has been provided for the [TextInput](../components/TextInput) component. - -### NO_KEYBOARD_TRAP - -This error is triggered by the [TextInput](../components/TextInput) component if the next input field does not have the focus as expected. - -:::note - -This rule cannot be turned off! -::: - -## Related AMA components - -- [Form](../components/form) -- [FormField](../components/formfield) -- [SwitchListItem](../components/switchlistitem) -- [SwitchWrapper](../components/switchwrapper) -- [TextInput](../components/textinput) diff --git a/website/versioned_docs/version-0.7.x/guidelines/guidelines.md b/website/versioned_docs/version-0.7.x/guidelines/guidelines.md deleted file mode 100644 index 7635bd17..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/guidelines.md +++ /dev/null @@ -1,19 +0,0 @@ -import { Must, MustNot, Should, ShouldNot } from '@site/src/components'; - -# Mobile Accessibility Guidelines - -This section contains accessibility best practices for native mobile apps. - -The guidelines are based on the w3c recommendations [Accessibility Guideline](https://www.w3.org/TR/WCAG21/) and are intended for use -by anyone building an accessible app with React Native and are not limited to being used with AMA. - -:::info - -The guidelines are still work in progress and are not yet complete. The more feedback we get, the better the guidelines will be. - -::: - -## External references - -- https://www.w3.org/TR/WCAG21 -- https://www.bbc.co.uk/accessibility/forproducts/guides/mobile/ diff --git a/website/versioned_docs/version-0.7.x/guidelines/headers.md b/website/versioned_docs/version-0.7.x/guidelines/headers.md deleted file mode 100644 index 5affb9a7..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/headers.md +++ /dev/null @@ -1,29 +0,0 @@ -# Headers - -Headers are defined by setting the property: `accessibilityRole = "header"` and are equivalent to the HTML _H\*_ tags. - -:::note - -Each page/screen should contain at least one header. - -::: - -## Why do we need headers? - -Because people who depend on assistive technology often navigate by heading first to quickly get a sense of the content offered in the page. - -On iOS, the user will use the [VoiceOver rotor](https://support.apple.com/en-gb/HT204783) to move through the different elements on the screen, i.e. headers. On Android is possible but varies by device. - -:::tip - -You can have "invisible" header on your screen, for example: - -```jsx - -``` - -::: - -## Related AMA components - -- [Text](../components/text) diff --git a/website/versioned_docs/version-0.7.x/guidelines/lists-grids.md b/website/versioned_docs/version-0.7.x/guidelines/lists-grids.md deleted file mode 100644 index 718e3b45..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/lists-grids.md +++ /dev/null @@ -1,22 +0,0 @@ -# Lists & Grids - -## Number of results - -If a list is filtered due to any UI interaction, the screen reader **must** announce the number of elements the list is showing. - -For example, if a search box updates the list a list while the user is typing, the screen reader **must** read how many items we are displaying after applying the filter if the number is different from the total. Same if a list is filtered because we used a filter via a button. - -Failing to do so means forcing the user to scroll all the time to the list and back to know what's happening. - -## Android - -With a native app, TalkBack, to announce when the user focuses or leaves a list for the first time. This info is additionally provided as in list (or in grid), and out of list (or out of the grid), according to the fact that the list has one or more columns. - -A React Native app must provide the same experience to the screen reader users. The FlatList provided by AMA already provides this out of the box. -Suppose the list you're using does not provide this kind of experience. In that case, you can wrap your list inside the [ListWrapper](../components/ListWrapper.mdx) component and specify the number of rows and columns to fix this issue. - -## Related AMA components - -- [DynamicFlatList](../components/DynamicFlatList) -- [StaticFlatList](../components/StaticFlatList) -- [ListWrapper](../components/ListWrapper) diff --git a/website/versioned_docs/version-0.7.x/guidelines/minimum-size.md b/website/versioned_docs/version-0.7.x/guidelines/minimum-size.md deleted file mode 100644 index 8b3e184c..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/minimum-size.md +++ /dev/null @@ -1,30 +0,0 @@ -import { Must } from '@site/src/components'; - -# Minimum Size - -AMA performs a minimum size check for tappable elements like Pressable, Button, etc. The expected minimum size is: - -- [44x44px on iOS](https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/adaptivity-and-layout/) -- [48x48dp on Android](https://support.google.com/accessibility/android/answer/7101858?hl=en-GB) - - -:::tip - -The Log level type can be customised, [here for more info](../introduction/config-file#customising-the-log-levels) -::: - -## hitSlop vs min size - -AMA prefers forcing a minimum size check instead of using [hitSlop](https://reactnative.dev/docs/pressable#hitslop); as with the latter, the hit area is **never** extended beyond the parent boundaries: - -> The touch area never extends past the parent view bounds, and the Z-index of sibling views always takes precedence if a touch hits two overlapping views. -> -> [https://reactnative.dev/docs/touchablewithoutfeedback#hitslop](https://reactnative.dev/docs/touchablewithoutfeedback#hitslop) - -So, if the parent width or height is less than 44 or 48px, the touch area will not meet the minimum requirement. In contrast, `min-width` and `min-height` forces the component to have the minimum size preferred. - -## AMA dev runtime errors - -### MINIMUM_SIZE - -This error is used when a touchable area is less than [44x44px on iOS](https://developer.apple.com/design/human-interface-guidelines/ios/visual-design/adaptivity-and-layout/) or [48x48dp on Android](https://support.google.com/accessibility/android/answer/7101858?hl=en-GB) diff --git a/website/versioned_docs/version-0.7.x/guidelines/predictable-consistent.md b/website/versioned_docs/version-0.7.x/guidelines/predictable-consistent.md deleted file mode 100644 index 5f82307f..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/predictable-consistent.md +++ /dev/null @@ -1,6 +0,0 @@ -# Predictable/Consistent - -To make an app understandable, it should be predictable and consistent. - -- Use consistent patterns, which help users predict what will happen when they perform an action. -- No two identical-looking controls should function differently. The inverse is also true; two controls with the same function should have the same appearance. diff --git a/website/versioned_docs/version-0.7.x/guidelines/text.md b/website/versioned_docs/version-0.7.x/guidelines/text.md deleted file mode 100644 index 29ad4d83..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/text.md +++ /dev/null @@ -1,92 +0,0 @@ -import { MustNot } from '@site/src/components'; - -# Text - - -## No uppercase - -For [<Text />](../components/Text.md) elements AMA checks if the style has the `textTransform` property set to `uppercase`, and if so throws an error if the `accessibilityLabel` one is not set. -It also checks that the accessibilityLabel provided for the various component is not all caps. - -### Why `textTransform:uppercase` is bad for accessibility? - -Besides [all CAPS](https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read) being bad for readability, it can also change the inflexion of the screen reader voice or in some cases can cause some words to be read as separate characters. - -Let's consider the following example: - -```jsx - - - Add to the cart - - - - - - Contact us - - -``` - -If we inspect the layout view on Android using: `adb shell uiautomator dump`, we get something similar to this: - -```xml - -... - -``` - -So, React Native converts the text to `UPPERCASE` and this version of the text is used by the Screen Reader. - -#### No inflection - -Both Talkback and VoiceOver reads the words with the same flat tone, which becomes more noticeable with long sentences. - -#### Wrong spelling - -Some words could be misinterpreted, causing the screen readers to read a word as separate characters. - -##### Example: `ADD TO THE CART` - -```jsx -... -``` - -This is how the different screen readers handle the uppercase label: - -| Voice Over | Talkback | -|--------------------|-----------------| -| A-D-D to the cart | Add to the cart | - -In this case, VoiceOver does the spelling of the word `ADD` while talkback reads it correctly. -The remaining words are read correctly by both screen readers. - -##### Example: `CONTACT US` - -| Voice Over | Talkback | -|--------------|--------------| -| Contact U.S. | Contact U.S. | - -The word `CONTACT` is read correctly, but both screen readers spell the word `US` as it is interpreted as `U.S.` for `United States. - -A similar issue happens if a sentence contains the word **IT**, for example. - -## AMA Errors - -### UPPERCASE_TEXT_NO_ACCESSIBILITY_LABEL - -This is used when a component uses the `textTransform: uppercase` style without providing an accessible label. - -## Known issues - -- Nested Text components with onPress property are not accessible [https://github.com/facebook/react-native/issues/24515](https://github.com/facebook/react-native/issues/24515) - -## Resources - -Some helpful resources about accessibility and all caps. - -- https://www.mity.com.au/blog/writing-readable-content-and-why-all-caps-is-so-hard-to-read -- http://uxmovement.com/content/how-letterspacing-can-make-all-caps-easier-to-read/ -- http://ux.stackexchange.com/questions/67454/how-does-capitalization-affect-readability -- http://www.sciencedirect.com/science/article/pii/S0042698907002830 -- http://www.dyslexia.ie/information/computers-and-technology/making-information-accessible-dyslexia-friendly-style-guide/ diff --git a/website/versioned_docs/version-0.7.x/guidelines/timed-actions.md b/website/versioned_docs/version-0.7.x/guidelines/timed-actions.md deleted file mode 100644 index d1b7b0fc..00000000 --- a/website/versioned_docs/version-0.7.x/guidelines/timed-actions.md +++ /dev/null @@ -1,28 +0,0 @@ -# Timed actions - -> Success Criterion 2.2.1 Timing Adjustable (Level A): For each time limit that is set by the content, at least one of the following is true: -> -> - **Turn off**: The user is allowed to turn off the time limit before encountering it; or -> -> - **Adjust**: The user is allowed to adjust the time limit before encountering it over a wide range that is at least ten times the length of the default setting; or -> -> - **Extend**: The user is warned before time expires and given at least 20 seconds to extend the time limit with a simple action (for example, "press the space bar"), and the user is allowed to extend the time limit at least ten times; or -> -> - **Real-time Exception**: The time limit is a required part of a real-time event (for example, an auction), and no alternative to the time limit is possible; or -> -> - **Essential Exception**: The time limit is essential and extending it would invalidate the activity; or -> -> - **20 Hour Exception**: The time limit is longer than 20 hours. -> -> This success criterion helps ensure that users can complete tasks without unexpected changes in content or context that are a result of a time limit. This success criterion should be considered in conjunction with [Success Criterion 3.2.1](https://www.w3.org/TR/UNDERSTANDING-WCAG20/consistent-behavior-receive-focus.html), which puts limits on changes of content or context as a result of user action. -> -> [https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html](https://www.w3.org/WAI/WCAG21/Understanding/timing-adjustable.html) - -Some users might need more time to complete an activity with a time limit. - -On Android is possible to know the time, in milliseconds, needed by the user using the utility: [getRecommendedTimeoutMillis](https://reactnative.dev/docs/accessibilityinfo#getrecommendedtimeoutmillis-android). - -On iOS, there is no equivalent option, so if the app does not provide any mechanism to adjust the timing, at least for screen reader users, we should then disable any timeout whenever they're not essential[^1] - - -[^1]: In a quiz app, the timer is considered an essential