For each pair it resolves both tokens to colours, settles any alpha against a known backdrop, computes the ratio, and compares it with the policy threshold. Text failures and non-text failures are separate rules with separate counts, so a build can treat a label and a control differently.
This walkthrough uses the tool's public README and checked-in example files. Run the command from a repository checkout with Node.js 22+.
Run the checked-in example
# a clean run: every pair resolves and every ratio meets its threshold
node bin/color-contrast-token-auditor.mjs \
--tokens examples/clean/tokens.json \
--policy examples/clean/contrast.policy.json \
--now 2026-09-18
# exit 0, status "pass"
# a failing run: one text pair and one control pair below their thresholds
node bin/color-contrast-token-auditor.mjs \
--tokens examples/failing/tokens.json \
--policy examples/failing/contrast.policy.json \
--now 2026-09-18
# exit 1, status "fail"
# an undetermined run: a value this tool does not read, and a scrim over nothing known
node bin/color-contrast-token-auditor.mjs \
--tokens examples/undetermined/tokens.json \
--policy examples/undetermined/contrast.policy.json \
--now 2026-09-18
# exit 2, status "incomplete"Read the result
--now is optional and defaults to the system clock. Supply it to make a run that checks token age reproducible; every example above is pinned to one instant for that reason.
Scope
These are behaviour, not caveats. Each one is enforced by a test.