@ccslabs/xtend 0.1.0-rc.1 → 0.1.2

package/docs/de/components/xheader.md

@@ -0,0 +1,308 @@
+# xheader – XTend Komponente
+
+> **Siehe auch:** [xfooter](./xfooter.md), [xtheme](./xtheme.md)
+
+## Übersicht
+
+`<x-header>` ist eine vielseitige, barrierearme Header-Komponente für Branding, Navigation und flexible Layouts. Sie unterstützt Logo, Titel, Search-, Actions-/Utility- und Navigationsslots, Theming, State-Integration und mehrere Menu Presentation Modes für Enterprise App-Shells.
+
+---
+
+## Features
+- Optionales Logo (src-Attribut)
+- Slot-System für Titel, Suche, Actions, Legacy-Utility und Navigation
+- Sticky-Header
+- State-Integration via xstate
+- Theming via CSS Custom Properties (voll themefähig)
+- **Responsives Verhalten:** Header-Inhalte laufen über ein Slot-Grid. Suche und Actions umbrechen auf kleinen Displays kontrolliert, Navigation nutzt den konfigurierten Menu Presentation Mode.
+- **Slot Alignment:** Brand, Actions und Menü-Trigger bleiben bei schmalen Viewports in einer festen Kopfzeile; Search liegt darunter und verhindert dadurch verschobene Action-Buttons.
+- **Menu Presentation Modes:** `drawer`, `side-panel`, `popover`, `fullscreen` und `inline-main` decken Shell-, App- und Portal-Navigation ab.
+- **Full-Width-Drawer:** Der Default `drawer` rendert weiterhin als fixed Overlay über die verfügbare Seitenbreite und verlängert den Dokument-Scrollbereich nicht.
+- **Overflow-sichere Navigation:** Direkte `x-link`-Einträge und komplexe `[data-menu-shell]`-Menüs bleiben im Menü-Surface innerhalb ihrer Container.
+- **Burger-Menü:** Animierter Button, Farbe per Theme steuerbar
+- **Barrierefreiheit:** Landmark-Rollen, ARIA, Keyboard-Navigation, Fokus-Management
+- **Events:** Menü geöffnet/geschlossen, Logo geladen
+
+---
+
+## Verwendung
+
+```html
+<x-header src="logo.svg" logo-size="40">
+  <span slot="title">Meine App</span>
+  <x-form slot="search">...</x-form>
+  <button slot="actions">Theme</button>
+  <x-link slot="nav" href="/docs">Docs</x-link>
+</x-header>
+```
+
+**Hinweis:** `utility` bleibt als kompatibler Alias erhalten. Neue Apps sollten `search` für Suche und `actions` für Buttons, Toggle oder Status verwenden.
+
+---
+
+## Menu Presentation Modes
+
+`menu-mode` steuert, wie die Navigation sichtbar wird. Ohne neues Attribut bleibt `drawer` aktiv und damit das bisherige Full-Width-Drawer-Verhalten kompatibel.
+
+| Mode | Verhalten | A11y-Verhalten |
+|------|-----------|----------------|
+| `drawer` | Fixed Overlay unter dem Header, standardmäßig full-width | Navigation, Escape, Outside Click, Focus Return |
+| `side-panel` | Seitliches Panel über `menu-placement="start"` oder `end` | optional modal per `menu-modal`, dann Focus Trap und Backdrop |
+| `popover` | Kompaktes Menü nahe Trigger | nicht modal, Escape und Outside Click |
+| `fullscreen` | Vollflächige Navigation | modal, Backdrop, Focus Trap, Escape und Focus Return |
+| `inline-main` | Menü im Header-Dokumentfluss | keine Overlay-Falle, sauberer Navigation-Landmark |
+
+```html
+<x-header
+  menu-mode="side-panel"
+  menu-placement="end"
+  menu-modal
+  menu-width="min(32rem, 92vw)"
+  menu-max-height="calc(100dvh - 2rem)"
+  menu-align="stretch">
+  <span slot="title">Enterprise Shell</span>
+  <x-link slot="nav" href="/workbench">Workbench</x-link>
+</x-header>
+```
+
+`menu-open` kann deklarativ gesetzt werden. Programmatisch bleibt `toggleMenu(true | false, { source })` die stabile API. `snapshot()` liefert `menuMode`, `menuPlacement`, `menuModal`, `menuBreakpoint`, `menuWidth`, `menuMaxHeight` und `menuAlign`; `drawerMode: 'fixed-full-width-overlay'` bleibt als Legacy-Alias erhalten.
+
+---
+
+## Responsive Slot-Logik
+- Desktop: Brand, Search, Actions und Menübutton stehen in einer stabilen Grid-Zeile.
+- Tablet: Search belegt eine eigene Grid-Zeile, damit Eingabefelder nicht mit Actions clippen.
+- Mobile: Brand, Actions und Menübutton bleiben in der ersten Zeile. Search belegt die zweite Zeile. Navigation nutzt den konfigurierten Menu Presentation Mode.
+- Der Drawer wird als `fixed` Overlay positioniert. Dadurch bleibt die App-Shell stabil, und Route-Wechsel von geöffneter Navigation auf kurze Seiten erzeugen keine zusätzliche Dokumenthöhe.
+- Slotted Navigation nutzt `max-width: 100%`, `min-width: 0`, `box-sizing: border-box` und `overflow-wrap: anywhere`, damit lange Menüpunkte nicht aus App-Shell-Containern herausragen.
+- `header-layout-changed` wird emittiert, wenn der Header in den kompakten Zustand wechselt.
+
+## Slot Alignment
+
+`x-header` nutzt standardmäßig das Alignment `fixed-responsive-slot-grid`.
+
+| Viewport | Slot-Mapping |
+|----------|--------------|
+| Desktop | `brand search actions trigger` |
+| Tablet | `brand actions trigger` + `search search search` |
+| Mobile | `brand actions trigger` + `search search search` |
+
+Corporate Designs können dieses Mapping über CSS Custom Properties überschreiben, ohne die Komponente zu forken:
+
+```css
+x-header {
+  --header-slot-template-areas: "brand search actions trigger";
+  --header-tablet-slot-template-areas: "brand actions trigger" "search search search";
+  --header-mobile-slot-template-areas: "brand actions trigger" "search search search";
+  --header-mobile-actions-justify: flex-end;
+  --header-mobile-actions-wrap: nowrap;
+}
+```
+
+---
+
+## Slots
+| Name      | Beschreibung                                 |
+|-----------|----------------------------------------------|
+| `title`   | Bereich für den Titel/Branding               |
+| `search`  | Suchformular oder Filter-Eingabe             |
+| `actions` | Buttons, Theme Toggle, Status-Aktionen       |
+| `utility` | Kompatibler Alias für Actions                |
+| `nav`     | Navigationseinträge (Links, Menüs)           |
+| `logo`    | Optional: eigenes Logo-Element               |
+
+---
+
+## Attribute
+| Attribut      | Typ     | Beschreibung                        |
+|---------------|---------|-------------------------------------|
+| `src`         | String  | Logo-URL                            |
+| `logo-size`   | String  | Größe des Logos (z.B. 40, 64px)     |
+| `sticky`      | Boolean | Header bleibt oben fixiert           |
+| `shadow`      | Boolean | Schatten aktivieren                  |
+| `menu-mode`   | `drawer`, `side-panel`, `popover`, `fullscreen`, `inline-main` | Menu Presentation Mode |
+| `menu-placement` | `start`, `end`, `top`, `bottom` | bevorzugte Position |
+| `menu-modal`  | Boolean | Modalität mit Backdrop und Focus Trap |
+| `menu-open`   | Boolean | Menü deklarativ öffnen |
+| `menu-breakpoint` | String | Preset (`sm`, `md`, `lg`, `xl`) oder CSS Length |
+| `menu-width`  | String | Breite für Panel/Popover |
+| `menu-max-height` | String | Höhenbegrenzung des Menü-Surfaces |
+| `menu-align`  | `start`, `center`, `end`, `stretch` | Ausrichtung im Menü-Surface |
+
+---
+
+## Events
+| Event         | Beschreibung                        |
+|---------------|-------------------------------------|
+| `header-layout-changed` | Wird bei responsive Layoutwechseln ausgelöst |
+| `menu-before-open` | Cancelable Event vor dem Öffnen |
+| `menu-before-close` | Cancelable Event vor dem Schließen |
+| `menu-opened` | Wird mit Snapshot ausgelöst, wenn Menü öffnet |
+| `menu-closed` | Wird mit Snapshot ausgelöst, wenn Menü schließt |
+| `menu-mode-changed` | Wird bei Wechsel von `menu-mode` ausgelöst |
+| `menu-placement-changed` | Wird bei Wechsel von `menu-placement` ausgelöst |
+| `logo-loaded` | Wird ausgelöst, wenn Logo geladen    |
+
+---
+
+## API
+- **Logo dynamisch setzen:** `element.setAttribute('src', 'logo.svg')`
+- **Menü direkt steuern:** `header.toggleMenu(false, { source: 'router' })`
+- **State-Integration:** Automatisch via xstate (`xheader-state-<id>`, z.B. Menü öffnen/schließen)
+- **Menü programmatisch öffnen:**
+  ```js
+  xstate.set('xheader-state-<id>', { menuOpen: true });
+  ```
+
+---
+
+## Beispiel: Dynamisch per JS
+
+```js
+const header = document.createElement('x-header');
+header.setAttribute('src', 'logo.svg');
+document.body.appendChild(header);
+```
+
+---
+
+## Styling & Theming
+
+```css
+x-header {
+  --xtend-header-surface: #fff;
+  --xtend-header-text: #222;
+  --xtend-header-border-color: #d9dde5;
+  --xtend-header-menu-surface: #fff;
+  --xtend-header-menu-width: min(30rem, 92vw);
+  --xtend-header-menu-max-height: min(72dvh, 820px);
+  --xtend-header-menu-backdrop: rgba(15, 23, 42, 0.45);
+  --header-bg: var(--xtend-header-surface);
+  --header-fg: var(--xtend-header-text);
+  --header-title-color: #222; /* Titel im Light Mode */
+  --burger-color: #222;       /* Burger-Button-Striche im Light Mode */
+  --header-menu-bg: var(--xtend-header-menu-surface);
+  --header-mobile-slot-template-areas: "brand actions trigger" "search search search";
+  --header-drawer-inline-offset: 1rem;
+  --header-drawer-content-max: none;
+}
+x-header[theme="dark"] {
+  --header-bg: #222;
+  --header-fg: #fff;
+  --header-title-color: #fff; /* Titel im Dark Mode */
+  --burger-color: #fff;       /* Burger-Button-Striche im Dark Mode */
+}
+```
+
+---
+
+## Accessibility
+- Semantisches HTML, Landmark-Rollen (`role="banner"`)
+- ARIA-Attribute für Menü, Burger-Button, Navigation
+- Keyboard-Navigation (Tab, Escape)
+- Fokus-Management im Overlay; `fullscreen` und `menu-modal` nutzen Focus Trap, Backdrop und Focus Return
+
+---
+
+## Changelog
+- **18.07.2025:** Modernisierung, Theme-Variablen für Titel und Burger, Events, Accessibility, API, Doku aktualisiert
+- **bis 07/2025:** Diverse Bugfixes, Responsive-Verbesserungen
+
+---
+
+*Letzte Aktualisierung: 18. Juli 2025*
+
+## Layout Display Media UX Profil
+
+`x-header` stellt ab `WP-E11-12` das Profil `xtend.component.layout-display-media-ux-profile.v1` bereit. Die Komponente ist als Docs-/App-Shell-Header RMT-schedulbar und nutzt den State-Key `xheader-state-<id>`.
+
+- Profil-Getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.visible.mount`
+- Events: `header-ready`, `menu-before-open`, `menu-before-close`, `menu-opened`, `menu-closed`, `menu-mode-changed`, `menu-placement-changed`
+- Snapshot: `snapshot()`
+- CSS Parts: `root`, `brand`, `title`, `logo`, `search`, `actions`, `utility`, `trigger`, `trigger-icon`, `menu`, `menu-surface`, `menu-content`, `nav`, `backdrop`
+- Legacy CSS Parts: `drawer` und `drawer-surface` bleiben als Alias für `menu` und `menu-surface` erhalten.
+
+## ECH-WP-07 Token-Tabelle und signatureDesign
+
+`signatureDesign`: Praezise Enterprise App-Shell mit ruhiger Flaechenhierarchie, dichter Slot-Rhythmik, hochwertigem Menue-Surface und brand-neutraler Premium-Wirkung. Das Default-Design soll eigenstaendig wirken, ohne eine One-Brand-Optik zu erzwingen.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-layout-surface` | Shell- und Menueflaeche |
+| `--xtend-layout-text` | Header-, Brand- und Navigationsfarbe |
+| `--xtend-layout-border-color` | Header-, Trigger- und Menuekanten |
+| `--xtend-layout-radius` | Header- und Menue-Radius |
+| `--xtend-layout-elevation` | Header- und Menue-Schatten |
+| `--xtend-layout-spacing` | Header-Padding |
+| `--xtend-layout-gap` | Slot- und Menueabstand |
+| `--xtend-layout-font-family` | Shell-Typografie |
+| `--xtend-layout-font-size` | Brand-/Navigationstypografie |
+| `--xtend-layout-media-radius` | Logo- und Medienradius |
+| `--xtend-layout-focus-ring` | Tastaturfokus |
+| `--xtend-layout-grid-min` | Slot-Grid-Untergrenze |
+| `--xtend-layout-content-max` | Menuebreite und Content-Grenze |
+
+## ECH-WP-07 Fremdtheme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-header {
+  --xtend-layout-surface: #f6f2ea;
+  --xtend-layout-text: #17231f;
+  --xtend-layout-border-color: rgba(23, 35, 31, 0.22);
+  --xtend-layout-radius: 0.35rem;
+  --xtend-layout-elevation: 0 14px 34px rgba(23, 35, 31, 0.14);
+  --xtend-layout-spacing: 0.9rem;
+  --xtend-layout-gap: 0.7rem;
+  --xtend-layout-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-layout-font-size: 1rem;
+  --xtend-layout-media-radius: 0.2rem;
+  --xtend-layout-focus-ring: 3px solid #8f4f2a;
+  --xtend-layout-grid-min: minmax(0, 1fr);
+  --xtend-layout-content-max: 24rem;
+}
+```
+
+## ECH-WP-09 Token-Tabelle und Navigation States
+
+`signatureDesign`: `x-header` verbindet eine hochwertige Enterprise-App-Shell mit sichtbar stabiler Navigation. Active/Current/Selected, Hover, Focus und Disabled gelten fuer slotted `nav`-Eintraege in `drawer`, `side-panel`, `popover`, `fullscreen` und `inline-main`.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-nav-surface` | Menue- und Nav-Surface |
+| `--xtend-nav-text` | Nav-Text |
+| `--xtend-nav-border-color` | Menue- und Nav-Kante |
+| `--xtend-nav-radius` | Nav-Radius |
+| `--xtend-nav-gap` | Abstand im Menue |
+| `--xtend-nav-font-family` | Navigationstypografie |
+| `--xtend-nav-font-size` | Navigationstextgroesse |
+| `--xtend-nav-active-surface` | Active/Current/Selected Flaeche |
+| `--xtend-nav-active-text` | Active/Current/Selected Text |
+| `--xtend-nav-current-indicator` | nicht farb-only Current-Indikator |
+| `--xtend-nav-hover-surface` | Hover-Flaeche |
+| `--xtend-nav-focus-ring` | Tastaturfokus |
+| `--xtend-nav-disabled-opacity` | Disabled-Dimmung |
+
+## ECH-WP-09 Keyboard-Verhalten
+
+Der Menue-Trigger ist ein Icon Control mit `part="trigger-icon control icon"`. Overlay-Modi unterstuetzen Escape, Outside Click, Focus Return und bei `menu-modal` Focus Trap. Slotted Navigation kann `aria-current="page"`, `aria-selected="true"`, `active`, `disabled` oder `aria-disabled="true"` tragen. Verschachtelte Navigation muss Disclosure Icons als Icon Controls, z.B. `part="disclosure-icon control icon"`, auszeichnen.
+
+## ECH-WP-09 Fremdtheme
+
+```css
+[data-xtend-nav-theme="enterprise-foreign"] x-header {
+  --xtend-nav-surface: #f7f4ee;
+  --xtend-nav-text: #17231f;
+  --xtend-nav-border-color: rgba(23, 35, 31, 0.22);
+  --xtend-nav-radius: 0.35rem;
+  --xtend-nav-gap: 0.45rem;
+  --xtend-nav-font-family: "Aptos", "Segoe UI", sans-serif;
+  --xtend-nav-font-size: 0.98rem;
+  --xtend-nav-active-surface: #173f35;
+  --xtend-nav-active-text: #fffaf0;
+  --xtend-nav-current-indicator: #b56b35;
+  --xtend-nav-hover-surface: rgba(181, 107, 53, 0.14);
+  --xtend-nav-focus-ring: 3px solid #b56b35;
+  --xtend-nav-disabled-opacity: 0.44;
+}
+```

