From 71f0c39c968a0efd9a21581163c32c38611f3afb Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Thu, 12 Mar 2026 12:13:05 +0200 Subject: [PATCH 01/15] docs: add AI Tooling page to documentation website Surface the MCP server, llms.txt, AGENTS.md, and AI components package on the docs website so developers can discover AI-assisted development tooling. --- docs/06-AI.md | 89 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 89 insertions(+) create mode 100644 docs/06-AI.md diff --git a/docs/06-AI.md b/docs/06-AI.md new file mode 100644 index 000000000000..824140c01950 --- /dev/null +++ b/docs/06-AI.md @@ -0,0 +1,89 @@ +--- +sidebar_label: AI Tooling +title: AI-Assisted Development +--- + +# AI-Assisted Development + +UI5 Web Components is built for AI-assisted development. Whether you're using an AI coding assistant to build apps or exploring the component library for the first time, we provide first-class tooling to make the experience seamless. + +## MCP Server + +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server gives your AI assistant direct access to UI5 Web Components documentation, component APIs, and integration guides — no copy-pasting needed. + +### Setup + +Add this to your MCP client configuration: + +```json +{ + "mcpServers": { + "@ui5/webcomponents-mcp-server": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@ui5/webcomponents-mcp-server"] + } + } +} +``` + +Or use a one-liner for your tool of choice: + +**VS Code (GitHub Copilot)** +```bash +code --add-mcp '{"name":"@ui5/webcomponents-mcp-server","type":"stdio","command":"npx","args":["-y","@ui5/webcomponents-mcp-server"]}' +``` + +**Claude Code** +```bash +claude mcp add --transport stdio --scope user ui5-webc-mcp-server -- npx -y @ui5/webcomponents-mcp-server +``` + +**Codex** +```bash +codex mcp add --transport stdio ui5-webc-mcp-server -- npx -y @ui5/webcomponents-mcp-server +``` + +### Available Tools + +| Tool | Description | +|------|-------------| +| `get_component_api` | Fetch API docs for any component — properties, slots, events, methods | +| `get_guidelines` | Get integration guides for React, Angular, or vanilla JavaScript | +| `list_docs` | List all available documentation with summaries | +| `get_doc` | Fetch full content of a specific documentation page | + +### Example Prompts + +Once the MCP server is configured, try asking your AI assistant: + +- *"Show me the API for ui5-button"* +- *"How do I use UI5 Web Components with React?"* +- *"Show me the available documentation"* +- *"Get the theming documentation"* + +[View on npm](https://www.npmjs.com/package/@ui5/webcomponents-mcp-server) · [GitHub](https://github.com/UI5/ui5-web-components-mcp-server) + +## llms.txt + +We publish a machine-readable [llms.txt](/llms.txt) file — a structured summary of the entire component library designed for LLM consumption. It includes the component catalog across all packages, documentation links, common usage patterns, and important conventions. + +AI tools that support the `llms.txt` standard can use this file to understand the project without needing the MCP server. + +## AGENTS.md + +The repository includes an [`AGENTS.md`](https://github.com/SAP/ui5-webcomponents/blob/main/AGENTS.md) file — project-level guidance for AI coding assistants. It covers the monorepo structure, build commands, component development rules, testing patterns, and commit conventions. + +AI tools such as Claude Code, GitHub Copilot, and Cursor automatically pick up this file when working inside the repository. + +## AI Components + +UI5 Web Components includes a dedicated package of AI-specific components built for conversational and generative AI interfaces: + +- **AI Button** — Button with AI-specific states and styling +- **AI Input** — Input field tailored for AI interactions +- **AI PromptInput** — Specialized input for prompt-based UIs +- **AI TextArea** — Text area for longer AI content +- **AI Writing Assistant** — Assistant component for writing scenarios + +Explore them in the [AI Components](/components/ai/) section. From 962c3b7c9e6fc265119adde9c44287597da3fdf2 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Thu, 12 Mar 2026 15:13:54 +0200 Subject: [PATCH 02/15] docs: align page title with sidebar label --- docs/06-AI.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/06-AI.md b/docs/06-AI.md index 824140c01950..770d5323acb9 100644 --- a/docs/06-AI.md +++ b/docs/06-AI.md @@ -1,9 +1,9 @@ --- sidebar_label: AI Tooling -title: AI-Assisted Development +title: AI Tooling --- -# AI-Assisted Development +# AI Tooling UI5 Web Components is built for AI-assisted development. Whether you're using an AI coding assistant to build apps or exploring the component library for the first time, we provide first-class tooling to make the experience seamless. From 2351a58a0d99ff39b4bdd611ee138d73596b1b14 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 13 Mar 2026 17:53:02 +0200 Subject: [PATCH 03/15] docs: update --- docs/{06-AI.md => 05-AI.md} | 6 +++--- .../01-development-workflow.md | 0 .../02-conventions-and-guidelines.md | 0 docs/{5-contributing => 6-contributing}/03-DoD.md | 0 docs/{5-contributing => 6-contributing}/04-website.md | 0 docs/{5-contributing => 6-contributing}/README.md | 0 6 files changed, 3 insertions(+), 3 deletions(-) rename docs/{06-AI.md => 05-AI.md} (97%) rename docs/{5-contributing => 6-contributing}/01-development-workflow.md (100%) rename docs/{5-contributing => 6-contributing}/02-conventions-and-guidelines.md (100%) rename docs/{5-contributing => 6-contributing}/03-DoD.md (100%) rename docs/{5-contributing => 6-contributing}/04-website.md (100%) rename docs/{5-contributing => 6-contributing}/README.md (100%) diff --git a/docs/06-AI.md b/docs/05-AI.md similarity index 97% rename from docs/06-AI.md rename to docs/05-AI.md index 770d5323acb9..b788ecaa31a5 100644 --- a/docs/06-AI.md +++ b/docs/05-AI.md @@ -1,9 +1,9 @@ --- -sidebar_label: AI Tooling -title: AI Tooling +sidebar_label: AI Development +title: AI-Assisted Development --- -# AI Tooling +# AI-Assisted Development UI5 Web Components is built for AI-assisted development. Whether you're using an AI coding assistant to build apps or exploring the component library for the first time, we provide first-class tooling to make the experience seamless. diff --git a/docs/5-contributing/01-development-workflow.md b/docs/6-contributing/01-development-workflow.md similarity index 100% rename from docs/5-contributing/01-development-workflow.md rename to docs/6-contributing/01-development-workflow.md diff --git a/docs/5-contributing/02-conventions-and-guidelines.md b/docs/6-contributing/02-conventions-and-guidelines.md similarity index 100% rename from docs/5-contributing/02-conventions-and-guidelines.md rename to docs/6-contributing/02-conventions-and-guidelines.md diff --git a/docs/5-contributing/03-DoD.md b/docs/6-contributing/03-DoD.md similarity index 100% rename from docs/5-contributing/03-DoD.md rename to docs/6-contributing/03-DoD.md diff --git a/docs/5-contributing/04-website.md b/docs/6-contributing/04-website.md similarity index 100% rename from docs/5-contributing/04-website.md rename to docs/6-contributing/04-website.md diff --git a/docs/5-contributing/README.md b/docs/6-contributing/README.md similarity index 100% rename from docs/5-contributing/README.md rename to docs/6-contributing/README.md From aff63b441582a77f61717e7068d406029a316eaf Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 13 Mar 2026 18:37:32 +0200 Subject: [PATCH 04/15] docs: restructure AI docs into CLI, MCP Server, Skills - Split "AI Development" into focused pages: CLI, MCP Server, and Skills - Add CLI page for project scaffolding and component generation - Add Skills page for Agent Skills - Add AI-Ready bullet to Introduction - Add bash/json Prism highlighting - Add styling Agent Skill (SKILL.md) - Renumber sidebar and fix broken links --- docs/04-CLI.md | 112 ++++++++++++++++++ docs/05-AI.md | 89 -------------- docs/05-MCP-Server.md | 71 +++++++++++ docs/06-Skills.md | 48 ++++++++ .../01-package.md | 0 .../02-component.md | 0 .../03-properties.md | 0 .../04-slots.md | 0 .../05-events.md | 0 .../06-lifecycle-hooks.md | 0 .../07-styling.md | 0 .../08-templates.md | 0 .../09-internationalization.md | 0 .../10-testing.md | 0 .../11-deep-dive-and-best-practices.md | 0 .../README.md | 0 .../01-development-workflow.md | 2 +- .../02-conventions-and-guidelines.md | 2 +- .../03-DoD.md | 0 .../04-website.md | 0 .../README.md | 0 .../01-to-version-2.md | 0 .../README.md | 0 docs/{08-Releases.md => 10-Releases.md} | 0 docs/{09-FAQ.md => 11-FAQ.md} | 2 +- docs/2-advanced/08-using-i18n-for-apps.md | 2 +- docs/README.md | 20 ++-- packages/website/docusaurus.config.ts | 1 + skills/styling/SKILL.md | 80 +++++++++++++ 29 files changed, 329 insertions(+), 100 deletions(-) create mode 100644 docs/04-CLI.md delete mode 100644 docs/05-AI.md create mode 100644 docs/05-MCP-Server.md create mode 100644 docs/06-Skills.md rename docs/{4-development => 07-development}/01-package.md (100%) rename docs/{4-development => 07-development}/02-component.md (100%) rename docs/{4-development => 07-development}/03-properties.md (100%) rename docs/{4-development => 07-development}/04-slots.md (100%) rename docs/{4-development => 07-development}/05-events.md (100%) rename docs/{4-development => 07-development}/06-lifecycle-hooks.md (100%) rename docs/{4-development => 07-development}/07-styling.md (100%) rename docs/{4-development => 07-development}/08-templates.md (100%) rename docs/{4-development => 07-development}/09-internationalization.md (100%) rename docs/{4-development => 07-development}/10-testing.md (100%) rename docs/{4-development => 07-development}/11-deep-dive-and-best-practices.md (100%) rename docs/{4-development => 07-development}/README.md (100%) rename docs/{6-contributing => 08-contributing}/01-development-workflow.md (98%) rename docs/{6-contributing => 08-contributing}/02-conventions-and-guidelines.md (98%) rename docs/{6-contributing => 08-contributing}/03-DoD.md (100%) rename docs/{6-contributing => 08-contributing}/04-website.md (100%) rename docs/{6-contributing => 08-contributing}/README.md (100%) rename docs/{6-migration-guides => 09-migration-guides}/01-to-version-2.md (100%) rename docs/{6-migration-guides => 09-migration-guides}/README.md (100%) rename docs/{08-Releases.md => 10-Releases.md} (100%) rename docs/{09-FAQ.md => 11-FAQ.md} (98%) create mode 100644 skills/styling/SKILL.md diff --git a/docs/04-CLI.md b/docs/04-CLI.md new file mode 100644 index 000000000000..49b9b15dbc73 --- /dev/null +++ b/docs/04-CLI.md @@ -0,0 +1,112 @@ +--- +sidebar_label: CLI +title: CLI +--- + +# CLI + +UI5 Web Components provides command-line tools for scaffolding projects and generating components. + +## Create a New Project + +Scaffold a fully configured UI5 Web Components package with a single command: + +```bash +npm create @ui5/webcomponents-package +``` + +This launches an interactive wizard that sets up a ready-to-run TypeScript project with a sample component, theming, i18n, and a dev server. + +### Options + +| Option | Description | Default | +|--------|-------------|---------| +| `--name` | Package name (npm-compatible, supports scopes) | `my-package` | +| `--tag` | Component tag name (e.g., `my-button`) | Derived from class name | +| `--testSetup` | Test setup: `cypress` or `manual` | `manual` | +| `--skip` | Skip interactive prompts and use defaults | `false` | +| `--skipSubfolder` | Create files in current directory instead of a subfolder | `false` | + +### Examples + +**Non-interactive with a custom name** + +```bash +npm create @ui5/webcomponents-package -- \ + --name "my-components" \ + --skip +``` + +**Scoped package with Cypress testing** + +```bash +npm create @ui5/webcomponents-package -- \ + --name "@scope/my-lib" \ + --testSetup "cypress" \ + --skip +``` + +### What Gets Generated + +The scaffolded project includes: + +- A sample **web component** (`MyFirstComponent`) with a template, styles, and i18n +- **Dev server** with hot reload (`npm start`) +- **Build pipeline** for production (`npm run build`) +- **TypeScript** configuration +- **Cypress** test setup (if selected) +- **ESLint** configuration +- **Theming** infrastructure (SAP Horizon) + +After the project is created: + +```bash +cd my-package +npm install +npm start +``` + +## Generate a Component + +Inside a scaffolded project, generate a new web component: + +```bash +npm run create-ui5-element +``` + +This prompts for a PascalCase component name (e.g., `MyButton`) and generates three files: + +| File | Purpose | +|------|---------| +| `src/.ts` | Component class with `@customElement` decorator | +| `src/Template.tsx` | JSX template | +| `src/themes/.css` | Component styles | + +The tag name is derived automatically — `MyButton` becomes `my-my-button` (using the prefix from `.env`). + +You can also pass the name directly: + +```bash +npm run create-ui5-element "MyButton" +``` + +After generating, import the component in `src/bundle.esm.ts`: + +```typescript +import "./MyButton.js"; +``` + +## Project Commands + +Every scaffolded project comes with these commands: + +| Command | Description | +|---------|-------------| +| `npm start` | Start the dev server with hot reload | +| `npm run build` | Production build | +| `npm run create-ui5-element` | Generate a new web component | +| `npm run lint` | Lint the project | +| `npm run clean` | Clean generated and build artifacts | +| `npm test` | Run tests (if Cypress was selected) | + +[View on npm](https://www.npmjs.com/package/@ui5/create-webcomponents-package) · [GitHub](https://github.com/SAP/ui5-webcomponents/tree/main/packages/create-package) diff --git a/docs/05-AI.md b/docs/05-AI.md deleted file mode 100644 index b788ecaa31a5..000000000000 --- a/docs/05-AI.md +++ /dev/null @@ -1,89 +0,0 @@ ---- -sidebar_label: AI Development -title: AI-Assisted Development ---- - -# AI-Assisted Development - -UI5 Web Components is built for AI-assisted development. Whether you're using an AI coding assistant to build apps or exploring the component library for the first time, we provide first-class tooling to make the experience seamless. - -## MCP Server - -The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server gives your AI assistant direct access to UI5 Web Components documentation, component APIs, and integration guides — no copy-pasting needed. - -### Setup - -Add this to your MCP client configuration: - -```json -{ - "mcpServers": { - "@ui5/webcomponents-mcp-server": { - "type": "stdio", - "command": "npx", - "args": ["-y", "@ui5/webcomponents-mcp-server"] - } - } -} -``` - -Or use a one-liner for your tool of choice: - -**VS Code (GitHub Copilot)** -```bash -code --add-mcp '{"name":"@ui5/webcomponents-mcp-server","type":"stdio","command":"npx","args":["-y","@ui5/webcomponents-mcp-server"]}' -``` - -**Claude Code** -```bash -claude mcp add --transport stdio --scope user ui5-webc-mcp-server -- npx -y @ui5/webcomponents-mcp-server -``` - -**Codex** -```bash -codex mcp add --transport stdio ui5-webc-mcp-server -- npx -y @ui5/webcomponents-mcp-server -``` - -### Available Tools - -| Tool | Description | -|------|-------------| -| `get_component_api` | Fetch API docs for any component — properties, slots, events, methods | -| `get_guidelines` | Get integration guides for React, Angular, or vanilla JavaScript | -| `list_docs` | List all available documentation with summaries | -| `get_doc` | Fetch full content of a specific documentation page | - -### Example Prompts - -Once the MCP server is configured, try asking your AI assistant: - -- *"Show me the API for ui5-button"* -- *"How do I use UI5 Web Components with React?"* -- *"Show me the available documentation"* -- *"Get the theming documentation"* - -[View on npm](https://www.npmjs.com/package/@ui5/webcomponents-mcp-server) · [GitHub](https://github.com/UI5/ui5-web-components-mcp-server) - -## llms.txt - -We publish a machine-readable [llms.txt](/llms.txt) file — a structured summary of the entire component library designed for LLM consumption. It includes the component catalog across all packages, documentation links, common usage patterns, and important conventions. - -AI tools that support the `llms.txt` standard can use this file to understand the project without needing the MCP server. - -## AGENTS.md - -The repository includes an [`AGENTS.md`](https://github.com/SAP/ui5-webcomponents/blob/main/AGENTS.md) file — project-level guidance for AI coding assistants. It covers the monorepo structure, build commands, component development rules, testing patterns, and commit conventions. - -AI tools such as Claude Code, GitHub Copilot, and Cursor automatically pick up this file when working inside the repository. - -## AI Components - -UI5 Web Components includes a dedicated package of AI-specific components built for conversational and generative AI interfaces: - -- **AI Button** — Button with AI-specific states and styling -- **AI Input** — Input field tailored for AI interactions -- **AI PromptInput** — Specialized input for prompt-based UIs -- **AI TextArea** — Text area for longer AI content -- **AI Writing Assistant** — Assistant component for writing scenarios - -Explore them in the [AI Components](/components/ai/) section. diff --git a/docs/05-MCP-Server.md b/docs/05-MCP-Server.md new file mode 100644 index 000000000000..b206886b8e4e --- /dev/null +++ b/docs/05-MCP-Server.md @@ -0,0 +1,71 @@ +--- +sidebar_label: MCP Server +title: MCP Server +--- + +# MCP Server + +The [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server gives your AI assistant direct access to UI5 Web Components documentation, component APIs, and integration guides — no copy-pasting needed. + +## Setup + +Add the following entry to your MCP client configuration (e.g. `mcp.json`): + +```json +{ + "mcpServers": { + "@ui5/webcomponents-mcp-server": { + "type": "stdio", + "command": "npx", + "args": ["-y", "@ui5/webcomponents-mcp-server"] + } + } +} +``` + +### One-Click Setup + +**VS Code (GitHub Copilot)** — paste the JSON config above into your `.vscode/mcp.json`, or run: + +```bash +code --add-mcp '{"name":"@ui5/webcomponents-mcp-server","type":"stdio","command":"npx","args":["-y","@ui5/webcomponents-mcp-server"]}' +``` + +**Claude Code** + +```bash +claude mcp add \ + --transport "stdio" \ + --scope "user" \ + "ui5-webc-mcp-server" \ + -- npx -y "@ui5/webcomponents-mcp-server" +``` + +**Codex** + +```bash +codex mcp add \ + --transport "stdio" \ + "ui5-webc-mcp-server" \ + -- npx -y "@ui5/webcomponents-mcp-server" +``` + +## Available Tools + +| Tool | Description | +|------|-------------| +| `get_component_api` | Fetch API docs for any component — properties, slots, events, methods | +| `get_guidelines` | Get integration guides for React, Angular, or vanilla JavaScript | +| `list_docs` | List all available documentation with summaries | +| `get_doc` | Fetch full content of a specific documentation page | + +## Example Prompts + +Once the MCP server is configured, try asking your AI assistant: + +- *"Show me the API for ui5-button"* +- *"How do I use UI5 Web Components with React?"* +- *"Show me the available documentation"* +- *"Get the theming documentation"* + +[View on npm](https://www.npmjs.com/package/@ui5/webcomponents-mcp-server) · [GitHub](https://github.com/UI5/ui5-web-components-mcp-server) diff --git a/docs/06-Skills.md b/docs/06-Skills.md new file mode 100644 index 000000000000..ecc9028f0b50 --- /dev/null +++ b/docs/06-Skills.md @@ -0,0 +1,48 @@ +--- +sidebar_label: Skills +title: Skills +--- + +# Skills + +UI5 Web Components ships [Agent Skills](https://agentskills.io) — portable, structured knowledge files that teach AI coding assistants how to work with the library. Skills provide domain-specific guidance that goes beyond what a general-purpose LLM knows out of the box. + +## Available Skills + +| Skill | Description | +|-------|-------------| +| **styling** | How to customize and style UI5 Web Components — CSS shadow parts, custom states, CSS variables, and tag-level styling | + +## Installation + +Install all UI5 Web Components skills into your project: + +```bash +npx skills add "SAP/ui5-webcomponents" +``` + +This clones the skill files into your project so that AI assistants (Claude Code, Copilot, Cursor, etc.) can pick them up automatically. + +To install a specific skill: + +```bash +npx skills add "SAP/ui5-webcomponents" --skill "styling" +``` + +### Manual Setup + +You can also copy skills directly from the repository's [`skills/`](https://github.com/SAP/ui5-webcomponents/tree/main/skills) directory into your project's `.agents/skills/` folder: + +``` +your-project/ +└── .agents/ + └── skills/ + └── styling/ + └── SKILL.md +``` + +## How Skills Work + +Each skill is a Markdown file (`SKILL.md`) with structured frontmatter (name, description, trigger conditions) and a body containing the actual guidance. When an AI assistant encounters a relevant task — for example, a question about styling a component — it uses the skill's content to provide accurate, project-specific answers instead of generic advice. + +Skills are part of the open [Agent Skills](https://agentskills.io) standard and work across AI tools that support it. diff --git a/docs/4-development/01-package.md b/docs/07-development/01-package.md similarity index 100% rename from docs/4-development/01-package.md rename to docs/07-development/01-package.md diff --git a/docs/4-development/02-component.md b/docs/07-development/02-component.md similarity index 100% rename from docs/4-development/02-component.md rename to docs/07-development/02-component.md diff --git a/docs/4-development/03-properties.md b/docs/07-development/03-properties.md similarity index 100% rename from docs/4-development/03-properties.md rename to docs/07-development/03-properties.md diff --git a/docs/4-development/04-slots.md b/docs/07-development/04-slots.md similarity index 100% rename from docs/4-development/04-slots.md rename to docs/07-development/04-slots.md diff --git a/docs/4-development/05-events.md b/docs/07-development/05-events.md similarity index 100% rename from docs/4-development/05-events.md rename to docs/07-development/05-events.md diff --git a/docs/4-development/06-lifecycle-hooks.md b/docs/07-development/06-lifecycle-hooks.md similarity index 100% rename from docs/4-development/06-lifecycle-hooks.md rename to docs/07-development/06-lifecycle-hooks.md diff --git a/docs/4-development/07-styling.md b/docs/07-development/07-styling.md similarity index 100% rename from docs/4-development/07-styling.md rename to docs/07-development/07-styling.md diff --git a/docs/4-development/08-templates.md b/docs/07-development/08-templates.md similarity index 100% rename from docs/4-development/08-templates.md rename to docs/07-development/08-templates.md diff --git a/docs/4-development/09-internationalization.md b/docs/07-development/09-internationalization.md similarity index 100% rename from docs/4-development/09-internationalization.md rename to docs/07-development/09-internationalization.md diff --git a/docs/4-development/10-testing.md b/docs/07-development/10-testing.md similarity index 100% rename from docs/4-development/10-testing.md rename to docs/07-development/10-testing.md diff --git a/docs/4-development/11-deep-dive-and-best-practices.md b/docs/07-development/11-deep-dive-and-best-practices.md similarity index 100% rename from docs/4-development/11-deep-dive-and-best-practices.md rename to docs/07-development/11-deep-dive-and-best-practices.md diff --git a/docs/4-development/README.md b/docs/07-development/README.md similarity index 100% rename from docs/4-development/README.md rename to docs/07-development/README.md diff --git a/docs/6-contributing/01-development-workflow.md b/docs/08-contributing/01-development-workflow.md similarity index 98% rename from docs/6-contributing/01-development-workflow.md rename to docs/08-contributing/01-development-workflow.md index 5768703d42a1..689f66efcdce 100644 --- a/docs/6-contributing/01-development-workflow.md +++ b/docs/08-contributing/01-development-workflow.md @@ -37,7 +37,7 @@ The server will reload the pages whenever you make changes in the code. **4.1.** Read the dedicated tutorials for component developers: - [Development Conventions and Guidelines](02-conventions-and-guidelines.md); -- [Developing Custom UI5 Web Components](../4-development/01-package.md); +- [Developing Custom UI5 Web Components](../07-development/01-package.md); **4.2.** Create a local branch within your fork and work with it as usual. diff --git a/docs/6-contributing/02-conventions-and-guidelines.md b/docs/08-contributing/02-conventions-and-guidelines.md similarity index 98% rename from docs/6-contributing/02-conventions-and-guidelines.md rename to docs/08-contributing/02-conventions-and-guidelines.md index b7eef50fd70e..8926068273d3 100644 --- a/docs/6-contributing/02-conventions-and-guidelines.md +++ b/docs/08-contributing/02-conventions-and-guidelines.md @@ -6,7 +6,7 @@ You may also find an ESLint integration for your favorite IDE [here](https://esl ## Testing Integration tests are implemented with [Cypress](https://www.cypress.io/). You can run all tests using `npm run test`. -If reasonable, take the time and write a test for the proposed change or fix. Learn more about testing at the [Testing UI5 Web Components page](../4-development/10-testing.md). +If reasonable, take the time and write a test for the proposed change or fix. Learn more about testing at the [Testing UI5 Web Components page](../07-development/10-testing.md). ## Git Guidelines diff --git a/docs/6-contributing/03-DoD.md b/docs/08-contributing/03-DoD.md similarity index 100% rename from docs/6-contributing/03-DoD.md rename to docs/08-contributing/03-DoD.md diff --git a/docs/6-contributing/04-website.md b/docs/08-contributing/04-website.md similarity index 100% rename from docs/6-contributing/04-website.md rename to docs/08-contributing/04-website.md diff --git a/docs/6-contributing/README.md b/docs/08-contributing/README.md similarity index 100% rename from docs/6-contributing/README.md rename to docs/08-contributing/README.md diff --git a/docs/6-migration-guides/01-to-version-2.md b/docs/09-migration-guides/01-to-version-2.md similarity index 100% rename from docs/6-migration-guides/01-to-version-2.md rename to docs/09-migration-guides/01-to-version-2.md diff --git a/docs/6-migration-guides/README.md b/docs/09-migration-guides/README.md similarity index 100% rename from docs/6-migration-guides/README.md rename to docs/09-migration-guides/README.md diff --git a/docs/08-Releases.md b/docs/10-Releases.md similarity index 100% rename from docs/08-Releases.md rename to docs/10-Releases.md diff --git a/docs/09-FAQ.md b/docs/11-FAQ.md similarity index 98% rename from docs/09-FAQ.md rename to docs/11-FAQ.md index 1dcbf08e9e52..c7a1efb38d03 100644 --- a/docs/09-FAQ.md +++ b/docs/11-FAQ.md @@ -27,7 +27,7 @@ sidebar_label: FAQ **Q: Can I create my own UI5 Web Components?** -**A:** Yes, for more information see [Creating a Custom UI5 Web Components Package](4-development/01-package.md) +**A:** Yes, for more information see [Creating a Custom UI5 Web Components Package](07-development/01-package.md) **Q: How can I customize UI5 Web Components' styles?** diff --git a/docs/2-advanced/08-using-i18n-for-apps.md b/docs/2-advanced/08-using-i18n-for-apps.md index 80f3af7e9867..42705daf3ccc 100644 --- a/docs/2-advanced/08-using-i18n-for-apps.md +++ b/docs/2-advanced/08-using-i18n-for-apps.md @@ -10,7 +10,7 @@ None of the code below implies or requires the usage of UI5 Web Components, and The `@ui5/webcomponents-base` package allows the usage of `i18n` functionality not just for UI5 Web Components, but for apps as well. -*Note:* This section is dedicated to apps. For information on how to set up `i18n` for your custom components, please see [Developing Web Components](../4-development/01-package.md). +*Note:* This section is dedicated to apps. For information on how to set up `i18n` for your custom components, please see [Developing Web Components](../07-development/01-package.md). ## Step-by-Step Tutorial diff --git a/docs/README.md b/docs/README.md index 4dc666e155a5..485d714fc03a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -6,17 +6,19 @@ With UI5 Web Components, developers can leverage a powerful, flexible, and futur ## Key Features of UI5 Web Components -- Enterprise-Grade: A comprehensive collection of reusable UI elements that adhere to enterprise standards - accessibility, themeability, i18n and more. +- **Enterprise-Grade:** A comprehensive collection of reusable UI elements that adhere to enterprise standards - accessibility, themeability, i18n and more. -- Framework Agnostic: Fully compatible with any current or future web development frameworks such as React, Angular, and Vue, allowing seamless integration into any tech stack. +- **Framework Agnostic:** Fully compatible with any current or future web development frameworks such as React, Angular, and Vue, allowing seamless integration into any tech stack. -- Elegant: Being custom HTML elements, they hide implementation complexity behind a single HTML tag, making them easily usable with the standard DOM APIs. +- **Elegant:** Being custom HTML elements, they hide implementation complexity behind a single HTML tag, making them easily usable with the standard DOM APIs. -- Consistent User Experience: Implementing the [SAP Fiori design](https://experience.sap.com/fiori-design/) and adhering to the [SAP Fiori Design Guidelines](https://experience.sap.com/fiori-design-web/) ensures a consistent and intuitive user experience across all applications. +- **Consistent User Experience:** Implementing the [SAP Fiori design](https://experience.sap.com/fiori-design/) and adhering to the [SAP Fiori Design Guidelines](https://experience.sap.com/fiori-design-web/) ensures a consistent and intuitive user experience across all applications. -- Open Source: UI5 Web Components is an open-source project available to the general public, inviting developers from all backgrounds to contribute and benefit. +- **Open Source:** UI5 Web Components is an open-source project available to the general public, inviting developers from all backgrounds to contribute and benefit. -- SAP Backing: Developed and maintained by [SAP](https://sap.com) as part of the [UI5](https://openui5.org/) product family, guaranteeing ongoing support and integration with SAP's ecosystem. +- **SAP Backing:** Developed and maintained by [SAP](https://sap.com) as part of the [UI5](https://openui5.org/) product family, guaranteeing ongoing support and integration with SAP's ecosystem. + +- **AI-Ready:** The project is structured for AI-assisted development with an [MCP server](./05-MCP-Server.md) for direct IDE integration, a machine-readable [llms.txt](/llms.txt) file, an [AGENTS.md](https://github.com/SAP/ui5-webcomponents/blob/main/AGENTS.md) guide for coding assistants, installable [Agent Skills](./06-Skills.md), and a dedicated set of [AI components](/components/ai/) for building conversational and generative AI interfaces. ## Ecosystem @@ -27,7 +29,11 @@ UI5 Web Components are complemented by a range of related projects that enhance [UI5 Web Components for React](https://github.com/UI5/webcomponents-react) is a wrapper implementation around UI5 Web Components which makes using them in React even more comfortable. The current version of React (`react 18`) has some shortcomings when it comes to handling Custom Elements, namely the binding of `boolean` attributes as well as adding event listeners to custom event names like `selection-change`. With the help of UI5 Web Components for React, you can use the UI5 Web Components in React as if they were native React components. In addition to that, this library is also offering some complex layout components built on top of UI5 Web Components as well as Charting Components. -**Note:** [React 19](https://react.dev/blog/2024/04/25/react-19) promises to fill all gaps in the web coponents support - the binding of `boolean` attributes and subscribing to custom events. +#### Native Web Components Support in React 19 + +[React 19](https://react.dev/blog/2024/04/25/react-19) introduces full native support for Custom Elements, resolving the long-standing gaps in how React handles web components. Specifically, React 19 correctly binds `boolean` attributes, passes properties (not just attributes) to custom elements, and supports subscribing to custom events. This means you can use UI5 Web Components directly in React 19 without a wrapper library — they work just like any other HTML element. + +The UI5 Web Components for React library remains valuable for its additional features — higher-level layout components, charting components, and TypeScript definitions — but it is no longer required for basic usage. ### UI5 Web Components for Angular diff --git a/packages/website/docusaurus.config.ts b/packages/website/docusaurus.config.ts index cf13e8a57e75..43551c69c5b0 100644 --- a/packages/website/docusaurus.config.ts +++ b/packages/website/docusaurus.config.ts @@ -311,6 +311,7 @@ const config: Config = { prism: { theme: prismThemes.github, darkTheme: prismThemes.dracula, + additionalLanguages: ['bash', 'json'], }, } satisfies Preset.ThemeConfig, }; diff --git a/skills/styling/SKILL.md b/skills/styling/SKILL.md new file mode 100644 index 000000000000..85f2741e47a6 --- /dev/null +++ b/skills/styling/SKILL.md @@ -0,0 +1,80 @@ +--- +name: styling +description: How to customize and style UI5 Web Components. Covers CSS shadow parts, CSS custom states, CSS variables, and tag-level styling. Use when the user asks about changing component appearance, colors, spacing, theming, or overriding styles. +user-invocable: false +--- + +# Styling UI5 Web Components + +UI5 Web Components use Shadow DOM for encapsulation. Styles are isolated — external CSS won't leak in, but customization requires specific techniques. There are four approaches, ordered from most recommended to least. + +## 1. Styles on Tag Level + +Some components (Title, Label, Tag, Button, Input, and others) are designed so that styles set directly on the custom element take effect. + +```css +ui5-input { + width: 150px; + color: yellow; + background: purple; +} +``` + +This works for simpler components. For complex components with deep DOM structures, tag-level styling has no effect on internal elements. + +**Best practice:** Always use tag-level styling for sizing properties (margin, padding, width, height) to avoid design inconsistencies. + +## 2. CSS Shadow Parts + +For complex components, specific internal elements are exposed as [CSS shadow parts](https://developer.mozilla.org/en-US/docs/Web/CSS/::part). + +```css +ui5-card-header::part(status) { + color: red; +} +``` + +**Important:** Available shadow parts are listed in each component's API reference under the "Overview" section. Only documented parts are stable — do not rely on undocumented internal structure. + +## 3. CSS Custom States + +Components can expose custom states via the [CSS custom state pseudo-class](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/:state), allowing you to style based on internal component conditions. + +```css +ui5-toolbar-item:state(overflowed) { + flex-direction: column; +} +``` + +**Important:** Available custom states are listed in each component's API reference under the "Overview" section. + +## 4. Overriding CSS Variables + +UI5 Web Components use SAP CSS variables (`--sap*`) for theming. You can override these on a per-component or per-scope basis. + +```css +ui5-button { + --sapButton_TextColor: purple; +} +``` + +All global SAP CSS variables are defined in [@sap-theming/theming-base-content](https://github.com/SAP/theming-base-content/blob/master/content/Base/baseLib/sap_horizon/css_variables.css). Overriding them changes the appearance of any component that uses them. + +**Best practice:** For broad theme changes, prefer using the UI Theme Designer to ensure consistency. Use direct CSS variable overrides only for targeted, scoped customizations. + +## What NOT to Do + +- **Don't pierce shadow DOM** with deprecated `>>>` or `/deep/` selectors — they don't work. +- **Don't rely on internal DOM structure** — it can change between versions. Only use documented shadow parts. +- **Don't use `!important` on SAP variables** — scope your overrides instead. +- **Don't override raw colors** when a SAP CSS variable exists — use the variable to maintain theme consistency. + +## Quick Decision Guide + +| Goal | Technique | +|------|-----------| +| Change width, margin, padding | Tag-level styles | +| Restyle a specific internal element | `::part(name)` | +| Style based on component state | `:state(name)` | +| Change colors/fonts globally | Override `--sap*` CSS variables | +| Full theme customization | UI Theme Designer | From 5dd73591dec51dd87aecb00cdd8ea3a346c89f20 Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 13 Mar 2026 18:46:48 +0200 Subject: [PATCH 05/15] docs: add NEW badge to MCP Server and Skills, align sidebar badges - Add sidebar-sparkle class for highlighting new doc pages - Align NEW/EXP/DEPR component badges to consistent style - Vertically center all sidebar badges --- docs/05-MCP-Server.md | 1 + docs/06-Skills.md | 1 + packages/website/src/css/custom.css | 55 ++++++++++++++++++++--------- 3 files changed, 41 insertions(+), 16 deletions(-) diff --git a/docs/05-MCP-Server.md b/docs/05-MCP-Server.md index b206886b8e4e..fb8d865b237f 100644 --- a/docs/05-MCP-Server.md +++ b/docs/05-MCP-Server.md @@ -1,5 +1,6 @@ --- sidebar_label: MCP Server +sidebar_class_name: sidebar-sparkle title: MCP Server --- diff --git a/docs/06-Skills.md b/docs/06-Skills.md index ecc9028f0b50..9aa1c54e5f6f 100644 --- a/docs/06-Skills.md +++ b/docs/06-Skills.md @@ -1,5 +1,6 @@ --- sidebar_label: Skills +sidebar_class_name: sidebar-sparkle title: Skills --- diff --git a/packages/website/src/css/custom.css b/packages/website/src/css/custom.css index 26d8ae76b572..3101ad9901c1 100644 --- a/packages/website/src/css/custom.css +++ b/packages/website/src/css/custom.css @@ -217,13 +217,16 @@ code { .expComponentBadge:before { color: #fff; position: absolute; - top: 0.25rem; + top: 50%; + transform: translateY(-50%); inset-inline-end: 1rem; - border-radius: 0.5rem; - padding: 0.125rem 0.25rem; + border-radius: 3px; + padding: 1px 5px; box-sizing: border-box; - font-size: 0.75rem; - content: "exp"; + font-size: 0.55rem; + font-weight: 700; + letter-spacing: 0.03em; + content: "EXP"; background: #a100c2; pointer-events: none; } @@ -231,13 +234,16 @@ code { .deprComponentBadge:before { color: #fff; position: absolute; - top: 0.25rem; + top: 50%; + transform: translateY(-50%); inset-inline-end: 1rem; - border-radius: 0.5rem; - padding: 0.125rem 0.25rem; + border-radius: 3px; + padding: 1px 5px; box-sizing: border-box; - font-size: 0.75rem; - content: "depr"; + font-size: 0.55rem; + font-weight: 700; + letter-spacing: 0.03em; + content: "DEPR"; background: #ffb700e0; pointer-events: none; } @@ -255,14 +261,17 @@ code { .newComponentBadge:after { color: #fff; position: absolute; - top: 0.25rem; + top: 50%; + transform: translateY(-50%); inset-inline-end: 1rem; - border-radius: 0.5rem; - padding: 0.125rem 0.25rem; + border-radius: 3px; + padding: 1px 5px; box-sizing: border-box; - font-size: 0.75rem; - content: "new"; - background: #334eff; + font-size: 0.55rem; + font-weight: 700; + letter-spacing: 0.03em; + content: "NEW"; + background: linear-gradient(135deg, #6366f1, #8b5cf6); pointer-events: none; } @@ -277,6 +286,20 @@ code { inset-inline-end: 4.5rem; } +/* Sparkle icon for new/trending sidebar items — add sidebar_class_name: sidebar-sparkle to frontmatter */ +.sidebar-sparkle > a::after { + content: "NEW"; + margin-left: 0.5rem; + font-size: 0.55rem; + font-weight: 700; + letter-spacing: 0.03em; + padding: 1px 5px; + border-radius: 3px; + background: linear-gradient(135deg, #6366f1, #8b5cf6); + color: #fff; + vertical-align: middle; +} + .componentAdditionalInfo { margin-top: calc(-1 * calc(var(--ifm-h1-vertical-rhythm-bottom) * var(--ifm-leading))) !important; From fd90ef2842f39ce8dcba7c13ba8c60fe6a90020f Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 13 Mar 2026 18:52:11 +0200 Subject: [PATCH 06/15] feat: add addCustomCSS as last resort in styling skill --- skills/styling/SKILL.md | 26 +++++++++++++++++++++++++- 1 file changed, 25 insertions(+), 1 deletion(-) diff --git a/skills/styling/SKILL.md b/skills/styling/SKILL.md index 85f2741e47a6..ea89407c3d70 100644 --- a/skills/styling/SKILL.md +++ b/skills/styling/SKILL.md @@ -6,7 +6,7 @@ user-invocable: false # Styling UI5 Web Components -UI5 Web Components use Shadow DOM for encapsulation. Styles are isolated — external CSS won't leak in, but customization requires specific techniques. There are four approaches, ordered from most recommended to least. +UI5 Web Components use Shadow DOM for encapsulation. Styles are isolated — external CSS won't leak in, but customization requires specific techniques. There are five approaches, ordered from most recommended to least. ## 1. Styles on Tag Level @@ -62,6 +62,29 @@ All global SAP CSS variables are defined in [@sap-theming/theming-base-content]( **Best practice:** For broad theme changes, prefer using the UI Theme Designer to ensure consistency. Use direct CSS variable overrides only for targeted, scoped customizations. +## 5. Custom CSS via `addCustomCSS` (Last Resort) + +If none of the above work, custom CSS can be injected directly into a component's shadow DOM using the `addCustomCSS` API. **This approach is fragile** — it targets internal DOM structure that may change between versions. Only use it when CSS variables, tag-level styles, and shadow parts cannot achieve the desired result. + +Before writing custom CSS: +1. Inspect the component's shadow DOM in DevTools to understand the internal structure +2. Target the minimal set of selectors needed +3. Warn users that this may break on version upgrades + +Custom CSS must be registered before any instances of the component are created: + +```javascript +import { addCustomCSS } from "@ui5/webcomponents-base/dist/Theming.js"; + +addCustomCSS("ui5-select", ` + .ui5-select-root { + background-color: red; + } +`); +``` + +The first argument is the component's tag name, the second is a CSS string that gets injected into every instance's shadow DOM. + ## What NOT to Do - **Don't pierce shadow DOM** with deprecated `>>>` or `/deep/` selectors — they don't work. @@ -78,3 +101,4 @@ All global SAP CSS variables are defined in [@sap-theming/theming-base-content]( | Style based on component state | `:state(name)` | | Change colors/fonts globally | Override `--sap*` CSS variables | | Full theme customization | UI Theme Designer | +| Override internal shadow DOM styles | `addCustomCSS` (last resort) | From c7852332f493d7d7ce3cbe4b94bcd6088492695b Mon Sep 17 00:00:00 2001 From: ilhan007 Date: Fri, 13 Mar 2026 19:31:11 +0200 Subject: [PATCH 07/15] feat: add accessibility Agent Skill Covers accessibility APIs, label-input relationships, invisible messaging, icon modes, high contrast themes, and tooltips. --- docs/06-Skills.md | 1 + skills/accessibility/SKILL.md | 233 ++++++++++++++++++++++++++++++++++ 2 files changed, 234 insertions(+) create mode 100644 skills/accessibility/SKILL.md diff --git a/docs/06-Skills.md b/docs/06-Skills.md index 9aa1c54e5f6f..c9604c2d6330 100644 --- a/docs/06-Skills.md +++ b/docs/06-Skills.md @@ -13,6 +13,7 @@ UI5 Web Components ships [Agent Skills](https://agentskills.io) — portable, st | Skill | Description | |-------|-------------| | **styling** | How to customize and style UI5 Web Components — CSS shadow parts, custom states, CSS variables, and tag-level styling | +| **accessibility** | How to make UI5 Web Components applications accessible — accessibility APIs, label-input relationships, invisible messaging, keyboard handling, and high contrast themes | ## Installation diff --git a/skills/accessibility/SKILL.md b/skills/accessibility/SKILL.md new file mode 100644 index 000000000000..0c9e45c81d73 --- /dev/null +++ b/skills/accessibility/SKILL.md @@ -0,0 +1,233 @@ +--- +name: accessibility +description: How to make UI5 Web Components applications accessible. Covers accessibility APIs (accessibleName, accessibleNameRef, accessibleDescription, accessibleRole, accessibilityAttributes), label-input relationships, invisible messaging, keyboard handling, high contrast themes, and screen reader support. Use when the user asks about ARIA attributes, screen readers, keyboard navigation, accessibility properties, or making their app accessible. +user-invocable: false +--- + +# Accessibility in UI5 Web Components + +UI5 Web Components have built-in accessibility: ARIA roles, keyboard navigation, screen reader support, and high contrast themes are handled automatically in the shadow DOM. Applications should use the accessibility APIs described here to provide additional context that only the app can know (labels, descriptions, relationships). + +## Built-in Accessibility (No App Code Needed) + +Components automatically provide: +- **ARIA roles and attributes** mapped in the shadow DOM (e.g., `ui5-combobox` renders `role="combobox"` internally) +- **Keyboard navigation** within complex components (arrow keys in lists, tables, date pickers, etc.) +- **Focus management** with visible focus indicators +- **State mapping** — `disabled`, `readonly`, `required`, `checked` are automatically mapped to their ARIA equivalents (`aria-disabled`, `aria-readonly`, `aria-required`, `aria-checked`) + +## Accessibility APIs + +Use these properties to enrich the accessibility context for your application. + +### accessibleName + +Maps to `aria-label`. Provides a text alternative when the visual label is insufficient or absent. + +```html + + + + + +``` + +Use `accessibleName` when there is no visible text label, for example icon-only buttons or inputs without a ``. + +### accessibleNameRef + +Alternative to `aria-labelledby` that works across shadow DOM boundaries. Takes one or more IDs of elements whose text content serves as the label. + +```html +Full name + + + +Shipping +Address + +``` + +Prefer `accessibleNameRef` over `accessibleName` when a visible label exists — this keeps the label and the ARIA text in sync automatically. + +### accessibleDescription / accessibleDescriptionRef + +Maps to `aria-description`. Provides additional descriptive text beyond the label. + +```html + + + + +

Must be at least 8 characters

+ + +``` + +### accessibleRole + +Overrides the default ARIA role of a component. + +```html +... +... +Navigate +``` + +Only change the role when the component is used in a non-standard way (e.g., a List used as a menu). + +### accessibilityAttributes + +An object that sets additional ARIA attributes on the component's root element. Use for `aria-expanded`, `aria-haspopup`, `aria-controls`, and similar relationship attributes. + +```html +Open Menu +... + + +``` + +For composite components like `ui5-shellbar`, the object contains nested objects for different internal elements — check the component's API docs. + +## Label-Input Relationships + +Due to shadow DOM, standard HTML `