angular-accessibility

Files (1)

• SKILL.md

SKILL.md (first lines)

# Angular Accessibility (a11y)

## When To Activate

- After any development touching Angular templates, including a new feature, bug fix, or refactor
- After updating Angular Material markup, control structure, labels, dialogs, tables, forms, or navigation UI
- Fixing Lighthouse, axe, or ESLint accessibility findings
- Auditing Angular templates or Angular Material screens
- Debugging keyboard navigation, focus order, or screen reader output
- Refactoring interactive UI in Angular HTML templates

## Default Post-Development Trigger

Run this skill as a final verification step whenever the implementation modified `.html` templates or materially changed rendered UI structure, even if the original task did not mention accessibility.

Typical triggers:

- New feature that introduces or changes template markup
- Bug fix that changes form controls, buttons, tables, dialogs, drawers, or navigation
- Refactor that restructures conditionals, loops, landmarks, headings, or interactive elements
- Angular Material component replacement or reconfiguration affecting labels, focus, or keyboard behavior

## Hard Rules

- Prefer semantic HTML first: native `<button>`, `<a>`, `<label>`, `<main>`, `<table>`, and `<th>` before ARIA workarounds
- Prefer visible labels, `<label for>`, `<mat-label>`, or `aria-labelledby` before `aria-label`
- Use ARIA to fill missing semantics, not to replace native semantics
- For native elements, bind ARIA with `[attr.aria-*]`
- For Angular Material components that expose dedicated inputs, prefer `[aria-label]` or `[aria-labelledby]` without `attr.`
- Do not add redundant roles to native controls (`role="button"` on `<button>`, `role="checkbox"` on `<input type="checkbox">`, etc.)
- All user-facing accessible text must be translated with Transloco. Never hard-code text in templates
- After each fix, verify keyboard and focus behavior, not just lint output

## Audit Workflow

1. Run the ESLint accessibility check first:
   ```bash
   npx eslint "src/app/<feature>/**/*.html"
   ```
2. Run an automated audit on the affected screen:
   - Lighthouse
   - axe DevTools or equivalent
3. Perform a keyboard-only smoke test:
   - `Tab` / `Shift+Tab` reaches all interactive controls in a logical order
   - `Enter` / `Space` activates buttons, toggles, and checkboxes
   - `Escape` closes dialogs, menus, or drawers where applicable
   - Focus remains visible throughout the flow
4. Spot-check the changed flow with a screen reader
5. Fix issues systematically using the patterns below
6. Re-run lint and the automated audit on the affected screen

---

## Common Issues & Fixes

### 1. Icon-only buttons - missing accessible name

Any `<button>` whose only content is a `<mat-icon>` or similar icon has no accessible name.

**Fix**: add a translated accessible name and mark the icon as decorative.

```html
<!-- ❌ Before -->
<button type="button" (click)="onClose()">
  <mat-icon>close</mat-icon>
</button>

<!-- ✅ After -->
<button
  type="button"
  [attr.aria-label]="t('scope.key.close-btn-aria')"
  (click)="onClose()"
>
  <mat-icon aria-hidden="true">close</mat-icon>
</button>
```

Same pattern applies to pagination, toggle, toolbar, and other icon-only actions.

---

### 2. Form controls - missing programmatic label

Prefer a visible label first. Use `aria-label` only when a visible label or `aria-labelledby` is not practical.

**Standard forms**: use `<label for>` or `<mat-label>`.

```html
<!-- ✅ Preferred in a regular form -->
<mat-form-field>
  <mat-label>{{ t('scope.key.amount') }}</mat-label>
  <input matInput id="amount" type="number" />
</mat-form-field>
```

**Dense table/grid cells**: use row-level context so each control is uniquely identifiable.

```html
<!-- ❌ Before -->
<input matInput type="number" [value]="row.amount" />
<mat-select [value]="row.type"></mat-select>

<!-- ✅ After -->
<input
  matInput
  type="number"
  [value]="row.amount"
  [attr.aria-label]="t('scope.key.amount-aria', { invoiceNumber: row.invoiceNumber })"
/>

<mat-select
  [value]="row.type"
  [aria-label]="t('scope.key.type-aria', { invoiceNumber: row.invoiceNumber })"
>
</mat-select>
```

---

From fmflurry/settings-opencode, MIT.

More from fmflurry/settings-opencode