feat(ui5): Add SAP Fiori guidelines skill

plugins/ui5/README.md

@@ -108,6 +108,17 @@ Authoritative development guidelines for all UI5 table controls (SAPUI5 1.136+ L
 - **Personalization** - `sap.m.p13n.Engine` integration
 - **Cell templates & alignment** - Type-based alignment and model type namespace rules
 
+#### ui5-fiori-guidelines
+
+Picks the correct SAP Fiori / UI5 control for a use case — and stops the wrong one — giving both the SAPUI5 class and the `ui5-*` web component tag:
+
+- **Wrong → Right mapping** - The exact wrong control mapped to the right one (e.g. `sap.m.Bar` used as an app header → `sap.f.ShellBar` / `ui5-shellbar`)
+- **Use-case → Component map** - "App-level navigation" → `ShellBar`; "list → detail split" → `FlexibleColumnLayout`
+- **Table selection by data, not looks** - Responsive vs Grid vs Analytical vs Tree, and when a responsive table degrades
+- **Decision-first reference files** - Per control: when to use, when NOT (with the alternative), machine-checkable rules, gotchas — across actions, inputs, containers, navigation, lists/tables, display, messages, AI, and upload
+- **Critical one-liners** - One emphasized button per page, icon-only buttons need a tooltip, links navigate / buttons act, Popover is non-modal / Dialog is modal
+- **Maintenance** - `REFRESH.md` documents an agent-driven re-sync against SAP sources with human review (no unattended writes)
+
 ---
 
 ## Installation

plugins/ui5/skills/ui5-fiori-guidelines/README.md

@@ -0,0 +1,61 @@
+# SAP Fiori Component Selection Skill
+
+Picks the correct SAP Fiori / UI5 control for a use case — and stops the wrong one (a `sap.m.Bar` used as an
+app header, a responsive table used for large and complex data). This skill catches those before the code ships.
+
+Built for AI coding assistants working alongside application developers.
+
+## What it does
+
+- **Wrong → Right mapping.** The exact wrong control → the correct one, with the `sap.*` class and OpenUI5 / SAPUI5 availability.
+- **Use-case → Component map.** "I need to show app navigation" → `ShellBar`, not `Bar`.
+- **Decision-first reference files.** Every component: when to use, when NOT (with the alternative), machine-checkable rules, gotchas. No anatomy, no fluff.
+
+## Usage
+
+Starts automatically on SAP Fiori / UI5 questions and on code containing UI5 control names. Example triggers:
+
+- "How do I build a navigation bar in Fiori?"
+- "I'm using sap.m.Bar for my app header" (→ ShellBar)
+- "Which table should I use for large and complex data?"
+- "Which control for a brief success confirmation?" (→ MessageToast)
+- "Review my Fiori app against the guidelines" (→ review mode, implementation checklist)
+
+## Contents
+
+`SKILL.md` is the router: Wrong→Right table, Use-case→Component map, reference routing, critical one-liners.
+
+| Reference file | Topic |
+|---|---|
+| `component-selection.md` | Full wrong→right + table-type decision + long tail |
+| `theming-tokens.md` | CSS tokens, semantic colors, density tiers |
+| `ui-actions.md` | Buttons, links, toggle/segmented/menu buttons, menu, table toolbar |
+| `ui-inputs.md` | Inputs, selects, combo/multi, pickers, mask, filter bar, facet filter, value help |
+| `ui-layouts.md` | Dynamic page, flexible column layout, side panel, app / nav container |
+| `ui-containers.md` | Cards, dialog, popover, quick view, color palette, P13n, variant management |
+| `ui-navigation.md` | Shell bar, user menu, product switch, icon tab bar, tab container, side nav, shell search, breadcrumbs |
+| `ui-lists-tables.md` | Responsive / Grid / Analytical / Tree table, Grid List, List, pull to refresh |
+| `ui-display.md` | Avatar, progress, busy, illustrated message, carousel, tag, generic tag, expandable text, image, draft indicator |
+| `ui-messages.md` | Message strip / box / toast / popover |
+| `ui-ai.md` | AI button, guided/quick prompts, regenerate, local AI notice |
+| `ui-upload.md` | File Uploader vs Upload Set |
+| `implementation-checklist.md` | Code-review checklist for a built app (review mode) |
+
+## Tests
+
+`tests/eval.json` holds manual evaluation cases: control-selection prompts, reference-dispatch checks,
+and review-mode fixtures under `tests/fixtures/`. See `tests/README.md`.
+
+## Maintenance
+
+`REFRESH.md` documents the repeatable, agent-driven process to re-sync against latest SAP sources
+(diff + human review, no unattended writes).
+
+## Version
+
+Source: SAP Fiori Design Guidelines (`sap.com/design-system/fiori-design-web/`). Control names verified against `ui5.sap.com`.
+
+| Area | Guideline version | UI5 API version | Refreshed |
+|---|---|---|---|
+| Button (`ui-actions.md` Button + Split Button) | v1.151 | 1.153.0 | 2026-10-21 |
+| Everything else | not stamped (pre-refresh snapshot) | — | — |

plugins/ui5/skills/ui5-fiori-guidelines/REFRESH.md

@@ -0,0 +1,91 @@
+# Refreshing this skill
+
+The skill is a snapshot of SAP Fiori guidelines + UI5 APIs. Sources change. This is the repeatable
+process to re-sync it and keep it up to date. **No unattended writes** — the process reports drift and proposes edits; a
+human reviews and applies.
+
+## Authoritative sources
+
+| Source | URL | Reachable? | Use for |
+|---|---|---|---|
+| Fiori Design Guidelines | `sap.com/design-system/fiori-design-web/` | Yes, via versioned `.plain.html` (below) | Design rules, when-to-use |
+| SAPUI5 / OpenUI5 API | `ui5.sap.com/` | Yes | Verifying `sap.*` class names, deprecations, OpenUI5 library membership |
+| Theming tokens | `github.com/SAP/theming-base-content` | Yes (raw.githubusercontent.com) | CSS token names + values |
+
+### Fetching the design guidelines
+
+The portal is client-rendered, but each page's content is served as a static HTML fragment:
+
+```bash
+B=https://www.sap.com/design-system/fiori-design-web
+curl -sS "$B/v1-151/ui-elements/button/usage.plain.html"   # guideline body (When to Use, Types, Guidelines…)
+curl -sS "$B/v1-151/ui-elements/button.plain.html"         # hero: title + sap.* classes
+```
+
+- **Use a versioned path.** Unversioned URLs (`$B/ui-elements/button/`) return 404. Versions are published
+  every third release (`v1-136`, `v1-139`, … `v1-151`); find the newest by probing upward until 404.
+- **Headers.** Plain `curl` works. A browser `User-Agent` *without* an `Accept` header gets a 403 from the
+  bot filter; send `Accept: text/html` with it. `WebFetch`-style tools hit the unversioned URL and fail.
+- **Slug** = the control name in kebab case (`menu-button`, `segmented-button`, `upload-set`). Links inside a
+  page point to sibling slugs.
+- **Strip before use.** Content contains `[internal_only]…[/internal_only]` blocks and links to
+  `wiki.one.int.sap` / `wiki.wdf.sap.corp` — drop both (internal SAP material). Keep `[external_only]` text.
+- **API JSON** for step 2: `ui5.sap.com/test-resources/<lib path>/designtime/apiref/api.json`
+  (e.g. `sap/m`, `sap/ui/core`); current version at `ui5.sap.com/resources/sap-ui-version.json`.
+
+## Refresh process (agent-driven diff + review)
+
+Run one agent per file group so context stays scoped. Each agent:
+1. Reads its current reference file(s).
+2. Fetches the matching live source(s) above. For every `sap.*` class, checks `ui5.sap.com` for
+   existence, deprecation, and whether the library is part of OpenUI5 or SAPUI5-only. For tokens, fetches
+   `theming-base-content`.
+3. Diffs live vs current and **reports** — new/renamed/deprecated controls, changed token values,
+   new wrong-component pitfalls, dead links — plus a proposed edit list. It does **not** write.
+4. A human reviews the report and applies edits.
+
+File groups: `ui-actions/inputs/navigation` · `ui-containers/layouts/lists-tables` ·
+`ui-display/messages/ai/upload` ·
+`SKILL.md + component-selection/theming-tokens`.
+
+Can be launched as a Workflow (one agent per group, results collected) or via the Agent tool.
+
+### Scheduled refresh
+
+The Fiori design portal cannot be fetched live while the skill runs, so the skill is maintained as a
+snapshot. To keep it from drifting, run the process above on a schedule — at least once per UI5
+release — for example from a CI job that runs the agents and opens a pull request containing only the
+drift report and proposed edits. The "no unattended writes" rule still applies: a human reviews and
+merges.
+
+## Invariants every refresh must preserve
+
+- Decision-first contract per section: **OpenUI5 / SAPUI5 control · Use when · Do NOT use when → alternative · Rules · Gotchas.** No anatomy, no state prose.
+- Every control names its `sap.*` class and OpenUI5 vs SAPUI5 availability.
+- When a guideline page names a deprecated API, follow the API: recommend the replacement and mention the deprecated name only as a gotcha.
+- A section with no guideline page is marked "API-based, no guideline page" on its control line.
+- SKILL.md body stays a router: Wrong→Right table, Use-case→Component map, routing table, one-liners. Keep it under ~200 lines; keep `description` under ~1,536 chars.
+- Tone: short, concise, no fluff.
+
+## Verification after any refresh
+
+```bash
+# 1. No scrape artifacts or dead/internal links (must return nothing)
+grep -rnE '\+-+x-+\+|:badge|:decline:|:overflow:|:bell:|builder-prospect|ui5\.github\.io|wiki\.one\.int\.sap|&#x[0-9a-f]+;|Section Metadata|external_only' references/ SKILL.md
+
+# 2. Every ui-*.md component section names a sap.* identifier (spot-check)
+grep -rnE '`sap\.' references/ui-*.md | head
+
+# 3. SKILL.md budget
+wc -l SKILL.md   # target < 200
+```
+- For each `sap.*` class, confirm via `ui5.sap.com` that it exists and note OpenUI5 vs SAPUI5 availability.
+- Run the cases in `tests/eval.json` (see `tests/README.md`); add a case for every new control or wrong→right row.
+- Trigger test in a fresh session: "how do I build a navigation bar in Fiori", "I'm using sap.m.Bar
+  for my header", "which table for large and complex data", "design an object page" should each surface the right
+  guidance.
+
+## Version stamping
+
+- Record the SAP Fiori guideline version and refresh date in `README.md`.
+- On material change, bump the version line in `README.md`.

plugins/ui5/skills/ui5-fiori-guidelines/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: ui5-fiori-guidelines
+description: Picks the correct SAP Fiori / UI5 control for a use case and prevents the usage of the wrong one; also reviews built OpenUI5/SAPUI5 apps against the Fiori guidelines. Use when (1) choosing between UI5 controls or planning page and app layout (DynamicPage, FlexibleColumnLayout, ObjectPageLayout, ShellBar, ToolPage, App), or (2) the user asks to review, audit, or check an existing Fiori app, view, or fragment against the Fiori guidelines. Covers sap.m.*, sap.f.*, sap.tnt.*, sap.uxap.*, sap.ui.table.* in XML views, fragments, controllers, and manifest.json. Catches classic wrong-component mistakes, for example sap.m.Bar as app header (use sap.f.ShellBar), List as side navigation (use sap.tnt.SideNavigation), responsive sap.m.Table for large data (use sap.ui.table.Table) or group subtotals (use AnalyticalTable), Dialog for a plain error (use MessageBox or MessageStrip), Page for object details (use sap.uxap.ObjectPageLayout).
+---
+
+# SAP Fiori Component Selection
+
+The job of this skill: pick the right control for the task or plan the correct Fiori application architecture / UX.
+
+## Two modes
+
+- **Select** (default) — the user is choosing a control or planning a layout. Answer from the tables below; open one reference file only when they do not answer it.
+- **Review** — the user asks to review, audit, or check existing code against the Fiori guidelines. Read `references/implementation-checklist.md` and check every item against the code. Report each failing item under its checklist section with the file, the control, and the fix. If nothing fails, reply "No Fiori guideline violations found."
+
+## OpenUI5 vs SAPUI5
+
+OpenUI5 and SAPUI5 share almost all `sap.*` controls. Label availability explicitly:
+- **OpenUI5 / SAPUI5** — `sap.m`, `sap.f`, `sap.tnt`, `sap.uxap`, `sap.ui.table`, `sap.ui.layout`, `sap.ui.unified`, `sap.ui.mdc`, `sap.ui.fl`, `sap.ui.integration`.
+- **SAPUI5** only — `sap.ui.comp.*` (smart controls), `sap.fe.*`, `sap.suite.ui.*`, `sap.ushell.*`.
+
+## Wrong → Right
+
+| Developer says / writes | WRONG | RIGHT | Why |
+|---|---|---|---|
+| "navigation bar", "app header", "top bar" | `sap.m.Bar` | `sap.f.ShellBar` | Bar is a generic toolbar; ShellBar is the app-level header (logo, search, notifications, profile, Joule). |
+| "side menu", "left navigation" | `sap.m.List` | `sap.tnt.SideNavigation` | List has no nav semantics, expand/collapse, or selection state. |
+| "tabs on a page", "sections" | `sap.m.TabContainer` | `sap.m.IconTabBar` | TabContainer is editable multi-document tabs; IconTabBar is in-page section/filter nav. |
+| "header with title + actions on a detail page" | `sap.m.Bar` / `sap.m.Page` | `sap.uxap.ObjectPageLayout` | ObjectPage provides standard header + anchored sections. |
+| "error popup", "confirmation dialog" | hand-built `sap.m.Dialog` | `sap.m.MessageBox` | MessageBox gives semantic types and standard buttons. |
+| "inline error / warning banner" | `sap.m.Dialog` / `MessageBox` | `sap.m.MessageStrip` | Dialogs interrupt; strips are non-blocking. |
+| "brief success confirmation" | `sap.m.MessageStrip` / `Dialog` | `sap.m.MessageToast` | Toast auto-dismisses; a strip persists. |
+| "many validation errors at once" | repeated `MessageStrip` | `sap.m.MessagePopover` | One entry point, grouped by severity. |
+| "big data table", "grid table with thousands of rows" | `sap.m.Table` | `sap.ui.table.Table` | Responsive table degrades past ~200 loaded items; grid table is for large desktop datasets and column comparison. |
+| "subtotals per group", "multilevel grouping" | `sap.m.Table` | `sap.ui.table.AnalyticalTable` (V4: `Table` + `ODataV4Aggregation`) | Responsive table only has footer totals, no group subtotals. A single column total stays in `sap.m.Table`. |
+| "hierarchy / tree" | grouped `AnalyticalTable` | `sap.ui.table.TreeTable` | Grouping clusters by value; TreeTable models parent-child nodes. |
+| "master–detail", "list + details side by side" | nested routes / custom CSS columns / `sap.m.SplitApp` | `sap.f.FlexibleColumnLayout` | FCL handles column transitions, breakpoints, and back nav. |
+| "page with title and collapsible header" | `sap.m.Page` + hand-built header | `sap.f.DynamicPage` | Title stays visible, header snaps on scroll, floating footer. |
+| "app with header and left menu" | custom layout around `SideNavigation` | `sap.tnt.ToolPage` | ToolPage places ShellBar and SideNavigation with correct responsive behavior. |
+| "object detail page" | `sap.m.Page` | `sap.uxap.ObjectPageLayout` | Page has no anchored section navigation. |
+| "menu button" | custom split markup | `sap.m.MenuButton` | Use MenuButton (or split mode) instead of ad-hoc menus. |
+| "secondary button in header/footer toolbar" | `type="Transparent"` | `type="Ghost"` | Ghost gives the guideline's default style there; Transparent is for negative path (Cancel) and the less important buttons in content toolbars. |
+| "on/off setting" | `sap.m.CheckBox` for immediate effect | `sap.m.Switch` | Switch = immediate effect; CheckBox = confirmed-on-save. |
+| "pick one from a long list" | `sap.m.Select` | `sap.m.ComboBox` / value help | Select is for short fixed lists (~2–12). |
+| "pick a date" | `sap.m.Input` | `sap.m.DatePicker` | Input has no calendar, parsing, or validation. |
+
+## Use case → Component
+
+| I need to… | Use | NOT |
+|---|---|---|
+| App-level nav: logo, search, notifications, profile | `sap.f.ShellBar` | Bar, Toolbar |
+| Left-hand navigation menu | `sap.tnt.SideNavigation` | List, VerticalLayout |
+| Navigate between facets of one object | `sap.m.IconTabBar` | TabContainer, SegmentedButton |
+| Switch a small set of views (2–3) | `sap.m.SegmentedButton` | RadioButtonGroup, Select |
+| Persistent page-level error/warning | `sap.m.MessageStrip` | MessageBox, Dialog |
+| One-time success confirmation | `sap.m.MessageToast` | MessageStrip, Dialog |
+| Show entity details (header + sections) | `sap.uxap.ObjectPageLayout` | Page, Panel |
+| List → detail split layout | `sap.f.FlexibleColumnLayout` | custom columns, SplitApp |
+| Page with title, collapsible header, footer | `sap.f.DynamicPage` | Page with custom header |
+| Switch between suite products from the header | `sap.f.ProductSwitch` | Menu, custom popover grid |
+| KPI / situation in a page header | `sap.m.GenericTag` | ObjectStatus, Text |
+| Empty / no-data / error state | `sap.m.IllustratedMessage` | plain Text/Label |
+| Contextual detail without leaving page | `sap.m.Popover` | Dialog (that's modal) |
+| Personalize 20+ table columns | `sap.m.p13n.Popup` | ViewSettingsDialog |
+
+## Reference files — read on demand
+
+| Topic | File | Read when |
+|---|---|---|
+| Full wrong→right + long tail, table-type decision | `references/component-selection.md` | Any control-choice question not fully answered above |
+| CSS tokens, semantic colors, density tiers | `references/theming-tokens.md` | Colors, theming, cozy/compact/condensed |
+| Buttons, links, toggle/segmented/menu buttons, menu, table toolbar | `references/ui-actions.md` | Choosing an action control |
+| Inputs, selects, combo/multi, pickers, mask, filter bar, facet filter | `references/ui-inputs.md` | Form/input/filter design |
+| Layouts: dynamic page, flexible column layout, side panel, app / nav container | `references/ui-layouts.md` | Page structure, list-detail, app root |
+| Containers: cards, panel, wizard, dialog, popover, color palette, P13n, variant management | `references/ui-containers.md` | Overlays, cards, panels, wizards, personalization |
+| Navigation: shell bar, user menu, product switch, icon tab bar, side nav, breadcrumbs | `references/ui-navigation.md` | Shell header, tab/section/side navigation |
+| Tables and lists (Responsive/Grid/Analytical/Tree/List), pull to refresh | `references/ui-lists-tables.md` | Choosing a table or list |
+| Avatar, image, carousel, tags, tokens, rating, draft indicator, progress, busy, illustrated message | `references/ui-display.md` | Status/empty-state display |
+| Message strip / popover / box / toast | `references/ui-messages.md` | Message pattern and placement |
+| AI/Joule: AI button, guided/quick prompts, notice | `references/ui-ai.md` | AI-powered features |
+| Upload (File Uploader vs Upload Set) | `references/ui-upload.md` | File upload |
+| Implementation review checklist | `references/implementation-checklist.md` | Review mode — always read it first |
+
+## Rules that stop the most mistakes
+
+- **One emphasized/primary button per page or dialog.** Everything else is Default/Transparent.
+- **Icon-only buttons need a tooltip** and a recognizable, worldwide-consistent icon metaphor.
+- **App header = ShellBar, never Bar.** Bar is a content-area toolbar.
+- **Button text is an imperative verb** — Save, Edit, Create. Not "OK to save?".
+- **Table choice is by data, not looks:** ≤~200 loaded items → Responsive (footer totals OK); large/desktop → Grid; multilevel grouping + subtotals → Analytical; simple hierarchy → `sap.m.Tree`, deep/large → TreeTable.
+- **Links navigate, buttons act.** Don't use a Button to go to a page or a Link to submit.
+- **Popover is non-modal contextual; Dialog is modal.** Don't use a Popover for anything requiring focus or confirmation.