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 |
dt/Configuration.js exists, is being created, or is being modified |
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. |
| Show preview when requested |
See 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 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:
dt/Configuration.js — exports a function that returns new Designtime({ form: {...} }).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 for the canonical paired example.
6. Analytical cards
Load 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):
"feeds": [
{ "type": "Dimension", "uid": "color", "values": ["Store Name"] },
{ "type": "Measure", "uid": "size", "values": ["Revenue"] }
]
7. Card Explorer (reference)
1---2name: ui5-best-practices-integration-cards3description: 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.4---56# Best practices for UI Integration Cards development78Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.910## When to load each reference1112| Trigger | Load |13|---|---|14| Working on or planning an Analytical card | [`references/analytical_chart_types.md`](references/analytical_chart_types.md) |15| `dt/Configuration.js` exists, is being created, or is being modified | [`references/configuration_editor_example.md`](references/configuration_editor_example.md) |1617If the trigger applies, load before producing any output. Do not work from memory.1819## 1. Core rules2021| Rule | Detail |22|---|---|23| Prefer declarative cards | Types: List, Table, Calendar, Timeline, Object, Analytical. Create an Extension only in exceptional cases. |24| Use `create_integration_card` MCP tool | When creating a new declarative card. |25| Parameter binding syntax | `{parameters>/parameterKey/value}` — single braces, `>` separator, `value` suffix. |26| Destination binding syntax | `{{destinations.destinationName}}` — double braces, dot. Configure under `sap.card/configuration/destinations/`. Reference by name; never replace with raw URL. |27| Use destinations for service URLs | Wrap every external service URL in a destination under `sap.card/configuration/destinations/` and reference it as `{{destinations.name}}`. |28| i18n binding | Bind every non-data, user-visible string to the i18n model. |29| Links | Use the `actions` property; never inline `<a>` or hand-rolled URL handlers. |30| Validate before declaring done | See [3. Validation](#3-validation). |31| Show preview when requested | See [4. Preview](#4-preview). |32| Don't modify provided data | Use it as supplied. |33| 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. |3435## 2. Data placement3637`sap.card/data/` is the only correct top-level location for the data request.3839| Path | Purpose |40|---|---|41| `sap.card/data/path` | Primary data path |42| `sap.card/content/data/path` | Content-specific path; **overrides** the primary path if set |43| `sap.card/header/data/path` | Header-specific path; **overrides** the primary path if set |4445Forbidden: putting the request itself under `sap.card/content/data/` or `sap.card/header/data/`.4647**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.4849## 3. Validation5051| Rule | Detail |52|---|---|53| Valid JSON | `manifest.json` must parse. |54| `sap.app/type` | Must be `"card"`. |55| Schema validation | Use `run_manifest_validation` MCP tool. |56| No deprecated properties | In `manifest.json` or elsewhere. |57| Not a UI5 project | Except for `Component`-type cards. |5859## 4. Preview6061If 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.6263## 5. Configuration Editor6465The editor lets the Administrator, Page/Content Administrator, and Translator personas customize a card without editing `manifest.json` directly.6667Two pieces:681. `dt/Configuration.js` — exports a function that returns `new Designtime({ form: {...} })`.692. `manifest.json` — references the file at `sap.card/configuration/editor`.7071Design as the **Administrator** persona.7273| Rule | Detail |74|---|---|75| 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. |76| All existing fields editable | Title, subtitle, header icon, parameters — make them configurable. |77| Ask the user | Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?" |78| No invented fields | Never add an editor field that does not exist in `manifest.json`. |79| Keep in sync | Add to or remove from the editor when adding to or removing from `manifest.json`. |8081Load [`references/configuration_editor_example.md`](references/configuration_editor_example.md) for the canonical paired example.8283## 6. Analytical cards8485Load [`references/analytical_chart_types.md`](references/analytical_chart_types.md) for the full chart-type catalog (UIDs and per-type examples).8687| Rule | Detail |88|---|---|89| Set `chartType` | `sap.card/content/chartType` is required. |90| Match feeds to chart type | `measures`, `dimensions`, and `feeds` must match the UIDs the chart type expects. The reference file lists them per chart. |91| Each feed needs three keys | `type` (`Dimension`\|`Measure`), `uid`, `values`. |92| `chartProperties` | Use it for labels, colors, legend, etc. Do not invent keys. Omit entirely if defaults are fine. |9394Minimal feeds example (donut/pie):95```json96"feeds": [97 { "type": "Dimension", "uid": "color", "values": ["Store Name"] },98 { "type": "Measure", "uid": "size", "values": ["Revenue"] }99]100```101102## 7. Card Explorer (reference)103104- Schema docs and live samples: <https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html>105- Sample sources: <https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples>
williamcorrea23