diff --git a/docs/2-advanced/18-using-custom-illustrations.md b/docs/2-advanced/18-using-custom-illustrations.md
new file mode 100644
index 000000000000..453212717a35
--- /dev/null
+++ b/docs/2-advanced/18-using-custom-illustrations.md
@@ -0,0 +1,317 @@
+# Using Custom Illustrations
+
+*Learn how to create and register custom illustrations for the UI5 Web Components IllustratedMessage component.*
+
+The [`ui5-illustrated-message`](https://ui5.github.io/webcomponents/components/fiori/IllustratedMessage/) component enhances user experience by displaying contextual illustrations in empty states, error conditions, onboarding flows, and other scenarios where visual communication improves usability.
+
+While UI5 Web Components includes a comprehensive set of [built-in illustrations](https://ui5.github.io/webcomponents/components/fiori/enums/IllustrationMessageType/), you can extend this collection by registering your own custom illustrations that match your application's brand and design requirements.
+
+## Overview
+
+Custom illustrations in UI5 Web Components consist of four size variants that automatically adapt to different container dimensions and [design contexts](https://ui5.github.io/webcomponents/components/fiori/enums/IllustrationMessageDesign/):
+
+| Variant | Size | Breakpoint | Container Width | Design Type |
+|------------|-------------|------------|-----------------|-------------|
+| **Scene** | Large | L | > 681px | Large |
+| **Dialog** | Medium | M | ≤ 681px | Medium |
+| **Spot** | Small | S | ≤ 360px | Small |
+| **Dot** | Extra Small | XS | ≤ 260px | ExtraSmall |
+
+Each custom illustration must include all four variants to ensure optimal display across different use cases and responsive breakpoints.
+
+## Prerequisites
+
+Before implementing custom illustrations, ensure you have installed the required packages:
+
+```bash
+npm install @ui5/webcomponents @ui5/webcomponents-fiori
+```
+
+The [`@ui5/webcomponents`](https://www.npmjs.com/package/@ui5/webcomponents) package provides the base framework and asset registry functionality, while [`@ui5/webcomponents-fiori`](https://www.npmjs.com/package/@ui5/webcomponents-fiori) contains the `IllustratedMessage` component.
+
+## Custom Illustrations Registration
+
+UI5 Web Components allow developers to register custom illustrations using the `registerIllustration` and `unsafeRegisterIllustration` methods. These methods enable you to add your own illustrations and make them available for use in your application.
+
+### registerIllustration (recommended)
+
+The `registerIllustration` method is the preferred approach, as it includes built-in safety checks to prevent security vulnerabilities. You can register illustrations using JSX templates.
+
+**Note:** JSX templates only work if your project is scaffolded with `npm init @ui5/webcomponents-package`. Otherwise, use `unsafeRegisterIllustration`.
+
+**TypeScript/JSX:**
+```tsx
+import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
+import { registerIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
+import type { I18nText } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+
+// Register the illustration with JSX templates
+registerIllustration("EmptyCart", {
+ sceneTemplate: () => (
+
+ ),
+ dialogTemplate: () => (
+
+ ),
+ spotTemplate: () => (
+
+ ),
+ dotTemplate: () => (
+
+ ),
+ title: "Your cart is empty" as I18nText,
+ subtitle: "Add items to get started with your order" as I18nText,
+ set: "custom"
+});
+```
+
+**Parameters:**
+
+- `name`: unique identifier for the illustration
+- `illustrationData` (object): illustration configuration containing:
+ - `sceneTemplate`: template function for the Scene variant (large, > 681px)
+ - `dialogTemplate`: template function for the Dialog variant (medium, ≤ 681px)
+ - `spotTemplate`: template function for the Spot variant (small, ≤ 360px)
+ - `dotTemplate`: template function for the Dot variant (extra small, ≤ 260px)
+ - `title`: the illustration's title text
+ - `subtitle`: the illustration's subtitle text
+ - `set`: unique illustration set identifier (e.g., "custom")
+
+### unsafeRegisterIllustration
+
+The `unsafeRegisterIllustration` method allows you to register raw SVG strings **without sanitization**. Use this only if you trust the SVG source and have validated it yourself, or when JSX templates are not available in your project.
+
+#### Step 1: Prepare SVG Assets
+
+Create four SVG files for each illustration following the naming convention:
+```
+{set}-{Variant}-{IllustrationName}.js
+```
+
+**Example file structure:**
+```
+assets/
+├── custom-Scene-EmptyCart.js # Large variant (> 681px)
+├── custom-Dialog-EmptyCart.js # Medium variant (≤ 681px)
+├── custom-Spot-EmptyCart.js # Small variant (≤ 360px)
+└── custom-Dot-EmptyCart.js # Extra small variant (≤ 260px)
+```
+
+Each SVG asset file should export the SVG content as a string:
+
+**custom-Dialog-EmptyCart.js:**
+```js
+export default ``;
+```
+
+#### Step 2: Register the Illustration
+
+**JavaScript:**
+```js
+import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
+import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
+
+// Import SVG assets
+import sceneSvg from "./assets/custom-Scene-EmptyCart.js";
+import dialogSvg from "./assets/custom-Dialog-EmptyCart.js";
+import spotSvg from "./assets/custom-Spot-EmptyCart.js";
+import dotSvg from "./assets/custom-Dot-EmptyCart.js";
+
+// Register the illustration
+unsafeRegisterIllustration("EmptyCart", {
+ sceneSvg,
+ dialogSvg,
+ spotSvg,
+ dotSvg,
+ title: "Your cart is empty",
+ subtitle: "Add items to get started with your order",
+ set: "custom"
+});
+```
+
+**TypeScript:**
+```ts
+import "@ui5/webcomponents-fiori/dist/IllustratedMessage.js";
+import { unsafeRegisterIllustration } from "@ui5/webcomponents-base/dist/asset-registries/Illustrations.js";
+import type { I18nText } from "@ui5/webcomponents-base/dist/i18nBundle.js";
+
+// Import SVG assets
+import sceneSvg from "./assets/custom-Scene-EmptyCart.js";
+import dialogSvg from "./assets/custom-Dialog-EmptyCart.js";
+import spotSvg from "./assets/custom-Spot-EmptyCart.js";
+import dotSvg from "./assets/custom-Dot-EmptyCart.js";
+
+// Register the illustration with proper typing
+unsafeRegisterIllustration("EmptyCart", {
+ sceneSvg,
+ dialogSvg,
+ spotSvg,
+ dotSvg,
+ title: "Your cart is empty" as I18nText,
+ subtitle: "Add items to get started with your order" as I18nText,
+ set: "custom"
+});
+```
+
+**Parameters:**
+
+- `name`: unique identifier for the illustration
+- `illustrationData` (object): illustration configuration containing:
+ - `sceneSvg`: SVG string for the Scene variant (large, > 681px)
+ - `dialogSvg`: SVG string for the Dialog variant (medium, ≤ 681px)
+ - `spotSvg`: SVG string for the Spot variant (small, ≤ 360px)
+ - `dotSvg`: SVG string for the Dot variant (extra small, ≤ 260px)
+ - `title`: the illustration's title text
+ - `subtitle`: the illustration's subtitle text
+ - `set`: unique illustration set identifier (e.g., "custom")
+
+> **⚠️ Security Warning:**
+> The `unsafeRegisterIllustration` method accepts raw SVG strings without sanitization. Only use this function with SVG content that you trust and have validated yourself. Improperly sanitized SVG strings can lead to security vulnerabilities such as XSS (Cross-Site Scripting).
+
+## Design Guidelines
+
+**SVG Requirements:**
+- Include a unique `id` attribute: `{set}-{Variant}-{IllustrationName}`
+- Use responsive dimensions appropriate for each variant
+- All four size variants must be provided for optimal display
+
+**Theming Support:**
+- Use CSS custom properties for colors (e.g., `var(--sapContent_Illustrative_Color1)`)
+- Avoid hard-coded colors to ensure theme compatibility
+- Test illustrations across different UI5 themes
+
+**Security Compliance** (for `unsafeRegisterIllustration`):
+
+- ⚠️ **No inline JavaScript**: Avoid `
+
+
+
+
+
Custom Illustration Playground
+
+ This page showcases both safe (registerIllustration) and unsafe
+ (unsafeRegisterIllustration) APIs for registering custom illustrations with
+ ui5-illustrated-message.
+
+
+
+
+
Safe registration (templates)
+
SVG rendered via JSX templates registered through registerIllustration.
+
+ Primary Action
+ Secondary Action
+
+
+
+
+
Unsafe registration (raw strings)
+
SVG sourced from assets/ via unsafeRegisterIllustration.