Skip to content

Commit c34d265

Browse files
dimovpetardimovpetar
committed
docs(ui5): Restructure integration-cards skill for agent efficiency
Reduce word count from ~1058 to ~740 by restructuring prose into compact rules tables. Hoist reference-loading triggers to the top so agents load analytical_chart_types.md and configuration_editor_example.md before working on those areas. Replace section symbols with markdown anchor links, demote the Card Explorer reference to the bottom, and add a "No data to display" symptom callout pointing at the data-placement rule (the most common cause).
1 parent 45c7c6a commit c34d265

1 file changed

Lines changed: 89 additions & 109 deletions

File tree

  • plugins/ui5/skills/integration-cards

‎plugins/ui5/skills/integration-cards/SKILL.md‎

Lines changed: 89 additions & 109 deletions
Original file line numberDiff line numberDiff line change
@@ -5,119 +5,99 @@ description: MUST be loaded before any UI Integration Cards (also called UI5 Int
55

66
# UI Integration Cards Development Guidelines
77

8-
> *This document outlines the fundamental rules and best practices an AI agent must follow when developing or modifying Integration Cards. Adherence to these guidelines is critical for creating modern, maintainable, and performant UI Integration Cards.*
9-
10-
## 1. Coding Guidelines
11-
- **ALWAYS** strive to create declarative Integration Card, such as "Calendar", "List", "Table", "Timeline", "Object" or "Analytical".
12-
- create an Integration Card Extension only in exceptional cases.
13-
- **ALWAYS** create links using the `actions` property.
14-
- **ALWAYS** refer to parameters using correct syntax - `{parameters>/parameterKey/value}`.
15-
- **ALWAYS** perform validation of the integration card as described in [2. Validation](#2-validation).
16-
- **ALWAYS** show a preview of the generated card following the [4. Preview Instructions](#4-preview-instructions).
17-
- **ALWAYS** generate new declarative integration cards using the `create_integration_card` tool.
18-
19-
### 1.1 Data
20-
- **NEVER** modify the provided data under any circumstances.
21-
- **ALWAYS** include the service URL directly in the card manifest when one is supplied.
22-
- **ALWAYS** reference destinations by name when available. Configure the destination in the `sap.card/configuration/destinations/` and reuse it with binding syntax like `{{destinations.destinationName}}`.
23-
- **NEVER** replace destination name with its URL.
24-
- **ALWAYS** place data configuration in: `"sap.card"/data/`
25-
- **NEVER** place data configuration in:
26-
- `"sap.card"/content/data/`
27-
- `"sap.card"/header/data/`
28-
- Data can be provided via:
29-
1. Inline JSON object
30-
2. Network request (HTTP/HTTPS/Destination)
31-
3. Extension method call
32-
- **ALWAYS** verify these paths are correctly set:
33-
- `"sap.card"/data/path` (Primary data path)
34-
- `"sap.card"/content/data/path` (Content-specific path. It overrides the primary data path)
35-
- `"sap.card"/header/data/path` (Header-specific path. It overrides the primary data path)
36-
37-
#### 1.1.1 Data Errors Detection
38-
- Symptom: "No data to display" message appears.
39-
- Cause: Incorrect data configuration or data path in the content incorrectly overrides the primary data path.
40-
- Solution: Verify all rules in [1.1 Data](#11-data) are properly followed.
41-
42-
### 1.2 Internationalization
43-
- **ALWAYS** bind properties that are not bound to the data to the `i18n` model.
44-
45-
### 1.3 Analytical Cards
46-
- **ALWAYS** follow [6. Analytical Cards Coding Guidelines](#6-analytical-cards-coding-guidelines) when developing Analytical cards.
47-
48-
### 1.4 Configuration Editor
49-
- **ALWAYS** follow [5. Configuration Editor](#5-configuration-editor) guidelines when creating or modifying Configuration Editors for Integration Cards.
50-
- **ALWAYS** load [references/configuration_editor_example.md](references/configuration_editor_example.md) whenever a `dt/Configuration.js` file is present in the project, is being created, or is being modified — even if the user did not explicitly mention the Configuration Editor.
51-
52-
## 2. Validation
53-
- **ALWAYS** ensure that `manifest.json` file is valid JSON.
54-
- **ALWAYS** ensure that in `manifest.json` file the property `sap.app/type` is set to `"card"`.
55-
- **ALWAYS** validate the `manifest.json` against the UI5 Manifest schema. Use the `run_manifest_validation` tool to do this.
56-
- **ALWAYS** avoid using deprecated properties in `manifest.json` and elsewhere.
57-
- **NEVER** treat Integration Cards' project as UI5 project, except for cards of type "Component".
58-
59-
## 3. Card Explorer
60-
- The Card Explorer provides detailed documentation for the Integration Cards schema, including descriptions of every property, guidance for integrating cards into hosting environments, configuration editor documentation with examples, and broader best practices. It is available at: https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html
61-
- The Card Explorer sample sources (manifest.json, data.json, etc.) are available in the openui5 GitHub repository: https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples
62-
63-
## 4. Preview Instructions
64-
- If preview of the card must be shown, **ALWAYS** check the card folder for an existing preview file and any accompanying instructions or scripts, and reuse them if available.
65-
* for example, in NodeJS-based projects, search the `package.json` file for `start` or similar script. If such is available, use it
66-
* also search in the `README.md` file.
67-
- If preview instructions are not available, you have to create an HTML page that contains a `ui-integration` card element which references the card manifest. Then serve the HTML page using `http` server.
8+
Rules an agent must follow when creating, modifying, validating, or previewing a UI Integration Card. Adherence is critical for working cards.
9+
10+
## When to load each reference
11+
12+
| 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) |
16+
17+
If the trigger applies, load before producing any output. Do not work from memory.
18+
19+
## 1. Core rules
20+
21+
| 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+
| i18n binding | Bind every non-data, user-visible string to the i18n model. |
28+
| Links | Use the `actions` property; never inline `<a>` or hand-rolled URL handlers. |
29+
| Validate before declaring done | See [3. Validation](#3-validation). |
30+
| Show preview when requested | See [4. Preview](#4-preview). |
31+
| Don't modify provided data | Use it as supplied. |
32+
33+
## 2. Data placement
34+
35+
`sap.card/data/` is the only correct top-level location for the data request.
36+
37+
| Path | Purpose |
38+
|---|---|
39+
| `sap.card/data/path` | Primary data path |
40+
| `sap.card/content/data/path` | Content-specific path; **overrides** the primary path if set |
41+
| `sap.card/header/data/path` | Header-specific path; **overrides** the primary path if set |
42+
43+
Forbidden: putting the request itself under `sap.card/content/data/` or `sap.card/header/data/`.
44+
45+
**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.
46+
47+
## 3. Validation
48+
49+
| Rule | Detail |
50+
|---|---|
51+
| Valid JSON | `manifest.json` must parse. |
52+
| `sap.app/type` | Must be `"card"`. |
53+
| Schema validation | Use `run_manifest_validation` MCP tool. |
54+
| No deprecated properties | In `manifest.json` or elsewhere. |
55+
| Not a UI5 project | Except for `Component`-type cards. |
56+
57+
## 4. Preview
58+
59+
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.
6860

6961
## 5. Configuration Editor
70-
Configuration Editor allows different personas to customize Integration Cards without modifying the manifest file directly.
71-
The following roles/personas are supported:
72-
- Administrator
73-
- Page/Content Administrator
74-
- Translator
75-
76-
The Configuration Editor is implemented through two key components:
77-
78-
1. **Definition file**: Create a `dt/Configuration.js` file that exports a Designtime definition object
79-
2. **Manifest reference**: Reference this definition in the `manifest.json` under the `sap.card/configuration/editor` property
80-
81-
The `dt/Configuration.js` file defines the Configuration Editor's structure by specifying:
82-
- Form layout and field definitions
83-
- Input controls and visualizations
84-
- Validation rules and field relationships
85-
- Grouping and organization of configuration options
86-
87-
When creating or modifying Integration Cards, follow these guidelines for Configuration Editors:
88-
- Assume the role of Administrator persona when designing the Configuration Editor.
89-
- **ALWAYS** ensure that the Configuration Editor reflects the current structure and fields of the `manifest.json`.
90-
- **ALWAYS** make the existing fields in the `manifest.json` configurable via the editor. For example manifest parameters, title, subtitle, icon of the header, etc.
91-
- **ALWAYS** ask the user if they agree to make all fields editable and what other fields should be added.
92-
- **NEVER** add fields to the editor that do not exist in the `manifest.json`.
93-
- **ALWAYS** remove fields from the editor when removing them from the `manifest.json`.
94-
- **ALWAYS** add fields in the Configuration Editor when adding them to the `manifest.json`.
95-
96-
- **ALWAYS** load [references/configuration_editor_example.md](references/configuration_editor_example.md) before creating or modifying a Configuration Editor (i.e. a `dt/Configuration.js` file). It contains a complete example of a `manifest.json` paired with the corresponding `dt/Configuration.js` file.
97-
98-
## 6. Analytical Cards Coding Guidelines
99-
- **ALWAYS** set `sap.card/content/chartType` property.
100-
- **ALWAYS** adjust `sap.card/content/measures`, `sap.card/content/dimensions` and `sap.card/content/feeds` to match the `sap.card/content/chartType` property and data structure. This is critical for proper data display.
101-
- **ALWAYS** use `sap.card/content/chartProperties` to adjust labels, colors, the legend, and other chart aspects.
102-
- **ALWAYS** define each feed with its type (Dimension or Measure), its unique identifier (uid), and the associated values using defined measures and dimensions. Example (for a donut/pie chart):
62+
63+
The editor lets the Administrator, Page/Content Administrator, and Translator personas customise a card without editing `manifest.json` directly.
64+
65+
Two pieces:
66+
1. `dt/Configuration.js` — exports a function that returns `new Designtime({ form: {...} })`.
67+
2. `manifest.json` — references the file at `sap.card/configuration/editor`.
68+
69+
Design as the **Administrator** persona.
70+
71+
| Rule | Detail |
72+
|---|---|
73+
| Mirror the manifest | Editor reflects the current structure and parameters of `manifest.json` exactly. |
74+
| All existing fields editable | Title, subtitle, header icon, parameters — make them configurable. |
75+
| Ask the user | Before deciding which fields to expose, ask: "Make all manifest fields editable? Anything else to add?" |
76+
| No invented fields | Never add an editor field that does not exist in `manifest.json`. |
77+
| Keep in sync | Add to or remove from the editor when adding to or removing from `manifest.json`. |
78+
79+
Load [`references/configuration_editor_example.md`](references/configuration_editor_example.md) for the canonical paired example.
80+
81+
## 6. Analytical cards
82+
83+
Load [`references/analytical_chart_types.md`](references/analytical_chart_types.md) for the full chart-type catalog (UIDs and per-type examples).
84+
85+
| Rule | Detail |
86+
|---|---|
87+
| Set `chartType` | `sap.card/content/chartType` is required. |
88+
| Match feeds to chart type | `measures`, `dimensions`, and `feeds` must match the UIDs the chart type expects. The reference file lists them per chart. |
89+
| Each feed needs three keys | `type` (`Dimension`\|`Measure`), `uid`, `values`. |
90+
| `chartProperties` | Use it for labels, colours, legend, etc. Do not invent keys. Omit entirely if defaults are fine. |
91+
92+
Minimal feeds example (donut/pie):
10393
```json
10494
"feeds": [
105-
{
106-
"type": "Dimension",
107-
"uid": "color",
108-
"values": [
109-
"Store Name"
110-
]
111-
},
112-
{
113-
"type": "Measure",
114-
"uid": "size",
115-
"values": [
116-
"Revenue"
117-
]
118-
}
95+
{ "type": "Dimension", "uid": "color", "values": ["Store Name"] },
96+
{ "type": "Measure", "uid": "size", "values": ["Revenue"] }
11997
]
12098
```
121-
- **ALWAYS** ensure the `uid` in `feeds` exactly matches the UID required for the selected chartType (e.g., color, size, dataFrame).
12299

123-
- **ALWAYS** load [references/analytical_chart_types.md](references/analytical_chart_types.md) before creating or modifying an Analytical card. It contains the comprehensive list of all supported chart types, their required UIDs, and example configurations.
100+
## 7. Card Explorer (reference)
101+
102+
- Schema docs and live samples: <https://ui5.sap.com/test-resources/sap/ui/integration/demokit/cardExplorer/webapp/index.html>
103+
- Sample sources: <https://github.com/UI5/openui5/tree/master/src/sap.ui.integration/test/sap/ui/integration/demokit/cardExplorer/webapp/samples>

0 commit comments

Comments
 (0)