feat(ui5): Add UI Integration Cards Guidelines as Skills #51
+2,104
−0
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change | ||||
|---|---|---|---|---|---|---|
| @@ -0,0 +1,105 @@ | ||||||
| --- | ||||||
|
dimovpetar marked this conversation as resolved.
|
||||||
| name: integration-cards | ||||||
|
Member
There was a problem hiding this comment. @dimovpetar @alexandar-mitsev please name the skill ``
Suggested change
Member
There was a problem hiding this comment. Please consider also the folder name of the skill |
||||||
| 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. | ||||||
| --- | ||||||
|
|
||||||
| # UI Integration Cards Development Guidelines | ||||||
|
Member
There was a problem hiding this comment.
Suggested change
|
||||||
|
|
||||||
| 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. | | ||||||
|
|
||||||
|
dimovpetar marked this conversation as resolved.
|
||||||
| ## 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> | ||||||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.