@design-parity/checks

Deterministic accessibility + internationalization spec checks over a (DesignReference, CandidateRender) pair. These are the high-value, spec-backed findings the verdict leads with (see docs/PRINCIPLES.md Principle 2): the objective details developers routinely miss and design tools don't enforce.

Every check is a pure function that reads committed thresholds and the candidate's rendered semantics — no network call and no model at run time (Principle 1). The same PR always scores the same.

Checks

| Function | Kind | What it asserts | | --- | --- | --- | | checkContrast | contrast | WCAG 1.4.3/1.4.6 text contrast per theme; fails AA → error, meets AA but not AAA → info. | | checkTouchTargets | a11y | Interactive targets ≥ 48dp (Material 3); below the WCAG 2.5.8 floor of 24dp → error. | | checkSemantics | a11y | Interactive/image nodes expose an accessible label / content description. | | checkTextExpansion | i18n | Pseudolocale text growth vs available width → truncation risk (warn). | | checkLocaleFormatting | i18n | Hardcoded locale-specific currency/date/number literals in labels. | | checkRtlMirroring | i18n | Directional icons that must mirror under RTL; right-to-left text. | | checkHardcodedStrings | i18n | Un-keyed user-facing literals (opt-in — a render can't prove a string came from a resource). |

runChecks(reference, candidate, config?) runs the whole suite and returns findings a11y first, then i18n, severity-ordered within each group. runA11yChecks / runI18nChecks run one group.

Configuration

All policy is committed and overridable via ChecksConfig (contrast level, touch-target minimum, glyph-advance estimate, themes, hardcoded-string opt-in). Defaults live in src/thresholds.ts and encode WCAG 2.2

• Material 3 + standard pseudolocale guidance.

A repo commits these knobs to design-parity.checks.json — the file @design-parity/baseline writes during bootstrap. It is read deterministically at run time so its tuned thresholds actually reach the engine (Principle 1):

• loadChecksConfig(path) — read, parse, and schema-validate a config file; throws a readable error if it is missing, not JSON, or schema-invalid.
• loadChecksConfigOrDefault(path) — same, but a missing file resolves to the committed defaults, so a repo in steady state with no setup still works. A present-but-invalid file still throws.
• validateChecksConfig(value) — validate an already-parsed object against the draft-07 schema.

The config shape mirrors ChecksConfig exactly, so bootstrap output validates and loads without translation. See examples/design-parity.checks.json.

Validate CLI

design-parity-validate-checks [path ...] validates one or more config files against the schema and exits non-zero on the first invalid one, so it can gate CI. Defaults to design-parity.checks.json in the cwd.

node packages/checks/dist/cli/validate-checks.js design-parity.checks.json

Finding kinds

This package introduced the dedicated a11y and i18n FindingKinds in @design-parity/core so the verdict can cleanly lead with them. contrast keeps its own kind (it carries a numeric ratio and is the headline a11y finding). Focus order and state-announcement gaps are not asserted yet: SemanticNode does not model them, so adding those checks is a contract change in core — tracked rather than faked.

Develop

npm run build --workspace @design-parity/checks
npm test