Skip to main content
Version: 1.2.x

Config File

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.

info

The library does not perform any accessibility checks on the production build!

Log Levels​

AMA guidelines are categorised as:

  • MUST and MUST NOT: Those best practices are enforced and AMA overlays an error when fail
  • SHOULD and SHOULD_NOT: 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
  • warn: A console.warn is performed when a check fails

AMA Rules​

Log keyGuidelineDefaultCan override
BOTTOM_SHEET_CLOSE_ACTIONMUSTerror
CONTRAST_FAILEDMUSTerror
CONTRAST_FAILED_AAASHOULDwarn
FLATLIST_NO_COUNT_IN_SINGULAR_MESSAGESHOULDwarn
FLATLIST_NO_COUNT_IN_PLURAL_MESSAGEMUSTerror
MINIMUM_SIZEMUSTerror
NO_ACCESSIBILITY_LABEL1MUSTerror
NO_ACCESSIBILITY_ROLE 1MUSTerror
NO_FORM_LABELMUSTerror
NO_FORM_ERRORMUSTerror
NO_KEYBOARD_TRAP 1MUST NOTerror
UPPERCASE_TEXT_NO_ACCESSIBILITY_LABELMUST NOTerror
NO_UPPERCASE_TEXTMUST NOTerror
note

Rules marked with are considered bad practices and cannot be turned off!

Customizing the Log Levels​

A JSON file called ama.config.json should have been automatically generated in the project's root folder (If it didn't simply create it). This file is used to customize the log rules, then specify the custom log level for the wanted key. accessibilityLabelExceptions can also be specified in this file. Any changes to this file will automatically be picked up by AMA's config and applied to the applications warnings and errors in Dev mode. (You will need to restart your application to see the changes applied)

warning

If you are running a monorepo setup this file won't automatically generate and you will have two options customize AMA's config.

Options for monorepos (Expand me)

You have two options to add userDefinedRules to AMA's config:

  • You can create a symlink to the ama.rules.json file in the root of your project (recommended)
  • You can create a new ama.rules.json file in the root of your project and copy this file over the ama.rules.json file in @react-native-ama/internal package every time you make changes to it. (This will also need to be done every time you update or delete and reinstall AMA node_modules)

Option 1: (recommended)

To create a symlink to the ama.rules.json file in the root of your project, run the following command:


# In the root of your App or root of your project create a symlink to the ama.rules.json file
# Adjust the file path as needed depending on where the ama.rules.json file is located in your monorepo relative to the root of your project
ln -s node_modules/@react-native-ama/internal/ama.rules.json ./ama.rules.json

Option 2:

To create a new ama.rules.json file in the root of your project, run the following command:

# In the root of your App or root of your project
# Adjust the file path as needed depending on where the ama.rules.json file is located in your monorepo relative to the root of your project
cp node_modules/@react-native-ama/internal/ama.rules.json ./ama.rules.json

Don't forget if you make changes to the ama.rules.json file in the root you will need to copy the changes over to the ama.rules.json file in the @react-native-ama/internal package of your project.

# In the root of your App or root of your project
# Adjust the file path as needed depending on where the ama.rules.json file is located in your monorepo relative to the root of your project
cp ama.rules.json node_modules/@react-native-ama/internal/ama.rules.json

# Restart your application to see the changes

Example​

The JSON file does not need to contain all log keys. AMA uses the default rule if a key is not present:

ama.rules.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.

Constant keyDefault value
CONTRAST_CHECKER_MAX_DEPTH5
ama.rules.json
{
  "rules": {
    "CONTRAST_CHECKER_MAX_DEPTH": 0
  }
}
tip

This can be turned off by specifying a level of 0

accessibilityLabelExceptions​

AMA performs various checks, including one for uppercase. This rule allows specifying a list of approved all-caps accessibility labels.

ama.rules.json
{
  "accessibilityLabelExceptions": ["FAQ"]
}
note

The key accessibilityLabelExceptions is not nested under the rules key as the above values must be.

Footnotes​

  1. The rule cannot be overridden ↩ ↩2 ↩3