feat(ui5): Add accessibility best practices skill (#85)

Adds a new skill for UI5 accessibility best practices covering keyboard navigation, labelling,
landmarks, heading levels, reading order, target size, shortcuts, and invisible messages.
Includes reference documentation and test fixtures for each topic.

JIRA: FIORITECHP1-35629

Author: nikolay-kolarov

plugins/ui5/README.md

@@ -28,6 +28,19 @@ Development guidelines and coding standards derived from official SAP UI5 guidel
 
 **Note**: For TypeScript conversion specifically, use the separate [`ui5-typescript-conversion`](https://github.com/UI5/plugins-coding-agents/tree/main/plugins/ui5-typescript-conversion) plugin.
 
+#### ui5-best-practices-accessibility
+
+Accessibility guidelines and review checklist for UI5 views, fragments, and controllers:
+
+- **Landmarks** - `landmarkInfo` and `accessibleRole` for `DynamicPage`, `Page`, `Panel`, `ObjectPage`, `FlexibleColumnLayout`
+- **Labeling** - `<Label labelFor>` for inputs, `ariaLabelledBy` for tables, tooltips for icon-only buttons, `alt` for standalone icons and images
+- **Heading levels** - Explicit `level` on `<Title>`, no heading level jumps within a view
+- **Focus handling** - `initialFocus` on `Dialog`/`Popover`, fast navigation groups, no `tabindex > 0`
+- **Keyboard shortcuts** - `CommandExecution` for action buttons that should support keyboard shortcuts
+- **Invisible messaging** - `InvisibleMessage.announce()` for dynamic state changes visible to sighted users only
+- **Reading order** - Controls not visually reordered out of DOM sequence; `ariaDescribedBy` pointing to correct DOM order
+- **Target size** - `reactiveAreaMode` for interactive controls in dense layouts
+
 #### ui5-best-practices-integration-cards
 
 Development guidelines for UI Integration Cards (also known as UI5 Integration Cards):

plugins/ui5/skills/ui5-best-practices-accessibility/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: ui5-best-practices-accessibility
+description: |
+  This skill should be used when the user asks to audit, fix, check, review, or
+  improve accessibility, a11y, ARIA, WCAG compliance, landmarks, labeling, heading
+  levels, focus handling, keyboard navigation, keyboard shortcuts, screen reader
+  support, invisible messaging, reading order, or touch / target size in UI5
+  application files (views, fragments, controllers). Also use when the user
+  creates a new UI5 view, fragment, or controller and wants it to be accessible,
+  or asks whether a specific control (Dialog, Table, Panel, etc.) meets
+  accessibility requirements.
+
+  Keywords: accessibility, a11y, ARIA, WCAG, screen reader, NVDA, JAWS, VoiceOver,
+  landmark, landmarkInfo, accessibleRole, ariaLabelledBy, ariaDescribedBy,
+  labelFor, tooltip, alt text, decorative, heading level, initialFocus, F6,
+  fast nav, fastnavgroup, tabindex, CommandExecution, keyboard shortcut,
+  InvisibleMessage, announce, reading order, reactiveAreaMode, target size.
+---
+
+# Accessibility Review
+
+Accessibility in UI5 is incorporated in two levels: framework and application.
+This review supports what application developers must still provide explicitly
+to improve the accessibility of their application.
+
+## Step 1 — Find the files
+
+If `$ARGUMENTS` lists specific files, review only those.
+
+Otherwise, discover all app source files automatically:
+
+```!
+find . \( -name "*.view.xml" -o -name "*.fragment.xml" -o -name "*.controller.js" \) \
+  -not -path "*/node_modules/*" \
+  -not -path "*/dist/*" \
+  -not -path "*/test/*" \
+  -not -path "*/resources/*" \
+  | sort
+```
+
+If more than 15 files are found, use `AskUserQuestion` to let the user choose:
+- Review everything (may take a moment)
+- Focus on a specific folder or area
+
+Read each file in scope.
+
+## Step 2 — Review
+
+Check the code against the eight topics below. For each topic where you find a gap,
+**read the corresponding topic file before writing the fix** — it contains the correct
+API pattern and wrong/correct examples.
+
+| # | Topic | What to detect | Topic file |
+|---|-------|---------------|------------|
+| 1 | Landmarks | `DynamicPage`, `Page`, `Panel`, `ObjectPage`, `FlexibleColumnLayout` missing `landmarkInfo` or `accessibleRole`; landmark role set without its corresponding label (e.g. `rootRole` without `rootLabel`) | `references/landmark.md` |
+| 2 | Labeling | Inputs without `<Label labelFor>` (except inside `SimpleForm`); Tables without `ariaLabelledBy`; icon-only `Button` without `tooltip`; standalone `Icon` without `alt` and not marked `decorative`; `Image` with `decorative=false` and no `alt`; `Dialog` with `showHeader:false` and no `ariaLabelledBy` | `references/labeling.md` |
+| 3 | Heading levels | `<Title>` without explicit `level`; heading level jumps (e.g. H1 → H3) within a view | `references/heading.md` |
+| 4 | Focus & keyboard | `Dialog` or `Popover` without `initialFocus` when a specific starting element is required; larger composite areas that act as distinct logical regions and need a `sap-ui-fastnavgroup` `CustomData` entry; `tabindex` values greater than 0 in rendered HTML | `references/keyboard.md` |
+| 5 | Keyboard shortcuts | Action buttons (save, delete, etc.) using plain `press=".onX"` that should support keyboard shortcuts but have no `CommandExecution` | `references/shortcut.md` |
+| 6 | Invisible messaging | Dynamic state changes (save confirmations, errors, filter results) that are visible-only with no `InvisibleMessage.announce()` call in the handler | `references/invisible-message.md` |
+| 7 | Reading order | Controls visually reordered via CSS/layout but out of sequence in XML; `ariaDescribedBy` pointing to IDs that appear later in the DOM | `references/reading-order.md` |
+| 8 | Target size | `Link`, `ObjectIdentifier`, `ObjectStatus`, `ObjectNumber`, `ObjectMarker`, `ObjectAttribute` inside an interactive container without `reactiveAreaMode`; or in other dense layout without spacing | `references/target-size.md` |
+
+## Step 3 — Report
+
+For each gap found:
+
+**Issue**: one line — names the control and the missing property/association
+**Impact**: `critical` (blocks AT users entirely) | `serious` (significant barrier) | `moderate` (partial barrier) | `minor` (best practice, low direct impact)
+**Why**: one sentence on user impact
+**Fix**: minimal corrected XML or JS snippet (only the changed part)
+
+Group findings by topic, critical/serious first within each group. End with a summary count by impact level.
+If no gaps are found, say so.

plugins/ui5/skills/ui5-best-practices-accessibility/references/heading.md

@@ -0,0 +1,77 @@
+# Heading Levels
+
+Heading hierarchy lets screen reader users scan the page structure and jump between
+sections. Missing or skipped heading levels break this navigation.
+
+**Rule: every `<Title>` used as a heading must have an explicit `level` property set.**
+
+**Wrong:**
+```xml
+<Title text="{i18n>orderDetailsTitle}"/>
+```
+
+**Correct:**
+```xml
+<Title level="H1" text="{i18n>orderDetailsTitle}"/>    <!-- page title -->
+<Title level="H2" text="{i18n>lineItemsTitle}"/>       <!-- section header -->
+<Title level="H3" text="{i18n>itemNotesTitle}"/>       <!-- subsection -->
+```
+
+## Heading hierarchy rules
+
+- Each page should have exactly one `H1` — the page title.
+- Section headers = `H2`, subsection headers = `H3`, and so on.
+- **Never skip levels** — H1 → H3 with no H2 breaks the document outline and
+  confuses AT users navigating by heading.
+
+## `sap.m.Dialog` heading level
+
+When using the `title` property, the framework renders it as `<h1>` automatically — no extra configuration needed. When using `customHeader` or `showHeader: false`, set `level: TitleLevel.H1` explicitly on the `Title` control.
+
+**Wrong:**
+```xml
+<Dialog>
+  <customHeader>
+    <Toolbar>
+      <Title id="dlgTitle" text="{i18n>confirmDeletionTitle}"/>
+    </Toolbar>
+  </customHeader>
+</Dialog>
+```
+
+**Correct:**
+```xml
+<Dialog ariaLabelledBy="dlgTitle">
+  <customHeader>
+    <Toolbar>
+      <Title id="dlgTitle" text="{i18n>confirmDeletionTitle}" level="H1"/>
+    </Toolbar>
+  </customHeader>
+</Dialog>
+```
+
+## `sap.m.Panel` heading level
+
+A `Panel` with `headerText` renders that text as a heading. If the heading level needs
+to be explicitly controlled, replace `headerText` with a `headerToolbar` aggregation
+containing a `Title` with an explicit `level`:
+
+```xml
+<Panel accessibleRole="Region">
+  <headerToolbar>
+    <Toolbar>
+      <Title level="H3" text="{i18n>shippingDetailsTitle}"/>
+    </Toolbar>
+  </headerToolbar>
+  ...
+</Panel>
+```
+
+## Available values
+
+`H1` · `H2` · `H3` · `H4` · `H5` · `H6` · `Auto` (avoid — use explicit levels)
+
+## i18n bindings
+
+All snippets above use `{i18n>...}` for user-facing strings — bind every UI text to
+the resource model, never hard-code English literals in the view.

plugins/ui5/skills/ui5-best-practices-accessibility/references/invisible-message.md

@@ -0,0 +1,71 @@
+# Invisible Messaging
+
+Use `sap.ui.core.InvisibleMessage` to announce dynamic state changes to screen reader
+users who would otherwise miss purely visual updates (badge counts, success banners,
+loading indicators, filter results).
+
+All announcement text and static labels below are pulled from the i18n resource
+bundle — bind every UI text to the resource model, never hard-code English literals.
+
+## When not to use
+
+- Do not provide information exclusively for AT users — screen reader users should not receive content that sighted users cannot access
+- Do not use it to hide long texts — if the information matters, show it
+
+## Dynamic announcements — `InvisibleMessage`
+
+```js
+sap.ui.define([
+  "sap/ui/core/mvc/Controller",
+  "sap/ui/core/InvisibleMessage",
+  "sap/ui/core/library"
+], function(Controller, InvisibleMessage, library) {
+  "use strict";
+
+  var InvisibleMessageMode = library.InvisibleMessageMode;
+
+  return Controller.extend("my.app.Controller", {
+    onInit: function () {
+      this.oIM = InvisibleMessage.getInstance();
+      this.oResourceBundle = this.getOwnerComponent()
+        .getModel("i18n")
+        .getResourceBundle();
+    },
+
+    onDeleteItems: function (iCount) {
+      // ... perform deletion ...
+      this.oIM.announce(
+        this.oResourceBundle.getText("itemsDeletedAnnouncement", [iCount]),
+        InvisibleMessageMode.Polite
+      );
+    },
+
+    onSubmitError: function () {
+      // ... handle error ...
+      this.oIM.announce(
+        this.oResourceBundle.getText("submissionFailedAnnouncement"),
+        InvisibleMessageMode.Assertive
+      );
+    }
+  });
+});
+```
+
+| Mode | Behavior | When to use |
+|---|---|---|
+| `Polite` | Waits for a pause in current speech | Status updates, counts, non-urgent feedback |
+| `Assertive` | Interrupts current speech immediately | Errors, warnings, critical state changes |
+
+## Static ARIA references — `core:InvisibleText`
+
+Use when you need a hidden text node that other controls reference via `ariaLabelledBy`
+or `ariaDescribedBy`, and a visible `<Label>` is not suitable:
+
+```xml
+<core:InvisibleText id="postalLabel" text="{i18n>postalCodeLabel}"/>
+<core:InvisibleText id="cityLabel"   text="{i18n>cityLabel}"/>
+<Input ariaLabelledBy="postalLabel" value="{addr>/postalCode}" fieldWidth="35%"/>
+<Input ariaLabelledBy="cityLabel"   value="{addr>/city}"       fieldWidth="35%"/>
+```
+
+Place `InvisibleText` nodes **before** the controls that reference them.

plugins/ui5/skills/ui5-best-practices-accessibility/references/keyboard.md

@@ -0,0 +1,71 @@
+# Focus Handling and Keyboard Navigation
+
+## Initial focus — `initialFocus`
+
+When a Dialog or Popover opens, set which element receives focus. Without this, focus lands
+on the first focusable element, which may not be the right starting point for the task.
+
+```xml
+<Popover title="{i18n>productDetailsTitle}" initialFocus="firstActionBtn">
+  <content>
+    <VBox>
+      <Text text="{i18n>notebookProductName}"/>
+      <Button id="firstActionBtn" text="{i18n>addToCartButton}"/>
+    </VBox>
+  </content>
+</Popover>
+```
+
+Same attribute on `<Dialog initialFocus="elementId">`.
+
+All user-facing strings above are bound via `{i18n>...}` — bind every UI text to the
+resource model, never hard-code English literals in the view.
+
+## F6 fast navigation
+
+F6 / Shift+F6 lets users jump between logical groups. Some standard containers create
+F6 groups automatically — for example, `sap.m.Panel` (the whole panel is one group)
+and `sap.uxap.ObjectPageSection` (each section is a separate group).
+
+**Adding or removing a custom area from the F6 chain**
+
+Standard containers create their own F6 groups automatically. Groups can also be nested —
+pressing F6 inside a nested group moves focus to the next group at that level; if none
+exists, focus moves up to the parent group.
+
+To add a custom area as an F6 group, use the `sap-ui-fastnavgroup` key via `CustomData`:
+
+```xml
+<!-- XML view -->
+<VBox>
+  <customData>
+    <core:CustomData key="sap-ui-fastnavgroup" value="true" writeToDom="true"/>
+  </customData>
+</VBox>
+```
+
+```js
+// Controller / JS
+oControl.data("sap-ui-fastnavgroup", "true", true /* writeToDom */);
+```
+
+To remove a group that a control defines by default, set the value to `"false"`:
+
+```js
+oControl.data("sap-ui-fastnavgroup", "false", true /* writeToDom */);
+```
+
+## Custom interactive elements — `tabindex`
+
+Native HTML elements (button, input, a) are focusable by default. Custom elements
+rendered with a non-interactive tag need explicit `tabindex`:
+
+```html
+<!-- Focusable custom widget -->
+<div role="combobox" tabindex="0" ...> ... </div>
+
+<!-- Remove from tab order but keep programmatically focusable -->
+<div tabindex="-1" ...> ... </div>
+```
+
+Avoid `tabindex` values greater than 0 — they override the natural reading order.