package/docs/de/components/xhero.md

@@ -0,0 +1,142 @@
+# xhero – XTend Komponente
+
+> **Siehe auch:** [xsection](./xsection.md), [xbutton](./xbutton.md)
+
+## Übersicht
+
+`<x-hero>` ist eine flexible Hero-Komponente für aufmerksamkeitsstarke Headerbereiche, Landingpages und Einstiege. Sie unterstützt Slots für Titel, Untertitel, Aktionen und Medien.
+
+---
+
+## Features
+- Flexibles Layout für Hero-Bereiche
+- Slots für Titel, Text, Aktionen, Medien
+- Theming via CSS Custom Properties
+- Theme-Varianten über `background-light`, `background-dark`, `font-color-light`, `font-color-dark`, `overlay-light` und `overlay-dark`
+- Responsive Design
+
+---
+
+## Verwendung
+
+```html
+<x-hero>
+  <h1 slot="title">Willkommen!</h1>
+  <p slot="subtitle">XTend macht Webentwicklung einfach.</p>
+  <x-button slot="action">Loslegen</x-button>
+</x-hero>
+```
+
+---
+
+## Attribute
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `background` | String | Fester Hintergrund oder CSS-Variable |
+| `background-light` | String | Hintergrund für helle Themes |
+| `background-dark` | String | Hintergrund für dunkle Themes |
+| `background-image` | String | Bildhintergrund |
+| `overlay` | Boolean | Aktiviert Overlay-Fläche |
+| `overlay-light` | String | Overlay-Farbe für helle Themes |
+| `overlay-dark` | String | Overlay-Farbe für dunkle Themes |
+| `font-color` | String | Feste Textfarbe |
+| `font-color-light` | String | Textfarbe für helle Themes |
+| `font-color-dark` | String | Textfarbe für dunkle Themes |
+| `animate` | Boolean | Aktiviert Einstiegstransition mit Reduced-Motion-Fallback |
+
+---
+
+## Events
+| Event         | Beschreibung                        |
+|---------------|-------------------------------------|
+| –             | –                                   |
+
+---
+
+## API
+- **Inhalte per Slot einfügen**
+- **State-Integration:** Optional via xstate
+
+---
+
+## Beispiel: Dynamisch per JS
+
+```js
+const hero = document.createElement('x-hero');
+hero.innerHTML = '<h1 slot="title">Hallo XTend!</h1>';
+document.body.appendChild(hero);
+```
+
+---
+
+## Styling & Theming
+
+```css
+x-hero {
+  --hero-bg: #f5f5f5;
+  --hero-color: #222;
+}
+```
+
+## Viewport-Sicherheit
+
+`x-hero` begrenzt Host, Root und Content auf `max-width: 100%` und nutzt auf schmalen Viewports keine innere `100vw`-Breite. Dadurch bleibt die Komponente auch in gepaddeten App-Shells oder Docs-Layouts innerhalb des sichtbaren Viewports.
+
+---
+
+## Accessibility
+- Semantisches HTML, ARIA
+
+---
+
+*Letzte Aktualisierung: 16. Juli 2025*
+
+## Layout Display Media UX Profil
+
+`x-hero` stellt ab `WP-E11-12` das Profil `xtend.component.layout-display-media-ux-profile.v1` bereit. Die Komponente bleibt Hero-/Display-Shell und kann in RMT mit `component.shell.render` zuerst gerendert werden. Der State-Key lautet `xhero-state-<id>`.
+
+- Profil-Getter: `xtendLayoutDisplayMediaUxProfile`
+- Schedule: `component.shell.render`
+- Events: `hero-rendered`, `hero-animated`
+- Snapshot: `snapshot()`
+- CSS Parts: `root`, `overlay`, `content`, `scroll-button`
+
+## ECH-WP-07 Token-Tabelle und signatureDesign
+
+`signatureDesign`: Immersive Enterprise-Hero-Komposition mit editorialer Tiefe, medienfaehigem Surface und tokenisiertem Content-Block. Die Standardwirkung soll elegant und eigenstaendig sein, aber Bild-, App- und Corporate-Inszenierungen zulassen.
+
+| Token | Zweck |
+| --- | --- |
+| `--xtend-layout-surface` | Hero- und Content-Flaeche |
+| `--xtend-layout-text` | Hero-Textfarbe |
+| `--xtend-layout-border-color` | Scroll-Control-Kante |
+| `--xtend-layout-radius` | Hero-, Content- und Titelradius |
+| `--xtend-layout-elevation` | Hero-, Content- und Titel-Schatten |
+| `--xtend-layout-spacing` | Hero- und Content-Padding |
+| `--xtend-layout-gap` | Kompositionsabstand fuer Theme-Autoren |
+| `--xtend-layout-font-family` | Hero-Typografie |
+| `--xtend-layout-font-size` | Control- und Content-Skalierung |
+| `--xtend-layout-media-radius` | Bild-/Hero-Radius |
+| `--xtend-layout-focus-ring` | Scroll-Control-Fokus |
+| `--xtend-layout-grid-min` | Responsive Kompositionsbasis |
+| `--xtend-layout-content-max` | Content-Breite |
+
+## ECH-WP-07 Fremdtheme
+
+```css
+[data-xtend-layout-theme="enterprise-foreign"] x-hero {
+  --xtend-layout-surface: rgba(248, 244, 239, 0.88);
+  --xtend-layout-text: #15231d;
+  --xtend-layout-border-color: rgba(21, 35, 29, 0.22);
+  --xtend-layout-radius: 0.45rem;
+  --xtend-layout-elevation: 0 20px 60px rgba(21, 35, 29, 0.16);
+  --xtend-layout-spacing: 4rem 2rem;
+  --xtend-layout-gap: 1rem;
+  --xtend-layout-font-family: "Aptos Display", "Segoe UI", sans-serif;
+  --xtend-layout-font-size: 1.05rem;
+  --xtend-layout-media-radius: 0.65rem;
+  --xtend-layout-focus-ring: 3px solid #8f4f2a;
+  --xtend-layout-grid-min: minmax(0, 1fr);
+  --xtend-layout-content-max: 42rem;
+}
+```

