feat(ui5): Add UI Integration Cards Guidelines as Skills

plugins/ui5/README.md

@@ -12,7 +12,9 @@ Complete SAPUI5 / OpenUI5 plugin for Claude Code with MCP tools, API documentati
 - **Run UI5 linter** - Code quality validation and best practices checks
 - **UI5 tooling integration** - Version info and project management
 
-### 📋 Skills: ui5-best-practices
+### 📋 Skills
+
+#### ui5-best-practices
 
 Development guidelines and coding standards derived from official SAP UI5 guidelines:
 - **Async module loading** - sap.ui.define patterns
@@ -26,6 +28,20 @@ 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-claude/tree/main/plugins/ui5-typescript-conversion) plugin.
 
+#### ui5-best-practices-integration-cards
+
+Development guidelines for UI Integration Cards (also known as UI5 Integration Cards):
+- **Declarative card types** - List, Table, Calendar, Timeline, Object, Analytical
+- **Building a card** - Structure of the declarative `manifest.json` format for a UI Integration Card
+- **Parameter and destination binding** - `{parameters>/key/value}` and `{{destinations.name}}` syntax
+- **Data rules** - Where the data block goes (`sap.card/data`/`content/data`/`header/data`), wrapping URLs in destinations, and requiring JSON responses
+- **Manifest validation** - JSON, schema, and deprecated-property checks before declaring done
+- **Local preview workflow** - Reusing existing entry points or serving via a `<ui-integration-card>` HTML page
+- **Configuration Editor patterns** - `dt/Configuration.js` paired with `manifest.json`, mirroring fields and `manifestpath` targets
+- **Analytical cards** - 44 chart types with required UIDs, feeds, and per-type examples
+- **i18n** - Bind all user-facing strings to the i18n model; never hardcode
+- **Actions** - Use the `actions` property for links and interactions; never inline `<a>` tags or hand-roll URL handlers
+
 ---
 
 ## Installation

plugins/ui5/skills/ui5-best-practices-integration-cards/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: ui5-best-practices-integration-cards
+description: MUST be loaded before any UI Integration Cards (also called UI5 Integration Cards) task — creating, modifying, validating, previewing, or reviewing a card, its `manifest.json`, its Configuration Editor (`dt/Configuration.js`), or any analytical chart configuration. Provides the official guidelines, validation rules, supported chart types, and Configuration Editor patterns.
+---
+
+# Best practices for UI Integration Cards development
+
+Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.
+
+## When to load each reference
+
+| Trigger | Load |
+|---|---|
+| Working on or planning an Analytical card | [`references/analytical_chart_types.md`](references/analytical_chart_types.md) |
+| `dt/Configuration.js` exists, is being created, or is being modified | [`references/configuration_editor_example.md`](references/configuration_editor_example.md) |
+
+If the trigger applies, load before producing any output. Do not work from memory.
+
+## 1. Core rules
+
+| Rule | Detail |
+|---|---|
+| Prefer declarative cards | Types: List, Table, Calendar, Timeline, Object, Analytical. Create an Extension only in exceptional cases. |
+| Use `create_integration_card` MCP tool | When creating a new declarative card. |
+| Parameter binding syntax | `{parameters>/parameterKey/value}` — single braces, `>` separator, `value` suffix. |
+| Destination binding syntax | `{{destinations.destinationName}}` — double braces, dot. Configure under `sap.card/configuration/destinations/`. Reference by name; never replace with raw URL. |
+| Use destinations for service URLs | Wrap every external service URL in a destination under `sap.card/configuration/destinations/` and reference it as `{{destinations.name}}`. |
+| i18n binding | Bind every non-data, user-visible string to the i18n model. |
+| Links | Use the `actions` property; never inline `<a>` or hand-rolled URL handlers. |
+| Validate before declaring done | See [3. Validation](#3-validation). |
+| Show preview when requested | See [4. Preview](#4-preview). |
+| Don't modify provided data | Use it as supplied. |
+| JSON responses only | The endpoint behind `sap.card/data/request` must return JSON. For OData services, append `$format=json` to the request URL or parameters. |
+
+## 2. Data placement
+
+`sap.card/data/` is the only correct top-level location for the data request.
+
+| Path | Purpose |
+|---|---|
+| `sap.card/data/path` | Primary data path |
+| `sap.card/content/data/path` | Content-specific path; **overrides** the primary path if set |
+| `sap.card/header/data/path` | Header-specific path; **overrides** the primary path if set |
+
+Forbidden: putting the request itself under `sap.card/content/data/` or `sap.card/header/data/`.
+
+**Symptom — "No data to display":** typically caused by a `content/data` block that overrides the primary data path. Verify [2. Data placement](#2-data-placement) before debugging anything else.
+
+## 3. Validation
+
+| Rule | Detail |
+|---|---|
+| Valid JSON | `manifest.json` must parse. |
+| `sap.app/type` | Must be `"card"`. |
+| Schema validation | Use `run_manifest_validation` MCP tool. |
+| No deprecated properties | In `manifest.json` or elsewhere. |
+| Not a UI5 project | Except for `Component`-type cards. |
+
+## 4. Preview
+
+If asked to preview, first check the card folder for an existing preview entry point — `package.json` `start` script, `README.md`, or an existing HTML file. Reuse it if present. Otherwise create an HTML page with a `<ui-integration-card>` element pointing at the manifest, and serve via an `http` server.
+
+## 5. Configuration Editor
+
+The editor lets the Administrator, Page/Content Administrator, and Translator personas customize a card without editing `manifest.json` directly.
+
+Two pieces:
+1. `dt/Configuration.js` — exports a function that returns `new Designtime({ form: {...} })`.
+2. `manifest.json` — references the file at `sap.card/configuration/editor`.
+
+Design as the **Administrator** persona.
+
+| Rule | Detail |
+|---|---|
+| Mirror the manifest | Editor reflects the current structure and parameters of `manifest.json` exactly. `manifestpath` can target any existing path — a `configuration/parameters/*/value` for parameterized fields, or a direct path like `/sap.card/header/icon/shape` for static manifest properties. |
+| All existing fields editable | Title, subtitle, header icon, parameters — make them configurable. |
+| Ask the user | Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?" |
+| No invented fields | Never add an editor field that does not exist in `manifest.json`. |
+| Keep in sync | Add to or remove from the editor when adding to or removing from `manifest.json`. |
+
+Load [`references/configuration_editor_example.md`](references/configuration_editor_example.md) for the canonical paired example.
+
+## 6. Analytical cards
+
+Load [`references/analytical_chart_types.md`](references/analytical_chart_types.md) for the full chart-type catalog (UIDs and per-type examples).
+
+| Rule | Detail |
+|---|---|
+| Set `chartType` | `sap.card/content/chartType` is required. |
+| Match feeds to chart type | `measures`, `dimensions`, and `feeds` must match the UIDs the chart type expects. The reference file lists them per chart. |
+| Each feed needs three keys | `type` (`Dimension`\|`Measure`), `uid`, `values`. |
+| `chartProperties` | Use it for labels, colors, legend, etc. Do not invent keys. Omit entirely if defaults are fine. |
+
+Minimal feeds example (donut/pie):
+```json
+"feeds": [
+  { "type": "Dimension", "uid": "color", "values": ["Store Name"] },
+  { "type": "Measure", "uid": "size", "values": ["Revenue"] }
+]
+```
+
+## 7. Card Explorer (reference)
+
+- Schema docs and live samples: <https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html>
+- Sample sources: <https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples>