


Most accessibility documentation focuses on the component level: how to annotate states, specify contrast, and document keyboard behavior. That work matters, but it leaves a gap — what happens when a product team builds on a well-documented base system and runs into a pattern the base system wasn't meant to anticipate?
This article explains how product systems can structure documentation so that deviation doesn't quietly become accessibility debt.

I see this most often in enterprise design system teams, where there are multiple layers to the system: base systems (e.g. Fluent, Material) intended for use in product systems (e.g. Outlook, Gmail). Base systems can't account for every unique pattern a product will need. Their job is to offer ubiquitous, reusable components that work across a company, not to anticipate every product's specific patterns.
In product design system teams, our job is to extend the base system into our context, not replace it. In atomic design terms, the base system handles atoms, molecules, and some organisms; we take those and build the product-specific organisms, templates, and pages our context requires.
That extension work follows a consistent sequence: We assess what the base system already offers, figure out how those pieces combine for our specific use case, then build and document it.

Let's take errors as an example. A base design system might offer errors on inputs, but it doesn’t require a specific pattern for multiple input errors. This raises questions the base system may not be built to answer: How do we handle input errors across a form? How do we summarize those errors for the user? How might we handle errors in a multi-step form?
The base system gives us error guidance at the component level, such as how a single input should look and behave when it's invalid. It doesn't tell us how those errors behave in concert, across a form. That gap is ours to define and document.

When we define product components and patterns, we have to gather requirements from three places: the base system, accessibility standards (WCAG), and the product itself.
Let's extend our error example:

In these situations, we often look to other products, in our company or elsewhere, to see how they've handled it. GOV.UK's design system offers a well-tested pattern for our example here: error summary. We check that it's consistent with the base system's guidance and directly addresses frustrations disabled and neurodivergent users commonly report when finding errors in long forms. We can use an error summary to show multiple input errors, and link to specific input errors to reduce the burden on users to find them.
From here, it's on us to decide how we extend the base system for our context. We can build a component that pairs an error summary with the individual input errors it links to. Beyond building it, we still have to document when to use it, how to implement it, the required content structure, and the accessibility requirements it must meet.

Once we've gathered those requirements and decided how to extend the base system, the real work begins: turning that decision into a default our product teams can rely on, specific enough to be useful without burying them in detail they won't read.
Take the error summary from our example. The base system gives us a starting point: An error summary can be used to surface errors, with focus moving to it on submission. That foundation holds as we extend the pattern, but it can only take us so far.
In a product system, our guidance can be more exact, since we're solving a narrower problem. We have to document how the pieces interact: that the error summary links to each individual input error, the minimum and maximum number of errors it should handle, and the edge cases in between.
This is where defaults matter most for accessibility. There's a common tension in documenting it: too little guidance, and designers don't know what's expected of them; too much, and they get overwhelmed, skip it, or apply it inconsistently. The way through is to be precise about what's already handled versus what's left to the designer.
In practice, this means our documentation states the default and the deviation cost in the same breath. Something like this:

This confirms the pattern is accessible, what the default behavior is, and what they should do if they change that. Teams don't need to know WCAG in depth to use the pattern correctly; they only need to know what they're choosing if they step outside it.
This precision matters because of how designers actually behave when asked to "annotate for accessibility" without it: most default to annotating focus order, often incorrectly, with no clear sense of what else to annotate, and eventually give up trying. Naming the decision points explicitly, and pairing each one with its exact required annotation, closes that gap.
Defaults work when teams use them as designed. But not every team will, and when a team decides to deviate, the documentation needs to tell them exactly what they're now responsible for.
Take our error summary example. A team might decide they want errors to "pop up" more assertively, and reach for a toast notification instead. It's an understandable instinct, but a poor fit: Toasts are transient, often disappearing before users can process them, with no way to recover the list of errors short of resubmitting the form.
This is exactly the kind of decision the deviation contract exists for. The system can't stop a team from making this choice; it can only tell them what they now own by making it. Our documentation should make clear that they:
The point isn't to forbid deviation. Sometimes a team has a genuinely good reason to diverge. If we don’t offer that option, teams will do it anyway.
Divergence without a contract is how accessibility debt accumulates quietly: months later, as a bug report. Naming the cost up front, in the documentation itself, is what keeps that debt from being invisible.

Over the years, I've been asked many times how to motivate teams to prioritize accessibility. This is a small piece of how to do that.
Every design system team needs at least one accessibility specialist to define the system's contracts and defaults. Without one, accessibility becomes everyone's job in theory and no one's job in practice.
That single investment pays off across every product team consuming the system. When teams know the default will be accessible if used as intended, and know exactly what their part is when they deviate from it, they don't feel like they have to learn everything about accessibility in a single sprint.
This also reduces the testing burden. Accessibility testing will always be a factor requirement, but when the system is accessible and the decisions required to use it are clear, teams can test their work more easily, understand how it should behave, and spot where things might have broken rather than starting from scratch each time.
That clarity cuts both ways: Stay within the system, and accessibility is faster and easier to deliver. Deviate from it, and that same testing and bug-fixing effort lands back on you.
Design systems can't automate away all of your accessibility considerations, but small actions like these reduce risk. They show teams, concretely, that straying from the system costs time and that the system itself is the easier, faster path.
