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

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

• #4169 (a11y: buttons without accessible names) — closes via Phase 2 button plumbing
• #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.

Start by defining the Phase 1 ARIA vocabulary and the split between semantic ARIA attributes and theming-only data-variant values. Then review the listed shared component families and the de-risk slice of button, signal-list, and dialog. Done means the Stratos KS contract is documented and the selected components emit the agreed attributes, with the Angular ESLint checks and PR checklist addressed.