Grammar specification · WCAG Grammar

This material is a specification and reference set. It is not an accessibility scanner, a legal opinion, a certification, or evidence of a completed audit. Sample observations are explicitly untested, and WCAG 3 is draft guidance rather than the target here.

Accessibility grammar specification

Version 1.0. The DSL below is a declarative specification, not an existing command language. JSON examples are schema-validated, but require product-specific predicate implementations.

1. The accessibility sentence

FOR EACH [OBJECT]
IN [PAGE / COMPONENT / COMPLETE PROCESS]
WHEN [STATE + USER ACTION + ENVIRONMENT]
IF [APPLICABILITY EXPRESSION]
THEN REQUIRE [OUTCOME EXPRESSION]
USING [IMPLEMENTATION MECHANISM]
VERIFY WITH [TEST PROCEDURE]
RECORD [OBSERVATION + BUILD + ENVIRONMENT + EVIDENCE]
ELSE [NOT_APPLICABLE WITH REVIEWED REASON]
ON FAILURE [OWNER + LAKA CHANGE LEVEL + REPAIR + REGRESSION TEST]

A sentence is incomplete until the object, scope, relevant states, required outcome, source, evidence method and owner are specified. A screenshot by itself cannot establish interaction behavior.

2. Three separate authority layers

Authority	Meaning	Evaluation
`wcag_requirement`	Operational expression of a referenced WCAG success criterion.	Assess the criterion, including its definitions and exceptions.
`implementation_pattern`	One selected implementation approach, such as an APG dialog pattern.	Check its contract, but do not pretend every pattern detail is verbatim WCAG.
`product_policy`	A deliberately stronger or supplemental product rule.	Report policy failures separately from WCAG failures.

Normative text controls the WCAG requirement. Understanding documents explain it. Techniques and APG supply implementation guidance rather than the only permitted solution. A technique can require more than the minimum criterion. [S-WCAG22, S-APG-FIRST]

For example, a 44px primary control can be a product policy without being the universal AA minimum. A fully unobscured focus target can be a policy stronger than the AA partial-visibility minimum. [S-TARGET-ENHANCED, SC-2.4.11]

3. Operators

Operator	Meaning
`IF / THEN / ELSE`	Choose behavior from established applicability; unknown applicability does not take the ELSE branch.
`AND`	Every required operand must be satisfied.
`OR`	At least one complete permitted alternative must be satisfied.
`NOT`	Negates known truth; it never converts an unknown observation into a pass.
`XOR / EXACTLY ONE`	One and only one option is selected, only where the particular contract requires exclusivity.
`FOR EACH`	Evaluate every instance in the declared test scope. The scope cannot be silently reduced.
`AT LEAST n`	Count verified matching instances; unresolved candidates remain unresolved if they affect the result.
`UNTIL`	A bounded workflow condition, not permission for an agent to loop indefinitely.
`EXCEPTION`	A criterion-specific, evidence-backed qualification; not a managerial waiver.

XOR is not appropriate when WCAG permits multiple valid accommodations at once. OR cannot join unrelated criteria to let one compensate for another. Use parentheses to distinguish alternatives within a criterion from obligations across criteria.

CORRECT:
  keyboard_operation
  AND (pointer_target_size OR verified_target_exception)
  AND accessible_name

INCORRECT:
  keyboard_operation OR sufficient_contrast

4. Truth and verdicts

Predicates evaluate to TRUE, FALSE or UNKNOWN.

AND(FALSE, UNKNOWN) = FALSE
AND(TRUE, UNKNOWN)  = UNKNOWN
OR(TRUE, UNKNOWN)   = TRUE
OR(FALSE, UNKNOWN)  = UNKNOWN
NOT(UNKNOWN)       = UNKNOWN

An OR can resolve TRUE only when its TRUE branch is a genuinely permitted complete alternative, with the required evidence. A test adapter must not treat a missing selector, timeout, null response or unimplemented predicate as FALSE or TRUE by default.

Verdict	Use
`PASS`	Applicable assertions are supported by adequate evidence for this instance.
`FAIL`	A reproducible assertion is false.
`NOT_APPLICABLE`	The triggering condition does not apply, with a recorded and reviewed reason.
`NOT_TESTED`	No adequate test has been performed.
`NEEDS_REVIEW`	Applicability, exception, interpretation or evidence needs qualified judgment.
`BLOCKED`	Access, fixtures, environment or a technical failure prevents evaluation.

These are grammar verdicts, not replacements for formal evaluation terminology. Never count NOT_TESTED, NEEDS_REVIEW or BLOCKED as passed. A verified exception to one assertion can leave other obligations in the same criterion fully applicable.

5. Required rule fields

id, version, authority, source_refs
wcag_refs: criterion ID + level
object: type + scope + states
applicability: expression
require: expression
exceptions: clause + scope + proof + reviewer
implementation: selected mechanism and constraints
laka: chosen level + all ten internal variables + relevant meta-variables
tests: steps + expected result + method + environment
metrics: measure + unit + operator + threshold + denominator
guardrails: regressions that must not occur
owner: accountable role

Actual executions are separate records. A rule describes what to test; an execution stores what happened. Editing a rule must not overwrite historical evidence.

6. Exception contract

exception =
  exact criterion clause
  + affected instances
  + reason its conditions hold
  + evidence
  + qualified reviewer
  + build/context validity
  + remaining obligations

Budget, brand preference, an inaccessible supplier, a high scan score, and lack of a reported complaint do not create WCAG exceptions. Product risk acceptance is a separate business record and never changes a failed requirement to PASS. [S-WCAG22]

7. Native semantics rule

IF an appropriate native HTML element supports the needed task
THEN prefer it and preserve its browser behavior.
ELSE define the custom interaction, semantics and keyboard contract
     before adding ARIA, then test the rendered behavior.

This is an implementation preference. ARIA attributes do not independently implement keyboard behavior, focus management or business logic. Avoid using an ARIA role as a substitute for those behaviors. [S-APG-FIRST]

8. Machine representation

The JSON schema supports a deliberately small expression tree: predicate, all, any, not. Advanced DSL quantifiers are expanded into explicit test instances by the implementer before serialization. The tree is data, not executable code; do not call eval() on it.

{
  "all": [
    {"predicate": "keyboard.task_complete"},
    {"any": [
      {"predicate": "target.meets_24_by_24"},
      {"predicate": "target.valid_exception_verified"}
    ]}
  ]
}

Every predicate needs a documented adapter with input, units, test procedure, evidence output and UNKNOWN behavior. Names do not imply a browser capability. A model prediction that a screen reader will announce something is not an actual screen-reader observation.