Accessible Component Contract

An organisation with 40 services on one component library and a WCAG obligation has a choice that is arithmetic before it is philosophy. A keyboard trap in a shared dropdown is one defect or 40 findings, fixed once or fixed 40 times, depending only on where verification happens.

The second fact that shapes the pattern: automated tooling can decide only a minority of accessibility success criteria — published estimates generally sit in the 30-40% range for WCAG, which became a 2.2 Recommendation in 2023, and rule engines such as axe-core state plainly that they detect a subset. The defects that dominate real audits, keyboard traps and focus order and misleading announcements, sit in the part a machine cannot judge, because the criterion is whether a person can complete a task.

Put those together and the design follows: verify the hard part once, with a human and an assistive technology, at the place where the behaviour is defined.

Why it matters

Accessibility is usually organised as an audit: a specialist reviews a product, files findings, the team fixes them, and the same defects reappear in the next product. That loop has a feedback time measured in weeks and no memory. A component contract converts a recurring audit finding into a regression test, which is the same move that made functional testing tractable.

It also changes who needs the scarce skill. Screen-reader expertise spread thinly across 40 teams decays; concentrated in the library team, used weekly, it sharpens.

Implementation patterns

• Write the contract as tests, not documentation. Unit tests asserting the accessible name and role for each state, a keyboard interaction test per component (Tab, Shift-Tab, arrows, Escape, Enter), and a recorded manual verification per release naming the assistive technology and version.
• State the keyboard model explicitly: which keys move focus, what closes the component, what returns focus where, and what happens at the ends of a list. Most traps are an unhandled Escape or a focus that never leaves.
• Publish what the consumer must still do. Label text, heading order, landmark structure and error-message association are composition concerns the library cannot guarantee, and saying so prevents false confidence.
• Version the contract with the component, so a consumer upgrading from 3.x to 4.x can see that the focus behaviour changed.
• Keep automated scanning, in one place. It is cheap and it catches the mechanical third — missing alt text, contrast, missing form labels — which is real value at near-zero cost.
• Budget remediation time in the library team, because the first honest audit of a mature component set produces a backlog, and a contract nobody has time to satisfy is a document.

Industry example

The pattern is most visible in public-sector digital services, where the obligation is statutory and the estate is large. The UK's GOV.UK Design System publishes components with their keyboard behaviour and accessibility notes, and services are built from them rather than from scratch — which is why an accessibility fix to a shared component propagates across government services rather than being rediscovered by each one. The structural claim generalises beyond that example: wherever a component is shared, the verification is worth moving to where it is defined.

Failure scenarios

• The green scan. A pipeline check reports zero violations, leadership reads it as compliance, and an external audit later finds 60 issues in the part the tool never assessed.
• Contract without verification. A documented keyboard model that nobody tested against a screen reader, which is confidence with no evidence behind it.
• Composition defects blamed on the library. Correct components assembled in a broken heading order, which the contract explicitly does not cover and consuming teams must still test.
• The library becomes a bottleneck. An accessible date picker takes weeks, a product team under deadline builds its own, and the estate silently fragments — the most common way this pattern dies.
• Assistive technology drift. A component verified against one screen-reader version behaves differently on the next, so verification has a shelf life.

Trade-offs

The pattern trades autonomy for reach: teams give up freedom over interaction details, and get correctness they did not have to produce. It makes the library a gating dependency, which is a real organisational cost and the main reason it fails.

It also does not reduce per-service testing to zero. It reduces it to what composition can break, which is a smaller and better-defined job: heading structure, labels in context, error association, and the specific flows the service adds.

When not to use it

When the sharing is not real. Services on different stacks, vendor products, and acquired applications share no component library, so there is nothing to fix centrally and the honest answer is per-service auditing with a remediation budget. The rule flips at roughly the point where less than half a typical page comes from shared components — below that, fixing the library leaves most of the estate untouched.

It is also the wrong first move for an organisation with one product and two engineers. There, the audit-and-fix loop is cheaper than building and maintaining a contract, and the library will not exist until the third product does.

Interview question

Q: Your automated accessibility checks pass on all 40 services and an external audit returns 60 findings, mostly keyboard traps and focus-order problems in shared components. You have one specialist and a fixed budget. Where do you spend it, and what do you tell leadership about what the green checks were measuring?

What a strong answer covers: the arithmetic that puts the work in the library rather than in 40 pipelines; the explicit statement that rule engines decide a minority of criteria and that keyboard and focus behaviour sit outside it, so the green check was never evidence of compliance; the contract's contents as tests rather than prose; the residual per-service work that composition creates; the bottleneck risk and how to manage it (remediation capacity in the library team, and a documented escape hatch); and the flip condition where services share nothing and per-service auditing is correct.

Quick check

Quiz: An audit finds the same keyboard trap in eleven services. What does that tell you about where the verification should sit? — That the defect is in a shared component, so it should be verified once where the component is defined; 40 pipelines running a tool that cannot detect keyboard traps multiply cost without changing the outcome.

Flashcard: What does an accessible component contract guarantee, and what does it explicitly not? — It guarantees the component's keyboard model, roles, names and announced states, verified against assistive technology; it does not guarantee composition — heading order, labels in context, error association — which each consuming service still has to test.