From 3a2fd2e82bf86d3192a8978b31be5d4a69e1c7c9 Mon Sep 17 00:00:00 2001 From: Eli Zibin Date: Mon, 2 Dec 2024 11:40:09 -0800 Subject: [PATCH 1/3] massage docs a bit --- website/docs/ama/config-file.md | 53 ++++++++++++++++------------- website/docs/ama/getting-started.md | 18 +++++++--- website/docs/ama/index.md | 37 +++++++++++++------- website/docs/ama/usage.md | 13 +++---- website/sidebars.ts | 20 ++++++++++- 5 files changed, 94 insertions(+), 47 deletions(-) diff --git a/website/docs/ama/config-file.md b/website/docs/ama/config-file.md index ff87ade2..8df690b2 100644 --- a/website/docs/ama/config-file.md +++ b/website/docs/ama/config-file.md @@ -1,10 +1,12 @@ --- displayed_sidebar: docs +pagination_next: 'usage' +pagination_prev: 'getting-started' --- -# Config file +# Config File -AMA comes with predefined rules and severity for the built-in components and hooks. Those rules have been created to improve the accessibility of those elements and should always be respected. +**AMA** comes with predefined rules and severity levels for the built-in components and hooks. These rules have been created to improve the accessibility of each element and should always be respected. Customizing log levels can be done via the `ama.config.json` file to handle edge cases that are out of our control, and require breaking a rule or two. @@ -14,16 +16,34 @@ The library does not perform any accessibility checks on the production build! ::: -## The log levels +## Customising the Log Levels -AMA guidelines are categorised as: +Create a JSON file called `ama.config.json` in the project's root folder to customise the log rules, then specify the custom log level for the wanted key. + +### Example + +The JSON file does not need to contain all log keys. **AMA** uses the default rule if a key is not present: + +```json +{ + rules: { + "CONTRAST_FAILED": "warn", + "CONTRAST_CHECKER_MAX_DEPTH": 0, + } + "accessibilityLabelExceptions": ["FAQ"] +} +``` + +## Log Levels + +**AMA** guidelines are categorised as: - and : Those best practices are enforced and AMA overlays an error when fail - and : Those best practices are preferred and AMA prints only prints a warning message when fail The possible log levels are: -- **error**: The AMA error overlay when a check fails +- **error**: The **AMA** error overlay when a check fails - **warn**: A `console.warn` is performed when a check fails ### AMA Rules @@ -59,7 +79,7 @@ Elements that perform a contrast check do it on all the children up to the level ```json { - rules: { + "rules": { "CONTRAST_CHECKER_MAX_DEPTH": 0 } } @@ -71,7 +91,7 @@ This can be turned off by specifying a level of **0** ### accessibilityLabelExceptions -AMA performs various checks, including one for [uppercase](/guideliens/uppercase). This rule allows specifying a list of approved all-caps accessibility labels. +**AMA** performs various checks, including one for [uppercase](/guidelines/uppercase). This rule allows specifying a list of approved all-caps accessibility labels. ```json { @@ -79,22 +99,9 @@ AMA performs various checks, including one for [uppercase](/guideliens/uppercase } ``` -## Customising the log levels - -Create a JSON file called `ama.config.json` in the project's root folder to customise the log rules, then specify the custom log level for the wanted key. - -### Example - -The JSON file does not need to contain all log keys. AMA uses the default rule if a key is not present: +:::note -```json -{ - rules: { - "CONTRAST_FAILED": "warn", - "CONTRAST_CHECKER_MAX_DEPTH": 0, - } - "accessibilityLabelExceptions": ["FAQ"] -} -``` +The key `accessibilityLabelExceptions` is not nested under the `rules` key as the above values must be. +::: [^1]: The rule cannot be overridden diff --git a/website/docs/ama/getting-started.md b/website/docs/ama/getting-started.md index 84264219..e185cce0 100644 --- a/website/docs/ama/getting-started.md +++ b/website/docs/ama/getting-started.md @@ -1,11 +1,13 @@ --- sidebar_position: 1 displayed_sidebar: docs +pagination_next: 'config-file' +pagination_prev: 'index' --- -# Getting started +# Getting Started -AMA is made of the following packages: +**AMA** is made of the following packages: - `@react-native-ama/core`: the core components and hooks, providers and consumers used by AMA packages - `@react-native-ama/animations`: to create accessible animations @@ -16,7 +18,7 @@ AMA is made of the following packages: ## Setup -The `core` package, is the minimum installable setup for AMA to function. This package contains the AMA context provider and consumer as well various other hooks and utilities for focusing, WCAG checks, accessibility tree management, etc. +The `core` package, is the minimum installable setup for **AMA** to function. This package contains the **AMA** context provider and consumer as well various other hooks and utilities for focusing, WCAG checks, accessibility tree management, etc. Start off by installing `core` and then any other packages you wish to make use of for building an accessible mobile app. @@ -29,13 +31,21 @@ npm install @react-native-ama/core When you install the `@react-native-ama/core` package, `the ama.rules.json` file should be generated automatically. If this didn't happen you can run the following from the root of your project: ```bash +# Create ama.rules.json with an empty JSON object if it doesn't exist +echo "{}" >> ama.rules.json + +# Navigate to the internal directory cd node_modules/@react-native-ama/internal + +# Create symlinks in src and dist directories ln -s ../../../ama.rules.json src/ama.rules.json ln -s ../../../ama.rules.json dist/ama.rules.json + +# Go back to the root directory cd - ``` -See more on configuring AMA rules and severity [here](./config-file.md). +See more on configuring **AMA** rules and severity [here](./config-file.md). ### Jest diff --git a/website/docs/ama/index.md b/website/docs/ama/index.md index 6b8e4333..c5b80ce0 100644 --- a/website/docs/ama/index.md +++ b/website/docs/ama/index.md @@ -1,24 +1,35 @@ --- slug: / -title: AMA Introduction +id: index +title: Overview sidebar_position: 0 displayed_sidebar: docs +pagination_next: 'getting-started' --- # Accessibility as a First-Class Citizen With React Native AMA -A.M.A. stands for **A**ccessible **M**obile **A**pp and is a React Native library that offers the best accessibility tooling experience and guides to guide you through accessibility best practices while you code your app. +## Overview -That's why we created AMA, a set of components and hooks designed to enforce minimum accessibility requirements. -This is combined with extensive [guidelines](https://commerce.nearform.com/open-source/react-native-ama/guidelines/) to help you understand how accessibility should work when manually testing your app. Finally we have provided a [checklist](https://commerce.nearform.com/open-source/react-native-ama/checklist/) which condenses these guidelines, explaining their intended functionality against specific features or components. +**A.M.A.** stands for **A**ccessible **M**obile **A**pp and is a React Native library that offers the best accessibility tooling experience as well as expert guides to support you with accessibility best practices while developing your app. -AMA consists of a family of packages under the npm `@react-native-ama` namespace. These packages are designed to work together to build up an accessible mobile app, allowing developers to subscribe to the bits they need without installing the full set of packages from the start. All packages leverage the `@react-native-ama/core` package to provide accessible mobile app functionality. This package must be installed first before any others can work. +The library consists of -## Run time dev tooling (Accessibility Checks) +1. A set of components and hooks designed to enforce minimum accessibility requirements. +2. Extensive [guidelines](https://commerce.nearform.com/open-source/react-native-ama/guidelines/) to help you understand how accessibility should work when manually testing your app. +3. A [checklist](https://commerce.nearform.com/open-source/react-native-ama/checklist/) which condenses these guidelines, explaining their intended functionality against specific features or components. -Adopting an "accessibility-first" approach is the best way to ensure that digital experiences are inclusive for everyone. By prioritizing accessibility in the early stages of code development, you avoid needing time-consuming and expensive retroactive fixes. +**AMA** consists of a family of packages under the npm `@react-native-ama` namespace. These packages are designed to work together to build up an accessible mobile app, allowing developers to subscribe to the bits they need without installing the full set of packages from the start. -React Native provides the necessary tools to create accessible apps [^1]. However, it leaves the developer on their own to determine what and when to use them. AMA solves this issue [^1] by conducting accessibility checks during your app's runtime [^1]. +:::tip +All packages leverage the `@react-native-ama/core` package to provide accessible mobile app functionality. This package must be installed first before any others can work. +::: + +## Runtime Dev Tooling (Accessibility Checks) + +Adopting an "accessibility-first" approach is the best way to ensure that digital experiences are inclusive for everyone. By prioritizing accessibility in the early stages of code development, you avoid having to later apply retroactive fixes which can be very time-consuming, expensive and difficult. + +React Native provides the necessary tools to create accessible apps [^1]. However, it leaves the developer on their own to determine what and when to use them. **AMA** solves this issue [^1] by conducting accessibility checks during your app's runtime [^1]. :::info @@ -26,13 +37,13 @@ The library does not perform any accessibility checks on the production build! ::: -### Example of a failed accessibility check +### Example of a Failed Accessibility Check -If AMA detects an accessibility issue: +If **AMA** detects an accessibility issue it: -- Highlight the offending component -- Show a banner to inform that something went wrong -- Provide a guideline link to the issue +- Highlights the offending component +- Shows a banner to inform that something went wrong +- Provides a guideline link to the issue An example of a form field that displays several form fields, and a Last Name field emphasized in red. There is an error at the bottom that reads: 'AMA: One or more component didn't pass the accessibility check. Please check the console for more info...' diff --git a/website/docs/ama/usage.md b/website/docs/ama/usage.md index 7de7e23b..714ff3c9 100644 --- a/website/docs/ama/usage.md +++ b/website/docs/ama/usage.md @@ -7,15 +7,15 @@ displayed_sidebar: docs ## Installation ```bash npm2yarn -npm install -D react-native-ama +npm install @react-native-ama/core ``` -## The provider +## Wrap App with Provider -You need to add the [AMAProvider](../components/AMAProvider) to your app as is needed by some components/hooks. +You need to add the [AMAProvider](../components/AMAProvider) to your app as it is needed by the components, hooks, and to provide information about accessbility violations. ```jsx {1-4,8-9} -import { AMAProvider } from 'react-native-ama'; +import { AMAProvider } from '@react-native-ama/core'; const App = () => { return ( @@ -28,14 +28,15 @@ const App = () => { ## Example -In the following Example the navigation animation are disabled when the user enables the [Reduce Motion](/guidelines/animations) setting. +In the following example, the navigation animation is disabled when the user enables the [Reduce Motion](/guidelines/animations) setting. It also shows how to build a more accessible [form](/guidelines/forms) using the built-in components. ```jsx import * as React from 'react'; import { ScrollView, StyleSheet } from 'react-native'; -import { AMAProvider, useAMAContext, Form, SwitchListItem, Text, TextInput } from 'react-native-ama' +import { AMAProvider, useAMAContext } from '@react-native-ama/core' +import { Form, SwitchListItem, Text, TextInput } from '@react-native-ama/forms' import { NavigationContainer } from '@react-navigation/native'; import { createNativeStackNavigator, NativeStackNavigationOptions } from '@react-navigation/native-stack'; diff --git a/website/sidebars.ts b/website/sidebars.ts index e2012501..4aa963ed 100644 --- a/website/sidebars.ts +++ b/website/sidebars.ts @@ -54,7 +54,25 @@ function autoGenerate(path: string) { /** @type {import('@docusaurus/plugin-content-docs').SidebarsConfig} */ const sidebars: SidebarsConfig = { docs: [ - ...autoGenerate('docs/ama'), + { + type: 'link', + label: 'Overview', + href: '/docs/', + autoAddBaseUrl: true, + }, + { + type: 'link', + label: 'Getting Started', + href: 'getting-started', + autoAddBaseUrl: true, + }, + { + type: 'link', + label: 'Config File', + href: 'config-file', + autoAddBaseUrl: true, + }, + { type: 'link', label: 'Usage', href: 'usage', autoAddBaseUrl: true }, { type: 'category', label: 'Packages', From 78a7f85220a5908e9d879ac4e788156e23ed4253 Mon Sep 17 00:00:00 2001 From: Eli Zibin Date: Wed, 4 Dec 2024 12:31:23 -0800 Subject: [PATCH 2/3] capitalize Update sidebarsPackages.ts --- packages/animations/docs/animations.md | 2 +- packages/core/docs/core.md | 2 +- packages/extras/docs/extras.md | 2 +- packages/forms/docs/forms.md | 2 +- packages/lists/docs/lists.md | 2 +- packages/react-native/docs/react-native.md | 2 +- website/sidebarsPackages.ts | 5 +++-- 7 files changed, 9 insertions(+), 8 deletions(-) diff --git a/packages/animations/docs/animations.md b/packages/animations/docs/animations.md index 884d207c..6648f9c5 100644 --- a/packages/animations/docs/animations.md +++ b/packages/animations/docs/animations.md @@ -1,6 +1,6 @@ --- slug: / -title: The animations package +title: The Animations Package sidebar_position: 1 --- diff --git a/packages/core/docs/core.md b/packages/core/docs/core.md index dccc1848..348e9542 100644 --- a/packages/core/docs/core.md +++ b/packages/core/docs/core.md @@ -1,6 +1,6 @@ --- slug: / -title: The core package +title: The Core Package sidebar_position: 1 --- diff --git a/packages/extras/docs/extras.md b/packages/extras/docs/extras.md index ffe60468..27d2d305 100644 --- a/packages/extras/docs/extras.md +++ b/packages/extras/docs/extras.md @@ -1,6 +1,6 @@ --- slug: / -title: The extras package +title: The Extras Package sidebar_position: 1 --- diff --git a/packages/forms/docs/forms.md b/packages/forms/docs/forms.md index 927322b7..e57c6a4e 100644 --- a/packages/forms/docs/forms.md +++ b/packages/forms/docs/forms.md @@ -1,6 +1,6 @@ --- slug: / -title: The forms package +title: The Forms Package sidebar_position: 1 --- diff --git a/packages/lists/docs/lists.md b/packages/lists/docs/lists.md index 27a037eb..c00e0c08 100644 --- a/packages/lists/docs/lists.md +++ b/packages/lists/docs/lists.md @@ -1,6 +1,6 @@ --- slug: / -title: The lists package +title: The Lists Package sidebar_position: 1 --- diff --git a/packages/react-native/docs/react-native.md b/packages/react-native/docs/react-native.md index c9b6f2d6..0c09f918 100644 --- a/packages/react-native/docs/react-native.md +++ b/packages/react-native/docs/react-native.md @@ -1,6 +1,6 @@ --- slug: / -title: The react-native package +title: The React Native Package sidebar_position: 1 --- diff --git a/website/sidebarsPackages.ts b/website/sidebarsPackages.ts index aea7e6a8..6d0ec99a 100644 --- a/website/sidebarsPackages.ts +++ b/website/sidebarsPackages.ts @@ -21,7 +21,8 @@ const sidebars: SidebarsConfig = { type: 'link', label: 'Core', href: '/core/', - description: 'Needed to create an app with accessibility in mind', + description: + 'The core functionality needed to create an app with accessibility in mind', autoAddBaseUrl: true, }, { @@ -43,7 +44,7 @@ const sidebars: SidebarsConfig = { type: 'link', label: 'React Native', href: '/react-native/', - description: 'Extends react-native components with accessibility', + description: 'Extends React Native components with accessibility', autoAddBaseUrl: true, }, { From c7cf6ab28089479c0e0738af978f7160ebdecae5 Mon Sep 17 00:00:00 2001 From: Eli Zibin Date: Thu, 5 Dec 2024 09:36:32 -0800 Subject: [PATCH 3/3] Update config-file.md --- website/docs/ama/config-file.md | 35 +++++++++++++++++---------------- 1 file changed, 18 insertions(+), 17 deletions(-) diff --git a/website/docs/ama/config-file.md b/website/docs/ama/config-file.md index 8df690b2..d07a250c 100644 --- a/website/docs/ama/config-file.md +++ b/website/docs/ama/config-file.md @@ -16,23 +16,6 @@ The library does not perform any accessibility checks on the production build! ::: -## Customising the Log Levels - -Create a JSON file called `ama.config.json` in the project's root folder to customise the log rules, then specify the custom log level for the wanted key. - -### Example - -The JSON file does not need to contain all log keys. **AMA** uses the default rule if a key is not present: - -```json -{ - rules: { - "CONTRAST_FAILED": "warn", - "CONTRAST_CHECKER_MAX_DEPTH": 0, - } - "accessibilityLabelExceptions": ["FAQ"] -} -``` ## Log Levels @@ -69,6 +52,24 @@ The possible log levels are: Rules marked with are considered bad practices and cannot be turned off! ::: +## Customising the Log Levels + +Create a JSON file called `ama.config.json` in the project's root folder to customise the log rules, then specify the custom log level for the wanted key. + +### Example + +The JSON file does not need to contain all log keys. **AMA** uses the default rule if a key is not present: + +```json +{ + rules: { + "CONTRAST_FAILED": "warn", + "CONTRAST_CHECKER_MAX_DEPTH": 0, + } + "accessibilityLabelExceptions": ["FAQ"] +} +``` + ### Constants Elements that perform a contrast check do it on all the children up to the level specified by `CONTRAST_CHECKER_MAX_DEPTH`.