ARIA tokens as theming-tool input contract: vocabulary + component plumbing

[nabramovitz]

Goal

Establish a stable vocabulary of ARIA + companion data-* attributes emitted by Stratos shared components, so a theming tool can read those attributes to know what it's styling.

This is not a WCAG-compliance pass. ARIA attributes are inert (no behavior change). They mark up components with their semantic role and state so an external theming tool has a stable input contract.

Scope

Phase 1 — vocabulary + companion attribute (~1 day)

• Pick the standard ARIA token set: roles (button/navigation/region/dialog/listbox/combobox/tablist/grid/etc.), state attributes (aria-expanded/aria-selected/aria-current/aria-checked/aria-busy/aria-disabled/aria-invalid), relationship attributes (aria-controls/aria-labelledby), naming attributes (aria-label/aria-labelledby).
• Decide on data-variant="primary|secondary|destructive|…" as the companion attribute for theming-only concerns ARIA can't express. Document the split: ARIA for semantic, data-* for pure theming.
• Land as a Stratos KS doc that future component changes reference.

Phase 2 — per-component plumbing (~2-3 weeks parallelizable)

Shared component families to plumb, ordered roughly by visibility:

• <app-button> family (mat-button variants) — role="button", aria-label for icon-only, data-variant, aria-pressed for toggles.
• Page header / side nav — role="banner", role="navigation", current-page via aria-current="page".
• Cards — role="region"|"article", aria-busy during load, data-variant for status.
• Steppers — role="navigation", step aria-current="step".
• Signal-list — role="grid", rows role="row", cells role="cell", aria-busy during drain, aria-rowcount.
• Custom select / dropdown — role="combobox", aria-expanded, listbox role="listbox", items role="option", aria-selected.
• Dialogs / drawers — role="dialog", aria-modal, aria-labelledby, aria-describedby.
• Toolbars — role="toolbar", aria-label.
• Form fields — aria-invalid, aria-required, aria-describedby for error text.
• Status / loading — role="status", aria-live="polite".
• Tabs — role="tablist", role="tab", aria-controls, aria-selected.

~10-12 families. 4-8 hours each.

Phase 3 — theming-tool contract doc (~0.5 day)

Document the attributes the theming tool reads. This is the output of Phase 1 + 2 and the input of the theming tool. Versioned. Lives in Stratos KS.

Phase 4 — regression guard (~0.5 day)

• @angular-eslint/template a11y rules where they catch emission gaps cheaply.
• PR checklist for new shared components: "ARIA + data-variant contract emitted."

Sequencing

Phase 1 before Phase 2 (otherwise components ship inconsistent ARIA the theming tool then has to absorb). Phase 2 can ship per component-family PR. Phase 3 + 4 in parallel with Phase 2 once vocabulary is locked.

De-risk option

Pick 3 components for an initial slice (button, signal-list, dialog), plumb them, wire a theming-tool prototype that reads from those three. If the contract holds up, expand to the rest. Cuts upfront commitment to ~1 week.

Supersedes

• a11y: Buttons without accessible names #4169 (a11y: buttons without accessible names) — closes via Phase 2 button plumbing
• a11y: Creation date (sort/filter) control is missing an accessible name #4174 (a11y: Creation date sort/filter select missing accessible name) — closes via Phase 2 signal-list / custom-select plumbing

Total estimate: ~3 weeks focused work, parallelizable.

[nabramovitz]

Cross-link: PR #5378 (dev.100 bump merged as 8f02875a5e) was the build used during this session's adepttech deploy — the same Playwright re-test window in which this ARIA-as-theming-tokens umbrella was scoped and filed. The bump itself is unrelated to ARIA work; linking for session-traceability only.

[nabramovitz]

Positioning vs. WCAG

This effort is not aimed at delivering a WCAG 2.1 Level A or AA compliant interface — it's an ARIA-tokens-as-theming-contract effort. That said, it provides the foundation a future compliance push would build on.

The token contract picks up the bulk of WCAG 4.1.2 (Name, Role, Value) and 1.3.1 (Info and Relationships) by construction, and the labeling / live-region patterns become the consumable seam that later workstreams (keyboard + focus audit, color contrast pass, focus-visible CSS, skip links, modal focus traps, form-error patterns, axe-core test gating, manual + screen-reader audit) would plug into.