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,50 @@
+# 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 5,000 rows). 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 both the SAPUI5 class and the `ui5-*` web component tag.
+- **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 5,000 rows?"
+- "Which control for a brief success confirmation?" (→ MessageToast)
+
+## 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 |
+| `ui-inputs.md` | Inputs, selects, combo/multi, pickers, filter bar, value help |
+| `ui-containers.md` | Cards, dialog, popover, shell bar, toolbars, user menu |
+| `ui-navigation.md` | Icon tab bar, tab container, side nav, shell search, breadcrumbs |
+| `ui-lists-tables.md` | Responsive / Grid / Analytical / Tree table, Grid List, List |
+| `ui-display.md` | Avatar, progress, busy, illustrated message |
+| `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 |
+
+## 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. Component tags verified against `ui5.sap.com`,
+`sap.github.io/ui5-webcomponents`, and the UI5 Web Components MCP server.

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

@@ -0,0 +1,66 @@
+# 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/` | Often 403s automated fetches | Human reference for design rules, when-to-use |
+| SAPUI5 API | `ui5.sap.com/` | Yes | Verifying `sap.*` class names, deprecations |
+| UI5 Web Components | `sap.github.io/ui5-webcomponents/` | Yes | Verifying `ui5-*` tags, slots, properties |
+| Theming tokens | `github.com/SAP/theming-base-content` | Yes (raw.githubusercontent.com) | CSS token names + values |
+| UI5 Web Components MCP server | local MCP (`get_component_api`, `get_doc`, `list_docs`) | Yes | Fastest tag/API verification + V2→V3 migration/deprecations |
+
+The design portal blocks scrapers; treat it as a human-read source. Everything machine-checkable
+(control names, tags, tokens) comes from the API sources and the MCP server.
+
+## 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 `ui5-*` tag, calls MCP `get_component_api`
+   to confirm it still exists and its package hasn't moved. For tokens, fetches
+   `theming-base-content`. For `sap.*` classes, checks `ui5.sap.com`.
+3. Diffs live vs current and **reports** — new/renamed/deprecated controls, changed tags or
+   packages, 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/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.
+
+## Invariants every refresh must preserve
+
+- Decision-first contract per section: **SAPUI5 + Web Component identifiers · Use when · Do NOT use when → alternative · Rules · Gotchas.** No anatomy, no state prose.
+- Every control names both framework identifiers, or explicitly states "none" when one doesn't exist.
+- 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 an identifier (spot-check)
+grep -rnE '`sap\.|`ui5-' references/ui-*.md | head
+
+# 3. SKILL.md budget
+wc -l SKILL.md   # target < 200
+```
+- For each `ui5-*` tag referenced anywhere, confirm via MCP `get_component_api` that it resolves
+  (this catches invented tags like the non-existent `ui5-menu-button`).
+- 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 5000 rows", "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,80 @@
+---
+name: ui5-fiori-guidelines
+description: Picks the correct SAP Fiori / UI5 control for a use case and prevents the usage of the wrong one. Use when choosing between UI5 controls, building or reviewing code with sap.m.*, sap.f.*, sap.uxap.*, sap.ui.table.*, or ui5-* web components (XML views, fragments, controllers, manifest.json). Catches the classic wrong-component mistakes that cause false usage, for example: sap.m.Bar used as a navigation bar / app header (use sap.f.ShellBar), a List used as side navigation (use sap.f.SideNavigation), a responsive sap.m.Table used for large or aggregated data (use sap.ui.table.Table / AnalyticalTable), a Dialog used for a plain error (use MessageBox or MessageStrip), a Page used 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 frameworks, two names for the same component. Always give both:
+- **SAPUI5** — `sap.m.*`, `sap.f.*`, `sap.uxap.*`, `sap.ui.table.*` (XML views, S/4HANA, Fiori Elements).
+- **UI5 Web Components** — `ui5-*` (React/Vue/Angular, framework-agnostic).
+
+Not every control exists in both. Where it doesn't, say so — don't invent a tag.
+
+## Wrong → Right
+
+| Developer says / writes | WRONG | RIGHT (SAPUI5 · Web Component) | Why |
+|---|---|---|---|
+| "navigation bar", "app header", "top bar" | `sap.m.Bar` | `sap.f.ShellBar` · `ui5-shellbar` | Bar is a generic toolbar container; ShellBar is the app-level header (logo, search, notifications, profile, Joule). |
+| "side menu", "left navigation" | `sap.m.List` | `sap.f.SideNavigation` · `ui5-side-navigation` | List has no nav semantics, no expand/collapse, no selection state. WC must sit in `ui5-navigation-layout`. |
+| "tabs on a page", "sections" | `sap.m.TabContainer` | `sap.m.IconTabBar` · `ui5-tabcontainer` | TabContainer is for editable multi-document (like browser 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` · (no WC) | ObjectPage provides the standard header + anchored sections; Bar/Page don't compose with it. |
+| "error popup", "confirmation dialog" | hand-built `sap.m.Dialog` | `sap.m.MessageBox` · `ui5-dialog` + `ui5-message-strip` | MessageBox gives semantic types (Error/Warning/Success/Confirm) and buttons for free. |
+| "inline error / warning banner" | `sap.m.Dialog` / `MessageBox` | `sap.m.MessageStrip` · `ui5-message-strip` | Dialogs interrupt; strips are non-blocking, stay on the page. |
+| "brief success confirmation" | `sap.m.MessageStrip` / `Dialog` | `sap.m.MessageToast` · (no WC — use `ui5-toast`) | Toast auto-dismisses; a strip persists and clutters. |
+| "many validation errors at once" | repeated `MessageStrip` | `sap.m.MessagePopover` · (no direct WC) | One entry point, grouped by severity, navigable. |
+| "big data table", "needs totals/subtotals" | `sap.m.Table` | `sap.ui.table.AnalyticalTable` · (no WC) | Responsive table has no aggregation/freeze and degrades past ~200 rows. |
+| "grid table with thousands of rows" | `sap.m.Table` | `sap.ui.table.Table` · (no WC — `ui5-table` ≠ grid table) | `ui5-table` is popin-capable but not a grid/analytical replacement. |
+| "hierarchy / tree" | grouped `AnalyticalTable` | `sap.ui.table.TreeTable` · (no WC) | Grouping clusters by value; TreeTable models real parent-child nodes. |
+| "master–detail", "list + details side by side" | nested routes / custom CSS columns | `sap.f.FlexibleColumnLayout` · (no WC) | FCL handles column transitions, breakpoints, and back nav. |
+| "object detail page" | `sap.m.Page` | `sap.uxap.ObjectPageLayout` · (no WC) | Page has no anchored section navigation. |
+| "menu button / split button (WC)" | `ui5-menu-button` | `ui5-button` + `ui5-menu` · `sap.m.MenuButton` | No standalone `ui5-menu-button` exists. |
+| "secondary button (WC)" | `design="Ghost"` | `design="Transparent"` · `sap.m.Button type="Transparent"` | `Ghost` is legacy SAPUI5-only; WC has no Ghost design. |
+| "on/off setting" | `sap.m.CheckBox` for immediate effect | `sap.m.Switch` · `ui5-switch` | Switch = immediate effect; CheckBox = confirmed-on-save. |
+| "pick one from a long list" | `sap.m.Select` | `sap.m.ComboBox` / value help · `ui5-combobox` | Select is for short fixed lists (~2–12); ComboBox filters/free-texts. |
+| "pick a date" | `sap.m.Input` | `sap.m.DatePicker` · `ui5-date-picker` | Input has no calendar, parsing, or validation. |
+
+## Use case → Component
+
+| I need to… | Use (SAPUI5 · WC) | NOT |
+|---|---|---|
+| App-level nav: logo, search, notifications, profile | `sap.f.ShellBar` · `ui5-shellbar` | Bar, Toolbar |
+| Left-hand navigation menu | `sap.f.SideNavigation` · `ui5-side-navigation` | List, VerticalLayout |
+| Navigate between facets of one object | `sap.m.IconTabBar` · `ui5-tabcontainer` | TabContainer, SegmentedButton |
+| Switch a small set of views (2–3) | `sap.m.SegmentedButton` · `ui5-segmented-button` | RadioButtonGroup, Select |
+| Persistent page-level error/warning | `sap.m.MessageStrip` · `ui5-message-strip` | MessageBox, Dialog |
+| One-time success confirmation | `sap.m.MessageToast` · `ui5-toast` | MessageStrip, Dialog |
+| Show entity details (header + sections) | `sap.uxap.ObjectPageLayout` | Page, Panel |
+| List → detail split layout | `sap.f.FlexibleColumnLayout` | custom columns |
+| Empty / no-data / error state | `sap.m.IllustratedMessage` · `ui5-illustrated-message` | plain Text/Label |
+| Contextual detail without leaving page | `sap.m.Popover` · `ui5-popover` | Dialog (that's modal) |
+| Personalize 20+ table columns | `sap.m.p13n.Popup` · (no WC) | 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 | `references/ui-actions.md` | Choosing an action control |
+| Inputs, selects, combo/multi, pickers, filter bar | `references/ui-inputs.md` | Form/input/filter design |
+| Containers: cards, dialog, popover, shell bar, toolbars | `references/ui-containers.md` | Overlays, cards, shell structure |
+| Navigation: icon tab bar, side nav, shell search | `references/ui-navigation.md` | Tab/section/side navigation |
+| Tables and lists (Responsive/Grid/Analytical/Tree/List) | `references/ui-lists-tables.md` | Choosing a table or list |
+| Avatar, 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` | Reviewing a built app |
+
+## 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 rows → Responsive; large/desktop → Grid; totals → Analytical; hierarchy → Tree.
+- **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.