[Deep Dive #37] ARIA Ornamentation Contracts - discussion
Deep Dive #37 takes a strong position: accessibility is most stable when ARIA cues are treated as a styling-aligned ornamentation layer with a small vocabulary, applied through primitives, and backed by evidence (ledger + doc hints) so drift is visible.
Do you keep an explicit vocabulary for ARIA notes, or let teams annotate ad-hoc? Where should ornamentation live: route policy, component primitives, or both? How do you prevent ornamentation from becoming stale as screens evolve?
Comments (10)
Back to latestA small vocabulary is underrated. The chaos is not missing ARIA, it is inconsistent ARIA.
The styling-first semantics point resonates with me. When primitives own semantics, the route can be consistent without chasing leaf nodes.
Related: Accessibility Best Practices.
Tiny example of how we kept it consistent: a wrapper component that only allows approved notes.
tsx
type Note = 'Primary action' | 'Navigation action' | 'Destructive action';
export function LabelButton({ ariaNote, ...props }: { ariaNote: Note } & JSX.IntrinsicElements['button']) {
return <button ariaNote={ariaNote} {...props} />;
}It is strict, but it prevented random strings from spreading.
Counterpoint: strict vocabularies can block legitimate nuance.
Sometimes you need a descriptive label for a weird one-off surface.
I think the post is trying to optimize for predictability over expressiveness.
We allow one-offs, but they must be attached to a route policy update (so the vocabulary evolves deliberately).
That makes sense. It is not about banning nuance, it is about making it explicit.
The ledger idea clicked for me when we started running a11y audits in CI.
If you can snapshot the ledger output, drift shows up as a diff instead of a vague regression report.
Misunderstanding I had at first: I thought this meant adding ARIA to everything.
But the point is the opposite: add a small, consistent layer that stays aligned to styling primitives.
Yes. It is about reducing variance so assistive cues are predictable across routes.
If you do doc hints, keep them shallow.
We tried embedding a lot of policy metadata and it became a second config system that nobody maintained.
We render ornamentation keys as data attributes in internal builds.
It made it easy to answer support questions like: did this screen ship with the navigation notes or not?
The best part of the post is it ties a11y to the same forum theme: route evidence and contracts.
If a route cannot prove its ornamentation posture, you are basically hoping it stays correct.
A small vocabulary plus a ledger feels like the right kind of boring. Boring is good for accessibility.