WCAG Compliance as an Architecture Constraint, Not a Checklist

Context

The people using this portal had specific needs most products assume away. Some navigated with screen readers or keyboard only. Others had cognitive or visual impairments that made dense, poorly structured UIs harder to process. Some had no assistive technology but still relied on clear layout and logical flow more than a typical user would. When that’s your audience, “we’ll worry about accessibility later” isn’t a tradeoff - it’s a failure of the product.

I co-led the greenfield frontend build of the portal they’d use - no existing codebase to retrofit. That meant building the accessibility model into the architecture before a single component existed.

Approach

Treating accessibility as a quality pass at the end is how you get a mostly-compliant product with broken flows. The decision here was to make it a constraint from day one - that shifts the questions you ask when building anything. Not just “does this work?” but “can someone complete this flow with a keyboard?” and “what does VoiceOver announce when this state changes?”

Practically, that meant three disciplines.

Semantic HTML by default. Not because it’s always easier - custom interactive patterns sometimes make it harder - but because the native semantics carry meaning that ARIA has to reconstruct from scratch otherwise. Start with the right element, then add ARIA only where the element alone isn’t enough.

Manual testing alongside automated checks. Axe and similar tools catch structural problems: missing labels, invalid ARIA, broken heading hierarchy. They don’t catch interaction problems. Does focus land somewhere sensible after a form step completes? Does the screen reader announce the right thing when a table updates? You find out by actually using the interface with a keyboard and a screen reader. There’s no shortcut for that.

React Testing Library as a forcing function. If you write tests correctly - querying by accessible roles rather than class names or test IDs - components without the right semantic roles fail your tests. That pressure is constant. A component that ships without a role didn’t pass a test.

Mobile-first was also the right call. The core audience was likely to include phone-first users, and mobile constraints surface accessibility problems earlier than you’d otherwise catch them - small tap targets, scroll traps, unclear affordances. The two priorities reinforced each other.

Outcome

Shipped a WCAG 2.1 AA compliant portal handling the full workflow. The more meaningful part: that compliance held as the product grew. New form steps, new data views, new interactive patterns - each went through the same disciplines. No accessibility debt accumulated because the structure didn’t allow for it. That’s the difference between building it in and bolting it on.

Reflection

Working on this project changed how I think about accessibility on everything I’ve built since. Not because the techniques were new to me - they weren’t. But working on a product where the users’ situations are this specific makes it harder to treat accessibility as someone else’s concern.

The practical lesson carries beyond projects with these stakes: most of what makes a UI accessible also makes it better for everyone. Keyboard navigation, clear focus states, logical tab order - these aren’t disability accommodations, they’re good interface design. The discipline just forces you to be explicit about things you’d otherwise leave implicit.