package/docs/de/components/xicon.md

@@ -0,0 +1,125 @@
+# xicon – XTend Komponente
+
+> **Siehe auch:** [xbutton](./xbutton.md), [xtheme](./xtheme.md), [xrouter](./xrouter.md)
+
+## Uebersicht
+
+`<x-icon>` ist der universelle Ikonographie-Adapter fuer XTend Apps. Die Komponente rendert lokale Inline-SVG-Icons, registrierte Icon-Packs oder kontrollierte URL-Quellen und bleibt dabei framework-agnostisch, RMT-kompatibel und CDN-frei.
+
+Das mitgelieferte `core` Pack deckt die wichtigsten XTend-UI-Symbole ab. Der lokale `lucide` Adapter dient als groesseres Superset, wird aus lokalen ESM-Artefakten geladen und vermeidet externe CDN-Abhaengigkeiten, FCP-Bremsen und Datenschutzprobleme.
+
+## Features
+
+- lokales `core` Icon-Pack mit Basis-Icons fuer Shell, Docs, Status und Navigation
+- lokaler `lucide` IconPack Adapter als Superset ohne Remote Runtime Import
+- globale Registry `window.XTend.icons` fuer Custom Icon Packs und Corporate-Design-Sets
+- direkte Quellen ueber `src` fuer SVG-Dateien aus Repo, App-Bundle oder CDN-Policies des Hosts
+- rohe SVG-Pack-Eintraege werden vor dem Rendern auf erlaubte Knoten und Attribute reduziert
+- A11y-Modus fuer dekorative und semantische Icons
+- State-Integration ueber `xicon-state-<id>`
+- RMT Shell Authoring ueber `xtend.rmt.component-contract.v1`
+- Performance-Profil `xtend.performance.component-profile.v1` mit `display-micro` Budget
+
+## Verwendung
+
+```html
+<x-icon name="search" label="Suche"></x-icon>
+<x-icon name="gauge" pack="lucide" size="1.25rem" label="Performance"></x-icon>
+<x-icon src="/assets/icons/company.svg" label="Corporate Icon"></x-icon>
+<x-icon name="chevron-right" decorative></x-icon>
+```
+
+## Attribute
+
+| Attribut | Typ | Beschreibung |
+|----------|-----|--------------|
+| `name` | String | Icon-Name oder Alias aus der Registry |
+| `pack` | String | optionales Icon-Pack, z.B. `core` oder `lucide` |
+| `src` | String | kontrollierte URL-Quelle fuer ein Icon aus Repo, App-Bundle oder Host-Policy |
+| `label` | String | zugänglicher Name fuer Screenreader |
+| `size` | String | CSS-Groesse, z.B. `1em`, `20px`, `1.25rem` |
+| `stroke-width` | String | Strichstaerke fuer Inline-SVG-Pfade |
+| `color` | String | CSS-Farbwert; Standard ist `currentColor` |
+| `decorative` | Boolean | setzt `aria-hidden` und entfernt semantische Bildrolle |
+
+## Events
+
+| Event | Beschreibung |
+|-------|--------------|
+| `icon-ready` | Icon wurde aus Pack oder `src` aufgeloest |
+| `icon-missing` | Registry konnte `name`/`pack` nicht aufloesen |
+| `icon-pack-registered` | ein Pack wurde in der globalen Registry registriert |
+
+## API
+
+| Methode | Zweck |
+|---------|-------|
+| `setIcon(name, options?)` | setzt Icon, Pack, Label oder `src` programmatisch |
+| `registerPack(pack, options?)` | registriert ein Pack ueber die Komponente |
+| `snapshot()` | liefert `xtend.component.x-icon.state.v1` inklusive Registry-Snapshot |
+| `window.XTend.icons.register(pack, options?)` | globale Pack-Registrierung |
+| `window.XTend.icons.resolve(name, options?)` | globale Aufloesung ohne Rendering |
+| `window.XTend.icons.snapshot()` | Registry-Snapshot fuer Diagnostics |
+
+## Custom Icon Packs
+
+```js
+window.XTend.icons.register({
+  id: 'brand',
+  label: 'Corporate Design Icons',
+  cdnAllowed: false,
+  icons: {
+    product: {
+      aliases: ['logo-mark'],
+      nodes: [
+        { tag: 'path', attrs: { d: 'M12 3 21 8v8l-9 5-9-5V8Z' } }
+      ]
+    }
+  }
+});
+```
+
+Packs koennen eigene SVG-Node-Descriptoren, einzelne Path-Strings, inline SVG-Records oder URL-Records enthalten. Remote-Quellen sind nicht Default von XTend; sie muessen bewusst vom Host als `src` oder Pack-URL bereitgestellt werden.
+
+## ECH-WP-04 Control-Regel
+
+Keine Textglyphen als Controls: Close-, Menu-, Disclosure-, Status- und Action-Controls duerfen nicht ueber sichtbare Zeichen wie `x`, `&times;`, Pfeile oder Emoji gestaltet werden. Verwende `x-icon`, Inline-SVG oder eine tokenisierte CSS-Grafik.
+
+Pflicht fuer Icon-Controls:
+
+- Der Button hat einen zugaenglichen Namen, z.B. `aria-label`.
+- Der Button exponiert einen stabilen Control-Part, z.B. `part="close control"`.
+- Die Grafik exponiert einen Icon-Part, z.B. `part="control icon"` oder `part="close-icon control icon"`.
+- Das Core-Pack enthaelt fuer Framework-Controls mindestens `close`, `menu`, `chevron-left`, `chevron-right`, `chevron-up`, `chevron-down`, `success`, `warning`, `error` und `info`.
+- Eigene Icon Packs muessen lokale SVG-Node-Descriptoren oder sichere `src`-Quellen verwenden; CDN-Abhaengigkeiten sind keine XTend-Default-Basis.
+
+## RMT und Fabric
+
+`x-icon` deklariert `xtendRmtMetadata` mit `adapter: 'xtend.component'`, `templateMode: 'dom_descriptor'`, `shellAuthoring.attributes` und der Boundary `no-rmt-kernel-import-of-xtend-types`. RMT kann Icons dadurch in App Shells, Navigationen, Buttons oder Docs-Templates authoren, ohne den XTend-Kernel oder einen Icon-Vendor zu importieren.
+
+Fabric konsumiert:
+
+- `icon-ready`
+- `icon-missing`
+- `icon-pack-registered`
+- State-Key `xicon-state-<id>`
+- `snapshot()`
+
+## Styling & Theming
+
+```css
+x-icon {
+  --xtend-icon-size: 1rem;
+  --xtend-icon-color: currentColor;
+  --xtend-icon-stroke-width: 2;
+}
+```
+
+Das Icon folgt `currentColor` und integriert sich dadurch in `x-theme`, `x-header`, `x-button`, `x-menu` und eigene Corporate-Design-Tokens. Im Forced-Colors-Modus bleibt die Komponente ueber Systemfarben lesbar.
+
+## Accessibility
+
+- mit `label` rendert der Host `role="img"` und `aria-label`
+- ohne Label oder mit `decorative` rendert die Komponente `aria-hidden`
+- URL-Icons erhalten ein leeres `alt`, wenn sie dekorativ sind
+- `icon-missing` ist als diagnostisches Event verfuegbar, ohne Screenreader mit Fehlersignalen zu belasten