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 they fail
• SHOULD and SHOULD_NOT: Those best practices are preferred and AMA prints only a warning message when they fail

The possible log levels are:

• error: The AMA error overlay is shown when a check fails
• warn: A console.warn is performed when a check fails

ama.config rules

Log key	Guideline	Default	Can override
BOTTOM_SHEET_CLOSE_ACTION	MUST	error
CONTRAST_FAILED	MUST	error
CONTRAST_FAILED_AAA	SHOULD	warn
FLATLIST_NO_COUNT_IN_SINGULAR_MESSAGE	SHOULD	warn
FLATLIST_NO_COUNT_IN_PLURAL_MESSAGE	MUST	error
IMAGE_MISSING_ALT_TEXT	MUST	error
INCOMPATIBLE_ACCESSIBILITY_ROLE	MUST NOT	error
INCOMPATIBLE_ACCESSIBILITY_STATE	MUST	error
INPUT_HAS_FOCUSABLE_LABEL	MUST	error
INPUT_HAS_NO_VISIBLE_LABEL	MUST	error
INPUT_HAS_NO_VISIBLE_LABEL_ENDING_WITH_ASTERISK	MUST NOT	error
INPUT_INVALID_RETURN_KEY	MUST	error
MINIMUM_SIZE	MUST	error
NO_ACCESSIBILITY_LABEL 1	MUST	error
NO_ACCESSIBILITY_ROLE 1	MUST	error
NO_ACCESSIBILITY_STATE_SET	MUST	error
NO_FORM_ERROR	MUST	error
NO_HEADER_FOUND	MUST	error
NO_KEYBOARD_TRAP 1	MUST NOT	error
NO_UNDEFINED 1	MUST NOT	error
NO_UPPERCASE_ACCESSIBILITY_LABEL	SHOULD_NOT	warn
NO_UPPERCASE_TEXT	MUST NOT	error
UPPERCASE_TEXT_NO_ACCESSIBILITY_LABEL	MUST NOT	error

note

Rules marked with are considered essential 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). Specify the custom log level for the keys you want to override. Any changes to this file are automatically picked up by AMA in dev mode — you will need to restart your application to see them applied.

Example

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

ama.config.json

{
  "rules": {
    "CONTRAST_FAILED": "warn",
    "CONTRAST_CHECKER_MAX_DEPTH": 0
  },
  "accessibilityLabelExceptions": ["FAQ"],
  "highlight": {
    "mode": "border",
    "borderWidth": 2,
    "gap": 8
  },
  "log": "always",
  "uppercaseMinLength": 5,
  "checks": {
    "ui": true,
    "forms": true,
    "delay": 300
  }
}

Configuration keys

rules

Per-rule severity overrides. Each key is an AmaRule string (see table above) and each value is one of:

Value	Effect
"MUST" / "MUST_NOT"	Triggers the AMA error overlay
"SHOULD" / "SHOULD_NOT"	Prints a console.warn
"PLEASE_FORGIVE_ME"	Silences the rule entirely

Non-overridable rules (marked in the table) ignore any value set here.

accessibilityLabelExceptions

AMA performs various checks, including one for uppercase. This key allows specifying a list of approved all-caps accessibility labels that should not trigger the uppercase rule.

ama.config.json

{
  "accessibilityLabelExceptions": ["FAQ"]
}

note

accessibilityLabelExceptions is a top-level key, not nested under rules.

highlight

Controls how AMA visually marks failing elements in the dev overlay.

Key	Type	Default	Description
mode	"border" | "background" | "both"	"both"	Whether to outline, fill, or both when highlighting a failing element
borderWidth	number	3	Width of the highlight border in dp
gap	number	4	Minimum gap between highlighted elements in dp

ama.config.json

{
  "highlight": {
    "mode": "border",
    "borderWidth": 2,
    "gap": 8
  }
}

log

Controls when AMA logs accessibility issues to the console.

Value	Behaviour
"inspect" (default)	Logs only when the AMA inspector is open
"always"	Always logs to the console in dev mode

ama.config.json

{
  "log": "always"
}

uppercaseMinLength

The minimum number of characters a text string must have before the uppercase rule (NO_UPPERCASE_TEXT) is applied. Strings shorter than this value are not checked for uppercase.

Type	Default
number	4

ama.config.json

{
  "uppercaseMinLength": 5
}

checks

Feature gates that enable or disable categories of AMA runtime checks.

Key	Type	Default	Description
ui	boolean	true	Enable UI interaction checks
forms	boolean	true	Enable form and node checks
delay	number	1000	Milliseconds to wait before re-checking after an interaction

ama.config.json

{
  "checks": {
    "ui": true,
    "forms": true,
    "delay": 300
  }
}

Constants

These values are set inside the rules object and control internal check behaviour rather than rule severity.

Constant key	Default	Description
CONTRAST_CHECKER_MAX_DEPTH	5	How many levels deep AMA checks children for contrast. Set to 0 to disable contrast checking entirely.
IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS	false	When true, contrast checks are skipped for elements that are disabled.

ama.config.json

{
  "rules": {
    "CONTRAST_CHECKER_MAX_DEPTH": 0,
    "IGNORE_CONTRAST_FOR_DISABLED_ELEMENTS": true
  }
}

Footnotes

1. The rule cannot be overridden ↩ ↩² ↩³ ↩⁴