@maggioli-design-system/magma 2.0.0-beta.2 → 2.0.0-beta.3

package/dist/documentation.json

@@ -1,5 +1,5 @@
 {
-  "timestamp": "2026-06-19T18:24:43",
+  "timestamp": "2026-07-03T14:20:50",
   "compiler": {
     "name": "@stencil/core",
     "version": "4.43.5",
@@ -19,13 +19,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `closable` is `false`, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` whenever the selected child set changes, carrying the live `children` NodeList and the `selected` index/indices as a string.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`closable`** governs whether the active panel can be dismissed; set it to `false` to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, heading `typography`, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../../mds-accordion-item) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Informazioni generali\">\n    <mds-text>Contenuto della prima sezione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Requisiti tecnici\">\n    <mds-text>Contenuto della seconda sezione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Contatti\">\n    <mds-text>Contenuto della terza sezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Panoramica\" selected>\n    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Dettagli\">\n    <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n  <mds-accordion-item label=\"Documentazione\" selected>\n    <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Video tutorial\" selected>\n    <mds-text>Guarda i video di formazione nel portale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"FAQ\">\n    <mds-text>Consulta le domande frequenti.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `closable=\"false\"` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion closable=\"false\">\n  <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n    <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n    <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n    <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Heading Typography on Items\n\nSet `typography` on each `mds-accordion-item` to align the header level with the document outline. Defaults to `h5`; use a heavier heading for more prominent section headers.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Sezione principale\" typography=\"h3\">\n    <mds-text>Contenuto della sezione principale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Sottosezione\" typography=\"h4\">\n    <mds-text>Contenuto della sottosezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to the Change Event\n\nListen for `mdsAccordionChange` to react when the active panel changes. The event detail carries `children` (the full NodeList) and `selected` (a string index or comma-separated indices when `multiple` is set).\n\n```html\n<mds-accordion id=\"faq-accordion\">\n  <mds-accordion-item label=\"Cos'e' Magma?\">\n    <mds-text>Magma e' il design system di Maggioli.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Come si installa?\">\n    <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {\n    console.log('Pannello aperto:', event.detail.selected);\n  });\n</script>\n```\n\n#### Rich Slotted Content in Items\n\nThe default slot of each `mds-accordion-item` accepts text, HTML elements, and other Magma components - use this to build complex content panels.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Dettagli del documento\">\n    <mds-text typography=\"label\">Nome file</mds-text>\n    <mds-text>Relazione_annuale_2024.pdf</mds-text>\n    <mds-hr></mds-hr>\n    <mds-text typography=\"label\">Dimensione</mds-text>\n    <mds-text>2,4 MB</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Azioni disponibili\">\n    <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n    <mds-button label=\"Condividi\" icon=\"mi/baseline/share\" variant=\"secondary\" tone=\"outline\"></mds-button>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Styling Customization\n\nStyle the accordion only through its documented `--mds-accordion-*` CSS custom properties. The properties cascade into all child `mds-accordion-item` elements from the host.\n\n```css\n.custom-faq mds-accordion {\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n  --mds-accordion-border-width: 1px;\n  --mds-accordion-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-description-color: rgb(var(--tone-neutral-04));\n  --mds-accordion-duration: 200ms;\n  --mds-accordion-padding-selected: var(--spacing-600) 0 var(--spacing-800) 0;\n  --mds-accordion-padding-unselected: var(--spacing-400) 0;\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-accordion>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Item Children Directly in the Accordion Slot\n\nThe default slot of `<mds-accordion>` is designed exclusively for `<mds-accordion-item>` elements. Placing raw HTML or other components there bypasses the parent's selection coordination and breaks the compound component communication.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <div>\n    <h3>Sezione uno</h3>\n    <p>Contenuto della sezione.</p>\n  </div>\n</mds-accordion>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Sezione uno\">\n    <mds-text>Contenuto della sezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\n`<mds-accordion-item>` is a compound child and relies on the parent to assign its `id` and manage selection state. Used standalone it has no coordinator and its `mdsAccordionItemSelect` / `mdsAccordionItemUnselect` events go unanswered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion-item label=\"Domanda frequente\">\n  <mds-text>Risposta alla domanda.</mds-text>\n</mds-accordion-item>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Domanda frequente\">\n    <mds-text>Risposta alla domanda.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Set `closable` to the String `\"false\"`\n\n`closable` is a boolean prop. In HTML, any non-empty attribute value - including the string `\"false\"` - is truthy, so `closable=\"false\"` does NOT disable the closable behavior; it is identical to `closable=\"true\"`. Remove the attribute entirely to let the default (`true`) apply, or omit it on purpose when you want `closable` enforced.\n\n```html\n<!-- 🚫 INCORRECT - still closable, this is a no-op -->\n<mds-accordion closable=\"false\">\n  <mds-accordion-item label=\"Passaggio obbligatorio\" selected>\n    <mds-text>Questo pannello dovrebbe restare sempre aperto.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<!-- ✅ CORRECT - use the attribute without a value (boolean form) -->\n<!-- Note: to DISABLE closable, set the prop to false in JS, or use a framework binding -->\n<!-- In plain HTML there is no boolean \"false\" form; control it via JS: -->\n<mds-accordion id=\"mandatory-accordion\">\n  <mds-accordion-item label=\"Passaggio obbligatorio\" selected>\n    <mds-text>Questo pannello resta sempre aperto.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n<script>\n  document.getElementById('mandatory-accordion').closable = false;\n</script>\n```\n\n#### Do Not Listen to Native `click` or `toggle` Instead of `mdsAccordionChange`\n\nThe selection logic lives inside shadow DOM. Native `click` events from inside the shadow root may not propagate as expected, and there is no native `toggle` event on this component. Always listen for `mdsAccordionChange` to react to open/close changes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion id=\"my-accordion\">\n  <mds-accordion-item label=\"Sezione A\">\n    <mds-text>Contenuto A.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n<script>\n  document.getElementById('my-accordion').addEventListener('click', (e) => {\n    // unreliable - shadow DOM events may not surface correctly\n    console.log('clicked');\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-accordion id=\"my-accordion\">\n  <mds-accordion-item label=\"Sezione A\">\n    <mds-text>Contenuto A.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n<script>\n  document.getElementById('my-accordion').addEventListener('mdsAccordionChange', (e) => {\n    console.log('Selezione corrente:', e.detail.selected);\n  });\n</script>\n```\n\n#### Do Not Mix `mds-accordion-item` and `mds-accordion-timer-item`\n\n[`mds-accordion-timer`](../../mds-accordion-timer) and its child [`mds-accordion-timer-item`](../../mds-accordion-timer-item) are a separate compound pair. Slotting timer items into a plain accordion (or vice versa) breaks internal event wiring because each parent only listens for its own child's events.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <mds-accordion-timer-item label=\"Avanzamento automatico\">\n    <mds-text>Contenuto con timer.</mds-text>\n  </mds-accordion-timer-item>\n</mds-accordion>\n\n<!-- ✅ CORRECT - use mds-accordion-timer with mds-accordion-timer-item -->\n<mds-accordion-timer>\n  <mds-accordion-timer-item label=\"Avanzamento automatico\">\n    <mds-text>Contenuto con timer.</mds-text>\n  </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the `--mds-accordion-*` CSS custom properties and the documented `::part()` names on `mds-accordion-item` (`content`, `icon`, `label`). Targeting undocumented internals via `>>>` or deep class selectors couples code to the Shadow DOM implementation and breaks on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-accordion >>> .action {\n  font-weight: bold;\n}\nmds-accordion-item::part(spinner) {\n  display: none;\n}\n\n/* ✅ CORRECT */\nmds-accordion {\n  --mds-accordion-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n}\nmds-accordion-item::part(label) {\n  font-style: italic;\n}\n```\n"
+        "1. Description": "The `<mds-accordion>` web component is the compound container of the Magma Design System that groups and orchestrates a set of collapsible `<mds-accordion-item>` panels. It acts as the coordination layer that decides which children are selected.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-accordion-item>` elements.\n- **Single vs. multiple selection**: By default opening one item collapses the others. With `multiple` set, any number of children may stay open at once and selection state is reported as a comma-separated list of indices.\n- **Mandatory selection**: When `disable-close` is set, the user cannot collapse the currently open item by clicking it again - one panel always remains open.\n- **Emitted event**: `mdsAccordionChange` whenever the selected child set changes, carrying the live `children` NodeList and the `selected` index/indices as a string.\n\n#### Properties & Visual Configurations\n\nThis component has no shared `variant` / `tone` / `size` props; its two booleans control selection semantics rather than appearance.\n\n#### Other behavioral props\n\n- **`multiple`** switches the group from accordion behavior (one panel at a time) to independent toggles, allowing several panels open simultaneously.\n- **`disableClose`** prevents the active panel from being dismissed; set it to force at least one panel to stay expanded at all times.\n\nPer-panel presentation - the visible `label`, heading `typography`, and the slotted body content - is configured on each `<mds-accordion-item>` child, not on the accordion itself.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-accordion>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more [`mds-accordion-item`](../../mds-accordion-item) elements as direct children. Each item requires a `label` for its always-visible header.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Informazioni generali\">\n    <mds-text>Contenuto della prima sezione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Requisiti tecnici\">\n    <mds-text>Contenuto della seconda sezione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Contatti\">\n    <mds-text>Contenuto della terza sezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Pre-selected Item on Load\n\nSet the `selected` attribute on a child to have that panel start open. Only one item should be pre-selected in single-selection mode (the default).\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Panoramica\" selected>\n    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Dettagli\">\n    <mds-text>Questa sezione e' chiusa inizialmente.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Selection Mode\n\nSet `multiple` to allow any number of panels to be open at the same time. The `mdsAccordionChange` event then reports a comma-separated list of open indices.\n\n```html\n<mds-accordion multiple>\n  <mds-accordion-item label=\"Documentazione\" selected>\n    <mds-text>Scarica la guida utente in formato PDF.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Video tutorial\" selected>\n    <mds-text>Guarda i video di formazione nel portale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"FAQ\">\n    <mds-text>Consulta le domande frequenti.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Mandatory Selection (Non-closable)\n\nSet `disable-close` to prevent the open panel from being collapsed. The currently expanded item stays open even when the user clicks its header again - exactly one panel is always visible.\n\n```html\n<mds-accordion disable-close>\n  <mds-accordion-item label=\"Passaggio 1 - Dati anagrafici\" selected>\n    <mds-text>Inserisci nome, cognome e codice fiscale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passaggio 2 - Residenza\">\n    <mds-text>Inserisci indirizzo e comune di residenza.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passaggio 3 - Riepilogo\">\n    <mds-text>Verifica i dati inseriti prima di inviare.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Heading Typography on Items\n\nSet `typography` on each `mds-accordion-item` to align the header level with the document outline. Defaults to `h5`; use a heavier heading for more prominent section headers.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Sezione principale\" typography=\"h3\">\n    <mds-text>Contenuto della sezione principale.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Sottosezione\" typography=\"h4\">\n    <mds-text>Contenuto della sottosezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to the Change Event\n\nListen for `mdsAccordionChange` to react when the active panel changes. The event detail carries `children` (the full NodeList) and `selected` (a string index or comma-separated indices when `multiple` is set).\n\n```html\n<mds-accordion id=\"faq-accordion\">\n  <mds-accordion-item label=\"Cos'e' Magma?\">\n    <mds-text>Magma e' il design system di Maggioli.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Come si installa?\">\n    <mds-text>Segui le istruzioni nel file README del pacchetto.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.getElementById('faq-accordion').addEventListener('mdsAccordionChange', (event) => {\n    console.log('Pannello aperto:', event.detail.selected);\n  });\n</script>\n```\n\n#### Rich Slotted Content in Items\n\nThe default slot of each `mds-accordion-item` accepts text, HTML elements, and other Magma components - use this to build complex content panels.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Dettagli del documento\">\n    <mds-text typography=\"label\">Nome file</mds-text>\n    <mds-text>Relazione_annuale_2024.pdf</mds-text>\n    <mds-hr></mds-hr>\n    <mds-text typography=\"label\">Dimensione</mds-text>\n    <mds-text>2,4 MB</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Azioni disponibili\">\n    <mds-button label=\"Scarica\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n    <mds-button label=\"Condividi\" icon=\"mi/baseline/share\" variant=\"secondary\" tone=\"outline\"></mds-button>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Styling Customization\n\nStyle the accordion only through its documented `--mds-accordion-*` CSS custom properties. The properties cascade into all child `mds-accordion-item` elements from the host.\n\n```css\n.custom-faq mds-accordion {\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n  --mds-accordion-border-width: 1px;\n  --mds-accordion-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-description-color: rgb(var(--tone-neutral-04));\n  --mds-accordion-duration: 200ms;\n  --mds-accordion-padding-selected: var(--spacing-600) 0 var(--spacing-800) 0;\n  --mds-accordion-padding-unselected: var(--spacing-400) 0;\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-accordion>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place Non-Item Children Directly in the Accordion Slot\n\nThe default slot of `<mds-accordion>` is designed exclusively for `<mds-accordion-item>` elements. Placing raw HTML or other components there bypasses the parent's selection coordination and breaks the compound component communication.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <div>\n    <h3>Sezione uno</h3>\n    <p>Contenuto della sezione.</p>\n  </div>\n</mds-accordion>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Sezione uno\">\n    <mds-text>Contenuto della sezione.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\n`<mds-accordion-item>` is a compound child and relies on the parent to assign its `id` and manage selection state. Used standalone it has no coordinator and its `mdsAccordionItemSelect` / `mdsAccordionItemUnselect` events go unanswered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion-item label=\"Domanda frequente\">\n  <mds-text>Risposta alla domanda.</mds-text>\n</mds-accordion-item>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Domanda frequente\">\n    <mds-text>Risposta alla domanda.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Listen to Native `click` or `toggle` Instead of `mdsAccordionChange`\n\nThe selection logic lives inside shadow DOM. Native `click` events from inside the shadow root may not propagate as expected, and there is no native `toggle` event on this component. Always listen for `mdsAccordionChange` to react to open/close changes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion id=\"my-accordion\">\n  <mds-accordion-item label=\"Sezione A\">\n    <mds-text>Contenuto A.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n<script>\n  document.getElementById('my-accordion').addEventListener('click', (e) => {\n    // unreliable - shadow DOM events may not surface correctly\n    console.log('clicked');\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-accordion id=\"my-accordion\">\n  <mds-accordion-item label=\"Sezione A\">\n    <mds-text>Contenuto A.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n<script>\n  document.getElementById('my-accordion').addEventListener('mdsAccordionChange', (e) => {\n    console.log('Selezione corrente:', e.detail.selected);\n  });\n</script>\n```\n\n#### Do Not Mix `mds-accordion-item` and `mds-accordion-timer-item`\n\n[`mds-accordion-timer`](../../mds-accordion-timer) and its child [`mds-accordion-timer-item`](../../mds-accordion-timer-item) are a separate compound pair. Slotting timer items into a plain accordion (or vice versa) breaks internal event wiring because each parent only listens for its own child's events.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <mds-accordion-timer-item label=\"Avanzamento automatico\">\n    <mds-text>Contenuto con timer.</mds-text>\n  </mds-accordion-timer-item>\n</mds-accordion>\n\n<!-- ✅ CORRECT - use mds-accordion-timer with mds-accordion-timer-item -->\n<mds-accordion-timer>\n  <mds-accordion-timer-item label=\"Avanzamento automatico\">\n    <mds-text>Contenuto con timer.</mds-text>\n  </mds-accordion-timer-item>\n</mds-accordion-timer>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the `--mds-accordion-*` CSS custom properties and the documented `::part()` names on `mds-accordion-item` (`content`, `icon`, `label`). Targeting undocumented internals via `>>>` or deep class selectors couples code to the Shadow DOM implementation and breaks on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-accordion >>> .action {\n  font-weight: bold;\n}\nmds-accordion-item::part(spinner) {\n  display: none;\n}\n\n/* ✅ CORRECT */\nmds-accordion {\n  --mds-accordion-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n}\nmds-accordion-item::part(label) {\n  font-style: italic;\n}\n```\n"
       },
       "props": [
         {
-          "name": "closable",
+          "name": "disableClose",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -33,16 +33,16 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "closable",
+          "attr": "disable-close",
           "reflectToAttr": false,
-          "docs": "Specifies if an item can be closed by user",
+          "docs": "Prevents the user from closing the currently open item, forcing at least one panel to stay expanded",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -195,7 +195,7 @@
       ],
       "usage": {
         "1. Description": "The `<mds-accordion-item>` web component is a single collapsible panel of the Magma Design System, designed to be slotted inside its parent [`<mds-accordion>`](../../mds-accordion). It renders a header button paired with an expandable content region; the parent controls which items are open.\n\n#### Semantic Behavior\n\n- **Compound child only**: Must be placed as a direct default-slot child of `<mds-accordion>`; it is not used standalone, and the parent's slot should hold only `mds-accordion-item` elements, not mixed child types.\n- **Parent-driven selection**: Clicking the header requests a toggle, but the authoritative open/closed state is resolved by the parent - in single mode opening one item closes its siblings, while in `multiple` mode each item toggles independently.\n- **Emitted events**: `mdsAccordionItemSelect` on open, `mdsAccordionItemUnselect` on close, and `mdsAccordionItemChange` on any toggle, each carrying `{ id, selected }`.\n- **Default slot**: Holds the collapsible body content (text, HTML, or components).\n\n#### Properties & Visual Configurations\n\n- **`label`** sets the always-visible header text shown whether the item is open or closed.\n- **`selected`** controls whether the panel is expanded; leave it to the parent to manage in coordinated accordions, or set it initially to have a panel start open.\n- **`typography`** picks the title style applied to the header label, defaulting to `h5`. Choose a heavier heading level (`h1`–`h4`) for more prominent section headers or `action` for a compact, control-like header; match it to the document's heading hierarchy so the accordion reads correctly to assistive technology.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../../mds-accordion). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Cos'e' Magma?\">\n    <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Come si installa?\">\n    <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"E' compatibile con React?\">\n    <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent resolves conflicts on load in single mode, so only set it on one item unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Introduzione\" selected>\n    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Prerequisiti\">\n    <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n  <mds-accordion-item label=\"Configurazione di base\">\n    <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Configurazione avanzata\" selected>\n    <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n    <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `closable` prop to `false` via JavaScript to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked (single mode only). Because `closable` defaults to `true`, do not set it via the HTML attribute - assign it through the element property instead.\n\n```html\n<mds-accordion id=\"steps\">\n  <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n    <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passo 2 - Configurazione\">\n    <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.querySelector('#steps').closable = false;\n</script>\n```\n\n#### Typography for Section Headers\n\nUse `typography` to match the panel header to the surrounding document hierarchy. Default is `h5`; use `h3` or `h4` for top-level FAQ sections, `action` for compact control-bar items.\n\n```html\n<!-- FAQ section at heading level 3 -->\n<mds-accordion>\n  <mds-accordion-item label=\"Come gestisco gli aggiornamenti?\" typography=\"h3\">\n    <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Posso personalizzare i colori?\" typography=\"h3\">\n    <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Rich Slot Content\n\nThe default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Dettagli del progetto\">\n    <mds-text typography=\"h6\">Tecnologie utilizzate</mds-text>\n    <mds-list>\n      <mds-list-item label=\"StencilJS\"></mds-list-item>\n      <mds-list-item label=\"TypeScript\"></mds-list-item>\n      <mds-list-item label=\"Storybook\"></mds-list-item>\n    </mds-list>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Contatti del team\">\n    <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to Item Events\n\n`mdsAccordionItemChange` fires on every toggle; `mdsAccordionItemSelect` fires only on open; `mdsAccordionItemUnselect` fires only on close. Use `mdsAccordionItemChange` when you only need to react to any state change, or the specific event when you need to handle open and close differently.\n\n```html\n<mds-accordion id=\"faq\">\n  <mds-accordion-item id=\"item-faq-1\" label=\"Domanda frequente 1\">\n    <mds-text>Risposta alla prima domanda.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item id=\"item-faq-2\" label=\"Domanda frequente 2\">\n    <mds-text>Risposta alla seconda domanda.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {\n    console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);\n  });\n\n  document.querySelector('#item-faq-1').addEventListener('mdsAccordionItemSelect', (e) => {\n    console.log('faq-1 opened');\n  });\n</script>\n```\n\n#### Styling Customization\n\nStyle each item only through its documented `--mds-accordion-item-*` CSS custom properties. Setting vars on the parent `<mds-accordion>` propagates to all children via the `--mds-accordion-*` cascade variables the items consume.\n\n```css\n/* Customize all items via the parent */\nmds-accordion {\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n  --mds-accordion-border-width: 1px;\n  --mds-accordion-duration: 200ms;\n}\n\n/* Or target a single item directly */\n.sidebar mds-accordion-item {\n  --mds-accordion-item-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-item-padding-selected: 1.5rem 0 2.5rem 0;\n  --mds-accordion-item-padding-unselected: 1rem 0;\n}\n```\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-accordion-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Accordion\n\nThe canonical form. Place one or more `<mds-accordion-item>` elements as direct children of [`<mds-accordion>`](../../mds-accordion). Provide `label` for the header text and put the body content in the default slot.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Cos'e' Magma?\">\n    <mds-text>Magma e' il design system di Maggioli, basato su web components.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Come si installa?\">\n    <mds-text>Importa il loader e chiama defineCustomElements() nell'entry point.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"E' compatibile con React?\">\n    <mds-text>Si', usa il pacchetto @maggioli-design-system/magma-react.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Panel Open by Default\n\nSet `selected` on the item you want pre-expanded. The parent resolves conflicts on load in single mode, so only set it on one item unless `multiple` is also set on the parent.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Introduzione\" selected>\n    <mds-text>Questa sezione e' aperta per impostazione predefinita.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Prerequisiti\">\n    <mds-text>Node.js 18+ e un package manager npm o pnpm.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Multiple Panels Open Simultaneously\n\nAdd `multiple` to `<mds-accordion>` so the user can expand more than one panel at once. Individual items do not change - the parent mode governs the behaviour.\n\n```html\n<mds-accordion multiple>\n  <mds-accordion-item label=\"Configurazione di base\">\n    <mds-text>Imposta i token di colore e il tema nell'entry point dell'applicazione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Configurazione avanzata\" selected>\n    <mds-text>Personalizza i CSS custom properties per adattare il tema al brand.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Integrazione CI/CD\" selected>\n    <mds-text>Configura il job di build per generare documentation.json e readme.md.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Non-closable Accordion\n\nSet the parent `disable-close` attribute to prevent the user from collapsing an open panel. An open item then stays open until another item is clicked (single mode only). Because `disableClose` defaults to `false`, just add the boolean attribute to enable mandatory selection.\n\n```html\n<mds-accordion disable-close>\n  <mds-accordion-item label=\"Passo 1 - Installazione\" selected>\n    <mds-text>Esegui npm install @maggioli-design-system/magma per aggiungere il pacchetto.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Passo 2 - Configurazione\">\n    <mds-text>Importa defineCustomElements e registra i componenti nell'app.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Typography for Section Headers\n\nUse `typography` to match the panel header to the surrounding document hierarchy. Default is `h5`; use `h3` or `h4` for top-level FAQ sections, `action` for compact control-bar items.\n\n```html\n<!-- FAQ section at heading level 3 -->\n<mds-accordion>\n  <mds-accordion-item label=\"Come gestisco gli aggiornamenti?\" typography=\"h3\">\n    <mds-text>Ogni release e' documentata nel changelog con note di migrazione.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Posso personalizzare i colori?\" typography=\"h3\">\n    <mds-text>Si', tramite i CSS custom properties esposti da ogni componente.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Rich Slot Content\n\nThe default slot accepts any HTML or components - not just text. Use it for structured content such as lists, forms, or nested components.\n\n```html\n<mds-accordion>\n  <mds-accordion-item label=\"Dettagli del progetto\">\n    <mds-text typography=\"h6\">Tecnologie utilizzate</mds-text>\n    <mds-list>\n      <mds-list-item label=\"StencilJS\"></mds-list-item>\n      <mds-list-item label=\"TypeScript\"></mds-list-item>\n      <mds-list-item label=\"Storybook\"></mds-list-item>\n    </mds-list>\n  </mds-accordion-item>\n  <mds-accordion-item label=\"Contatti del team\">\n    <mds-text>Scrivi a design-system@maggioli.it per supporto tecnico.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Listening to Item Events\n\n`mdsAccordionItemChange` fires on every toggle; `mdsAccordionItemSelect` fires only on open; `mdsAccordionItemUnselect` fires only on close. Use `mdsAccordionItemChange` when you only need to react to any state change, or the specific event when you need to handle open and close differently.\n\n```html\n<mds-accordion id=\"faq\">\n  <mds-accordion-item id=\"item-faq-1\" label=\"Domanda frequente 1\">\n    <mds-text>Risposta alla prima domanda.</mds-text>\n  </mds-accordion-item>\n  <mds-accordion-item id=\"item-faq-2\" label=\"Domanda frequente 2\">\n    <mds-text>Risposta alla seconda domanda.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.querySelector('#faq').addEventListener('mdsAccordionItemChange', (e) => {\n    console.log('item changed:', e.detail.id, 'selected:', e.detail.selected);\n  });\n\n  document.querySelector('#item-faq-1').addEventListener('mdsAccordionItemSelect', (e) => {\n    console.log('faq-1 opened');\n  });\n</script>\n```\n\n#### Styling Customization\n\nStyle each item only through its documented `--mds-accordion-item-*` CSS custom properties. Setting vars on the parent `<mds-accordion>` propagates to all children via the `--mds-accordion-*` cascade variables the items consume.\n\n```css\n/* Customize all items via the parent */\nmds-accordion {\n  --mds-accordion-border-color: rgb(var(--variant-primary-05));\n  --mds-accordion-border-width: 1px;\n  --mds-accordion-duration: 200ms;\n}\n\n/* Or target a single item directly */\n.sidebar mds-accordion-item {\n  --mds-accordion-item-color: rgb(var(--tone-neutral-02));\n  --mds-accordion-item-padding-selected: 1.5rem 0 2.5rem 0;\n  --mds-accordion-item-padding-unselected: 1rem 0;\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-accordion-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `mds-accordion-item` Outside `mds-accordion`\n\nThe item relies on the parent to assign its `id`, manage sibling state, and emit coordinated change events. Placing it standalone breaks selection, event coordination, and accessibility labelling.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion-item label=\"Sezione autonoma\">\n  <mds-text>Contenuto senza accordeon genitore.</mds-text>\n</mds-accordion-item>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Sezione autonoma\">\n    <mds-text>Contenuto all'interno del genitore corretto.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Wrap `mds-accordion-item` in Extra Elements\n\nThe parent queries its children directly with `querySelectorAll('mds-accordion-item')`; an intervening wrapper breaks that query, so items are never assigned an `id` and events are never coordinated.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <div class=\"group\">\n    <mds-accordion-item label=\"FAQ 1\">\n      <mds-text>Risposta alla prima domanda.</mds-text>\n    </mds-accordion-item>\n  </div>\n</mds-accordion>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"FAQ 1\">\n    <mds-text>Risposta alla prima domanda.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Set `label` via the Default Slot\n\n`label` is a required prop that drives the header button text, `aria-expanded`, and keyboard focus; the default slot holds only the collapsible body content. Putting header text in the slot places it inside the body region and leaves the required `label` prop empty, breaking both layout and accessibility.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <mds-accordion-item>\n    Dettagli dell'ordine\n  </mds-accordion-item>\n</mds-accordion>\n\n<!-- ✅ CORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Dettagli dell'ordine\">\n    <mds-text>Numero ordine: 12345, data: 01/06/2026.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n\n#### Do Not Override Open/Close State by Piercing the Shadow DOM\n\n`selected` is reflected as a host attribute and is writable via JavaScript. Targeting the internal `.content` div or `.icon` element via `::part()`, `>>>`, or undocumented class names to show/hide content manually bypasses the coordinated state machine and breaks sibling sync.\n\n```css\n/* 🚫 INCORRECT */\nmds-accordion-item::part(content) {\n  display: block !important;\n}\nmds-accordion-item >>> .content {\n  grid-template-rows: 1fr;\n}\n```\n\n```js\n/* ✅ CORRECT - toggle via the reflected property */\nconst item = document.querySelector('mds-accordion-item#item-0');\nitem.selected = true;\n```\n\n#### Do Not Listen for Native `click` or `change` Events Instead of the Documented `mds*` Events\n\nThe header click is handled inside the shadow DOM; the native `click` event does not bubble out reliably. The documented events `mdsAccordionItemChange`, `mdsAccordionItemSelect`, and `mdsAccordionItemUnselect` are the designed surface.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion id=\"faq\">\n  <mds-accordion-item id=\"q1\" label=\"Domanda 1\">\n    <mds-text>Risposta 1.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n\n<script>\n  document.querySelector('#q1').addEventListener('click', () => {\n    console.log('clicked - unreliable from outside shadow DOM');\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<script>\n  document.querySelector('#q1').addEventListener('mdsAccordionItemChange', (e) => {\n    console.log('stato:', e.detail.selected);\n  });\n</script>\n```\n\n#### Do Not Use `<details>`/`<summary>` Inside the Slot as a Second Disclosure Layer\n\nThe item already is a styled disclosure widget. Nesting a native `<details>` inside the slot creates redundant expand/collapse semantics, duplicates keyboard interactions, and produces conflicting visual states.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-accordion>\n  <mds-accordion-item label=\"Configurazione\">\n    <details>\n      <summary>Mostra dettagli</summary>\n      <p>Parametri avanzati di configurazione.</p>\n    </details>\n  </mds-accordion-item>\n</mds-accordion>\n\n<!-- ✅ CORRECT - put content directly in the slot -->\n<mds-accordion>\n  <mds-accordion-item label=\"Configurazione\">\n    <mds-text typography=\"h6\">Parametri avanzati</mds-text>\n    <mds-text>Descrizione dei parametri di configurazione avanzata.</mds-text>\n  </mds-accordion-item>\n</mds-accordion>\n```\n"
       },
       "props": [
@@ -1838,36 +1838,6 @@
           "annotation": "prop",
           "docs": "Text color for the count badge in the stack"
         },
-        {
-          "name": "--mds-avatar-stack-item-lg-border",
-          "annotation": "prop",
-          "docs": "Border width for large avatars"
-        },
-        {
-          "name": "--mds-avatar-stack-item-lg-offset",
-          "annotation": "prop",
-          "docs": "Overlap factor for large avatars (higher = more overlap)"
-        },
-        {
-          "name": "--mds-avatar-stack-item-lg-size",
-          "annotation": "prop",
-          "docs": "Size of large avatars in the stack"
-        },
-        {
-          "name": "--mds-avatar-stack-item-md-border",
-          "annotation": "prop",
-          "docs": "Border width for medium avatars"
-        },
-        {
-          "name": "--mds-avatar-stack-item-md-offset",
-          "annotation": "prop",
-          "docs": "Overlap factor for medium avatars"
-        },
-        {
-          "name": "--mds-avatar-stack-item-md-size",
-          "annotation": "prop",
-          "docs": "Size of medium avatars in the stack"
-        },
         {
           "name": "--mds-avatar-stack-item-offset",
           "annotation": "prop",
@@ -1882,21 +1852,6 @@
           "name": "--mds-avatar-stack-item-size",
           "annotation": "prop",
           "docs": "Computed active size (based on selected size)"
-        },
-        {
-          "name": "--mds-avatar-stack-item-sm-border",
-          "annotation": "prop",
-          "docs": "Border width for small avatars"
-        },
-        {
-          "name": "--mds-avatar-stack-item-sm-offset",
-          "annotation": "prop",
-          "docs": "Overlap factor for small avatars"
-        },
-        {
-          "name": "--mds-avatar-stack-item-sm-size",
-          "annotation": "prop",
-          "docs": "Size of small avatars in the stack"
         }
       ],
       "slots": [],
@@ -2259,13 +2214,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **Dismissal**: When `deletable` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`cockade`** (default `true`) wraps the leading `icon` in a colored decorative badge; disable it for a flatter icon presentation.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`deletable`** opts the banner into being dismissible - choose it for transient or user-acknowledged messages rather than persistent context.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n  <mds-text typography=\"detail\">\n    Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n  </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n  <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n  <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n  <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n  <mds-text typography=\"detail\">\n    La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n  </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). `cockade` is `true` by default, wrapping the icon in a colored badge; set `cockade=\"false\"` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n  <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" cockade=\"false\">\n  <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `deletable` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" deletable id=\"promo-banner\">\n  <mds-text typography=\"detail\">\n    Scopri le nuove funzioni premium disponibili nel tuo piano.\n  </mds-text>\n</mds-banner>\n\n<script>\n  document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n    document.querySelector('#promo-banner').remove();\n  });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is rendered only when at least one `[slot=\"action\"]` child is present. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n  <mds-text typography=\"detail\">\n    La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n    ma non puoi utilizzare le funzioni premium.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n  <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. Use `strong` for maximum contrast, `weak` (default) for subtle background tints, and `box` for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n  <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n  <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n  <mds-text typography=\"detail\">\n    Tre nuovi moduli sono stati aggiunti alla piattaforma.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n  <mds-text typography=\"detail\">\n    L'analisi ha rilevato tre anomalie nel documento caricato.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n#### Dismissible Banner inside mds-modal\n\nWhen `deletable` is set and the banner lives inside an `<mds-modal>`, activating the close button emits `mdsBannerClose` and also closes the modal automatically - no extra JavaScript needed.\n\n```html\n<mds-modal opened>\n  <mds-banner variant=\"warning\" deletable headline=\"Attenzione\">\n    <mds-text typography=\"detail\">\n      Stai per eliminare tutti i dati. L'azione non e reversibile.\n    </mds-text>\n    <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n    <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Elimina</mds-button>\n  </mds-banner>\n</mds-modal>\n```\n\n#### CSS Custom Property Customization\n\nOverride appearance only through the documented `--mds-banner-*` custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n  --mds-banner-background: rgb(var(--variant-primary-03));\n  --mds-banner-color: rgb(var(--tone-kaolin-10));\n  --mds-banner-headline-color: rgb(var(--tone-kaolin-10));\n  --mds-banner-radius: var(--radius-sm);\n  --mds-banner-shadow: 0 4px 16px rgb(var(--tone-neutral-02) / 0.15);\n}\n```\n",
+        "1. Description": "The `<mds-banner>` web component is the Magma Design System surface for contextual, in-page messages - informational notices, status callouts, and alerts - pairing an optional icon, headline, body text, and inline actions inside a single themed box.\n\n#### Semantic Behavior\n\n- **Variant-driven ARIA**: The announcement role is derived from `variant`, not set manually. `error` and `warning` announce assertively (`role=\"alert\"`); `ai`, `info`, `primary`, and `success` announce politely (`role=\"status\"`); `light` and `dark` are decorative and silent.\n- **Headline as label**: When `headline` is set it also becomes the banner's accessible label.\n- **Dismissal**: When `deletable` is true a close button is rendered; activating it emits `mdsBannerClose` and, if the banner sits inside an `mds-modal`, closes that modal.\n- **Localized close button**: The close button title is localized (el/en/es/it) from the host language.\n- **Action slot**: The `action` region is rendered only when a direct `[slot=\"action\"]` child is present, so banners without actions produce no empty container.\n\n#### Properties & Visual Configurations\n\nThis component uses the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); pick the `variant` according to the message's semantic weight, since it also governs the ARIA behavior described above. `tone` is limited to the minimal-box set (`'weak'`, `'strong'`, `'box'`), defaulting to `'weak'`.\n\n#### Other behavioral props\n\n- **`hideCockade`** (default `false`) removes the colored decorative badge wrapping the leading `icon`; set it for a flatter icon presentation.\n- **`icon`** is a Magma icon library slug shown at the top-left, surfaced as decorative.\n- **`deletable`** opts the banner into being dismissible - choose it for transient or user-acknowledged messages rather than persistent context.\n- The **default slot** carries the body text/markup; the **`action` slot** holds inline controls, with `mds-button` the recommended element.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-banner>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Informational Banner\n\nThe baseline usage. Provide `variant=\"info\"` and place the body copy in the default slot. The component derives `role=\"status\"` and `aria-live=\"polite\"` automatically from the variant.\n\n```html\n<mds-banner variant=\"info\">\n  <mds-text typography=\"detail\">\n    Il sistema e in manutenzione programmata dalle 22:00 alle 23:00.\n  </mds-text>\n</mds-banner>\n```\n\n#### Status Variants\n\nPick the variant that matches the message's semantic weight. `error` and `warning` set `role=\"alert\"` with assertive live region; the others use `role=\"status\"` with polite announcement.\n\n```html\n<!-- Esito positivo -->\n<mds-banner variant=\"success\">\n  <mds-text typography=\"detail\">Dati salvati correttamente.</mds-text>\n</mds-banner>\n\n<!-- Avviso non bloccante -->\n<mds-banner variant=\"warning\">\n  <mds-text typography=\"detail\">La sessione scadra tra 5 minuti.</mds-text>\n</mds-banner>\n\n<!-- Errore bloccante -->\n<mds-banner variant=\"error\">\n  <mds-text typography=\"detail\">Impossibile completare l'operazione. Riprovare.</mds-text>\n</mds-banner>\n```\n\n#### Banner with Headline\n\nUse the `headline` prop to add a title above the body text. The headline is also used as the banner's accessible label (`aria-label`).\n\n```html\n<mds-banner variant=\"warning\" headline=\"Licenza in scadenza\">\n  <mds-text typography=\"detail\">\n    La licenza del servizio scadra tra 7 giorni. Rinnova ora per non interrompere il servizio.\n  </mds-text>\n</mds-banner>\n```\n\n#### Banner with Icon\n\nSet `icon` to a Magma icon slug. The icon is decorative (`aria-hidden=\"true\"`). The colored badge wrapping the icon is shown by default; add `hide-cockade` for a flatter look.\n\n```html\n<!-- Con cockade (default) -->\n<mds-banner variant=\"info\" icon=\"mi/baseline/info\" headline=\"Aggiornamento disponibile\">\n  <mds-text typography=\"detail\">E disponibile una nuova versione dell'applicazione.</mds-text>\n</mds-banner>\n\n<!-- Senza cockade -->\n<mds-banner variant=\"success\" icon=\"mi/baseline/check-circle\" hide-cockade>\n  <mds-text typography=\"detail\">Operazione completata.</mds-text>\n</mds-banner>\n```\n\n#### Dismissible Banner\n\nSet `deletable` to show a close button. The button emits `mdsBannerClose` when activated. Listen for the event to remove the banner from the DOM or update application state.\n\n```html\n<mds-banner variant=\"info\" deletable id=\"promo-banner\">\n  <mds-text typography=\"detail\">\n    Scopri le nuove funzioni premium disponibili nel tuo piano.\n  </mds-text>\n</mds-banner>\n\n<script>\n  document.querySelector('#promo-banner').addEventListener('mdsBannerClose', () => {\n    document.querySelector('#promo-banner').remove();\n  });\n</script>\n```\n\n#### Banner with Action Buttons\n\nSlot `<mds-button>` elements with `slot=\"action\"` to add inline controls. The action region is rendered only when at least one `[slot=\"action\"]` child is present. Match the button variant to the banner variant for visual consistency.\n\n```html\n<mds-banner variant=\"warning\" headline=\"Abbonamento scaduto\">\n  <mds-text typography=\"detail\">\n    La licenza di questo servizio e scaduta. Il servizio continua a funzionare\n    ma non puoi utilizzare le funzioni premium.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n  <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova abbonamento</mds-button>\n</mds-banner>\n```\n\n#### Tone for Visual Emphasis\n\n`tone` controls emphasis without changing the semantic variant. Use `strong` for maximum contrast, `weak` (default) for subtle background tints, and `box` for high-contrast placements. `mds-banner` accepts only `weak`, `strong`, and `box` - not `outline` or `text`.\n\n```html\n<!-- Bassa enfasi (default) -->\n<mds-banner variant=\"error\" tone=\"weak\">\n  <mds-text typography=\"detail\">Errore di validazione nei campi del modulo.</mds-text>\n</mds-banner>\n\n<!-- Alta enfasi -->\n<mds-banner variant=\"error\" tone=\"strong\">\n  <mds-text typography=\"detail\">Account bloccato per attivita sospetta. Contatta il supporto.</mds-text>\n</mds-banner>\n```\n\n#### Dark and Light Decorative Variants\n\n`variant=\"dark\"` and `variant=\"light\"` are neutral, decorative banners without an ARIA live region (`role=\"presentation\"`). Use them for non-critical UI chrome - announcements or promotional content that does not require immediate attention.\n\n```html\n<mds-banner variant=\"dark\" tone=\"strong\" headline=\"Novita del mese\">\n  <mds-text typography=\"detail\">\n    Tre nuovi moduli sono stati aggiunti alla piattaforma.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"light\" tone=\"text\">Scopri</mds-button>\n</mds-banner>\n```\n\n#### AI Variant\n\nUse `variant=\"ai\"` to mark banners that present AI-generated content or AI-powered suggestions. The variant emits a polite `role=\"status\"` live announcement.\n\n```html\n<mds-banner variant=\"ai\" icon=\"mi/baseline/auto-awesome\" headline=\"Suggerimento IA\">\n  <mds-text typography=\"detail\">\n    L'analisi ha rilevato tre anomalie nel documento caricato.\n  </mds-text>\n  <mds-button slot=\"action\" variant=\"ai\" tone=\"outline\">Visualizza dettagli</mds-button>\n</mds-banner>\n```\n\n#### Dismissible Banner inside mds-modal\n\nWhen `deletable` is set and the banner lives inside an `<mds-modal>`, activating the close button emits `mdsBannerClose` and also closes the modal automatically - no extra JavaScript needed.\n\n```html\n<mds-modal opened>\n  <mds-banner variant=\"warning\" deletable headline=\"Attenzione\">\n    <mds-text typography=\"detail\">\n      Stai per eliminare tutti i dati. L'azione non e reversibile.\n    </mds-text>\n    <mds-button slot=\"action\" variant=\"warning\" tone=\"outline\">Annulla</mds-button>\n    <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Elimina</mds-button>\n  </mds-banner>\n</mds-modal>\n```\n\n#### CSS Custom Property Customization\n\nOverride appearance only through the documented `--mds-banner-*` custom properties. Set them on the host or a parent selector; use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.featured-notice mds-banner {\n  --mds-banner-background: rgb(var(--variant-primary-03));\n  --mds-banner-color: rgb(var(--tone-kaolin-10));\n  --mds-banner-headline-color: rgb(var(--tone-kaolin-10));\n  --mds-banner-radius: var(--radius-sm);\n  --mds-banner-shadow: 0 4px 16px rgb(var(--tone-neutral-02) / 0.15);\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-banner>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use an Invalid `tone` Value\n\n`mds-banner.tone` is typed as `ToneMinimalBoxVariantType`, which allows only `weak`, `strong`, and `box`. Values like `outline` or `text` are not accepted and will silently fall back to the default.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-banner variant=\"info\" tone=\"outline\">\n  <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n\n<!-- ✅ CORRECT -->\n<mds-banner variant=\"info\" tone=\"weak\">\n  <mds-text typography=\"detail\">Informazione di sistema.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Override the ARIA Role Manually\n\nThe component derives `role` and `aria-live` from `variant` - overriding them breaks the intentional severity mapping (`error`/`warning` assertive, others polite).\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-banner variant=\"info\" role=\"alert\" aria-live=\"assertive\">\n  <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n\n<!-- ✅ CORRECT - let variant drive the ARIA behavior -->\n<mds-banner variant=\"info\">\n  <mds-text typography=\"detail\">Aggiornamento disponibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Slot an `mds-button` into the Default Slot to Add Actions\n\nThe `action` named slot is the correct place for inline controls. Placing buttons in the default slot renders them inside the text region, breaks layout, and loses the flex wrapping the action row provides.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-banner variant=\"warning\">\n  <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n  <mds-button variant=\"warning\">Rinnova</mds-button>\n</mds-banner>\n\n<!-- ✅ CORRECT -->\n<mds-banner variant=\"warning\">\n  <mds-text typography=\"detail\">La licenza sta per scadere.</mds-text>\n  <mds-button slot=\"action\" variant=\"warning\" tone=\"strong\">Rinnova</mds-button>\n</mds-banner>\n```\n\n#### Do Not Set `deletable=\"false\"` to Hide the Close Button\n\n`deletable` is a boolean prop. Setting it to the string `\"false\"` evaluates as truthy in HTML and shows the close button. Remove the attribute (or omit it) to hide the button.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-banner variant=\"error\" deletable=\"false\">\n  <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n\n<!-- ✅ CORRECT -->\n<mds-banner variant=\"error\">\n  <mds-text typography=\"detail\">Errore permanente - non dismissibile.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Use `dark` or `light` for Status Messages\n\n`variant=\"dark\"` and `variant=\"light\"` produce `role=\"presentation\"` with no live region - they are silent to assistive tech. Using them for error, warning, or informational content means screen reader users never receive the announcement.\n\n```html\n<!-- 🚫 INCORRECT - errore silenzioso per tecnologie assistive -->\n<mds-banner variant=\"dark\">\n  <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n\n<!-- ✅ CORRECT -->\n<mds-banner variant=\"error\">\n  <mds-text typography=\"detail\">Errore: impossibile caricare il documento.</mds-text>\n</mds-banner>\n```\n\n#### Do Not Pierce Shadow DOM to Style Internals\n\nThe only supported customization surface is the `--mds-banner-*` CSS custom properties plus the `::part(text)` shadow part. Targeting internal class names with `>>>` or undocumented `::part()` names couples your code to the implementation and breaks on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-banner >>> .headline {\n  font-size: 1.5rem;\n}\nmds-banner::part(content) {\n  padding: 0;\n}\n\n/* ✅ CORRECT */\nmds-banner {\n  --mds-banner-headline-color: rgb(var(--variant-primary-03));\n  --mds-banner-radius: var(--radius-sm);\n}\nmds-banner::part(text) {\n  line-height: 1.6;\n}\n```\n\n#### Do Not Listen to the Native `click` Event for Dismissal\n\nThe component fires `mdsBannerClose` when the close button is activated (both pointer and keyboard). Listening to the native `click` event may miss keyboard activations and does not bubble out of Shadow DOM reliably.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-banner variant=\"info\" deletable id=\"notice\">\n  <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n  document.querySelector('#notice').addEventListener('click', () => {\n    document.querySelector('#notice').remove();\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-banner variant=\"info\" deletable id=\"notice\">\n  <mds-text typography=\"detail\">Avviso temporaneo.</mds-text>\n</mds-banner>\n<script>\n  document.querySelector('#notice').addEventListener('mdsBannerClose', () => {\n    document.querySelector('#notice').remove();\n  });\n</script>\n```\n"
       },
       "props": [
         {
-          "name": "cockade",
+          "name": "deletable",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -2273,16 +2228,10 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "cockade",
-          "reflectToAttr": true,
-          "docs": "Shows a decoration around the banner icon",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
+          "attr": "deletable",
+          "reflectToAttr": false,
+          "docs": "Shows the cross icon to perform cancel/delete action on element",
+          "docsTags": [],
           "values": [
             {
               "type": "boolean"
@@ -2297,21 +2246,21 @@
           "setter": false
         },
         {
-          "name": "deletable",
-          "type": "boolean | undefined",
+          "name": "headline",
+          "type": "string | undefined",
           "complexType": {
-            "original": "boolean",
-            "resolved": "boolean | undefined",
+            "original": "string",
+            "resolved": "string | undefined",
             "references": {}
           },
           "mutable": false,
-          "attr": "deletable",
+          "attr": "headline",
           "reflectToAttr": false,
-          "docs": "Shows the cross icon to perform cancel/delete action on element",
+          "docs": "The title on the top of the banner",
           "docsTags": [],
           "values": [
             {
-              "type": "boolean"
+              "type": "string"
             },
             {
               "type": "undefined"
@@ -2323,21 +2272,27 @@
           "setter": false
         },
         {
-          "name": "headline",
-          "type": "string | undefined",
+          "name": "hideCockade",
+          "type": "boolean | undefined",
           "complexType": {
-            "original": "string",
-            "resolved": "string | undefined",
+            "original": "boolean",
+            "resolved": "boolean | undefined",
             "references": {}
           },
           "mutable": false,
-          "attr": "headline",
-          "reflectToAttr": false,
-          "docs": "The title on the top of the banner",
-          "docsTags": [],
+          "attr": "hide-cockade",
+          "reflectToAttr": true,
+          "docs": "Hides the decoration around the banner icon",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
           "values": [
             {
-              "type": "string"
+              "type": "boolean"
             },
             {
               "type": "undefined"
@@ -3350,13 +3305,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-breadcrumb>` web component is the navigation-trail container of the Magma Design System. It is a compound parent that arranges a sequence of slotted `<mds-breadcrumb-item>` children into a hierarchical path and adds an optional back-navigation control.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-breadcrumb-item>` children.\n- **Selection tracking**: When a child is selected it becomes the single current depth and the others are cleared.\n- **Back button**: When `back` is enabled the host renders a leading arrow that steps selection to the previous item; it auto-disables whenever the first item is current.\n- **Change event**: `mdsBreadcrumbChange` fires after any selection change - via a child click or the back arrow - carrying the new index `id` and the originating `caller` item.\n- **Localized back button**: The back button's `title` is resolved per document language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThis component exposes a single behavioral prop:\n\n- **`back`** toggles the leading arrow control. Leave it enabled (the default) for multi-level trails where users benefit from a one-tap step backwards; disable it for shallow or display-only breadcrumbs where reverse navigation adds no value.\n\nVisual styling (button colors, current-depth color, separator arrow color) is driven by the CSS custom properties documented in [`readme.md`](../readme.md), not by props. The shared `variant` / `tone` / `size` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) do not apply here; per-item labels and selection state live on the `<mds-breadcrumb-item>` children.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Navigation Trail\n\nThe canonical form. Slot one `<mds-breadcrumb-item>` per level and mark the current depth with `selected`. The back arrow is shown by default.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio pratiche\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Pratica 2024/001\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Without the Back Arrow\n\nSet `back=\"false\"` - or remove the attribute - for display-only or shallow breadcrumbs where reverse navigation adds no value. Note: `back` defaults to `true`, so you must explicitly opt out.\n\n```html\n<!-- back is boolean; to disable it, pass the prop as false in frameworks\n     or omit / bind it. In plain HTML use :back=\"false\" (framework) or\n     control it programmatically. -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Impostazioni\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Profilo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\nIn a JavaScript context:\n\n```js\ndocument.querySelector('mds-breadcrumb').back = false;\n```\n\n#### Listening for Navigation Changes\n\n`mdsBreadcrumbChange` fires whenever a child item is clicked or the back arrow is activated. The detail carries the zero-based `id` string of the newly selected item and the originating `caller` element.\n\n```html\n<mds-breadcrumb id=\"nav\">\n  <mds-breadcrumb-item label=\"Dashboard\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Documenti\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Fatture\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n  document.getElementById('nav').addEventListener('mdsBreadcrumbChange', (e) => {\n    console.log('Livello selezionato:', e.detail.id);\n    console.log('Elemento:', e.detail.caller);\n  });\n</script>\n```\n\n#### Programmatic Selection\n\nSet `selected` on the item you want active - the component will deselect the others and update the back button state automatically.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Progetto Alpha\" selected></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sprint 3\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Attivita\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Item Label via `label` Prop\n\nAlways prefer the `label` prop on `<mds-breadcrumb-item>` over the default text slot. The prop is reflected as an HTML attribute, enabling CSS attribute selectors and framework bindings.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Area riservata\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Gestione utenti\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Nuovo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nApply `--mds-breadcrumb-*` vars on the host to retheme the whole trail at once. Use Magma color tokens wrapped in `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Changes on the parent propagate into the child items because the item vars inherit from the parent vars.\n\n```css\n.sidebar-nav mds-breadcrumb {\n  --mds-breadcrumb-button-color: rgb(var(--variant-secondary-03));\n  --mds-breadcrumb-button-color-hover: rgb(var(--variant-secondary-01));\n  --mds-breadcrumb-button-background-current: rgb(var(--variant-secondary-09));\n  --mds-breadcrumb-button-color-current: rgb(var(--variant-secondary-01));\n  --mds-breadcrumb-arrow-depth-color: rgb(var(--variant-secondary-05));\n}\n```\n\n#### Per-Item Styling via `::part(button)`\n\nWhen you need to restyle a single item's inner button beyond what the CSS vars allow, target the documented `::part(button)` on `<mds-breadcrumb-item>`. This is the only supported shadow-part surface on the child component.\n\n```css\nmds-breadcrumb-item[selected]::part(button) {\n  font-weight: bold;\n  letter-spacing: 0.02em;\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-breadcrumb>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Raw HTML Inside `<mds-breadcrumb>`\n\nThe default slot accepts only `<mds-breadcrumb-item>` elements; slotting arbitrary HTML breaks the internal selection-tracking and back-button logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <a href=\"/home\">Home</a>\n  <span>Archivio</span>\n  <strong>Documento corrente</strong>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Documento corrente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Disable the Back Button with `back=\"false\"`\n\n`back` is a boolean prop. In HTML, any non-empty string attribute value is truthy - `back=\"false\"` keeps the button visible. Set the prop to `false` via JavaScript, or omit the attribute entirely.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb back=\"false\">\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT (set via JS) -->\n<mds-breadcrumb id=\"bc\">\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n<script>document.getElementById('bc').back = false;</script>\n```\n\n#### Do Not Use `<mds-breadcrumb-item>` Outside `<mds-breadcrumb>`\n\nChild items rely on the parent for ID assignment and selection-state management. Rendering them standalone breaks both keyboard navigation and the change event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"my-nav\">\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pass Text or HTML as `<mds-breadcrumb-item>` Children\n\n`<mds-breadcrumb-item>` has no default slot; the `label` prop is the only way to set the visible text. Text or HTML placed between the tags is ignored and never rendered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item>\n    <strong>Categoria</strong>\n  </mds-breadcrumb-item>\n  <mds-breadcrumb-item selected>\n    <span class=\"active\">Sottocategoria</span>\n  </mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Categoria\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sottocategoria\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Manage Selection State Manually by Toggling Classes\n\nThe parent tracks which item is selected internally; toggling CSS classes or `aria-current` on the host bypasses that logic and leaves the back button in an inconsistent state. Use the `selected` prop instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\" class=\"is-active\" aria-current=\"page\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\" selected></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Internal Back Button\n\nThe back button rendered inside `<mds-breadcrumb>` is a private implementation detail. Use the documented `--mds-breadcrumb-*` CSS custom properties to control its appearance.\n\n```css\n/* 🚫 INCORRECT */\nmds-breadcrumb >>> .back {\n  background: red;\n}\nmds-breadcrumb::part(back) {\n  display: none;\n}\n\n/* ✅ CORRECT */\nmds-breadcrumb {\n  --mds-breadcrumb-button-background-disabled: transparent;\n  --mds-breadcrumb-button-color-disabled: rgb(var(--tone-neutral-08));\n}\n```\n"
+        "1. Description": "The `<mds-breadcrumb>` web component is the navigation-trail container of the Magma Design System. It is a compound parent that arranges a sequence of slotted `<mds-breadcrumb-item>` children into a hierarchical path and adds an optional back-navigation control.\n\n#### Semantic Behavior\n\n- **Compound parent/child**: The default slot accepts only `<mds-breadcrumb-item>` children.\n- **Selection tracking**: When a child is selected it becomes the single current depth and the others are cleared.\n- **Back button**: Unless `hide-back` is set the host renders a leading arrow that steps selection to the previous item; it auto-disables whenever the first item is current.\n- **Change event**: `mdsBreadcrumbChange` fires after any selection change - via a child click or the back arrow - carrying the new index `id` and the originating `caller` item.\n- **Localized back button**: The back button's `title` is resolved per document language (el/en/es/it).\n\n#### Properties & Visual Configurations\n\nThis component exposes a single behavioral prop:\n\n- **`hideBack`** removes the leading arrow control. Leave it off (the default) for multi-level trails where users benefit from a one-tap step backwards; set it for shallow or display-only breadcrumbs where reverse navigation adds no value.\n\nVisual styling (button colors, current-depth color, separator arrow color) is driven by the CSS custom properties documented in [`readme.md`](../readme.md), not by props. The shared `variant` / `tone` / `size` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system) do not apply here; per-item labels and selection state live on the `<mds-breadcrumb-item>` children.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-breadcrumb>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Navigation Trail\n\nThe canonical form. Slot one `<mds-breadcrumb-item>` per level and mark the current depth with `selected`. The back arrow is shown by default.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio pratiche\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Pratica 2024/001\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Without the Back Arrow\n\nAdd the `hide-back` attribute for display-only or shallow breadcrumbs where reverse navigation adds no value. The back arrow is shown by default, so this is an explicit opt-out.\n\n```html\n<mds-breadcrumb hide-back>\n  <mds-breadcrumb-item label=\"Impostazioni\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Profilo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Listening for Navigation Changes\n\n`mdsBreadcrumbChange` fires whenever a child item is clicked or the back arrow is activated. The detail carries the zero-based `id` string of the newly selected item and the originating `caller` element.\n\n```html\n<mds-breadcrumb id=\"nav\">\n  <mds-breadcrumb-item label=\"Dashboard\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Documenti\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Fatture\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<script>\n  document.getElementById('nav').addEventListener('mdsBreadcrumbChange', (e) => {\n    console.log('Livello selezionato:', e.detail.id);\n    console.log('Elemento:', e.detail.caller);\n  });\n</script>\n```\n\n#### Programmatic Selection\n\nSet `selected` on the item you want active - the component will deselect the others and update the back button state automatically.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Progetto Alpha\" selected></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sprint 3\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Attivita\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Item Label via `label` Prop\n\nAlways prefer the `label` prop on `<mds-breadcrumb-item>` over the default text slot. The prop is reflected as an HTML attribute, enabling CSS attribute selectors and framework bindings.\n\n```html\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Area riservata\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Gestione utenti\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Nuovo utente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nApply `--mds-breadcrumb-*` vars on the host to retheme the whole trail at once. Use Magma color tokens wrapped in `rgb(var(--<token>))` so dark mode and high-contrast modes keep working. Changes on the parent propagate into the child items because the item vars inherit from the parent vars.\n\n```css\n.sidebar-nav mds-breadcrumb {\n  --mds-breadcrumb-button-color: rgb(var(--variant-secondary-03));\n  --mds-breadcrumb-button-color-hover: rgb(var(--variant-secondary-01));\n  --mds-breadcrumb-button-background-current: rgb(var(--variant-secondary-09));\n  --mds-breadcrumb-button-color-current: rgb(var(--variant-secondary-01));\n  --mds-breadcrumb-arrow-depth-color: rgb(var(--variant-secondary-05));\n}\n```\n\n#### Per-Item Styling via `::part(button)`\n\nWhen you need to restyle a single item's inner button beyond what the CSS vars allow, target the documented `::part(button)` on `<mds-breadcrumb-item>`. This is the only supported shadow-part surface on the child component.\n\n```css\nmds-breadcrumb-item[selected]::part(button) {\n  font-weight: bold;\n  letter-spacing: 0.02em;\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-breadcrumb>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Slot Raw HTML Inside `<mds-breadcrumb>`\n\nThe default slot accepts only `<mds-breadcrumb-item>` elements; slotting arbitrary HTML breaks the internal selection-tracking and back-button logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <a href=\"/home\">Home</a>\n  <span>Archivio</span>\n  <strong>Documento corrente</strong>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Documento corrente\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Use `<mds-breadcrumb-item>` Outside `<mds-breadcrumb>`\n\nChild items rely on the parent for ID assignment and selection-state management. Rendering them standalone breaks both keyboard navigation and the change event.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"my-nav\">\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sezione\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pass Text or HTML as `<mds-breadcrumb-item>` Children\n\n`<mds-breadcrumb-item>` has no default slot; the `label` prop is the only way to set the visible text. Text or HTML placed between the tags is ignored and never rendered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item>\n    <strong>Categoria</strong>\n  </mds-breadcrumb-item>\n  <mds-breadcrumb-item selected>\n    <span class=\"active\">Sottocategoria</span>\n  </mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Categoria\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Sottocategoria\" selected></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Manage Selection State Manually by Toggling Classes\n\nThe parent tracks which item is selected internally; toggling CSS classes or `aria-current` on the host bypasses that logic and leaves the back button in an inconsistent state. Use the `selected` prop instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\" class=\"is-active\" aria-current=\"page\"></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n\n<!-- ✅ CORRECT -->\n<mds-breadcrumb>\n  <mds-breadcrumb-item label=\"Home\" selected></mds-breadcrumb-item>\n  <mds-breadcrumb-item label=\"Archivio\"></mds-breadcrumb-item>\n</mds-breadcrumb>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Internal Back Button\n\nThe back button rendered inside `<mds-breadcrumb>` is a private implementation detail. Use the documented `--mds-breadcrumb-*` CSS custom properties to control its appearance.\n\n```css\n/* 🚫 INCORRECT */\nmds-breadcrumb >>> .back {\n  background: red;\n}\nmds-breadcrumb::part(back) {\n  display: none;\n}\n\n/* ✅ CORRECT */\nmds-breadcrumb {\n  --mds-breadcrumb-button-background-disabled: transparent;\n  --mds-breadcrumb-button-color-disabled: rgb(var(--tone-neutral-08));\n}\n```\n"
       },
       "props": [
         {
-          "name": "back",
+          "name": "hideBack",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -3364,16 +3319,16 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "back",
+          "attr": "hide-back",
           "reflectToAttr": false,
-          "docs": "Choose to display or not the back arrow button",
+          "docs": "Hides the back arrow button",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -6290,13 +6245,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements still work when given the matching `slot` value.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); it exposes a single behavioral prop.\n\n- **`autoGrid`** (default `true`) toggles the intrinsic responsive grid. Leave it enabled to let the card own the placement and reflow of its regions; set it to `false` to opt out of the managed grid and lay the slotted content out yourself.\n\nSpacing is tuned through the `--mds-card-gap` and `--mds-card-padding` CSS custom properties rather than props.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n  </mds-card-header>\n  <mds-card-media>\n    <mds-img src=\"/immagini/copertina.jpg\" class=\"object-cover\"></mds-img>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text>\n      Descrizione dettagliata del contenuto della scheda.\n    </mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n    <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>\n      Il tuo ordine e' stato elaborato correttamente.\n    </mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/immagini/prodotto.jpg\" class=\"object-cover\"></mds-img>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Profilo utente</mds-text>\n    <mds-button\n      slot=\"action\"\n      icon=\"mi/round/more-vert\"\n      aria-label=\"Altre azioni\"\n      variant=\"dark\"\n      tone=\"text\"\n    ></mds-button>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/immagini/evento.jpg\" class=\"object-cover\"></mds-img>\n    <mds-badge slot=\"content\" variant=\"primary\" tone=\"strong\">In corso</mds-badge>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element. The layout engine recognizes the same four values: `media`, `header`, `content`, and `footer`.\n\n```html\n<mds-card>\n  <div slot=\"header\" class=\"flex items-center gap-400 px-400 py-400\">\n    <mds-avatar initials=\"LB\"></mds-avatar>\n    <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n  </div>\n  <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" class=\"object-cover\"></mds-img>\n  <mds-text slot=\"content\" class=\"px-400\">\n    Responsabile del progetto infrastrutture.\n  </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `auto-grid=\"false\"` to opt out of the managed responsive grid. All four regions stack in document order and you own all layout decisions.\n\n```html\n<mds-card auto-grid=\"false\">\n  <mds-card-header>\n    <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nSet `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector. Use Magma spacing tokens so the values remain consistent across themes.\n\n```css\n.scheda-articolo mds-card {\n  --mds-card-gap: var(--spacing-200);\n  --mds-card-padding: var(--spacing-400);\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n  border-radius: var(--radius-xl);\n}\n```\n",
+        "1. Description": "The `<mds-card>` web component is the surface container of the Magma Design System: a styled, self-contained panel that groups related media, heading, body and action content into a single bounded region. It is a pure layout shell built on named slots and compound children rather than a replacement for any single HTML primitive.\n\n#### Semantic Behavior\n\n- **Layout is inferred, not declared**: The card detects which of the `media` / `header` / `content` / `footer` regions are present and reshapes itself to whatever content you provide.\n- **Compound parent/child relationship**: `<mds-card-media>`, `<mds-card-header>`, `<mds-card-content>` and `<mds-card-footer>` are recognized by tag name and mapped onto the corresponding region, so they slot in without an explicit `slot` attribute. Plain elements still work when given the matching `slot` value.\n- **Responsive by width**: The card's internal layout switches between stacked and media-beside-content arrangements based on the card's own width, independent of viewport or theme.\n- **Slot regions are fixed**: Only the four named regions are rendered; there is no default (unnamed) slot, so loose text or elements without a recognized slot/tag are not laid out.\n\n#### Properties & Visual Configurations\n\n`<mds-card>` does not use the shared `variant` / `tone` ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); it exposes a single behavioral prop.\n\n- **`disableAutoGrid`** (default `false`) toggles the intrinsic responsive grid. Leave it off to let the card own the placement and reflow of its regions; set it to opt out of the managed grid and lay the slotted content out yourself.\n\nSpacing is tuned through the `--mds-card-gap` and `--mds-card-padding` CSS custom properties rather than props.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Full Card with All Four Regions\n\nThe most common form. Use `<mds-card-header>`, `<mds-card-media>`, `<mds-card-content>`, and `<mds-card-footer>` as direct children. Each compound child self-assigns to its slot - no explicit `slot` attribute needed.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n  </mds-card-header>\n  <mds-card-media>\n    <mds-img src=\"/immagini/copertina.jpg\" class=\"object-cover\"></mds-img>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text>\n      Descrizione dettagliata del contenuto della scheda.\n    </mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button variant=\"dark\" tone=\"text\" label=\"Annulla\"></mds-button>\n    <mds-button variant=\"primary\" tone=\"strong\" label=\"Conferma\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Header + Content (No Media)\n\nOmit the regions you do not need - the card detects which regions are present and adapts its grid layout accordingly. A header-and-content-only card stays single-column.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Riepilogo ordine</mds-text>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>\n      Il tuo ordine e' stato elaborato correttamente.\n    </mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Media + Content + Footer (No Header)\n\nOmitting the header region shifts media to the top and content immediately below. Useful for image-led catalog cards.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/immagini/prodotto.jpg\" class=\"object-cover\"></mds-img>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text>Descrizione prodotto disponibile nella gamma autunnale.</mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button variant=\"primary\" label=\"Aggiungi al carrello\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Header with Action Button via `mds-card-header`\n\n`<mds-card-header>` has a dedicated `action` slot for icon buttons placed in the trailing position. Use it instead of laying out the button manually.\n\n```html\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Profilo utente</mds-text>\n    <mds-button\n      slot=\"action\"\n      icon=\"mi/round/more-vert\"\n      aria-label=\"Altre azioni\"\n      variant=\"dark\"\n      tone=\"text\"\n    ></mds-button>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>Mario Rossi - Amministratore di sistema</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Media with Overlay Content via `mds-card-media`\n\n`<mds-card-media>` exposes a `content` slot that renders in front of the media element. Use it for captions, badges, or status chips overlaid on an image.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/immagini/evento.jpg\" class=\"object-cover\"></mds-img>\n    <mds-badge slot=\"content\" variant=\"primary\" tone=\"strong\">In corso</mds-badge>\n  </mds-card-media>\n  <mds-card-content>\n    <mds-text typography=\"h6\">Conferenza annuale 2025</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Using Raw Slot Attributes Instead of Compound Children\n\nWhen the compound children (`mds-card-*`) do not fit the use case, assign the `slot` attribute directly on any element. The layout engine recognizes the same four values: `media`, `header`, `content`, and `footer`.\n\n```html\n<mds-card>\n  <div slot=\"header\" class=\"flex items-center gap-400 px-400 py-400\">\n    <mds-avatar initials=\"LB\"></mds-avatar>\n    <mds-text typography=\"h6\">Luca Bianchi</mds-text>\n  </div>\n  <mds-img slot=\"media\" src=\"/immagini/lavoro.jpg\" class=\"object-cover\"></mds-img>\n  <mds-text slot=\"content\" class=\"px-400\">\n    Responsabile del progetto infrastrutture.\n  </mds-text>\n</mds-card>\n```\n\n#### Disabling the Auto-Grid\n\nSet `disable-auto-grid` to opt out of the managed responsive grid. All four regions stack in document order and you own all layout decisions.\n\n```html\n<mds-card disable-auto-grid>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Layout personalizzato</mds-text>\n  </mds-card-header>\n  <mds-card-content>\n    <mds-text>Il contenuto e' disposto senza griglia automatica.</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nSet `--mds-card-gap` and `--mds-card-padding` on the host or a parent selector. Use Magma spacing tokens so the values remain consistent across themes.\n\n```css\n.scheda-articolo mds-card {\n  --mds-card-gap: var(--spacing-200);\n  --mds-card-padding: var(--spacing-400);\n}\n```\n\n#### Customizing the Layout Part\n\nThe inner grid element is exposed as `::part(layout)`. Use it only for layout-level overrides that the CSS custom properties cannot cover, such as overriding the `border-radius` of the inner container.\n\n```css\n.scheda-highlight mds-card::part(layout) {\n  border-radius: var(--radius-xl);\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-card>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put Content Outside the Four Named Slots\n\n`<mds-card>` has no default (unnamed) slot. Loose text or elements placed without a recognized `slot` attribute - or without using an `mds-card-*` compound child - are silently ignored and never rendered.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <p>Questo testo non verra' mai visualizzato.</p>\n  <mds-button label=\"Azione\"></mds-button>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text>Questo testo e' correttamente posizionato nel content slot.</mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button label=\"Azione\" variant=\"primary\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Do Not Use `mds-card-*` Children Outside `<mds-card>`\n\nCompound children (`mds-card-header`, `mds-card-media`, `mds-card-content`, `mds-card-footer`) rely on `<mds-card>` for layout context. Used standalone they render without the managed grid and without the card's visual chrome.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"mia-sezione\">\n  <mds-card-header>\n    <mds-text typography=\"h6\">Titolo standalone</mds-text>\n  </mds-card-header>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Titolo nella scheda</mds-text>\n  </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Pierce the Shadow DOM with Undocumented Selectors\n\nThe only supported customization surface is `--mds-card-gap`, `--mds-card-padding`, and `::part(layout)`. Targeting internal class names with `>>>`, `/deep/`, or any selector that reaches inside the shadow root couples your code to implementation details and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-card >>> .layout {\n  padding: 16px;\n}\nmds-card .layout--cfhm {\n  grid-template-columns: 1fr 1fr;\n}\n\n/* ✅ CORRECT */\nmds-card {\n  --mds-card-padding: var(--spacing-400);\n}\nmds-card::part(layout) {\n  border-radius: var(--radius-xl);\n}\n```\n\n#### Do Not Assign an Explicit `slot` Attribute to `mds-card-*` Children\n\n`mds-card-header`, `mds-card-media`, `mds-card-content`, and `mds-card-footer` already set their own `slot` attribute on the host element from inside the component. Adding it again from the outside is redundant and may conflict with internal wiring.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-header slot=\"header\">...</mds-card-header>\n  <mds-card-content slot=\"content\">...</mds-card-content>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-header>...</mds-card-header>\n  <mds-card-content>...</mds-card-content>\n</mds-card>\n```\n\n#### Do Not Put Media Elements Directly in the `header` Slot\n\nThe `header` slot is intended for title and action controls. Placing an `<mds-img>` or `<img>` directly there bypasses the media region's responsive two-column behavior. Use the `media` slot (or `<mds-card-media>`) for images and videos.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-header>\n    <mds-img src=\"/immagini/banner.jpg\"></mds-img>\n  </mds-card-header>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/immagini/banner.jpg\" class=\"object-cover\"></mds-img>\n  </mds-card-media>\n  <mds-card-header>\n    <mds-text typography=\"h6\">Titolo della scheda</mds-text>\n  </mds-card-header>\n</mds-card>\n```\n\n#### Do Not Override Card Dimensions with Inline Styles\n\n`<mds-card>` manages its own min-height and responsive grid. Overriding `width`, `height`, or `min-height` inline breaks the container-query breakpoints and the proportional media column.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card style=\"width: 300px; height: 200px;\">\n  ...\n</mds-card>\n\n<!-- ✅ CORRECT: size the card from a parent container or CSS custom properties -->\n<div class=\"w-[300px]\">\n  <mds-card>\n    ...\n  </mds-card>\n</div>\n```\n"
       },
       "props": [
         {
-          "name": "autoGrid",
+          "name": "disableAutoGrid",
           "type": "boolean",
           "complexType": {
             "original": "boolean",
@@ -6304,16 +6259,16 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "auto-grid",
+          "attr": "disable-auto-grid",
           "reflectToAttr": true,
-          "docs": "Enables automatic responsive behavior based on container queries",
+          "docs": "Disables the automatic responsive behavior based on container queries",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -6382,8 +6337,8 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-card-content>` web component is the body region of a [`<mds-card>`](../../mds-card), grouping the primary textual or component content of a card. It is a thin layout wrapper with no HTML primitive equivalent: it exposes a single default slot and assigns itself to the parent card's `content` region automatically.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-content>` must be placed as a direct child of `<mds-card>`; it is not used standalone, and a card's content region is expected to be a dedicated `mds-card-*` child rather than mixed loose markup.\n- **Automatic slot targeting**: It lands in the parent's `content` region without the developer having to set the `slot` attribute manually.\n- **Presence affects parent layout**: The parent card adapts its responsive layout to whichever `mds-card-*` regions are present, so including or omitting the content region changes how the card arranges itself.\n- **No state, events, or ARIA**: The component declares no props or emitted events and applies no role or ARIA attributes; it is purely structural and inherits semantics from whatever is slotted into it.\n\n#### Slot semantics and layout role\n\nThis component is intentionally prop-free. Its only API is the **default slot**, which accepts text strings, HTML elements, or other components that make up the card's main content. All visual configuration (responsive behavior, grid layout) is governed by the parent `<mds-card>` through its `autoGrid` prop and the `--mds-card-gap` / `--mds-card-padding` custom properties; see the compound-component and slot rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card-content>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound-component composition documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Card with Content\n\nThe most common use: a card with only a content region. Place `<mds-card-content>` as a direct child of `<mds-card>` - no `slot` attribute needed, the component self-assigns to the parent's `content` region.\n\n```html\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"label\">Comune di Roma</mds-text>\n    <mds-text typography=\"body\">Aggiornato il 5 giugno 2026</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Full Card Composition\n\nUse `<mds-card-content>` alongside [`<mds-card-header>`](../../mds-card-header), [`<mds-card-media>`](../../mds-card-media), and [`<mds-card-footer>`](../../mds-card-footer) to build a complete card. The parent arranges them in a responsive grid automatically when `auto-grid` is enabled (the default).\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"copertina.jpg\" alt=\"Immagine documento\"></mds-img>\n  </mds-card-media>\n  <mds-card-header label=\"Delibera n. 42\"></mds-card-header>\n  <mds-card-content>\n    <mds-text typography=\"body\">\n      Approvazione del piano triennale delle opere pubbliche per il periodo 2026-2028.\n    </mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button label=\"Scarica PDF\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Mixed Rich Content\n\nThe default slot accepts any HTML or components. Use it for structured content like lists, banners, or data visualizations that make up the card body.\n\n```html\n<mds-card>\n  <mds-card-header label=\"Riepilogo pratiche\"></mds-card-header>\n  <mds-card-content>\n    <mds-banner variant=\"warning\" tone=\"weak\" label=\"3 pratiche in scadenza oggi\"></mds-banner>\n    <mds-list>\n      <mds-list-item label=\"Pratica SUAP 2026-001\"></mds-list-item>\n      <mds-list-item label=\"Pratica SUAP 2026-002\"></mds-list-item>\n      <mds-list-item label=\"Pratica SUAP 2026-003\"></mds-list-item>\n    </mds-list>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Content-Only Card Without a Header\n\nOmitting sibling regions is valid. A card holding only `<mds-card-content>` renders the content at full height in the grid's single-column layout. This is common for KPI panels or compact info tiles.\n\n```html\n<mds-card>\n  <mds-card-content>\n    <mds-kpi>\n      <mds-kpi-item label=\"Pratiche aperte\" value=\"142\" variant=\"info\"></mds-kpi-item>\n    </mds-kpi>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Adjusting Card Spacing via Parent Custom Properties\n\n`<mds-card-content>` has no CSS custom properties of its own. Control the gap and padding of the card composition - including the content region - through the parent's `--mds-card-gap` and `--mds-card-padding` properties. Set them on the `<mds-card>` host or on a parent selector.\n\n```css\n.card-compatta mds-card {\n  --mds-card-gap: var(--spacing-200);\n  --mds-card-padding: var(--spacing-300);\n}\n```\n",
+        "1. Description": "The `<mds-card-content>` web component is the body region of a [`<mds-card>`](../../mds-card), grouping the primary textual or component content of a card. It is a thin layout wrapper with no HTML primitive equivalent: it exposes a single default slot and assigns itself to the parent card's `content` region automatically.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-content>` must be placed as a direct child of `<mds-card>`; it is not used standalone, and a card's content region is expected to be a dedicated `mds-card-*` child rather than mixed loose markup.\n- **Automatic slot targeting**: It lands in the parent's `content` region without the developer having to set the `slot` attribute manually.\n- **Presence affects parent layout**: The parent card adapts its responsive layout to whichever `mds-card-*` regions are present, so including or omitting the content region changes how the card arranges itself.\n- **No state, events, or ARIA**: The component declares no props or emitted events and applies no role or ARIA attributes; it is purely structural and inherits semantics from whatever is slotted into it.\n\n#### Slot semantics and layout role\n\nThis component is intentionally prop-free. Its only API is the **default slot**, which accepts text strings, HTML elements, or other components that make up the card's main content. All visual configuration (responsive behavior, grid layout) is governed by the parent `<mds-card>` through its `disableAutoGrid` prop and the `--mds-card-gap` / `--mds-card-padding` custom properties; see the compound-component and slot rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card-content>` component, ordered from most common to most specialized. Patterns assume a working knowledge of compound-component composition documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Card with Content\n\nThe most common use: a card with only a content region. Place `<mds-card-content>` as a direct child of `<mds-card>` - no `slot` attribute needed, the component self-assigns to the parent's `content` region.\n\n```html\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"label\">Comune di Roma</mds-text>\n    <mds-text typography=\"body\">Aggiornato il 5 giugno 2026</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Full Card Composition\n\nUse `<mds-card-content>` alongside [`<mds-card-header>`](../../mds-card-header), [`<mds-card-media>`](../../mds-card-media), and [`<mds-card-footer>`](../../mds-card-footer) to build a complete card. The parent arranges them in a responsive grid automatically by default (unless `disable-auto-grid` is set on the parent).\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"copertina.jpg\" alt=\"Immagine documento\"></mds-img>\n  </mds-card-media>\n  <mds-card-header label=\"Delibera n. 42\"></mds-card-header>\n  <mds-card-content>\n    <mds-text typography=\"body\">\n      Approvazione del piano triennale delle opere pubbliche per il periodo 2026-2028.\n    </mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button label=\"Scarica PDF\" icon=\"mi/baseline/download\" variant=\"primary\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Mixed Rich Content\n\nThe default slot accepts any HTML or components. Use it for structured content like lists, banners, or data visualizations that make up the card body.\n\n```html\n<mds-card>\n  <mds-card-header label=\"Riepilogo pratiche\"></mds-card-header>\n  <mds-card-content>\n    <mds-banner variant=\"warning\" tone=\"weak\" label=\"3 pratiche in scadenza oggi\"></mds-banner>\n    <mds-list>\n      <mds-list-item label=\"Pratica SUAP 2026-001\"></mds-list-item>\n      <mds-list-item label=\"Pratica SUAP 2026-002\"></mds-list-item>\n      <mds-list-item label=\"Pratica SUAP 2026-003\"></mds-list-item>\n    </mds-list>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Content-Only Card Without a Header\n\nOmitting sibling regions is valid. A card holding only `<mds-card-content>` renders the content at full height in the grid's single-column layout. This is common for KPI panels or compact info tiles.\n\n```html\n<mds-card>\n  <mds-card-content>\n    <mds-kpi>\n      <mds-kpi-item label=\"Pratiche aperte\" value=\"142\" variant=\"info\"></mds-kpi-item>\n    </mds-kpi>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Adjusting Card Spacing via Parent Custom Properties\n\n`<mds-card-content>` has no CSS custom properties of its own. Control the gap and padding of the card composition - including the content region - through the parent's `--mds-card-gap` and `--mds-card-padding` properties. Set them on the `<mds-card>` host or on a parent selector.\n\n```css\n.card-compatta mds-card {\n  --mds-card-gap: var(--spacing-200);\n  --mds-card-padding: var(--spacing-300);\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-card-content>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-card-content>` Outside `<mds-card>`\n\n`<mds-card-content>` is a compound child and relies on `<mds-card>`'s slot infrastructure and grid layout. Used standalone it renders with no container context and produces unpredictable visual output.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card-content>\n  <mds-text typography=\"body\">Testo senza contesto.</mds-text>\n</mds-card-content>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"body\">Testo senza contesto.</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Set the `slot` Attribute Manually\n\n`<mds-card-content>` self-assigns `slot=\"content\"` in its `Host` render. Adding the attribute externally is redundant and can produce a double-assignment that breaks the grid-area resolution.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-content slot=\"content\">\n    <mds-text typography=\"body\">Intestazione sezione principale.</mds-text>\n  </mds-card-content>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"body\">Intestazione sezione principale.</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Replace `<mds-card-content>` with a Raw `<div slot=\"content\">`\n\nA raw element placed directly in `slot=\"content\"` bypasses the card-content component's internal grid and consistent padding, producing a layout that diverges from the design system baseline and breaks on card-region composition changes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <div slot=\"content\" style=\"padding: 16px;\">\n    <p>Descrizione pratica edilizia.</p>\n  </div>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"body\">Descrizione pratica edilizia.</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n\n#### Do Not Try to Style Spacing via `<mds-card-content>` CSS Vars\n\n`<mds-card-content>` exposes no `--mds-card-content-*` custom properties. Setting them has no effect. Spacing is controlled through `--mds-card-gap` and `--mds-card-padding` on the parent `<mds-card>`.\n\n```css\n/* 🚫 INCORRECT - has no effect */\nmds-card-content {\n  --mds-card-content-padding: var(--spacing-600);\n  --mds-card-content-gap: var(--spacing-400);\n}\n\n/* ✅ CORRECT - set on the parent card host */\nmds-card {\n  --mds-card-gap: var(--spacing-200);\n  --mds-card-padding: var(--spacing-400);\n}\n```\n\n#### Do Not Place Multiple `<mds-card-content>` Elements in One Card\n\nOnly one content region per card is supported. Multiple instances produce overlapping slot assignments and unpredictable grid output; consolidate all body content inside a single `<mds-card-content>`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"label\">Sezione A</mds-text>\n  </mds-card-content>\n  <mds-card-content>\n    <mds-text typography=\"label\">Sezione B</mds-text>\n  </mds-card-content>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-content>\n    <mds-text typography=\"label\">Sezione A</mds-text>\n    <mds-text typography=\"label\">Sezione B</mds-text>\n  </mds-card-content>\n</mds-card>\n```\n"
       },
       "props": [],
@@ -6497,7 +6452,7 @@
       ],
       "usage": {
         "1. Description": "The `<mds-card-media>` web component is the media region of a [`<mds-card>`](../../mds-card): it wraps an image, video or other visual asset and provides an optional overlay layer for text or controls rendered on top of that asset. It is a layout child with no HTML primitive equivalent - it exists purely to occupy and style the card's `media` region.\n\n#### Semantic Behavior\n\n- **Compound child only**: `<mds-card-media>` is designed to live as a direct child of `<mds-card>` and must not be used standalone or mixed in as a different card region.\n- **Self-slotting into the parent**: It lands in the card's `media` region automatically without the author setting any `slot`, and its presence is factored into the card layout.\n- **Two-layer composition**: The default slot holds the media asset itself (recommended `mds-img` or another media component), while the named `content` slot overlays that asset, bottom-aligned and centered, so overlay text/actions float in front of the media.\n- **No interactive state**: The component holds no props, state, events, ARIA roles or focus behavior of its own - it is a passive presentational wrapper, and any semantics come from the elements slotted into it.\n\n#### Slot semantics and layout role\n\n`<mds-card-media>` exposes no configurable properties; its behavior is entirely defined by its two slots and its position inside the card.\n\n- **default slot**: the media surface. Place the actual visual asset here (an `mds-img`, video, or equivalent component). This layer fills the host.\n- **`content` slot**: an overlay layer (exposed as the `content` shadow part) positioned over the media, aligned to the bottom and horizontally centered, intended for captions, titles, or action controls that should appear in front of the media rather than beside it.\n\nThe host paints a neutral background, so the media region keeps a defined surface even before its asset loads. For the shared variant/tone system that governs the parent card, see [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system).\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card-media>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Media Region with `mds-img`\n\nPlace `<mds-card-media>` as a direct child of `<mds-card>`. No `slot` attribute is needed - the component self-assigns into the card's `media` region. Put the visual asset in the default slot; `mds-img` is the recommended choice.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/copertina.jpg\" alt=\"Copertina articolo\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Media with an Overlay Caption via the `content` Slot\n\nUse the named `content` slot for text or controls that should float in front of the media asset. The overlay is absolutely positioned over the media, bottom-aligned and horizontally centered.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/evento.jpg\" alt=\"Evento annuale\"></mds-img>\n    <mds-text slot=\"content\" typography=\"label\">12 giugno 2026</mds-text>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Media with an Overlay Action Control\n\nThe `content` slot accepts any element or component. Use it to place a badge, chip, or button on top of the media when the design calls for an interactive overlay.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/prodotto.jpg\" alt=\"Scheda prodotto\"></mds-img>\n    <mds-badge slot=\"content\" label=\"Novita'\" variant=\"primary\" tone=\"strong\"></mds-badge>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Card with All Regions Composed Together\n\n`<mds-card-media>` composes alongside `mds-card-header`, `mds-card-content`, and `mds-card-footer` inside `mds-card`. Each region self-assigns its slot; the card's `auto-grid` prop drives the responsive layout automatically.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/notizia.jpg\" alt=\"Immagine della notizia\"></mds-img>\n  </mds-card-media>\n  <mds-card-header label=\"Titolo della notizia\"></mds-card-header>\n  <mds-card-content>\n    <mds-text>Descrizione breve della notizia.</mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button label=\"Leggi di piu'\" variant=\"primary\" tone=\"text\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Video in the Default Slot\n\nThe default slot accepts any media element or component. Use a native `<video>` when the design calls for motion content rather than a still image.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <video src=\"/media/presentazione.mp4\" autoplay muted loop playsinline></video>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Styling the Overlay Part via `::part(content)`\n\nThe `content` overlay div is exposed as the `content` shadow part. Use it for layout adjustments that the host's positioning rules do not cover - for example, changing alignment or adding a gradient scrim. Set the style on the host or a parent selector; do not pierce shadow DOM with `>>>` or undocumented class names.\n\n```css\n.card-destacada mds-card-media::part(content) {\n  align-items: flex-start;\n  background: linear-gradient(to top, rgb(var(--tone-neutral-01) / 0.7), transparent);\n  padding: var(--spacing-600);\n}\n```\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-card-media>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Media Region with `mds-img`\n\nPlace `<mds-card-media>` as a direct child of `<mds-card>`. No `slot` attribute is needed - the component self-assigns into the card's `media` region. Put the visual asset in the default slot; `mds-img` is the recommended choice.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/copertina.jpg\" alt=\"Copertina articolo\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Media with an Overlay Caption via the `content` Slot\n\nUse the named `content` slot for text or controls that should float in front of the media asset. The overlay is absolutely positioned over the media, bottom-aligned and horizontally centered.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/evento.jpg\" alt=\"Evento annuale\"></mds-img>\n    <mds-text slot=\"content\" typography=\"label\">12 giugno 2026</mds-text>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Media with an Overlay Action Control\n\nThe `content` slot accepts any element or component. Use it to place a badge, chip, or button on top of the media when the design calls for an interactive overlay.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/prodotto.jpg\" alt=\"Scheda prodotto\"></mds-img>\n    <mds-badge slot=\"content\" label=\"Novita'\" variant=\"primary\" tone=\"strong\"></mds-badge>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Card with All Regions Composed Together\n\n`<mds-card-media>` composes alongside `mds-card-header`, `mds-card-content`, and `mds-card-footer` inside `mds-card`. Each region self-assigns its slot; the card drives the responsive layout automatically unless `disable-auto-grid` is set.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/notizia.jpg\" alt=\"Immagine della notizia\"></mds-img>\n  </mds-card-media>\n  <mds-card-header label=\"Titolo della notizia\"></mds-card-header>\n  <mds-card-content>\n    <mds-text>Descrizione breve della notizia.</mds-text>\n  </mds-card-content>\n  <mds-card-footer>\n    <mds-button label=\"Leggi di piu'\" variant=\"primary\" tone=\"text\"></mds-button>\n  </mds-card-footer>\n</mds-card>\n```\n\n#### Video in the Default Slot\n\nThe default slot accepts any media element or component. Use a native `<video>` when the design calls for motion content rather than a still image.\n\n```html\n<mds-card>\n  <mds-card-media>\n    <video src=\"/media/presentazione.mp4\" autoplay muted loop playsinline></video>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Styling the Overlay Part via `::part(content)`\n\nThe `content` overlay div is exposed as the `content` shadow part. Use it for layout adjustments that the host's positioning rules do not cover - for example, changing alignment or adding a gradient scrim. Set the style on the host or a parent selector; do not pierce shadow DOM with `>>>` or undocumented class names.\n\n```css\n.card-destacada mds-card-media::part(content) {\n  align-items: flex-start;\n  background: linear-gradient(to top, rgb(var(--tone-neutral-01) / 0.7), transparent);\n  padding: var(--spacing-600);\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-card-media>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-card-media>` Outside `<mds-card>`\n\n`<mds-card-media>` is a compound child designed to live inside `<mds-card>`. Using it standalone produces unstyled output and breaks the card layout algorithm, which derives its responsive grid from the presence of its region children.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card-media>\n  <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n</mds-card-media>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Do Not Set `slot=\"media\"` Manually\n\n`<mds-card-media>` self-assigns into the card's `media` region via its internal `Host slot=\"media\"`. Adding `slot=\"media\"` on the element is redundant and signals a misunderstanding of the component's self-slotting contract.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-media slot=\"media\">\n    <mds-img src=\"/img/copertina.jpg\" alt=\"Copertina\"></mds-img>\n  </mds-card-media>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/copertina.jpg\" alt=\"Copertina\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Do Not Put the Overlay Text in the Default Slot\n\nText or controls that should appear in front of the media must go in the `content` named slot. Content placed in the default slot renders behind or beside the media asset, not as an overlay.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n    <mds-text>Didascalia</mds-text>\n  </mds-card-media>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n    <mds-text slot=\"content\">Didascalia</mds-text>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Do Not Place `<mds-card-media>` Inside a Wrapper Element\n\n`mds-card` reads its direct children to compute the layout grid. Wrapping `<mds-card-media>` in a `<div>` or any other element hides it from that detection pass and breaks the responsive layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <div class=\"media-wrapper\">\n    <mds-card-media>\n      <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n    </mds-card-media>\n  </div>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/foto.jpg\" alt=\"Foto\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Do Not Use a Raw `<img>` Instead of `<mds-img>`\n\nPlacing a raw `<img>` in the default slot works visually but bypasses the lazy loading, error state, consumption-preference handling, and accessible-name fallback that `mds-img` provides.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-card>\n  <mds-card-media>\n    <img src=\"/img/prodotto.jpg\" alt=\"Prodotto\">\n  </mds-card-media>\n</mds-card>\n\n<!-- ✅ CORRECT -->\n<mds-card>\n  <mds-card-media>\n    <mds-img src=\"/img/prodotto.jpg\" alt=\"Prodotto\"></mds-img>\n  </mds-card-media>\n</mds-card>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Overlay Container\n\nThe `content` div inside the shadow root is exposed as the `content` shadow part. Use `::part(content)` for style overrides, not `>>>`, `/deep/`, or internal class selectors - the latter couple your code to the implementation and break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-card-media >>> .content {\n  align-items: flex-start;\n}\n\n/* ✅ CORRECT */\nmds-card-media::part(content) {\n  align-items: flex-start;\n}\n```\n"
       },
       "props": [],
@@ -7212,62 +7167,94 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` disables all automatic wiring so visibility is controlled programmatically through `visible`.\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the preferred side relative to the caller; **`autoPlacement`** chooses the best side automatically, **`flip`** allows falling back to the opposite side when space runs out, and **`shift`** / **`shiftPadding`** keep the panel inside the viewport with a safe margin.\n- **`offset`** controls the gap between the panel and the caller; **`arrow`** toggles the pointer toward the caller and **`arrowPadding`** insets it from the panel edges.\n- **`smooth`** keeps the panel tracking the caller as the page scrolls; **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n  <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n  <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\n`arrow` is `true` by default. Use it to visually connect the panel to its caller. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"secondary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow arrow-padding=\"16\">\n  <mds-text typography=\"h6\">Come funziona?</mds-text>\n  <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n  <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n  <mds-filter>\n    <mds-filter-item label=\"Documenti\"></mds-filter-item>\n    <mds-filter-item label=\"Immagini\"></mds-filter-item>\n    <mds-filter-item label=\"Video\"></mds-filter-item>\n  </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n  <mds-entity icon=\"mi/baseline/folder\">\n    <mds-text>Progetto Alfa - In corso</mds-text>\n  </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n  <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n  const dropdown = document.querySelector('#pannello-opzioni');\n  document.querySelector('#apri-manuale').addEventListener('click', () => {\n    dropdown.visible = !dropdown.visible;\n  });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to anchor the panel to a specific side of the caller. Enable `auto-placement` to let the component choose the best available side automatically based on viewport space.\n\n```html\n<!-- Explicit right-start placement -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\">\n  <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n  <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"secondary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\" auto-placement>\n  <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` to let the panel jump to the opposite side when there is not enough space in the preferred direction. Enable `shift` (on by default) together with `shift-padding` to keep the panel inside the viewport when near an edge.\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" flip shift shift-padding=\"16\">\n  <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n  <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n  document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n    console.log('Aperto. Trigger:', e.detail.caller);\n  });\n  document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n    console.log('Chiuso.');\n  });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n  <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n  <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n  <!-- Trigger lives inside a complex layout -->\n  <div class=\"app-layout\">\n    <nav>\n      <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"secondary\"></mds-button>\n    </nav>\n  </div>\n\n  <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n  <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n    <mds-text typography=\"h6\">Mario Rossi</mds-text>\n    <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n  </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its documented `--mds-dropdown-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` to preserve dark-mode and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n  --mds-dropdown-background: rgb(var(--tone-neutral-09));\n  --mds-dropdown-drop-shadow-color-rgb: var(--variant-primary-03);\n  --mds-dropdown-duration: 0.3s;\n  --mds-dropdown-mouseover-delay: 0.2s;\n  --mds-dropdown-z-index: 5000;\n}\n```\n",
+        "1. Description": "The `<mds-dropdown>` web component is a floating overlay surface of the Magma Design System that anchors arbitrary slotted content next to an external trigger element. It has no built-in trigger of its own: it attaches to a separate caller resolved via `target` and positions, flips and shifts itself around that element.\n\n#### Semantic Behavior\n\n- **Caller binding**: The dropdown does not render a trigger; it resolves its caller from the `target` selector and wires the chosen interaction onto that external element. Changing `target` re-binds the caller.\n- **Visibility is the single source of truth**: The `visible` prop drives the whole lifecycle - it positions the floating element, optionally shows the backdrop, and emits the events; setting it back to `false` dismisses it.\n- **Outside-click dismissal**: While open, clicking outside both the host and the caller closes the dropdown.\n- **Escape to close**: Pressing Escape hides the dropdown.\n- **Backdrop**: When `backdrop` is set, a backdrop is shown while the dropdown is visible and removed on close.\n- **Emitted events**: `mdsDropdownChange` fires on every visibility transition; `mdsDropdownVisible` and `mdsDropdownHide` fire on open and close respectively. Each detail carries the resolved `caller` and the current `visible` state.\n- **Default slot is the panel content**: Anything in the default slot (text, HTML, or other components) is the surface shown when the dropdown is triggered.\n\n#### Properties & Visual Configurations\n\n- **`interaction`** decides how the caller opens the panel: `'click'` toggles on caller click (with outside-click and Escape dismissal), `'mouseover'` opens on hover and closes on mouse leave, and `'none'` disables all automatic wiring so visibility is controlled programmatically through `visible`.\n- **`target`** (required) is the CSS selector of the external element the dropdown attaches to and positions against.\n\n#### Other behavioral props\n\n- **`placement`** sets the preferred side relative to the caller; the best side is chosen automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`), **`flip`** allows falling back to the opposite side when space runs out, and the panel is shifted to stay inside the viewport with a safe margin by default — **`disableShift`** opts out of this and **`shiftPadding`** tunes the margin.\n- **`offset`** controls the gap between the panel and the caller; the pointer toward the caller is shown by default (**`hideArrow`** removes it) and **`arrowPadding`** insets it from the panel edges.\n- the panel tracks the caller smoothly as the page scrolls by default (**`disableSmooth`** opts out); **`strategy`** chooses the CSS positioning mode (`'absolute'` vs `'fixed'`) and **`zIndex`** sets the stacking order.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-dropdown>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Dropdown Menu\n\nThe minimal required setup: a trigger element with a unique `id` and a `<mds-dropdown>` with `target` pointing at it. The dropdown binds to the caller on `click` by default and dismisses on outside-click or Escape.\n\n```html\n<mds-button id=\"menu-utente\" label=\"Profilo\" icon=\"mi/baseline/account-circle\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-utente\">\n  <mds-button icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\" label=\"Impostazioni account\"></mds-button>\n  <mds-button icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\" label=\"Esci\"></mds-button>\n</mds-dropdown>\n```\n\n#### Dropdown with Arrow Pointer\n\nThe arrow pointer is shown by default to visually connect the panel to its caller; add `hide-arrow` to remove it. Adjust `arrow-padding` when the panel is narrow and the arrow would clip the rounded corners.\n\n```html\n<mds-button id=\"aiuto-contestuale\" label=\"Aiuto\" icon=\"mi/baseline/help-outline\" variant=\"secondary\" tone=\"outline\"></mds-button>\n\n<mds-dropdown target=\"#aiuto-contestuale\" arrow-padding=\"16\">\n  <mds-text typography=\"h6\">Come funziona?</mds-text>\n  <mds-text typography=\"detail\">Seleziona un campo per vedere la guida contestuale.</mds-text>\n</mds-dropdown>\n```\n\n#### Dropdown with Backdrop\n\nUse `backdrop` to dim the rest of the page while the panel is open. This is appropriate for panels with a higher modal weight, such as user-account menus or multi-step pickers.\n\n```html\n<mds-button id=\"selezione-filtri\" label=\"Filtra risultati\" icon=\"mi/baseline/filter-list\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#selezione-filtri\" backdrop>\n  <mds-text typography=\"h6\">Filtra per categoria</mds-text>\n  <mds-filter>\n    <mds-filter-item label=\"Documenti\"></mds-filter-item>\n    <mds-filter-item label=\"Immagini\"></mds-filter-item>\n    <mds-filter-item label=\"Video\"></mds-filter-item>\n  </mds-filter>\n</mds-dropdown>\n```\n\n#### Mouseover Interaction\n\nSet `interaction=\"mouseover\"` for navigation mega-menus or info tooltips that should open on hover. The component adds a configurable delay (default 0.5 s, controlled by `--mds-dropdown-mouseover-delay`) before opening and closing.\n\n```html\n<mds-button id=\"info-progetto\" label=\"Dettagli progetto\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#info-progetto\" interaction=\"mouseover\">\n  <mds-entity icon=\"mi/baseline/folder\">\n    <mds-text>Progetto Alfa - In corso</mds-text>\n  </mds-entity>\n</mds-dropdown>\n```\n\n#### Programmatic Control via `visible`\n\nSet `interaction=\"none\"` to disable automatic wiring and drive visibility yourself. This is useful when the trigger logic lives in app code - for example, opening on a keyboard shortcut or a programmatic state change.\n\n```html\n<mds-button id=\"apri-manuale\" label=\"Apri pannello\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-opzioni\" target=\"#apri-manuale\" interaction=\"none\">\n  <mds-text typography=\"detail\">Pannello gestito dal codice applicativo.</mds-text>\n</mds-dropdown>\n\n<script>\n  const dropdown = document.querySelector('#pannello-opzioni');\n  document.querySelector('#apri-manuale').addEventListener('click', () => {\n    dropdown.visible = !dropdown.visible;\n  });\n</script>\n```\n\n#### Placement and Auto-Placement\n\nUse `placement` to anchor the panel to a specific side of the caller. Auto-placement is on by default, letting the component choose the best available side based on viewport space; add `disable-auto-placement` to pin the panel strictly to `placement`.\n\n```html\n<!-- Pinned right-start placement (auto-placement disabled) -->\n<mds-button id=\"azioni-riga\" label=\"Azioni\" icon=\"mi/baseline/more-vert\" variant=\"dark\" tone=\"text\"></mds-button>\n\n<mds-dropdown target=\"#azioni-riga\" placement=\"right-start\" disable-auto-placement>\n  <mds-button icon=\"mi/baseline/edit\" variant=\"dark\" tone=\"text\" label=\"Modifica\"></mds-button>\n  <mds-button icon=\"mi/baseline/delete\" variant=\"error\" tone=\"text\" label=\"Elimina\"></mds-button>\n</mds-dropdown>\n\n<!-- Auto-placement (default) for constrained viewports -->\n<mds-button id=\"opzioni-voce\" label=\"Opzioni\" variant=\"secondary\" tone=\"weak\"></mds-button>\n<mds-dropdown target=\"#opzioni-voce\">\n  <mds-button label=\"Duplica\" icon=\"mi/baseline/content-copy\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### Flip and Shift for Viewport Safety\n\nEnable `flip` to let the panel jump to the opposite side when there is not enough space in the preferred direction. Shifting the panel to keep it inside the viewport is on by default; tune the safe margin with `shift-padding` (or set `disable-shift` to opt out).\n\n```html\n<mds-button id=\"btn-edge\" label=\"Vicino al bordo\" variant=\"primary\"></mds-button>\n\n<mds-dropdown target=\"#btn-edge\" placement=\"top\" flip shift-padding=\"16\">\n  <mds-text typography=\"detail\">Questo pannello si sposta automaticamente se manca spazio.</mds-text>\n</mds-dropdown>\n```\n\n#### Listening to Visibility Events\n\nListen for `mdsDropdownVisible`, `mdsDropdownHide`, or `mdsDropdownChange` to react to open/close transitions. Each event detail contains `caller` (the resolved trigger element) and `visible` (the new state).\n\n```html\n<mds-button id=\"btn-notifica\" label=\"Notifiche\" icon=\"mi/baseline/notifications\" variant=\"secondary\"></mds-button>\n\n<mds-dropdown id=\"pannello-notifiche\" target=\"#btn-notifica\">\n  <mds-text typography=\"detail\">Nessuna nuova notifica.</mds-text>\n</mds-dropdown>\n\n<script>\n  document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownVisible', (e) => {\n    console.log('Aperto. Trigger:', e.detail.caller);\n  });\n  document.querySelector('#pannello-notifiche').addEventListener('mdsDropdownHide', () => {\n    console.log('Chiuso.');\n  });\n</script>\n```\n\n#### Strategy `fixed` Inside Scrolling or Stacked Containers\n\nUse `strategy=\"fixed\"` when the dropdown is placed inside a scroll container, a sticky header, or a modal. With `strategy=\"absolute\"` (the default) the panel may be clipped by `overflow: hidden` ancestors.\n\n```html\n<!-- Inside a modal or a sticky nav - use fixed positioning -->\n<mds-button id=\"menu-header\" label=\"Menu\" variant=\"secondary\" tone=\"weak\"></mds-button>\n\n<mds-dropdown target=\"#menu-header\" strategy=\"fixed\">\n  <mds-button label=\"Pagina principale\" icon=\"mi/baseline/home\" variant=\"dark\" tone=\"text\"></mds-button>\n  <mds-button label=\"Impostazioni\" icon=\"mi/baseline/settings\" variant=\"dark\" tone=\"text\"></mds-button>\n</mds-dropdown>\n```\n\n#### DOM Placement at the Document Root\n\nPlace `<mds-dropdown>` as a direct child of `<body>` (or as close as possible to the root) when the caller lives deep inside a stacking context. Nesting the dropdown inside the same transformed or `overflow: hidden` ancestor as the caller can break positioning and backdrop rendering.\n\n```html\n<body>\n  <!-- Trigger lives inside a complex layout -->\n  <div class=\"app-layout\">\n    <nav>\n      <mds-button id=\"btn-profilo\" label=\"Profilo\" variant=\"secondary\"></mds-button>\n    </nav>\n  </div>\n\n  <!-- Dropdown is a sibling of the layout root, not nested inside it -->\n  <mds-dropdown target=\"#btn-profilo\" strategy=\"fixed\" backdrop>\n    <mds-text typography=\"h6\">Mario Rossi</mds-text>\n    <mds-button label=\"Esci\" icon=\"mi/baseline/logout\" variant=\"error\" tone=\"text\"></mds-button>\n  </mds-dropdown>\n</body>\n```\n\n#### Styling Customization\n\nCustomize the dropdown only through its documented `--mds-dropdown-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` to preserve dark-mode and high-contrast behavior.\n\n```css\n.my-context mds-dropdown {\n  --mds-dropdown-background: rgb(var(--tone-neutral-09));\n  --mds-dropdown-drop-shadow-color-rgb: var(--variant-primary-03);\n  --mds-dropdown-duration: 0.3s;\n  --mds-dropdown-mouseover-delay: 0.2s;\n  --mds-dropdown-z-index: 5000;\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-dropdown>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place the Dropdown Deep Inside a Scroll or Stacking Context\n\nNesting `<mds-dropdown>` inside a transformed, sticky, or `overflow: hidden` ancestor breaks floating positioning and backdrop rendering. Place it as close to `<body>` as the page structure allows, or switch to `strategy=\"fixed\"`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n  <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n  <mds-dropdown target=\"#trigger\" backdrop>\n    <mds-text>Contenuto</mds-text>\n  </mds-dropdown>\n</div>\n\n<!-- ✅ CORRECT -->\n<div style=\"overflow: hidden; position: relative;\">\n  <mds-button id=\"trigger\" label=\"Apri\" variant=\"primary\"></mds-button>\n</div>\n<mds-dropdown target=\"#trigger\" strategy=\"fixed\" backdrop>\n  <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `visible=\"false\"` to Close the Dropdown\n\n`visible` is a boolean prop. Setting it to the string `\"false\"` is truthy in HTML - the dropdown stays open. Remove the attribute or set the property to `false` in JavaScript to close it.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-dropdown target=\"#btn\" visible=\"false\">\n  <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n\n<!-- ✅ CORRECT -->\n<mds-dropdown target=\"#btn\">\n  <mds-text>Contenuto</mds-text>\n</mds-dropdown>\n```\n\n```js\n// ✅ CORRECT - closing programmatically\ndocument.querySelector('mds-dropdown').visible = false;\n```\n\n#### Do Not Listen for Native `click` on the Target Instead of Dropdown Events\n\nThe dropdown manages its own interaction and emits `mdsDropdownVisible`, `mdsDropdownHide`, and `mdsDropdownChange`. Attaching a raw `click` listener to the caller can interfere with inside-click handling and may fire before the dropdown has updated its state.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"secondary\"></mds-button>\n<mds-dropdown target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n  // raw native event on the caller - races with dropdown internals\n  document.querySelector('#btn-info').addEventListener('click', () => {\n    console.log('cliccato');\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"btn-info\" label=\"Info\" variant=\"secondary\"></mds-button>\n<mds-dropdown id=\"dd-info\" target=\"#btn-info\">...</mds-dropdown>\n\n<script>\n  document.querySelector('#dd-info').addEventListener('mdsDropdownVisible', (e) => {\n    console.log('dropdown aperto', e.detail.visible);\n  });\n</script>\n```\n\n#### Do Not Use `target` Without a Matching Element in the DOM\n\n`target` is resolved with `querySelector` at `componentDidLoad` time. If the selector does not match any element the dropdown has no caller and cannot position or open itself. Always verify the `id` is present in the DOM before the component loads.\n\n```html\n<!-- 🚫 INCORRECT - typo: button has id \"btn-salva\", target points to \"#salva\" -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#salva\">\n  <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"btn-salva\" label=\"Salva\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-salva\">\n  <mds-text>Opzioni di salvataggio</mds-text>\n</mds-dropdown>\n```\n\n#### Do Not Use `<mds-button-dropdown>` and `<mds-dropdown>` Interchangeably\n\n[`mds-button-dropdown`](../../mds-button-dropdown) is a compound component that already embeds a trigger button and a dropdown. Use it for a simple action-button-plus-menu. Use `<mds-dropdown>` directly only when the caller is not an `mds-button`, or when you need full control over the trigger element.\n\n```html\n<!-- 🚫 INCORRECT - re-implementing what mds-button-dropdown already does -->\n<mds-button id=\"btn-azioni\" label=\"Azioni\" icon=\"mi/baseline/expand-more\" variant=\"primary\"></mds-button>\n<mds-dropdown target=\"#btn-azioni\">\n  <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n  <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-dropdown>\n\n<!-- ✅ CORRECT - use the dedicated compound component -->\n<mds-button-dropdown label=\"Azioni\" variant=\"primary\">\n  <mds-button label=\"Modifica\" variant=\"dark\" tone=\"text\"></mds-button>\n  <mds-button label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n</mds-button-dropdown>\n```\n\n#### Do Not Customize via Undocumented Shadow Internals\n\nThe supported customization surface is the `--mds-dropdown-*` CSS custom properties. Targeting internal elements via `::part()` on non-documented parts, `>>>`, or class-name selectors couples your code to the Shadow DOM structure and breaks on any internal refactor.\n\n```css\n/* 🚫 INCORRECT */\nmds-dropdown::part(panel) {\n  border: 2px solid red;\n}\nmds-dropdown >>> .arrow {\n  display: none;\n}\n\n/* ✅ CORRECT */\nmds-dropdown {\n  --mds-dropdown-background: rgb(var(--tone-neutral-08));\n  --mds-dropdown-z-index: 6000;\n}\n```\n"
       },
       "props": [
         {
-          "name": "arrow",
-          "type": "boolean",
+          "name": "arrowPadding",
+          "type": "number",
+          "complexType": {
+            "original": "number",
+            "resolved": "number",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "arrow-padding",
+          "reflectToAttr": false,
+          "docs": "Sets the distance between arrow and dropdown margins.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "24"
+            }
+          ],
+          "default": "24",
+          "values": [
+            {
+              "type": "number"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "backdrop",
+          "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
-            "resolved": "boolean",
+            "resolved": "boolean | undefined",
             "references": {}
           },
           "mutable": false,
-          "attr": "arrow",
+          "attr": "backdrop",
           "reflectToAttr": true,
-          "docs": "If set, the component will have an arrow pointing to the caller.",
+          "docs": "Specifies if the component has a backdrop background",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
+            },
+            {
+              "type": "undefined"
             }
           ],
-          "optional": false,
+          "optional": true,
           "required": false,
           "getter": false,
           "setter": false
         },
         {
-          "name": "arrowPadding",
-          "type": "number",
+          "name": "disableAutoPlacement",
+          "type": "boolean",
           "complexType": {
-            "original": "number",
-            "resolved": "number",
+            "original": "boolean",
+            "resolved": "boolean",
             "references": {}
           },
           "mutable": false,
-          "attr": "arrow-padding",
+          "attr": "disable-auto-placement",
           "reflectToAttr": false,
-          "docs": "Sets the distance between arrow and dropdown margins.",
+          "docs": "If set, the component will not be placed automatically near it's caller.",
           "docsTags": [
             {
               "name": "default",
-              "text": "24"
+              "text": "false"
             }
           ],
-          "default": "24",
+          "default": "false",
           "values": [
             {
-              "type": "number"
+              "type": "boolean"
             }
           ],
           "optional": false,
@@ -7276,7 +7263,7 @@
           "setter": false
         },
         {
-          "name": "autoPlacement",
+          "name": "disableShift",
           "type": "boolean",
           "complexType": {
             "original": "boolean",
@@ -7284,9 +7271,9 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "auto-placement",
+          "attr": "disable-shift",
           "reflectToAttr": false,
-          "docs": "If set, the component will be placed automatically near it's caller.",
+          "docs": "If set, the component will not be kept inside the viewport.",
           "docsTags": [
             {
               "name": "default",
@@ -7305,17 +7292,17 @@
           "setter": false
         },
         {
-          "name": "backdrop",
-          "type": "boolean | undefined",
+          "name": "disableSmooth",
+          "type": "boolean",
           "complexType": {
             "original": "boolean",
-            "resolved": "boolean | undefined",
+            "resolved": "boolean",
             "references": {}
           },
           "mutable": false,
-          "attr": "backdrop",
-          "reflectToAttr": true,
-          "docs": "Specifies if the component has a backdrop background",
+          "attr": "disable-smooth",
+          "reflectToAttr": false,
+          "docs": "If set, the component will not follow the caller smoothly when the page scrolls.",
           "docsTags": [
             {
               "name": "default",
@@ -7326,12 +7313,9 @@
           "values": [
             {
               "type": "boolean"
-            },
-            {
-              "type": "undefined"
             }
           ],
-          "optional": true,
+          "optional": false,
           "required": false,
           "getter": false,
           "setter": false
@@ -7365,6 +7349,35 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "hideArrow",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "hide-arrow",
+          "reflectToAttr": true,
+          "docs": "If set, the component will not have an arrow pointing to the caller.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "interaction",
           "type": "\"click\" | \"mouseover\" | \"none\"",
@@ -7520,35 +7533,6 @@
           "getter": false,
           "setter": false
         },
-        {
-          "name": "shift",
-          "type": "boolean",
-          "complexType": {
-            "original": "boolean",
-            "resolved": "boolean",
-            "references": {}
-          },
-          "mutable": false,
-          "attr": "shift",
-          "reflectToAttr": false,
-          "docs": "If set, the component will be kept inside the viewport.",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
-          "values": [
-            {
-              "type": "boolean"
-            }
-          ],
-          "optional": false,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "shiftPadding",
           "type": "number",
@@ -7578,35 +7562,6 @@
           "getter": false,
           "setter": false
         },
-        {
-          "name": "smooth",
-          "type": "boolean",
-          "complexType": {
-            "original": "boolean",
-            "resolved": "boolean",
-            "references": {}
-          },
-          "mutable": false,
-          "attr": "smooth",
-          "reflectToAttr": false,
-          "docs": "If set, the component will follow the caller smoothly, visible when the page scrolls.",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
-          "values": [
-            {
-              "type": "boolean"
-            }
-          ],
-          "optional": false,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "strategy",
           "type": "\"absolute\" | \"fixed\"",
@@ -8737,9 +8692,9 @@
       "docs": "This is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.",
       "docsTags": [],
       "usage": {
-        "1. Description": "The `<mds-file>` web component is the Magma Design System control for representing a downloadable file as a rich, clickable card. It pairs a filename with an auto-detected file-type icon, badge, and human-readable description, and tracks whether the file has already been downloaded.\n\n#### Semantic Behavior\n\n- **Clickable card**: The whole host is focusable and clicking it emits `mdsFileDownload`; the component itself does not fetch or download - the consumer wires the actual download to that event.\n- **Download event payload**: `mdsFileDownload` carries the resolved `description`, `extension`, `filename`, the host element as `target`, and the detected `type`/format.\n- **Downloaded persistence**: On click the component remembers the file as downloaded and shows a \"done\" indicator on subsequent renders; the state survives reloads.\n- **Automatic file-type recognition**: From `filename` it derives the format icon, badge variant, and default description; `suffix` overrides this detection.\n- **Localization**: Descriptions and the \"already downloaded\" tooltip are resolved against the active locale.\n\n#### Properties & Visual Configurations\n\n- **`filename`** is the primary input: it provides the displayed title and drives icon, badge, suffix, and description detection. The name and extension are rendered separately, with the extension shown only when not explicitly overridden by `suffix`.\n- **`suffix`** forces a specific file type from the supported format set when the filename's extension is missing or wrong; it bypasses automatic recognition.\n- **`description`** overrides the derived, localized file-type description when a custom label is needed.\n- **`preview`** supplies an image URL (logo or thumbnail) rendered as the preview surface instead of the generic format icon - use it when a meaningful visual of the file exists.\n- **`showDownloadedIcon`** (default `true`) toggles the persisted \"already downloaded\" indicator; set it to `false` to suppress that affordance.\n- **`format`** is normally populated by the component itself from detection rather than set by the consumer.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-file>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic File Card\n\nThe minimal form. Pass `filename` with a real filename (including extension) and the component auto-detects the format icon, badge color, and localized description.\n\n```html\n<mds-file filename=\"relazione-annuale.pdf\"></mds-file>\n```\n\n#### Handling the Download Event\n\nThe component does not fetch or download anything by itself. Listen for `mdsFileDownload` and trigger the actual download in the event handler. The event detail carries `filename`, `extension`, `type`, `description`, and `target`.\n\n```html\n<mds-file filename=\"contratto-servizio.docx\" id=\"file-card\"></mds-file>\n\n<script>\n  document.getElementById('file-card').addEventListener('mdsFileDownload', (event) => {\n    const { filename, extension, type } = event.detail;\n    console.log(`Download avviato: ${filename} (${type})`);\n    // avvia il download effettivo dal server\n  });\n</script>\n```\n\n#### Forcing a File Type with `suffix`\n\nWhen the filename lacks an extension or carries a misleading one, use `suffix` to force a specific format from the supported set.\n\n```html\n<!-- filename senza estensione - forza il riconoscimento come PDF -->\n<mds-file filename=\"documento-firmato\" suffix=\"pdf\"></mds-file>\n\n<!-- estensione sconosciuta - forzata come archivio ZIP -->\n<mds-file filename=\"backup.bkp\" suffix=\"zip\"></mds-file>\n```\n\n#### Custom Description\n\nOverride the localized auto-generated description with a specific label relevant to the document context. Use `description` when the default type label (e.g. \"Documento PDF\") is not informative enough.\n\n```html\n<mds-file\n  filename=\"verbale-cda-2024.pdf\"\n  description=\"Verbale approvato dal Consiglio di Amministrazione\"\n></mds-file>\n```\n\n#### Image Preview\n\nProvide `preview` with an image URL when a meaningful visual thumbnail is available - a logo, a reduced version of an image file, or a document cover. The preview replaces the generic format icon in the left panel.\n\n```html\n<mds-file\n  filename=\"logo-aziendale.png\"\n  preview=\"https://cdn.example.com/thumbnails/logo-aziendale-128.png\"\n></mds-file>\n```\n\n#### Hiding the \"Already Downloaded\" Indicator\n\nBy default the component persists a \"done\" indicator once the file has been downloaded. Set `show-downloaded-icon=\"false\"` to suppress it when the affordance is not appropriate for the context (e.g. a list where every file is always shown as fresh).\n\n```html\n<mds-file filename=\"modulo-richiesta.xlsx\" show-downloaded-icon=\"false\"></mds-file>\n```\n\nNote: this is the only valid way to turn the indicator off - do not set it to the string `\"false\"` (see the Antipattern file).\n\n#### Rendering a List of Files\n\nPlace multiple `<mds-file>` cards inside a container and attach a single delegated event listener when the file list is dynamic.\n\n```html\n<div class=\"file-list\">\n  <mds-file filename=\"allegato-1.pdf\"></mds-file>\n  <mds-file filename=\"allegato-2.docx\"></mds-file>\n  <mds-file filename=\"allegato-3.xlsx\"></mds-file>\n</div>\n\n<script>\n  document.querySelector('.file-list').addEventListener('mdsFileDownload', (event) => {\n    const { filename } = event.detail;\n    avviaDownload(filename);\n  });\n</script>\n```\n\n#### Styling Customization\n\nStyle the preview panel only through the three documented `--mds-file-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.archivio-documenti mds-file {\n  --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n  --mds-file-preview-icon-bacground: rgb(var(--variant-primary-10));\n  --mds-file-preview-color: rgb(var(--variant-primary-04));\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-file>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Expect the Component to Perform the Download\n\n`<mds-file>` is a display card, not a download trigger. It emits `mdsFileDownload` and the consumer must wire the actual download logic to that event.\n\n```html\n<!-- 🚫 INCORRECT - expecting the component to handle the download itself -->\n<mds-file filename=\"report.pdf\" href=\"/files/report.pdf\"></mds-file>\n\n<!-- ✅ CORRECT - consumer listens to the event and handles the download -->\n<mds-file filename=\"report.pdf\" id=\"card-report\"></mds-file>\n\n<script>\n  document.getElementById('card-report').addEventListener('mdsFileDownload', (e) => {\n    window.location.href = '/files/' + e.detail.filename;\n  });\n</script>\n```\n\n#### Do Not Set `show-downloaded-icon` to the String \"false\"\n\n`showDownloadedIcon` is a boolean prop. Setting the attribute to the string `\"false\"` evaluates as truthy in HTML and leaves the indicator enabled. Remove the attribute or set the prop to `false` in your framework binding.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-file filename=\"modulo.pdf\" show-downloaded-icon=\"false\"></mds-file>\n\n<!-- ✅ CORRECT (HTML attribute absent = disabled) -->\n<mds-file filename=\"modulo.pdf\"></mds-file>\n```\n\n#### Do Not Set `format` Manually\n\n`format` is an internal reflected attribute automatically derived from the filename and suffix. Setting it directly has no guaranteed effect because the component overwrites it during `componentWillLoad` and on every `filename` change. Use `suffix` to control type detection.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-file filename=\"archivio\" format=\"document\"></mds-file>\n\n<!-- ✅ CORRECT - use suffix to override file-type detection -->\n<mds-file filename=\"archivio\" suffix=\"pdf\"></mds-file>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Preview Panel\n\nThe supported customization surface is `--mds-file-preview-*` CSS custom properties. Targeting internal elements with `>>>`, `/deep/`, or undocumented selectors couples your code to the Shadow DOM structure and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-file >>> .preview {\n  background-color: blue;\n}\n\n/* ✅ CORRECT */\nmds-file {\n  --mds-file-preview-icon-bacground: rgb(var(--variant-primary-10));\n  --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n}\n```\n\n#### Do Not Wrap `<mds-file>` in a Native Anchor or Button\n\nThe host is already focusable, keyboard-accessible, and emits its own interaction event. Wrapping it in `<a>` or `<button>` creates nested interactive controls and breaks keyboard semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<a href=\"/download/report.pdf\">\n  <mds-file filename=\"report.pdf\"></mds-file>\n</a>\n\n<!-- ✅ CORRECT - use the mdsFileDownload event to trigger navigation or download -->\n<mds-file filename=\"report.pdf\" id=\"file-report\"></mds-file>\n\n<script>\n  document.getElementById('file-report').addEventListener('mdsFileDownload', () => {\n    window.location.href = '/download/report.pdf';\n  });\n</script>\n```\n\n#### Do Not Use a Raw `<div>` or `<li>` as a File Row When `<mds-file>` Exists\n\n`<mds-file>` handles format detection, theming, accessibility focus, download persistence, and localization. Rolling a custom file row loses all of these affordances.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"file-row\" onclick=\"download('report.pdf')\">\n  <img src=\"pdf-icon.svg\" alt=\"PDF\" />\n  <span>report.pdf</span>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-file filename=\"report.pdf\"></mds-file>\n```\n"
+        "1. Description": "The `<mds-file>` web component is the Magma Design System control for representing a downloadable file as a rich, clickable card. It pairs a filename with an auto-detected file-type icon, badge, and human-readable description, and tracks whether the file has already been downloaded.\n\n#### Semantic Behavior\n\n- **Clickable card**: The whole host is focusable and clicking it emits `mdsFileDownload`; the component itself does not fetch or download - the consumer wires the actual download to that event.\n- **Download event payload**: `mdsFileDownload` carries the resolved `description`, `extension`, `filename`, the host element as `target`, and the detected `type`/format.\n- **Downloaded persistence**: On click the component remembers the file as downloaded and shows a \"done\" indicator on subsequent renders; the state survives reloads.\n- **Automatic file-type recognition**: From `filename` it derives the format icon, badge variant, and default description; `suffix` overrides this detection.\n- **Localization**: Descriptions and the \"already downloaded\" tooltip are resolved against the active locale.\n\n#### Properties & Visual Configurations\n\n- **`filename`** is the primary input: it provides the displayed title and drives icon, badge, suffix, and description detection. The name and extension are rendered separately, with the extension shown only when not explicitly overridden by `suffix`.\n- **`suffix`** forces a specific file type from the supported format set when the filename's extension is missing or wrong; it bypasses automatic recognition.\n- **`description`** overrides the derived, localized file-type description when a custom label is needed.\n- **`preview`** supplies an image URL (logo or thumbnail) rendered as the preview surface instead of the generic format icon - use it when a meaningful visual of the file exists.\n- **`hideDownloadedIcon`** (default `false`) suppresses the persisted \"already downloaded\" indicator; set it when that affordance is not appropriate.\n- **`format`** is normally populated by the component itself from detection rather than set by the consumer.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-file>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic File Card\n\nThe minimal form. Pass `filename` with a real filename (including extension) and the component auto-detects the format icon, badge color, and localized description.\n\n```html\n<mds-file filename=\"relazione-annuale.pdf\"></mds-file>\n```\n\n#### Handling the Download Event\n\nThe component does not fetch or download anything by itself. Listen for `mdsFileDownload` and trigger the actual download in the event handler. The event detail carries `filename`, `extension`, `type`, `description`, and `target`.\n\n```html\n<mds-file filename=\"contratto-servizio.docx\" id=\"file-card\"></mds-file>\n\n<script>\n  document.getElementById('file-card').addEventListener('mdsFileDownload', (event) => {\n    const { filename, extension, type } = event.detail;\n    console.log(`Download avviato: ${filename} (${type})`);\n    // avvia il download effettivo dal server\n  });\n</script>\n```\n\n#### Forcing a File Type with `suffix`\n\nWhen the filename lacks an extension or carries a misleading one, use `suffix` to force a specific format from the supported set.\n\n```html\n<!-- filename senza estensione - forza il riconoscimento come PDF -->\n<mds-file filename=\"documento-firmato\" suffix=\"pdf\"></mds-file>\n\n<!-- estensione sconosciuta - forzata come archivio ZIP -->\n<mds-file filename=\"backup.bkp\" suffix=\"zip\"></mds-file>\n```\n\n#### Custom Description\n\nOverride the localized auto-generated description with a specific label relevant to the document context. Use `description` when the default type label (e.g. \"Documento PDF\") is not informative enough.\n\n```html\n<mds-file\n  filename=\"verbale-cda-2024.pdf\"\n  description=\"Verbale approvato dal Consiglio di Amministrazione\"\n></mds-file>\n```\n\n#### Image Preview\n\nProvide `preview` with an image URL when a meaningful visual thumbnail is available - a logo, a reduced version of an image file, or a document cover. The preview replaces the generic format icon in the left panel.\n\n```html\n<mds-file\n  filename=\"logo-aziendale.png\"\n  preview=\"https://cdn.example.com/thumbnails/logo-aziendale-128.png\"\n></mds-file>\n```\n\n#### Hiding the \"Already Downloaded\" Indicator\n\nBy default the component persists a \"done\" indicator once the file has been downloaded. Add `hide-downloaded-icon` to suppress it when the affordance is not appropriate for the context (e.g. a list where every file is always shown as fresh).\n\n```html\n<mds-file filename=\"modulo-richiesta.xlsx\" hide-downloaded-icon></mds-file>\n```\n\nNote: this is the only valid way to turn the indicator off - do not set it to the string `\"false\"` (see the Antipattern file).\n\n#### Rendering a List of Files\n\nPlace multiple `<mds-file>` cards inside a container and attach a single delegated event listener when the file list is dynamic.\n\n```html\n<div class=\"file-list\">\n  <mds-file filename=\"allegato-1.pdf\"></mds-file>\n  <mds-file filename=\"allegato-2.docx\"></mds-file>\n  <mds-file filename=\"allegato-3.xlsx\"></mds-file>\n</div>\n\n<script>\n  document.querySelector('.file-list').addEventListener('mdsFileDownload', (event) => {\n    const { filename } = event.detail;\n    avviaDownload(filename);\n  });\n</script>\n```\n\n#### Styling Customization\n\nStyle the preview panel only through the three documented `--mds-file-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.archivio-documenti mds-file {\n  --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n  --mds-file-preview-icon-bacground: rgb(var(--variant-primary-10));\n  --mds-file-preview-color: rgb(var(--variant-primary-04));\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-file>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Expect the Component to Perform the Download\n\n`<mds-file>` is a display card, not a download trigger. It emits `mdsFileDownload` and the consumer must wire the actual download logic to that event.\n\n```html\n<!-- 🚫 INCORRECT - expecting the component to handle the download itself -->\n<mds-file filename=\"report.pdf\" href=\"/files/report.pdf\"></mds-file>\n\n<!-- ✅ CORRECT - consumer listens to the event and handles the download -->\n<mds-file filename=\"report.pdf\" id=\"card-report\"></mds-file>\n\n<script>\n  document.getElementById('card-report').addEventListener('mdsFileDownload', (e) => {\n    window.location.href = '/files/' + e.detail.filename;\n  });\n</script>\n```\n\n#### Do Not Set `format` Manually\n\n`format` is an internal reflected attribute automatically derived from the filename and suffix. Setting it directly has no guaranteed effect because the component overwrites it during `componentWillLoad` and on every `filename` change. Use `suffix` to control type detection.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-file filename=\"archivio\" format=\"document\"></mds-file>\n\n<!-- ✅ CORRECT - use suffix to override file-type detection -->\n<mds-file filename=\"archivio\" suffix=\"pdf\"></mds-file>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Preview Panel\n\nThe supported customization surface is `--mds-file-preview-*` CSS custom properties. Targeting internal elements with `>>>`, `/deep/`, or undocumented selectors couples your code to the Shadow DOM structure and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-file >>> .preview {\n  background-color: blue;\n}\n\n/* ✅ CORRECT */\nmds-file {\n  --mds-file-preview-icon-bacground: rgb(var(--variant-primary-10));\n  --mds-file-preview-icon-color: rgb(var(--variant-primary-04));\n}\n```\n\n#### Do Not Wrap `<mds-file>` in a Native Anchor or Button\n\nThe host is already focusable, keyboard-accessible, and emits its own interaction event. Wrapping it in `<a>` or `<button>` creates nested interactive controls and breaks keyboard semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<a href=\"/download/report.pdf\">\n  <mds-file filename=\"report.pdf\"></mds-file>\n</a>\n\n<!-- ✅ CORRECT - use the mdsFileDownload event to trigger navigation or download -->\n<mds-file filename=\"report.pdf\" id=\"file-report\"></mds-file>\n\n<script>\n  document.getElementById('file-report').addEventListener('mdsFileDownload', () => {\n    window.location.href = '/download/report.pdf';\n  });\n</script>\n```\n\n#### Do Not Use a Raw `<div>` or `<li>` as a File Row When `<mds-file>` Exists\n\n`<mds-file>` handles format detection, theming, accessibility focus, download persistence, and localization. Rolling a custom file row loses all of these affordances.\n\n```html\n<!-- 🚫 INCORRECT -->\n<div class=\"file-row\" onclick=\"download('report.pdf')\">\n  <img src=\"pdf-icon.svg\" alt=\"PDF\" />\n  <span>report.pdf</span>\n</div>\n\n<!-- ✅ CORRECT -->\n<mds-file filename=\"report.pdf\"></mds-file>\n```\n"
       },
       "props": [
         {
@@ -8817,6 +8772,38 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "hideDownloadedIcon",
+          "type": "boolean | undefined",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean | undefined",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "hide-downloaded-icon",
+          "reflectToAttr": false,
+          "docs": "Hides the download icon",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "preview",
           "type": "string | undefined",
@@ -8843,38 +8830,6 @@
           "getter": false,
           "setter": false
         },
-        {
-          "name": "showDownloadedIcon",
-          "type": "boolean | undefined",
-          "complexType": {
-            "original": "boolean",
-            "resolved": "boolean | undefined",
-            "references": {}
-          },
-          "mutable": false,
-          "attr": "show-downloaded-icon",
-          "reflectToAttr": false,
-          "docs": "Sets if the download icon must be shown or not",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
-          "values": [
-            {
-              "type": "boolean"
-            },
-            {
-              "type": "undefined"
-            }
-          ],
-          "optional": true,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "suffix",
           "type": "\"7z\" | \"ace\" | \"ai\" | \"db\" | \"default\" | \"dmg\" | \"doc\" | \"docm\" | \"docx\" | \"eml\" | \"eps\" | \"exe\" | \"flac\" | \"gif\" | \"heic\" | \"htm\" | \"html\" | \"jpe\" | \"jpeg\" | \"jpg\" | \"js\" | \"json\" | \"jsx\" | \"m2v\" | \"mp2\" | \"mp3\" | \"mp4\" | \"mp4v\" | \"mpeg\" | \"mpg\" | \"mpg4\" | \"mpga\" | \"odf\" | \"odp\" | \"ods\" | \"odt\" | \"ole\" | \"p7m\" | \"pdf\" | \"php\" | \"png\" | \"ppt\" | \"rar\" | \"rtf\" | \"sass\" | \"shtml\" | \"svg\" | \"tar\" | \"tiff\" | \"ts\" | \"tsd\" | \"txt\" | \"wav\" | \"webp\" | \"xar\" | \"xls\" | \"xlsx\" | \"xml\" | \"zip\" | undefined",
@@ -10503,9 +10458,9 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-header>` web component is the top-level page header container of the Magma Design System. It is a compound parent that wraps one or more `<mds-header-bar>` elements, orchestrating their scroll-driven appearance, auto-hide visibility, and an optional mobile menu rendered as a side modal.\n\n#### Semantic Behavior\n\n- **Compound parent**: Hosts `<mds-header-bar>` children in the default slot and relays its `menu` and `nav` settings down to the bar.\n- **Mobile menu**: A `[slot=\"menu\"]` child is rendered inside a right-positioned modal; when absent, the bar's menu mode is forced to `'none'`.\n- **Open/close control**: The menu modal is opened programmatically via the `setOpened()` method; closing it emits `mdsHeaderClose` (with the bound bar).\n- **Scroll-driven appearance**: When `appearanceSet` defines a threshold, `appearance` swaps between its initial and changed values as the page scrolls past the configured pixel threshold.\n- **Auto-hide on scroll**: When `autoHide` is set, scrolling down past that pixel offset hides the bar and scrolling up reveals it again, governed by `threshold` as the directional margin.\n- **Visibility event**: Any change to `visibility` (`'visible'`/`'hidden'`) emits `mdsHeaderVisibilityChange`.\n\n#### Properties & Visual Configurations\n\n- **`appearance`** is the bar's current visual mode (`'stripe'` or `'inline'`) and is mutable because the component rewrites it as the page scrolls.\n- **`appearanceSet`** is a space/comma-separated string declaring scroll behavior as three tokens: initial appearance, changed appearance, and the `scrollY` pixel threshold (e.g. `\"stripe, inline 200\"`). Use it instead of `appearance` when the header should transform on scroll; `appearance` alone keeps a fixed look.\n- **`autoHide`** is the pixel offset past which the bar starts hiding on downward scroll; leave it unset to keep the bar always present.\n- **`threshold`** tunes how many pixels of opposite-direction scroll are required to flip the auto-hide state - raise it to make hide/show less twitchy.\n- **`menu`** and **`nav`** select on which viewports the hamburger menu and the navigation are shown (`'all'`, `'desktop'`, `'mobile'`, `'none'`); they are relayed to the child bar.\n- **`backdrop`** toggles the blurred backdrop layer shown behind the bar when its appearance is `'inline'`.\n- **`visibility`** reflects the current shown/hidden state of the bar and can be set to force it.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-header>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Minimal Header with Navigation Bar\n\nThe default form. Place exactly one `<mds-header-bar>` in the default slot. The bar receives the `menu` and `nav` breakpoint settings from the parent automatically.\n\n```html\n<mds-header>\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n    <mds-button slot=\"nav\" label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Mobile Menu via the `menu` Slot\n\nProvide a `[slot=\"menu\"]` child to enable the hamburger-triggered side modal. When this slot is filled, the mobile menu icon is shown according to the `menu` breakpoint prop; when absent, `menu` is forced to `'none'` automatically.\n\n```html\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n\n  <div slot=\"menu\">\n    <div class=\"p-600\">\n      <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n      <mds-button label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n    </div>\n  </div>\n</mds-header>\n```\n\n#### Inline Appearance (Floating Bar)\n\nSet `appearance=\"inline\"` to detach the bar from the top edge and give it a rounded, floating look. A blurred backdrop is shown by default; set `backdrop` to `false` to remove it.\n\n```html\n<mds-header appearance=\"inline\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Scroll-Driven Appearance Change via `appearance-set`\n\nUse `appearance-set` to declare an initial appearance, a changed appearance, and a scroll threshold in pixels. The component swaps `appearance` automatically as the page scrolls past the threshold - no JavaScript needed. Do not combine `appearance-set` with manual writes to `appearance`.\n\n```html\n<!-- Starts inline (floating), switches to stripe (full-width) after 300 px of scroll -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Auto-Hide on Downward Scroll\n\nSet `auto-hide` to the pixel offset at which the bar should start hiding when the user scrolls down. The bar reappears when the user scrolls back up. Use `threshold` (default `1`) to control how many pixels of reverse-scroll are required before the bar snaps back - raise it to reduce twitchiness.\n\n```html\n<mds-header auto-hide=\"300\" threshold=\"10\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Controlling Menu and Nav Breakpoints\n\n`menu` controls on which viewports the hamburger icon is visible; `nav` controls on which viewports the inline navigation is visible. Both accept `'all'`, `'desktop'`, `'mobile'`, or `'none'`.\n\n```html\n<!-- Hamburger shown on all screen sizes; inline nav shown only on desktop -->\n<mds-header menu=\"all\" nav=\"desktop\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n\n  <div slot=\"menu\">\n    <div class=\"p-600\">\n      <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n    </div>\n  </div>\n</mds-header>\n```\n\n#### Reacting to Visibility Changes\n\nListen for `mdsHeaderVisibilityChange` to know when the bar is hidden or shown by auto-hide. The event detail carries a `visibility` boolean.\n\n```html\n<mds-header auto-hide=\"200\" id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n\n<script>\n  document.getElementById('siteHeader').addEventListener('mdsHeaderVisibilityChange', (e) => {\n    console.log('header visibile:', e.detail.visibility);\n  });\n</script>\n```\n\n#### Reacting to Mobile Menu Close\n\nListen for `mdsHeaderClose` to run cleanup logic when the side modal is dismissed. The event detail carries the bound `<mds-header-bar>` reference.\n\n```html\n<mds-header id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </div>\n</mds-header>\n\n<script>\n  document.getElementById('siteHeader').addEventListener('mdsHeaderClose', (e) => {\n    console.log('menu chiuso, bar:', e.detail.bar);\n  });\n</script>\n```\n\n#### Programmatic Open/Close via `setOpened()`\n\nUse the `setOpened()` method to open or close the mobile menu from JavaScript - for example after a navigation event inside the menu panel.\n\n```html\n<mds-header id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Vai alla home\" id=\"homeBtn\" variant=\"primary\" tone=\"strong\"></mds-button>\n  </div>\n</mds-header>\n\n<script>\n  document.getElementById('homeBtn').addEventListener('click', async () => {\n    window.location.href = '/';\n    await document.getElementById('siteHeader').setOpened(false);\n  });\n</script>\n```\n\n#### Styling Customization\n\nCustomize the header through its documented `--mds-header-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast continue to work.\n\n```css\nmds-header {\n  --mds-header-color: rgb(var(--tone-neutral));\n  --mds-header-icon-color: rgb(var(--variant-primary-03));\n  --mds-header-z-index: 200;\n}\n\n/* Inline appearance: wider floating margin on desktop */\nmds-header[appearance='inline'] {\n  --mds-header-inline-margin: 2rem;\n  --mds-header-backdrop-blur-strength: 4px;\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place `<mds-header-bar>` Outside `<mds-header>`\n\n`<mds-header-bar>` is a compound child; it must be a direct slot child of `<mds-header>`, which relays breakpoint and appearance state down to it. Using the bar standalone breaks that communication and leaves `menu`, `nav`, and auto-hide inoperative.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar>\n  <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n</mds-header-bar>\n\n<!-- ✅ CORRECT -->\n<mds-header>\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Set `backdrop=\"false\"` to Disable the Backdrop\n\n`backdrop` is a boolean prop. Setting it to the string `\"false\"` is truthy in HTML and keeps the backdrop visible. Remove the attribute entirely to disable it.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header appearance=\"inline\" backdrop=\"false\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n\n<!-- ✅ CORRECT -->\n<mds-header appearance=\"inline\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Drive Scroll Appearance with JavaScript When `appearance-set` Is Available\n\nManually toggling `appearance` on a scroll listener duplicates what `appearance-set` already handles declaratively and risks conflicts with the component's own watcher.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header id=\"hdr\" appearance=\"inline\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  window.addEventListener('scroll', () => {\n    document.getElementById('hdr').appearance = window.scrollY > 300 ? 'stripe' : 'inline';\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Omit the `menu` Slot When Providing a Hamburger-Only Nav\n\nIf no `[slot=\"menu\"]` child is present, the component forces `menu=\"none\"` on the bar, so the hamburger icon never appears regardless of the `menu` prop. Always provide menu content when you want the mobile toggle to be visible.\n\n```html\n<!-- 🚫 INCORRECT: hamburger icon will never show -->\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n\n<!-- ✅ CORRECT -->\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </div>\n</mds-header>\n```\n\n#### Do Not Listen to Native `scroll` Events to Detect Auto-Hide State\n\nThe component already emits `mdsHeaderVisibilityChange` when the bar flips between hidden and visible. Attaching a second `scroll` listener couples your code to the same threshold logic and risks running out of sync.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  window.addEventListener('scroll', () => {\n    const hidden = window.scrollY > 300;\n    document.body.classList.toggle('header-hidden', hidden);\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  document.getElementById('hdr').addEventListener('mdsHeaderVisibilityChange', (e) => {\n    document.body.classList.toggle('header-hidden', !e.detail.visibility);\n  });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Internal Modal\n\nThe side-modal container is exposed as `::part(menu)` and its colors are controllable via `--mds-header-*` CSS custom properties. Do not use `>>>`, `/deep/`, or undocumented internal selectors.\n\n```css\n/* 🚫 INCORRECT */\nmds-header >>> .menu mds-modal {\n  background: red;\n}\n\n/* ✅ CORRECT */\nmds-header {\n  --mds-header-z-index: 500;\n}\nmds-header::part(menu) {\n  /* documented part - safe to target */\n}\n```\n"
+        "1. Description": "The `<mds-header>` web component is the top-level page header container of the Magma Design System. It is a compound parent that wraps one or more `<mds-header-bar>` elements, orchestrating their scroll-driven appearance, auto-hide visibility, and an optional mobile menu rendered as a side modal.\n\n#### Semantic Behavior\n\n- **Compound parent**: Hosts `<mds-header-bar>` children in the default slot and relays its `menu` and `nav` settings down to the bar.\n- **Mobile menu**: A `[slot=\"menu\"]` child is rendered inside a right-positioned modal; when absent, the bar's menu mode is forced to `'none'`.\n- **Open/close control**: The menu modal is opened programmatically via the `setOpened()` method; closing it emits `mdsHeaderClose` (with the bound bar).\n- **Scroll-driven appearance**: When `appearanceSet` defines a threshold, `appearance` swaps between its initial and changed values as the page scrolls past the configured pixel threshold.\n- **Auto-hide on scroll**: When `autoHide` is set, scrolling down past that pixel offset hides the bar and scrolling up reveals it again, governed by `threshold` as the directional margin.\n- **Visibility event**: Any change to `visibility` (`'visible'`/`'hidden'`) emits `mdsHeaderVisibilityChange`.\n\n#### Properties & Visual Configurations\n\n- **`appearance`** is the bar's current visual mode (`'stripe'` or `'inline'`) and is mutable because the component rewrites it as the page scrolls.\n- **`appearanceSet`** is a space/comma-separated string declaring scroll behavior as three tokens: initial appearance, changed appearance, and the `scrollY` pixel threshold (e.g. `\"stripe, inline 200\"`). Use it instead of `appearance` when the header should transform on scroll; `appearance` alone keeps a fixed look.\n- **`autoHide`** is the pixel offset past which the bar starts hiding on downward scroll; leave it unset to keep the bar always present.\n- **`threshold`** tunes how many pixels of opposite-direction scroll are required to flip the auto-hide state - raise it to make hide/show less twitchy.\n- **`menu`** and **`nav`** select on which viewports the hamburger menu and the navigation are shown (`'all'`, `'desktop'`, `'mobile'`, `'none'`); they are relayed to the child bar.\n- **`hideBackdrop`** removes the blurred backdrop layer shown behind the bar when its appearance is `'inline'`.\n- **`visibility`** reflects the current shown/hidden state of the bar and can be set to force it.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-header>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the compound-component rules in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Minimal Header with Navigation Bar\n\nThe default form. Place exactly one `<mds-header-bar>` in the default slot. The bar receives the `menu` and `nav` breakpoint settings from the parent automatically.\n\n```html\n<mds-header>\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n    <mds-button slot=\"nav\" label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Mobile Menu via the `menu` Slot\n\nProvide a `[slot=\"menu\"]` child to enable the hamburger-triggered side modal. When this slot is filled, the mobile menu icon is shown according to the `menu` breakpoint prop; when absent, `menu` is forced to `'none'` automatically.\n\n```html\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n\n  <div slot=\"menu\">\n    <div class=\"p-600\">\n      <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n      <mds-button label=\"Registrati\" variant=\"primary\" tone=\"strong\"></mds-button>\n    </div>\n  </div>\n</mds-header>\n```\n\n#### Inline Appearance (Floating Bar)\n\nSet `appearance=\"inline\"` to detach the bar from the top edge and give it a rounded, floating look. A blurred backdrop is shown by default; add `hide-backdrop` to remove it.\n\n```html\n<mds-header appearance=\"inline\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Scroll-Driven Appearance Change via `appearance-set`\n\nUse `appearance-set` to declare an initial appearance, a changed appearance, and a scroll threshold in pixels. The component swaps `appearance` automatically as the page scrolls past the threshold - no JavaScript needed. Do not combine `appearance-set` with manual writes to `appearance`.\n\n```html\n<!-- Starts inline (floating), switches to stripe (full-width) after 300 px of scroll -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Auto-Hide on Downward Scroll\n\nSet `auto-hide` to the pixel offset at which the bar should start hiding when the user scrolls down. The bar reappears when the user scrolls back up. Use `threshold` (default `1`) to control how many pixels of reverse-scroll are required before the bar snaps back - raise it to reduce twitchiness.\n\n```html\n<mds-header auto-hide=\"300\" threshold=\"10\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Controlling Menu and Nav Breakpoints\n\n`menu` controls on which viewports the hamburger icon is visible; `nav` controls on which viewports the inline navigation is visible. Both accept `'all'`, `'desktop'`, `'mobile'`, or `'none'`.\n\n```html\n<!-- Hamburger shown on all screen sizes; inline nav shown only on desktop -->\n<mds-header menu=\"all\" nav=\"desktop\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n\n  <div slot=\"menu\">\n    <div class=\"p-600\">\n      <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n    </div>\n  </div>\n</mds-header>\n```\n\n#### Reacting to Visibility Changes\n\nListen for `mdsHeaderVisibilityChange` to know when the bar is hidden or shown by auto-hide. The event detail carries a `visibility` boolean.\n\n```html\n<mds-header auto-hide=\"200\" id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n\n<script>\n  document.getElementById('siteHeader').addEventListener('mdsHeaderVisibilityChange', (e) => {\n    console.log('header visibile:', e.detail.visibility);\n  });\n</script>\n```\n\n#### Reacting to Mobile Menu Close\n\nListen for `mdsHeaderClose` to run cleanup logic when the side modal is dismissed. The event detail carries the bound `<mds-header-bar>` reference.\n\n```html\n<mds-header id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </div>\n</mds-header>\n\n<script>\n  document.getElementById('siteHeader').addEventListener('mdsHeaderClose', (e) => {\n    console.log('menu chiuso, bar:', e.detail.bar);\n  });\n</script>\n```\n\n#### Programmatic Open/Close via `setOpened()`\n\nUse the `setOpened()` method to open or close the mobile menu from JavaScript - for example after a navigation event inside the menu panel.\n\n```html\n<mds-header id=\"siteHeader\">\n  <mds-header-bar>\n    <mds-img class=\"w-800\" src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Vai alla home\" id=\"homeBtn\" variant=\"primary\" tone=\"strong\"></mds-button>\n  </div>\n</mds-header>\n\n<script>\n  document.getElementById('homeBtn').addEventListener('click', async () => {\n    window.location.href = '/';\n    await document.getElementById('siteHeader').setOpened(false);\n  });\n</script>\n```\n\n#### Styling Customization\n\nCustomize the header through its documented `--mds-header-*` CSS custom properties. Use Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast continue to work.\n\n```css\nmds-header {\n  --mds-header-color: rgb(var(--tone-neutral));\n  --mds-header-icon-color: rgb(var(--variant-primary-03));\n  --mds-header-z-index: 200;\n}\n\n/* Inline appearance: wider floating margin on desktop */\nmds-header[appearance='inline'] {\n  --mds-header-inline-margin: 2rem;\n  --mds-header-backdrop-blur-strength: 4px;\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-header>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Place `<mds-header-bar>` Outside `<mds-header>`\n\n`<mds-header-bar>` is a compound child; it must be a direct slot child of `<mds-header>`, which relays breakpoint and appearance state down to it. Using the bar standalone breaks that communication and leaves `menu`, `nav`, and auto-hide inoperative.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header-bar>\n  <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n</mds-header-bar>\n\n<!-- ✅ CORRECT -->\n<mds-header>\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n  </mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Drive Scroll Appearance with JavaScript When `appearance-set` Is Available\n\nManually toggling `appearance` on a scroll listener duplicates what `appearance-set` already handles declaratively and risks conflicts with the component's own watcher.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header id=\"hdr\" appearance=\"inline\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  window.addEventListener('scroll', () => {\n    document.getElementById('hdr').appearance = window.scrollY > 300 ? 'stripe' : 'inline';\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-header appearance-set=\"inline, stripe 300\" appearance=\"inline\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n```\n\n#### Do Not Omit the `menu` Slot When Providing a Hamburger-Only Nav\n\nIf no `[slot=\"menu\"]` child is present, the component forces `menu=\"none\"` on the bar, so the hamburger icon never appears regardless of the `menu` prop. Always provide menu content when you want the mobile toggle to be visible.\n\n```html\n<!-- 🚫 INCORRECT: hamburger icon will never show -->\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n</mds-header>\n\n<!-- ✅ CORRECT -->\n<mds-header menu=\"mobile\">\n  <mds-header-bar>\n    <mds-img src=\"/logo.svg\" alt=\"Logo\"></mds-img>\n    <mds-button slot=\"nav\" label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </mds-header-bar>\n  <div slot=\"menu\">\n    <mds-button label=\"Accedi\" variant=\"dark\" tone=\"outline\"></mds-button>\n  </div>\n</mds-header>\n```\n\n#### Do Not Listen to Native `scroll` Events to Detect Auto-Hide State\n\nThe component already emits `mdsHeaderVisibilityChange` when the bar flips between hidden and visible. Attaching a second `scroll` listener couples your code to the same threshold logic and risks running out of sync.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  window.addEventListener('scroll', () => {\n    const hidden = window.scrollY > 300;\n    document.body.classList.toggle('header-hidden', hidden);\n  });\n</script>\n\n<!-- ✅ CORRECT -->\n<mds-header auto-hide=\"300\" id=\"hdr\">\n  <mds-header-bar>...</mds-header-bar>\n</mds-header>\n<script>\n  document.getElementById('hdr').addEventListener('mdsHeaderVisibilityChange', (e) => {\n    document.body.classList.toggle('header-hidden', !e.detail.visibility);\n  });\n</script>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Internal Modal\n\nThe side-modal container is exposed as `::part(menu)` and its colors are controllable via `--mds-header-*` CSS custom properties. Do not use `>>>`, `/deep/`, or undocumented internal selectors.\n\n```css\n/* 🚫 INCORRECT */\nmds-header >>> .menu mds-modal {\n  background: red;\n}\n\n/* ✅ CORRECT */\nmds-header {\n  --mds-header-z-index: 500;\n}\nmds-header::part(menu) {\n  /* documented part - safe to target */\n}\n```\n"
       },
       "props": [
         {
@@ -10590,7 +10545,7 @@
           "setter": false
         },
         {
-          "name": "backdrop",
+          "name": "hideBackdrop",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -10598,16 +10553,16 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "backdrop",
+          "attr": "hide-backdrop",
           "reflectToAttr": true,
-          "docs": "Sets if the backdrop is shown when the mds-header-bar attribute appearace is set to `inline`",
+          "docs": "Hides the backdrop shown when the mds-header-bar attribute appearace is set to `inline`",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -11219,13 +11174,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-help>` web component is a contextual help affordance of the Magma Design System: a small help icon that reveals an explanatory tooltip on interaction. It composes [`mds-icon`](../../mds-icon) and [`mds-tooltip`](../../mds-tooltip) into a single drop-in element, so there is no native HTML primitive it replaces.\n\n#### Semantic Behavior\n\n- **Tooltip-on-icon**: The host always renders a help icon and anchors a tooltip to it; the slotted text becomes the tooltip body and is shown on hover/focus of the icon.\n- **Auto-placement**: With `autoPlacement` enabled (the default), the tooltip repositions itself to stay near its caller and within the viewport, overriding the static `placement` when space is constrained.\n- **Default-slot is text**: The default slot is intended for a plain text string only; HTML elements or components in the slot are discouraged because the content is rendered inside the tooltip.\n\n#### Properties & Visual Configurations\n\n- **`icon`** is an SVG filename slug from the Magma icon library; when omitted, the component falls back to the standard outline help glyph, so set it only to convey a help affordance other than the default question mark.\n- **`placement`** sets the preferred side of the icon on which the tooltip appears (e.g. `'top'`, `'bottom-start'`). It is the starting position; `autoPlacement` may move the tooltip away from this preference at runtime.\n- **`autoPlacement`** toggles dynamic repositioning. Keep it enabled in scrollable or edge-of-viewport contexts; disable it only when you need the tooltip pinned strictly to the `placement` side.\n\nThe tooltip's dimensions and reveal timing are tuned via the CSS custom properties documented in [`readme.md`](../readme.md) (`--mds-help-tooltip-width`, `--mds-help-tooltip-min-width`, `--mds-help-tooltip-max-width`, `--mds-help-tooltip-delay`).\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-help>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Inline Help\n\nThe canonical form. Drop `<mds-help>` inline next to a label or piece of text and slot in a plain string explaining the concept. The tooltip appears on hover or focus of the help icon.\n\n```html\n<mds-text>\n  Periodo di fatturazione\n  <mds-help>Il ciclo di fatturazione inizia il primo giorno del mese e termina l'ultimo.</mds-help>\n</mds-text>\n```\n\n#### Placement Preference\n\nUse the `placement` prop to suggest a preferred side for the tooltip. The default is `top`; change it when the element sits near a viewport edge.\n\n```html\n<!-- Default: tooltip above the icon -->\n<mds-help placement=\"top\">Inserire il codice fiscale a 16 caratteri.</mds-help>\n\n<!-- Tooltip to the right, useful for left-aligned form labels -->\n<mds-help placement=\"right\">Il campo e' obbligatorio per la registrazione.</mds-help>\n\n<!-- Tooltip below, e.g. inside a sticky header bar -->\n<mds-help placement=\"bottom\">Clicca per espandere il pannello dei filtri.</mds-help>\n```\n\n#### Disabling Auto-Placement\n\n`autoPlacement` is enabled by default and overrides `placement` when space is constrained. Disable it only when you need the tooltip pinned strictly to one side - for example in a fixed overlay where you control the available space. In plain HTML, omit the attribute entirely to turn it off; in a framework binding, set the prop to `undefined`.\n\n```html\n<!-- Omit the attribute to disable auto-placement and pin the tooltip to placement=\"bottom\" -->\n<mds-help placement=\"bottom\">\n  Questa descrizione deve sempre apparire in basso.\n</mds-help>\n```\n\n#### Custom Icon\n\nOverride the default question-mark glyph with any slug from the Magma icon library by setting the `icon` prop. Use this to match a specific visual context - for example a warning glyph when the help text explains a potentially destructive action.\n\n```html\n<mds-help icon=\"mi/baseline/info\">\n  Questa operazione puo' richiedere alcuni minuti.\n</mds-help>\n\n<mds-help icon=\"mi/baseline/warning\">\n  Attenzione: la modifica sara' applicata a tutti i documenti selezionati.\n</mds-help>\n```\n\n#### Tooltip Width Customization\n\nControl the tooltip dimensions with `--mds-help-tooltip-width`, `--mds-help-tooltip-min-width`, and `--mds-help-tooltip-max-width`. Useful when the help text is very short (narrow the tooltip) or contains several sentences (widen it).\n\n```css\n/* Wider tooltip for a multi-sentence explanation */\n.configurazione-avanzata mds-help {\n  --mds-help-tooltip-max-width: 480px;\n  --mds-help-tooltip-min-width: 300px;\n}\n\n/* Narrow tooltip for a short label */\n.campo-codice mds-help {\n  --mds-help-tooltip-max-width: 180px;\n  --mds-help-tooltip-min-width: 120px;\n}\n```\n\n#### Reveal Delay Customization\n\nIncrease `--mds-help-tooltip-delay` to prevent accidental tooltip flicker when users move their pointer across a dense form, or decrease it for touch-primary interfaces where hover is not applicable.\n\n```css\n/* Slower reveal for dense data tables */\n.tabella-dati mds-help {\n  --mds-help-tooltip-delay: 0.6s;\n}\n\n/* Faster reveal in a step-by-step wizard */\n.wizard-step mds-help {\n  --mds-help-tooltip-delay: 0.1s;\n}\n```\n\n#### Icon Part Customization\n\nTint the help icon to match a surrounding context using the documented `::part(icon)` surface. Keep using Magma color tokens so dark mode and high-contrast modes continue to work.\n\n```css\n/* Match the icon color to a warning banner context */\n.banner-warning mds-help::part(icon) {\n  fill: rgb(var(--status-warning-05));\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-help>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put HTML Elements in the Default Slot\n\nThe default slot is text-only; the content is rendered inside [`mds-tooltip`](../../mds-tooltip), which expects a plain string. Nested elements or components may be stripped or break the tooltip layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-help>\n  <strong>Attenzione:</strong> il limite massimo e' <em>100 caratteri</em>.\n</mds-help>\n\n<!-- ✅ CORRECT -->\n<mds-help>Attenzione: il limite massimo e' 100 caratteri.</mds-help>\n```\n\n#### Do Not Disable Auto-Placement with a String \"false\"\n\n`autoPlacement` is a boolean prop. Setting it to the string `\"false\"` leaves it truthy - any non-empty attribute value is truthy in HTML. Remove the attribute to disable it.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-help placement=\"right\" auto-placement=\"false\">\n  Informazioni aggiuntive.\n</mds-help>\n\n<!-- ✅ CORRECT -->\n<mds-help placement=\"right\">\n  Informazioni aggiuntive.\n</mds-help>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Icon\n\nThe only supported customization surface is `--mds-help-*` CSS custom properties and the documented `::part(icon)` shadow part. Targeting internal elements via `>>>` or undocumented selectors couples your code to the shadow DOM implementation.\n\n```css\n/* 🚫 INCORRECT */\nmds-help >>> mds-icon {\n  fill: red;\n}\n\n/* ✅ CORRECT */\nmds-help::part(icon) {\n  fill: rgb(var(--status-warning-05));\n}\n```\n\n#### Do Not Use `<mds-help>` as a Generic Tooltip Anchor\n\n`<mds-help>` always renders its own help icon and wraps [`mds-tooltip`](../../mds-tooltip) internally. It is not a generic popover wrapper. If you need a tooltip on an arbitrary element, use [`mds-tooltip`](../../mds-tooltip) directly with a `target` selector.\n\n```html\n<!-- 🚫 INCORRECT: slotting a custom trigger to replace the icon -->\n<mds-help>\n  <mds-button slot=\"default\" label=\"Dettagli\"></mds-button>\n  Testo di spiegazione.\n</mds-help>\n\n<!-- ✅ CORRECT: use mds-tooltip with a target for a custom trigger -->\n<mds-button id=\"info-btn\" label=\"Dettagli\"></mds-button>\n<mds-tooltip target=\"#info-btn\">Testo di spiegazione.</mds-tooltip>\n```\n\n#### Do Not Override Width with Inline Styles Instead of CSS Custom Properties\n\nSetting `style=\"width: ...\"` on the host bypasses the component's layout contract. Use the documented `--mds-help-tooltip-*` CSS custom properties to size the tooltip, and leave the host dimensions alone.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-help style=\"width: 400px;\">Descrizione del campo.</mds-help>\n\n<!-- ✅ CORRECT -->\n<style>\n  .sezione-avanzata mds-help {\n    --mds-help-tooltip-max-width: 400px;\n  }\n</style>\n<mds-help class=\"sezione-avanzata\">Descrizione del campo.</mds-help>\n```\n"
+        "1. Description": "The `<mds-help>` web component is a contextual help affordance of the Magma Design System: a small help icon that reveals an explanatory tooltip on interaction. It composes [`mds-icon`](../../mds-icon) and [`mds-tooltip`](../../mds-tooltip) into a single drop-in element, so there is no native HTML primitive it replaces.\n\n#### Semantic Behavior\n\n- **Tooltip-on-icon**: The host always renders a help icon and anchors a tooltip to it; the slotted text becomes the tooltip body and is shown on hover/focus of the icon.\n- **Auto-placement**: Unless `disableAutoPlacement` is set (auto-placement is on by default), the tooltip repositions itself to stay near its caller and within the viewport, overriding the static `placement` when space is constrained.\n- **Default-slot is text**: The default slot is intended for a plain text string only; HTML elements or components in the slot are discouraged because the content is rendered inside the tooltip.\n\n#### Properties & Visual Configurations\n\n- **`icon`** is an SVG filename slug from the Magma icon library; when omitted, the component falls back to the standard outline help glyph, so set it only to convey a help affordance other than the default question mark.\n- **`placement`** sets the preferred side of the icon on which the tooltip appears (e.g. `'top'`, `'bottom-start'`). It is the starting position; auto-placement may move the tooltip away from this preference at runtime.\n- **`disableAutoPlacement`** turns off dynamic repositioning. Leave it off in scrollable or edge-of-viewport contexts; set it only when you need the tooltip pinned strictly to the `placement` side.\n\nThe tooltip's dimensions and reveal timing are tuned via the CSS custom properties documented in [`readme.md`](../readme.md) (`--mds-help-tooltip-width`, `--mds-help-tooltip-min-width`, `--mds-help-tooltip-max-width`, `--mds-help-tooltip-delay`).\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-help>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Inline Help\n\nThe canonical form. Drop `<mds-help>` inline next to a label or piece of text and slot in a plain string explaining the concept. The tooltip appears on hover or focus of the help icon.\n\n```html\n<mds-text>\n  Periodo di fatturazione\n  <mds-help>Il ciclo di fatturazione inizia il primo giorno del mese e termina l'ultimo.</mds-help>\n</mds-text>\n```\n\n#### Placement Preference\n\nUse the `placement` prop to suggest a preferred side for the tooltip. The default is `top`; change it when the element sits near a viewport edge.\n\n```html\n<!-- Default: tooltip above the icon -->\n<mds-help placement=\"top\">Inserire il codice fiscale a 16 caratteri.</mds-help>\n\n<!-- Tooltip to the right, useful for left-aligned form labels -->\n<mds-help placement=\"right\">Il campo e' obbligatorio per la registrazione.</mds-help>\n\n<!-- Tooltip below, e.g. inside a sticky header bar -->\n<mds-help placement=\"bottom\">Clicca per espandere il pannello dei filtri.</mds-help>\n```\n\n#### Disabling Auto-Placement\n\nAuto-placement is enabled by default and overrides `placement` when space is constrained. Add `disable-auto-placement` only when you need the tooltip pinned strictly to one side - for example in a fixed overlay where you control the available space.\n\n```html\n<!-- Add disable-auto-placement to pin the tooltip to placement=\"bottom\" -->\n<mds-help placement=\"bottom\" disable-auto-placement>\n  Questa descrizione deve sempre apparire in basso.\n</mds-help>\n```\n\n#### Custom Icon\n\nOverride the default question-mark glyph with any slug from the Magma icon library by setting the `icon` prop. Use this to match a specific visual context - for example a warning glyph when the help text explains a potentially destructive action.\n\n```html\n<mds-help icon=\"mi/baseline/info\">\n  Questa operazione puo' richiedere alcuni minuti.\n</mds-help>\n\n<mds-help icon=\"mi/baseline/warning\">\n  Attenzione: la modifica sara' applicata a tutti i documenti selezionati.\n</mds-help>\n```\n\n#### Tooltip Width Customization\n\nControl the tooltip dimensions with `--mds-help-tooltip-width`, `--mds-help-tooltip-min-width`, and `--mds-help-tooltip-max-width`. Useful when the help text is very short (narrow the tooltip) or contains several sentences (widen it).\n\n```css\n/* Wider tooltip for a multi-sentence explanation */\n.configurazione-avanzata mds-help {\n  --mds-help-tooltip-max-width: 480px;\n  --mds-help-tooltip-min-width: 300px;\n}\n\n/* Narrow tooltip for a short label */\n.campo-codice mds-help {\n  --mds-help-tooltip-max-width: 180px;\n  --mds-help-tooltip-min-width: 120px;\n}\n```\n\n#### Reveal Delay Customization\n\nIncrease `--mds-help-tooltip-delay` to prevent accidental tooltip flicker when users move their pointer across a dense form, or decrease it for touch-primary interfaces where hover is not applicable.\n\n```css\n/* Slower reveal for dense data tables */\n.tabella-dati mds-help {\n  --mds-help-tooltip-delay: 0.6s;\n}\n\n/* Faster reveal in a step-by-step wizard */\n.wizard-step mds-help {\n  --mds-help-tooltip-delay: 0.1s;\n}\n```\n\n#### Icon Part Customization\n\nTint the help icon to match a surrounding context using the documented `::part(icon)` surface. Keep using Magma color tokens so dark mode and high-contrast modes continue to work.\n\n```css\n/* Match the icon color to a warning banner context */\n.banner-warning mds-help::part(icon) {\n  fill: rgb(var(--status-warning-05));\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-help>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Put HTML Elements in the Default Slot\n\nThe default slot is text-only; the content is rendered inside [`mds-tooltip`](../../mds-tooltip), which expects a plain string. Nested elements or components may be stripped or break the tooltip layout.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-help>\n  <strong>Attenzione:</strong> il limite massimo e' <em>100 caratteri</em>.\n</mds-help>\n\n<!-- ✅ CORRECT -->\n<mds-help>Attenzione: il limite massimo e' 100 caratteri.</mds-help>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Icon\n\nThe only supported customization surface is `--mds-help-*` CSS custom properties and the documented `::part(icon)` shadow part. Targeting internal elements via `>>>` or undocumented selectors couples your code to the shadow DOM implementation.\n\n```css\n/* 🚫 INCORRECT */\nmds-help >>> mds-icon {\n  fill: red;\n}\n\n/* ✅ CORRECT */\nmds-help::part(icon) {\n  fill: rgb(var(--status-warning-05));\n}\n```\n\n#### Do Not Use `<mds-help>` as a Generic Tooltip Anchor\n\n`<mds-help>` always renders its own help icon and wraps [`mds-tooltip`](../../mds-tooltip) internally. It is not a generic popover wrapper. If you need a tooltip on an arbitrary element, use [`mds-tooltip`](../../mds-tooltip) directly with a `target` selector.\n\n```html\n<!-- 🚫 INCORRECT: slotting a custom trigger to replace the icon -->\n<mds-help>\n  <mds-button slot=\"default\" label=\"Dettagli\"></mds-button>\n  Testo di spiegazione.\n</mds-help>\n\n<!-- ✅ CORRECT: use mds-tooltip with a target for a custom trigger -->\n<mds-button id=\"info-btn\" label=\"Dettagli\"></mds-button>\n<mds-tooltip target=\"#info-btn\">Testo di spiegazione.</mds-tooltip>\n```\n\n#### Do Not Override Width with Inline Styles Instead of CSS Custom Properties\n\nSetting `style=\"width: ...\"` on the host bypasses the component's layout contract. Use the documented `--mds-help-tooltip-*` CSS custom properties to size the tooltip, and leave the host dimensions alone.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-help style=\"width: 400px;\">Descrizione del campo.</mds-help>\n\n<!-- ✅ CORRECT -->\n<style>\n  .sezione-avanzata mds-help {\n    --mds-help-tooltip-max-width: 400px;\n  }\n</style>\n<mds-help class=\"sezione-avanzata\">Descrizione del campo.</mds-help>\n```\n"
       },
       "props": [
         {
-          "name": "autoPlacement",
+          "name": "disableAutoPlacement",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -11233,16 +11188,16 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "auto-placement",
+          "attr": "disable-auto-placement",
           "reflectToAttr": true,
-          "docs": "If set, the component will be placed automatically near it's caller.",
+          "docs": "If set, the component will not be placed automatically near it's caller.",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -19414,59 +19369,11 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop closes the modal; with `interaction=\"strict\"` only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes the modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically. Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`backdrop`** toggles the dimmed overlay behind the window.\n- **`animating`** is a read-only runtime state used for transition styling, not a configuration knob.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the overlay conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n  <div class=\"p-400\">\n    <mds-text>Sei sicuro di voler continuare?</mds-text>\n  </div>\n</mds-modal>\n\n<script>\n  const btn = document.getElementById('btn-apri');\n  const modal = document.getElementById('dialogo');\n  btn.addEventListener('mdsButtonClick', () => { modal.opened = true; });\n  modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n  <header slot=\"top\" class=\"p-400 bg-tone-neutral shadow-outline-light\">\n    <mds-text typography=\"h5\">Modifica utente</mds-text>\n  </header>\n\n  <div class=\"p-400 grid gap-400\">\n    <mds-input name=\"nome\" label=\"Nome\"></mds-input>\n    <mds-input name=\"cognome\" label=\"Cognome\"></mds-input>\n  </div>\n\n  <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-tone-neutral shadow-outline-light\">\n    <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n    <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n  </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n  <div class=\"p-400\">\n    <mds-text>Dettagli del documento</mds-text>\n  </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n  <div class=\"p-400\">\n    <mds-text>Azioni disponibili</mds-text>\n  </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n  <div class=\"p-400 grid gap-400\">\n    <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n    <mds-text>Questa operazione non e' reversibile.</mds-text>\n    <div class=\"flex gap-300 justify-end\">\n      <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n      <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n    </div>\n  </div>\n</mds-modal>\n\n<script>\n  document.getElementById('btn-no').addEventListener('mdsButtonClick', () => {\n    document.getElementById('conferma-elimina').close();\n  });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n  <div class=\"p-400\">\n    <mds-text>Salvataggio in corso...</mds-text>\n  </div>\n</mds-modal>\n\n<script>\n  async function salva() {\n    const modal = document.getElementById('salvataggio');\n    modal.opened = true;\n    await salvaRisorsa();\n    await modal.close();\n  }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n  <div class=\"p-400\">\n    <mds-input id=\"input-ricerca\" label=\"Cerca\"></mds-input>\n  </div>\n</mds-modal>\n\n<script>\n  const modal = document.getElementById('modal-focus');\n  const input = document.getElementById('input-ricerca');\n\n  modal.addEventListener('mdsModalShow', () => {\n    input.setFocus();\n  });\n  modal.addEventListener('mdsModalHide', () => {\n    // safe point to detach or reset content\n    modal.opened = undefined;\n  });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n  <div class=\"p-400\">\n    <mds-text>Animazione 3D</mds-text>\n  </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n  <div class=\"p-400\">\n    <mds-text>Animazione personalizzata</mds-text>\n  </div>\n</mds-modal>\n```\n\n#### Custom Window via `window` Slot\n\nSlot any element with `slot=\"window\"` to completely replace the built-in chrome (the white window surface and the close button). The slotted element receives `role=\"dialog\"` automatically. Use this when a completely bespoke surface is needed - for example, a full-screen banner.\n\n```html\n<mds-modal id=\"modal-banner\" animation=\"custom\">\n  <mds-banner\n    slot=\"window\"\n    class=\"max-w-md w-full mx-400\"\n    tone=\"box\"\n    deletable\n    headline=\"Azione richiesta\"\n  >\n    <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n    <mds-button slot=\"actions\" variant=\"primary\" tone=\"text\">Annulla</mds-button>\n    <mds-button slot=\"actions\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n  </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nSet `backdrop` to absent (or `undefined`) to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\">\n  <div class=\"p-400\">\n    <mds-text>Informazioni contestuali</mds-text>\n  </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop at runtime\ndocument.getElementById('pannello-info').backdrop = undefined;\n```\n\n#### CSS Customization\n\nStyle the window surface only through the documented `--mds-modal-*` CSS custom properties. Set them on the host element.\n\n```css\n/* Rounded card-style center modal */\n#modal-card {\n  --mds-modal-window-radius: var(--radius-xl);\n  --mds-modal-window-distance: var(--spacing-600);\n  --mds-modal-window-overflow: hidden;\n  --mds-modal-window-background: rgb(var(--tone-neutral));\n  --mds-modal-window-shadow: var(--shadow-2xl);\n  --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n  --mds-modal-window-radius: var(--radius-lg) var(--radius-lg) 0 0;\n  --mds-modal-window-max-width: 100%;\n  --mds-modal-window-min-width: 100%;\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-modal>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nBoolean props in Stencil treat any non-empty string as truthy. Setting `opened=\"false\"` keeps the modal open instead of closing it. Remove the attribute or set the prop to `undefined`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-modal id=\"dialogo\" opened=\"false\"></mds-modal>\n\n<!-- ✅ CORRECT -->\n<mds-modal id=\"dialogo\"></mds-modal>\n```\n\n```javascript\n// 🚫 INCORRECT\nmodal.opened = false;\n\n// ✅ CORRECT\nmodal.opened = undefined;\n```\n\n#### Do Not Put Content in the `window` Slot Without Replacing the Entire Chrome\n\nThe `window` slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.\n\n```html\n<!-- 🚫 INCORRECT: only the slotted header renders; default slot and close button are suppressed -->\n<mds-modal id=\"modal\">\n  <header slot=\"window\" class=\"p-400\">Titolo</header>\n  <div>Contenuto del dialogo</div>\n</mds-modal>\n\n<!-- ✅ CORRECT: use slot=\"top\" for a sticky header, default slot for body -->\n<mds-modal id=\"modal\">\n  <header slot=\"top\" class=\"p-400 bg-tone-neutral\">Titolo</header>\n  <div class=\"p-400\">Contenuto del dialogo</div>\n</mds-modal>\n```\n\n#### Do Not Reach Into Shadow Parts to Style the Window\n\nThe only supported customization surface is `--mds-modal-*` CSS custom properties and the two documented shadow parts (`window`, `action-close`). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-modal >>> .window-content {\n  padding: 0;\n}\nmds-modal::part(window) > div {\n  border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-modal {\n  --mds-modal-window-background: rgb(var(--tone-neutral));\n  --mds-modal-window-radius: var(--radius-xl);\n  --mds-modal-window-distance: var(--spacing-400);\n}\n```\n\n#### Do Not Listen for Native `click` on the Backdrop to Close\n\n`mds-modal` emits `mdsModalClose` when it closes (and `mdsModalHide` when the animation finishes). Listening for a raw `click` on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and `interaction=\"strict\"` will silently break your handler.\n\n```javascript\n// 🚫 INCORRECT\ndocument.getElementById('modal').addEventListener('click', (e) => {\n  if (e.target === e.currentTarget) modal.opened = undefined;\n});\n\n// ✅ CORRECT\ndocument.getElementById('modal').addEventListener('mdsModalClose', () => {\n  modal.opened = undefined;\n});\n```\n\n#### Do Not Skip the `close()` Method When Dismissing Programmatically from Strict Modals\n\nWhen `interaction=\"strict\"` is set, the internal `closeModal` guard prevents backdrop-click dismissal. Manually setting `opened = undefined` bypasses the guard but skips the `mdsModalClose` event and animation teardown. Use the `close()` method instead.\n\n```javascript\n// 🚫 INCORRECT (skips event emission when interaction=\"strict\")\ndocument.getElementById('modal-strict').opened = undefined;\n\n// ✅ CORRECT\nawait document.getElementById('modal-strict').close();\n```\n\n#### Do Not Use `backdrop` to Toggle the Backdrop at Runtime via String\n\n`backdrop` is a boolean prop. Passing the string `\"false\"` is truthy and leaves the backdrop visible. To hide the backdrop, set the prop to `undefined` (remove the attribute in HTML).\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-modal backdrop=\"false\"></mds-modal>\n\n<!-- ✅ CORRECT (no attribute = no backdrop) -->\n<mds-modal></mds-modal>\n```\n\n#### Do Not Use `<dialog>` Directly When `<mds-modal>` Is Available\n\nUsing a raw `<dialog>` element bypasses the system's managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use `<mds-modal>` for overlays in a Magma application.\n\n```html\n<!-- 🚫 INCORRECT -->\n<dialog id=\"raw-dialog\">\n  <p>Contenuto del dialogo</p>\n  <button>Chiudi</button>\n</dialog>\n\n<!-- ✅ CORRECT -->\n<mds-modal id=\"modal\">\n  <div class=\"p-400\">\n    <mds-text>Contenuto del dialogo</mds-text>\n  </div>\n</mds-modal>\n```\n"
+        "1. Description": "The `<mds-modal>` web component is the Magma Design System overlay container for dialogs, presenting content in a windowed surface layered above the page with an optional backdrop. It is the system equivalent of the native `<dialog>` element, adding managed open/close animations, body scroll locking, positioning, and a built-in close affordance.\n\n#### Semantic Behavior\n\n- **Open state**: Visibility is driven by the `opened` prop. Setting it `true` runs the intro animation and emits `mdsModalOpen`; clearing it runs the outro animation and emits `mdsModalClose`.\n- **Programmatic close**: Exposes an async `close()` method that dismisses the modal regardless of `interaction`, mirroring the close-button action.\n- **Show/hide events**: `mdsModalShow` fires when the intro finishes (fully visible) and `mdsModalHide` when the outro finishes (fully hidden), the latter being the safe point to detach the modal to reclaim memory.\n- **Backdrop dismissal**: With `interaction=\"relaxed\"` (default) a click on the backdrop closes the modal; with `interaction=\"strict\"` only the close button or `close()` can dismiss it.\n- **Body scroll lock**: When `overflow=\"auto\"` the component locks body scroll while open and restores it on close.\n- **Touch dismissal**: On touch devices a horizontal swipe past a threshold closes the modal, respecting the swipe direction implied by edge `position` values.\n- **Slot-driven layout**: With no `window` slot, the default slot renders centered content framed by optional `top` (header) and `bottom` (footer) slots, and a close button is rendered automatically. Slotting a `window` element suppresses the built-in chrome and close button so the consumer supplies the entire surface.\n\n#### Properties & Visual Configurations\n\nThis component does not use the shared `variant` / `tone` ladders; its configuration is structural and motion-oriented.\n\n#### Other behavioral props\n\n- **`position`** sets where the window animates from and rests, from `'center'` to edge and corner anchors (`'top'`, `'bottom-left'`, etc.); edge positions also define the valid swipe-to-dismiss direction.\n- **`animation`** selects the motion style of the window: `'slide'` (default), `'3d'`, or `'custom'` (driven entirely by CSS custom properties).\n- **`interaction`** governs how forgiving dismissal is - `'relaxed'` allows backdrop clicks, `'strict'` requires the close button.\n- **`overflow`** chooses whether the component manages body scroll locking (`'auto'`) or leaves it to the consumer (`'manual'`).\n- **`hideBackdrop`** removes the dimmed overlay behind the window (shown by default).\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-modal>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the overlay conventions documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Modal with Inline Content\n\nThe simplest form: toggle `opened` from JavaScript to show the dialog. The built-in close button and backdrop dismiss the modal automatically with `interaction=\"relaxed\"` (default). React to the `mdsModalClose` event to sync your state.\n\n```html\n<mds-button id=\"btn-apri\">Apri dialogo</mds-button>\n\n<mds-modal id=\"dialogo\">\n  <div class=\"p-400\">\n    <mds-text>Sei sicuro di voler continuare?</mds-text>\n  </div>\n</mds-modal>\n\n<script>\n  const btn = document.getElementById('btn-apri');\n  const modal = document.getElementById('dialogo');\n  btn.addEventListener('mdsButtonClick', () => { modal.opened = true; });\n  modal.addEventListener('mdsModalClose', () => { modal.opened = undefined; });\n</script>\n```\n\n#### Fixed Header and Footer via `top` / `bottom` Slots\n\nUse the `top` slot for a sticky header and the `bottom` slot for a sticky footer (e.g. action buttons). The default slot renders scrollable body content between them.\n\n```html\n<mds-modal id=\"modifica-utente\" position=\"right\">\n  <header slot=\"top\" class=\"p-400 bg-tone-neutral shadow-outline-light\">\n    <mds-text typography=\"h5\">Modifica utente</mds-text>\n  </header>\n\n  <div class=\"p-400 grid gap-400\">\n    <mds-input name=\"nome\" label=\"Nome\"></mds-input>\n    <mds-input name=\"cognome\" label=\"Cognome\"></mds-input>\n  </div>\n\n  <footer slot=\"bottom\" class=\"p-400 flex gap-300 justify-end bg-tone-neutral shadow-outline-light\">\n    <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-annulla\">Annulla</mds-button>\n    <mds-button variant=\"primary\" tone=\"strong\" id=\"btn-salva\">Salva</mds-button>\n  </footer>\n</mds-modal>\n```\n\n#### Edge and Corner Positions\n\n`position` anchors the window to an edge or corner and drives the slide-in direction. Use `right` or `left` for side panels, `bottom` for mobile drawers.\n\n```html\n<!-- Side panel from the right (default in most app shells) -->\n<mds-modal id=\"pannello-laterale\" position=\"right\">\n  <div class=\"p-400\">\n    <mds-text>Dettagli del documento</mds-text>\n  </div>\n</mds-modal>\n\n<!-- Drawer from the bottom (mobile) -->\n<mds-modal id=\"drawer-mobile\" position=\"bottom\">\n  <div class=\"p-400\">\n    <mds-text>Azioni disponibili</mds-text>\n  </div>\n</mds-modal>\n```\n\n#### Strict Interaction Mode\n\nSet `interaction=\"strict\"` when the user must explicitly confirm or cancel before the dialog closes - for example, a form with unsaved changes. Backdrop clicks are ignored; only the close button or the `close()` method can dismiss the modal.\n\n```html\n<mds-modal id=\"conferma-elimina\" interaction=\"strict\">\n  <div class=\"p-400 grid gap-400\">\n    <mds-text typography=\"h5\">Eliminare il documento?</mds-text>\n    <mds-text>Questa operazione non e' reversibile.</mds-text>\n    <div class=\"flex gap-300 justify-end\">\n      <mds-button variant=\"dark\" tone=\"outline\" id=\"btn-no\">Annulla</mds-button>\n      <mds-button variant=\"error\" tone=\"strong\" id=\"btn-si\">Elimina</mds-button>\n    </div>\n  </div>\n</mds-modal>\n\n<script>\n  document.getElementById('btn-no').addEventListener('mdsButtonClick', () => {\n    document.getElementById('conferma-elimina').close();\n  });\n</script>\n```\n\n#### Programmatic Close via `close()` Method\n\nCall the async `close()` method from JavaScript when you need to dismiss the modal from outside its UI - for example, after a successful async operation.\n\n```html\n<mds-modal id=\"salvataggio\">\n  <div class=\"p-400\">\n    <mds-text>Salvataggio in corso...</mds-text>\n  </div>\n</mds-modal>\n\n<script>\n  async function salva() {\n    const modal = document.getElementById('salvataggio');\n    modal.opened = true;\n    await salvaRisorsa();\n    await modal.close();\n  }\n</script>\n```\n\n#### Listening to Animation Events\n\n`mdsModalShow` fires when the intro animation completes (the modal is fully visible). Use it to focus the first interactive element. `mdsModalHide` fires when the outro animation completes; use it to detach the element or reset content.\n\n```html\n<mds-modal id=\"modal-focus\" position=\"right\">\n  <div class=\"p-400\">\n    <mds-input id=\"input-ricerca\" label=\"Cerca\"></mds-input>\n  </div>\n</mds-modal>\n\n<script>\n  const modal = document.getElementById('modal-focus');\n  const input = document.getElementById('input-ricerca');\n\n  modal.addEventListener('mdsModalShow', () => {\n    input.setFocus();\n  });\n  modal.addEventListener('mdsModalHide', () => {\n    // safe point to detach or reset content\n    modal.opened = undefined;\n  });\n</script>\n```\n\n#### Custom Animation Styles\n\n`animation` selects the motion style. `'slide'` (default) translates from the entry edge; `'3d'` adds a perspective tilt; `'custom'` delegates entirely to the CSS custom properties `--mds-modal-custom-closed-transform` and `--mds-modal-custom-window-distance`.\n\n```html\n<!-- 3D perspective tilt animation -->\n<mds-modal id=\"modal-3d\" animation=\"3d\" position=\"center\">\n  <div class=\"p-400\">\n    <mds-text>Animazione 3D</mds-text>\n  </div>\n</mds-modal>\n\n<!-- Custom animation driven by CSS vars -->\n<mds-modal id=\"modal-custom\" animation=\"custom\" position=\"center\">\n  <div class=\"p-400\">\n    <mds-text>Animazione personalizzata</mds-text>\n  </div>\n</mds-modal>\n```\n\n#### Custom Window via `window` Slot\n\nSlot any element with `slot=\"window\"` to completely replace the built-in chrome (the white window surface and the close button). The slotted element receives `role=\"dialog\"` automatically. Use this when a completely bespoke surface is needed - for example, a full-screen banner.\n\n```html\n<mds-modal id=\"modal-banner\" animation=\"custom\">\n  <mds-banner\n    slot=\"window\"\n    class=\"max-w-md w-full mx-400\"\n    tone=\"box\"\n    deletable\n    headline=\"Azione richiesta\"\n  >\n    <mds-text typography=\"detail\">Conferma la tua identita' per procedere.</mds-text>\n    <mds-button slot=\"actions\" variant=\"primary\" tone=\"text\">Annulla</mds-button>\n    <mds-button slot=\"actions\" variant=\"primary\" tone=\"strong\">Conferma</mds-button>\n  </mds-banner>\n</mds-modal>\n```\n\n#### Disabling the Backdrop\n\nAdd `hide-backdrop` to render the modal without the dimmed overlay - useful for non-blocking side panels that coexist with interactive page content.\n\n```html\n<mds-modal id=\"pannello-info\" position=\"right\" hide-backdrop>\n  <div class=\"p-400\">\n    <mds-text>Informazioni contestuali</mds-text>\n  </div>\n</mds-modal>\n```\n\n```javascript\n// Remove the backdrop at runtime\ndocument.getElementById('pannello-info').hideBackdrop = true;\n```\n\n#### CSS Customization\n\nStyle the window surface only through the documented `--mds-modal-*` CSS custom properties. Set them on the host element.\n\n```css\n/* Rounded card-style center modal */\n#modal-card {\n  --mds-modal-window-radius: var(--radius-xl);\n  --mds-modal-window-distance: var(--spacing-600);\n  --mds-modal-window-overflow: hidden;\n  --mds-modal-window-background: rgb(var(--tone-neutral));\n  --mds-modal-window-shadow: var(--shadow-2xl);\n  --mds-modal-window-max-width: 480px;\n}\n\n/* Full-width drawer */\n#drawer-bottom {\n  --mds-modal-window-radius: var(--radius-lg) var(--radius-lg) 0 0;\n  --mds-modal-window-max-width: 100%;\n  --mds-modal-window-min-width: 100%;\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-modal>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Set `opened=\"false\"` to Close the Modal\n\nBoolean props in Stencil treat any non-empty string as truthy. Setting `opened=\"false\"` keeps the modal open instead of closing it. Remove the attribute or set the prop to `undefined`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-modal id=\"dialogo\" opened=\"false\"></mds-modal>\n\n<!-- ✅ CORRECT -->\n<mds-modal id=\"dialogo\"></mds-modal>\n```\n\n```javascript\n// 🚫 INCORRECT\nmodal.opened = false;\n\n// ✅ CORRECT\nmodal.opened = undefined;\n```\n\n#### Do Not Put Content in the `window` Slot Without Replacing the Entire Chrome\n\nThe `window` slot completely bypasses the built-in surface, header/footer regions, and close button. Do not use it to add a header element while expecting the default content area and close button to still render - they will not.\n\n```html\n<!-- 🚫 INCORRECT: only the slotted header renders; default slot and close button are suppressed -->\n<mds-modal id=\"modal\">\n  <header slot=\"window\" class=\"p-400\">Titolo</header>\n  <div>Contenuto del dialogo</div>\n</mds-modal>\n\n<!-- ✅ CORRECT: use slot=\"top\" for a sticky header, default slot for body -->\n<mds-modal id=\"modal\">\n  <header slot=\"top\" class=\"p-400 bg-tone-neutral\">Titolo</header>\n  <div class=\"p-400\">Contenuto del dialogo</div>\n</mds-modal>\n```\n\n#### Do Not Reach Into Shadow Parts to Style the Window\n\nThe only supported customization surface is `--mds-modal-*` CSS custom properties and the two documented shadow parts (`window`, `action-close`). Targeting internal shadow selectors couples your code to implementation details that will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-modal >>> .window-content {\n  padding: 0;\n}\nmds-modal::part(window) > div {\n  border: 2px solid red;\n}\n\n/* ✅ CORRECT */\nmds-modal {\n  --mds-modal-window-background: rgb(var(--tone-neutral));\n  --mds-modal-window-radius: var(--radius-xl);\n  --mds-modal-window-distance: var(--spacing-400);\n}\n```\n\n#### Do Not Listen for Native `click` on the Backdrop to Close\n\n`mds-modal` emits `mdsModalClose` when it closes (and `mdsModalHide` when the animation finishes). Listening for a raw `click` on the host or backdrop is fragile - the event target varies by browser and shadow DOM boundary, and `interaction=\"strict\"` will silently break your handler.\n\n```javascript\n// 🚫 INCORRECT\ndocument.getElementById('modal').addEventListener('click', (e) => {\n  if (e.target === e.currentTarget) modal.opened = undefined;\n});\n\n// ✅ CORRECT\ndocument.getElementById('modal').addEventListener('mdsModalClose', () => {\n  modal.opened = undefined;\n});\n```\n\n#### Do Not Skip the `close()` Method When Dismissing Programmatically from Strict Modals\n\nWhen `interaction=\"strict\"` is set, the internal `closeModal` guard prevents backdrop-click dismissal. Manually setting `opened = undefined` bypasses the guard but skips the `mdsModalClose` event and animation teardown. Use the `close()` method instead.\n\n```javascript\n// 🚫 INCORRECT (skips event emission when interaction=\"strict\")\ndocument.getElementById('modal-strict').opened = undefined;\n\n// ✅ CORRECT\nawait document.getElementById('modal-strict').close();\n```\n\n#### Do Not Use `<dialog>` Directly When `<mds-modal>` Is Available\n\nUsing a raw `<dialog>` element bypasses the system's managed animation, body-scroll locking, touch-swipe dismissal, and design-token theming. Always use `<mds-modal>` for overlays in a Magma application.\n\n```html\n<!-- 🚫 INCORRECT -->\n<dialog id=\"raw-dialog\">\n  <p>Contenuto del dialogo</p>\n  <button>Chiudi</button>\n</dialog>\n\n<!-- ✅ CORRECT -->\n<mds-modal id=\"modal\">\n  <div class=\"p-400\">\n    <mds-text>Contenuto del dialogo</mds-text>\n  </div>\n</mds-modal>\n```\n"
       },
       "props": [
-        {
-          "name": "animating",
-          "type": "\"intro\" | \"none\" | \"outro\" | undefined",
-          "complexType": {
-            "original": "ModalAnimationStateType",
-            "resolved": "\"intro\" | \"none\" | \"outro\" | undefined",
-            "references": {
-              "ModalAnimationStateType": {
-                "location": "import",
-                "path": "./meta/types",
-                "id": "src/components/mds-modal/meta/types.ts::ModalAnimationStateType",
-                "referenceLocation": "ModalAnimationStateType"
-              }
-            }
-          },
-          "mutable": true,
-          "attr": "animating",
-          "reflectToAttr": true,
-          "docs": "Specifies if the component is animating itself or not",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "'none'"
-            }
-          ],
-          "default": "'none'",
-          "values": [
-            {
-              "value": "intro",
-              "type": "string"
-            },
-            {
-              "value": "none",
-              "type": "string"
-            },
-            {
-              "value": "outro",
-              "type": "string"
-            },
-            {
-              "type": "undefined"
-            }
-          ],
-          "optional": true,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "animation",
           "type": "\"3d\" | \"custom\" | \"slide\" | undefined",
@@ -19485,7 +19392,7 @@
           "mutable": false,
           "attr": "animation",
           "reflectToAttr": true,
-          "docs": "Specifies if the component is animating itself or not",
+          "docs": "Specifies the animation style of the modal window",
           "docsTags": [
             {
               "name": "default",
@@ -19516,7 +19423,7 @@
           "setter": false
         },
         {
-          "name": "backdrop",
+          "name": "hideBackdrop",
           "type": "boolean | undefined",
           "complexType": {
             "original": "boolean",
@@ -19524,16 +19431,16 @@
             "references": {}
           },
           "mutable": true,
-          "attr": "backdrop",
+          "attr": "hide-backdrop",
           "reflectToAttr": true,
-          "docs": "Specifies if the modal shows the backdrop",
+          "docs": "Hides the modal backdrop",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -19912,6 +19819,10 @@
           "name": "action-close",
           "docs": "Selects the close button of the modal."
         },
+        {
+          "name": "dialog",
+          "docs": ""
+        },
         {
           "name": "window",
           "docs": "Selects the default window element of the modal when used."
@@ -20180,15 +20091,44 @@
       "filePath": "src/components/mds-notification/mds-notification.tsx",
       "encapsulation": "shadow",
       "tag": "mds-notification",
-      "readme": "# mds-notification\n\n<!-- Start script-generated Magma Docs -->\n\n# Install\n\nInstall the component via `npm` by running the following command\n\n```bash\nnpm install @maggioli-design-system/mds-notification\n```\n\nThis package works also with yarn:\n\n```bash\nyarn add @maggioli-design-system/mds-notification\n```\n\n#### Import\n\nImport the components in your project via `TypeScript` as follows:\n\n```typescript\nimport { defineCustomElements as dceMdsNotification } from '@maggioli-design-system/mds-notification/loader'\n\ndceMdsNotification()\n```\n\n`MdsNotification` depends on `MdsText`, so you will have to import it as well:\n\n```typescript\nimport { defineCustomElements as dceMdsText } from '@maggioli-design-system/mds-text/loader'\n\ndceMdsText()\n```\n\nYou will have to import also the css style from `@maggioli-design-system` as follows:\n\n```css\n@import '~@maggioli-design-system/styles/dist/css/colors-rgb.css`\n```\n\nIf you need to support older browsers (i.e. IE or early version of Edge), you can wrap the `defineCustomElements` in another utility awailable in the same package:\n\n```typescript\nimport { applyPolyfills as apMdsNotification, defineCustomElements as dceMdsNotification } from '@maggioli-design-system/mds-notification/loader'\n\napMdsNotification().then(dceMdsNotification())\n```\n\nUse alias for `defineCustomElements` method to initialize multiple web components in the same place:\n\n```typescript\nimport { defineCustomElements as dceMdsComponentOne } from '@maggioli-design-system/mds-component-one/loader'\nimport { defineCustomElements as dceMdsComponentTwo } from '@maggioli-design-system/mds-component-two/loader'\n\ndceMdsComponentOne()\ndceMdsComponentTwo()\n```\n\nYou can check how browser support works at [this page][stencil-browser-support].\n\n# Integration\n\n<!-- This section is useful to describe usages and configurations -->\n\n#### How to use it in HTML\n\n`MdsNotification` is meant to be used to support another HTML component (like an icon or a button) to notify the user of pending notifications.\n\nThe component accepts the following attributes:\n- `target`: (mandatory) specifies the id of the element to which is attached\n- `value`: specifies the number of notification to display (if set to the element will be hidden)\n- `visible`: specifies if the notification should be visible or not\n\n```html\n<mds-notification target='my-button' value=22 visible=true></mds-notification>\n<button id='my-button'>Click here!</button>\n```\n\nYou can try it out on the component's [Storybook website][storybook]!\n\n[storybook]: https://magma.maggiolicloud.it/storybook/?path=/story/ui-notification--default\n[stencil-browser-support]: https://stenciljs.com/docs/browser-support\n\n<!-- End script-generated Magma Docs -->\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
+      "readme": "# mds-notification\n\n<!-- Start script-generated Magma Docs -->\n\n# Install\n\nInstall the component via `npm` by running the following command\n\n```bash\nnpm install @maggioli-design-system/mds-notification\n```\n\nThis package works also with yarn:\n\n```bash\nyarn add @maggioli-design-system/mds-notification\n```\n\n#### Import\n\nImport the components in your project via `TypeScript` as follows:\n\n```typescript\nimport { defineCustomElements as dceMdsNotification } from '@maggioli-design-system/mds-notification/loader'\n\ndceMdsNotification()\n```\n\n`MdsNotification` depends on `MdsText`, so you will have to import it as well:\n\n```typescript\nimport { defineCustomElements as dceMdsText } from '@maggioli-design-system/mds-text/loader'\n\ndceMdsText()\n```\n\nYou will have to import also the css style from `@maggioli-design-system` as follows:\n\n```css\n@import '~@maggioli-design-system/styles/dist/css/colors-rgb.css`\n```\n\nIf you need to support older browsers (i.e. IE or early version of Edge), you can wrap the `defineCustomElements` in another utility awailable in the same package:\n\n```typescript\nimport { applyPolyfills as apMdsNotification, defineCustomElements as dceMdsNotification } from '@maggioli-design-system/mds-notification/loader'\n\napMdsNotification().then(dceMdsNotification())\n```\n\nUse alias for `defineCustomElements` method to initialize multiple web components in the same place:\n\n```typescript\nimport { defineCustomElements as dceMdsComponentOne } from '@maggioli-design-system/mds-component-one/loader'\nimport { defineCustomElements as dceMdsComponentTwo } from '@maggioli-design-system/mds-component-two/loader'\n\ndceMdsComponentOne()\ndceMdsComponentTwo()\n```\n\nYou can check how browser support works at [this page][stencil-browser-support].\n\n# Integration\n\n<!-- This section is useful to describe usages and configurations -->\n\n#### How to use it in HTML\n\n`MdsNotification` is meant to be used to support another HTML component (like an icon or a button) to notify the user of pending notifications.\n\nThe component accepts the following attributes:\n- `target`: (mandatory) specifies the id of the element to which is attached\n- `value`: specifies the number of notification to display (if set to `0` the badge is hidden)\n- `dismissed`: specifies if the notification is dismissed (hidden); the badge is shown by default\n\n```html\n<mds-notification target='my-button' value=22></mds-notification>\n<button id='my-button'>Click here!</button>\n```\n\nYou can try it out on the component's [Storybook website][storybook]!\n\n[storybook]: https://magma.maggiolicloud.it/storybook/?path=/story/ui-notification--default\n[stencil-browser-support]: https://stenciljs.com/docs/browser-support\n\n<!-- End script-generated Magma Docs -->\n\nThis is a web-component from Maggioli Design System [Magma](https://magma.maggiolicloud.it), built with StencilJS, TypeScript, Storybook. It's based on the web-component standard and it's designed to be agnostic from the JavaScript framework you are using.\n",
       "docs": "<!-- Start script-generated Magma Docs -->",
       "docsTags": [],
       "usage": {
-        "1. Description": "The `<mds-notification>` web component is a numeric badge/dot indicator of the Magma Design System that attaches to another element (an icon, a button, an avatar) to signal a count of pending items. It has no HTML primitive equivalent: it positions itself relative to a target element rather than wrapping content of its own.\n\n#### Semantic Behavior\n\n- **Target attachment**: The component anchors to the element matched by the `target` selector and tracks it as it scrolls or resizes.\n- **Missing target falls back**: If `target` is not set, positioning is disabled; if `target` is set but resolves to no element, it throws `No valid target found`.\n- **Zero-value hiding**: When `value` is `0` the badge renders empty, so it effectively disappears until there is a count to show.\n- **Count overflow**: When `max` is set and `value` exceeds it, the displayed text becomes `+max` (e.g. `+9`) instead of the raw number; otherwise the value is locale-formatted.\n- **Accessibility**: The badge labels its target with the current value.\n\n#### Properties & Visual Configurations\n\n- **`target`** is the CSS selector of the element the badge anchors to; it is effectively mandatory for positioned rendering.\n- **`value`** is the count shown in the badge and also the source of the accessible label; `0` hides the badge.\n- **`max`** caps the visible number - pick it when raw counts could grow large and you want a compact `+N` ceiling.\n- **`visible`** toggles whether the badge is shown independently of its value.\n\n#### Other behavioral props\n\n- **`strategy`** selects the positioning mode (`'fixed'` by default, `'absolute'`, or `'disabled'`). Use `'disabled'` to opt out of dynamic tracking; it is also set automatically when no `target` is provided.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-notification>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Badge Inside `mds-button` via Named Slot\n\nThe most common usage. Drop `<mds-notification>` into the `notification` slot of [`mds-button`](../../mds-button) so the badge is positioned and animated automatically by the button's internal layout. Set `strategy=\"disabled\"` because the button handles placement; the component is no longer responsible for floating positioning.\n\n```html\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\" tone=\"weak\">\n  <mds-notification slot=\"notification\" value=\"5\" strategy=\"disabled\"></mds-notification>\n</mds-button>\n```\n\n#### Floating Badge Anchored to an Arbitrary Element\n\nUse the `target` prop with a CSS selector to attach a floating badge to any element on the page. The component uses `position: fixed` by default and tracks the target through scroll and resize automatically.\n\n```html\n<mds-notification target=\"#icona-notifiche\" value=\"12\"></mds-notification>\n<mds-icon id=\"icona-notifiche\" name=\"mi/baseline/notifications\"></mds-icon>\n```\n\n#### Count Overflow via `max`\n\nWhen raw counts can grow large, set `max` to cap the visible number. Values above the cap display as `+max` (e.g. `+99`), keeping the badge compact.\n\n```html\n<mds-notification target=\"#posta-in-arrivo\" value=\"127\" max=\"99\"></mds-notification>\n<mds-icon id=\"posta-in-arrivo\" name=\"mi/baseline/mail\"></mds-icon>\n```\n\n#### Hiding and Showing the Badge\n\nUse the `visible` prop to show or hide the badge independently of its count. This is useful when the notification state is known but should not be displayed yet - for example while a panel is already open.\n\n```html\n<!-- Badge nascosto anche se ha un valore -->\n<mds-notification target=\"#avatar-utente\" value=\"3\" visible=\"false\"></mds-notification>\n\n<!-- Badge visibile (valore predefinito) -->\n<mds-notification target=\"#avatar-utente\" value=\"3\"></mds-notification>\n```\n\n#### Zero Value Produces an Empty Dot\n\nWhen `value` is `0` the badge renders without a number, appearing as a plain dot. Use this when you need a presence indicator without a count - for example to signal new activity without exposing a specific number.\n\n```html\n<mds-notification target=\"#attivita-recente\" value=\"0\"></mds-notification>\n<mds-button id=\"attivita-recente\" label=\"Attivita\" variant=\"secondary\" tone=\"weak\"></mds-button>\n```\n\n#### Absolute Positioning Strategy\n\nUse `strategy=\"absolute\"` when the badge must be positioned relative to a scrolling container rather than the viewport. The target element must have `position: relative` (or another non-static position) set on its nearest containing block.\n\n```html\n<div style=\"position: relative; overflow: auto;\">\n  <mds-notification target=\"#elemento-lista\" value=\"2\" strategy=\"absolute\"></mds-notification>\n  <mds-button id=\"elemento-lista\" label=\"Documenti\" variant=\"secondary\"></mds-button>\n</div>\n```\n\n#### Disabled Strategy for Manual Placement\n\nUse `strategy=\"disabled\"` when you want to position the badge yourself with utility classes or CSS instead of delegating to the floating-UI engine. This is the right choice whenever the badge lives inside a slot (the slot's host already controls layout) or when you use Tailwind position utilities.\n\n```html\n<mds-button label=\"Avvisi\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"strong\">\n  <mds-notification\n    slot=\"notification\"\n    value=\"4\"\n    strategy=\"disabled\"\n  ></mds-notification>\n</mds-button>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nCustomize the badge only through the documented `--mds-notification-*` CSS custom properties. Set them on the host element or a parent selector. Use the Magma color tokens with `rgb(var(--<token>))` so dark mode and high-contrast stay consistent.\n\n```css\n/* Colore di sfondo personalizzato, cerchio senza bordo */\n.header-nav mds-notification {\n  --mds-notification-dot-background: rgb(var(--status-warning-05));\n  --mds-notification-color: rgb(var(--tone-kaolin-10));\n  --mds-notification-ring-size: 0px;\n  --mds-notification-size: 18px;\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-notification>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Floating Strategy When Slotted Inside `mds-button`\n\nWhen `<mds-notification>` sits inside the `notification` slot of [`mds-button`](../../mds-button), the button's own layout handles placement. Keeping `strategy=\"fixed\"` (the default) causes the badge to escape the slot and position itself relative to the viewport instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\">\n  <mds-notification slot=\"notification\" value=\"5\"></mds-notification>\n</mds-button>\n\n<!-- ✅ CORRECT -->\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\">\n  <mds-notification slot=\"notification\" value=\"5\" strategy=\"disabled\"></mds-notification>\n</mds-button>\n```\n\n#### Do Not Omit `target` When Using a Floating Strategy\n\nWithout `target`, the component cannot locate its anchor, automatically falls back to `strategy=\"disabled\"`, and renders in document flow wherever the tag appears - usually in the wrong place.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-notification value=\"3\"></mds-notification>\n<mds-icon id=\"icona-posta\" name=\"mi/baseline/mail\"></mds-icon>\n\n<!-- ✅ CORRECT -->\n<mds-notification target=\"#icona-posta\" value=\"3\"></mds-notification>\n<mds-icon id=\"icona-posta\" name=\"mi/baseline/mail\"></mds-icon>\n```\n\n#### Do Not Set `visible=\"false\"` to Hide the Badge When the Count Is Zero\n\nSetting `value=\"0\"` already collapses the visible dot. Mixing `visible=\"false\"` (a string, not a boolean) with a non-zero value also triggers the boolean-as-string system anti-pattern: the string `\"false\"` is truthy in HTML and the component will not treat it as `false`.\n\n```html\n<!-- 🚫 INCORRECT - boolean passed as string -->\n<mds-notification target=\"#elemento\" value=\"0\" visible=\"false\"></mds-notification>\n\n<!-- ✅ CORRECT - remove the attribute or let value=0 do the work -->\n<mds-notification target=\"#elemento\" value=\"0\"></mds-notification>\n```\n\n#### Do Not Use `<mds-notification>` as a Status Dot Without a Count\n\n`<mds-notification>` is a numeric counter badge. For a purely visual status indicator with no count, use [`mds-badge`](../../mds-badge) instead, which is designed for dot, icon, and label status scenarios.\n\n```html\n<!-- 🚫 INCORRECT - abusing notification as a plain dot indicator -->\n<mds-notification target=\"#utente-online\" value=\"0\"></mds-notification>\n\n<!-- ✅ CORRECT - use mds-badge for status dots -->\n<mds-badge variant=\"success\"></mds-badge>\n```\n\n#### Do Not Wrap the Target in a Relative Container and Use `strategy=\"fixed\"`\n\n`strategy=\"fixed\"` anchors the badge to the viewport coordinate system. If the target sits inside a CSS-transformed or `position: relative` parent, `fixed` positioning will not track it correctly. Switch to `strategy=\"absolute\"` and ensure the containing block has a non-static position.\n\n```html\n<!-- 🚫 INCORRECT - fixed badge inside transformed container -->\n<div style=\"transform: translateX(0);\">\n  <mds-notification target=\"#btn-azioni\" value=\"2\" strategy=\"fixed\"></mds-notification>\n  <mds-button id=\"btn-azioni\" label=\"Azioni\"></mds-button>\n</div>\n\n<!-- ✅ CORRECT - absolute strategy with positioned containing block -->\n<div style=\"position: relative;\">\n  <mds-notification target=\"#btn-azioni\" value=\"2\" strategy=\"absolute\"></mds-notification>\n  <mds-button id=\"btn-azioni\" label=\"Azioni\"></mds-button>\n</div>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Dot\n\nThe internal `.dot` element is not a documented `::part()`. Targeting it with `::part(dot)` or deep-selector hacks breaks on any internal refactor. Use the documented `--mds-notification-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-notification::part(dot) {\n  background-color: purple;\n}\n\n/* ✅ CORRECT */\nmds-notification {\n  --mds-notification-dot-background: rgb(var(--status-warning-05));\n}\n```\n"
+        "1. Description": "The `<mds-notification>` web component is a numeric badge/dot indicator of the Magma Design System that attaches to another element (an icon, a button, an avatar) to signal a count of pending items. It has no HTML primitive equivalent: it positions itself relative to a target element rather than wrapping content of its own.\n\n#### Semantic Behavior\n\n- **Target attachment**: The component anchors to the element matched by the `target` selector and tracks it as it scrolls or resizes.\n- **Missing target falls back**: If `target` is not set, positioning is disabled; if `target` is set but resolves to no element, it throws `No valid target found`.\n- **Zero-value hiding**: When `value` is `0` the badge renders empty, so it effectively disappears until there is a count to show.\n- **Count overflow**: When `max` is set and `value` exceeds it, the displayed text becomes `+max` (e.g. `+9`) instead of the raw number; otherwise the value is locale-formatted.\n- **Accessibility**: The badge labels its target with the current value.\n\n#### Properties & Visual Configurations\n\n- **`target`** is the CSS selector of the element the badge anchors to; it is effectively mandatory for positioned rendering.\n- **`value`** is the count shown in the badge and also the source of the accessible label; `0` hides the badge.\n- **`max`** caps the visible number - pick it when raw counts could grow large and you want a compact `+N` ceiling.\n- **`dismissed`** hides the badge independently of its value (the badge is shown by default).\n\n#### Other behavioral props\n\n- **`strategy`** selects the positioning mode (`'fixed'` by default, `'absolute'`, or `'disabled'`). Use `'disabled'` to opt out of dynamic tracking; it is also set automatically when no `target` is provided.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-notification>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Badge Inside `mds-button` via Named Slot\n\nThe most common usage. Drop `<mds-notification>` into the `notification` slot of [`mds-button`](../../mds-button) so the badge is positioned and animated automatically by the button's internal layout. Set `strategy=\"disabled\"` because the button handles placement; the component is no longer responsible for floating positioning.\n\n```html\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\" tone=\"weak\">\n  <mds-notification slot=\"notification\" value=\"5\" strategy=\"disabled\"></mds-notification>\n</mds-button>\n```\n\n#### Floating Badge Anchored to an Arbitrary Element\n\nUse the `target` prop with a CSS selector to attach a floating badge to any element on the page. The component uses `position: fixed` by default and tracks the target through scroll and resize automatically.\n\n```html\n<mds-notification target=\"#icona-notifiche\" value=\"12\"></mds-notification>\n<mds-icon id=\"icona-notifiche\" name=\"mi/baseline/notifications\"></mds-icon>\n```\n\n#### Count Overflow via `max`\n\nWhen raw counts can grow large, set `max` to cap the visible number. Values above the cap display as `+max` (e.g. `+99`), keeping the badge compact.\n\n```html\n<mds-notification target=\"#posta-in-arrivo\" value=\"127\" max=\"99\"></mds-notification>\n<mds-icon id=\"posta-in-arrivo\" name=\"mi/baseline/mail\"></mds-icon>\n```\n\n#### Hiding and Showing the Badge\n\nAdd the `dismissed` prop to hide the badge independently of its count. This is useful when the notification state is known but should not be displayed yet - for example while a panel is already open.\n\n```html\n<!-- Badge nascosto anche se ha un valore -->\n<mds-notification target=\"#avatar-utente\" value=\"3\" dismissed></mds-notification>\n\n<!-- Badge visibile (valore predefinito) -->\n<mds-notification target=\"#avatar-utente\" value=\"3\"></mds-notification>\n```\n\n#### Zero Value Produces an Empty Dot\n\nWhen `value` is `0` the badge renders without a number, appearing as a plain dot. Use this when you need a presence indicator without a count - for example to signal new activity without exposing a specific number.\n\n```html\n<mds-notification target=\"#attivita-recente\" value=\"0\"></mds-notification>\n<mds-button id=\"attivita-recente\" label=\"Attivita\" variant=\"secondary\" tone=\"weak\"></mds-button>\n```\n\n#### Absolute Positioning Strategy\n\nUse `strategy=\"absolute\"` when the badge must be positioned relative to a scrolling container rather than the viewport. The target element must have `position: relative` (or another non-static position) set on its nearest containing block.\n\n```html\n<div style=\"position: relative; overflow: auto;\">\n  <mds-notification target=\"#elemento-lista\" value=\"2\" strategy=\"absolute\"></mds-notification>\n  <mds-button id=\"elemento-lista\" label=\"Documenti\" variant=\"secondary\"></mds-button>\n</div>\n```\n\n#### Disabled Strategy for Manual Placement\n\nUse `strategy=\"disabled\"` when you want to position the badge yourself with utility classes or CSS instead of delegating to the floating-UI engine. This is the right choice whenever the badge lives inside a slot (the slot's host already controls layout) or when you use Tailwind position utilities.\n\n```html\n<mds-button label=\"Avvisi\" icon=\"mi/baseline/notifications\" variant=\"primary\" tone=\"strong\">\n  <mds-notification\n    slot=\"notification\"\n    value=\"4\"\n    strategy=\"disabled\"\n  ></mds-notification>\n</mds-button>\n```\n\n#### Styling Customization via CSS Custom Properties\n\nCustomize the badge only through the documented `--mds-notification-*` CSS custom properties. Set them on the host element or a parent selector. Use the Magma color tokens with `rgb(var(--<token>))` so dark mode and high-contrast stay consistent.\n\n```css\n/* Colore di sfondo personalizzato, cerchio senza bordo */\n.header-nav mds-notification {\n  --mds-notification-dot-background: rgb(var(--status-warning-05));\n  --mds-notification-color: rgb(var(--tone-kaolin-10));\n  --mds-notification-ring-size: 0px;\n  --mds-notification-size: 18px;\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-notification>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Floating Strategy When Slotted Inside `mds-button`\n\nWhen `<mds-notification>` sits inside the `notification` slot of [`mds-button`](../../mds-button), the button's own layout handles placement. Keeping `strategy=\"fixed\"` (the default) causes the badge to escape the slot and position itself relative to the viewport instead.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\">\n  <mds-notification slot=\"notification\" value=\"5\"></mds-notification>\n</mds-button>\n\n<!-- ✅ CORRECT -->\n<mds-button label=\"Messaggi\" icon=\"mdi/email\" variant=\"secondary\">\n  <mds-notification slot=\"notification\" value=\"5\" strategy=\"disabled\"></mds-notification>\n</mds-button>\n```\n\n#### Do Not Omit `target` When Using a Floating Strategy\n\nWithout `target`, the component cannot locate its anchor, automatically falls back to `strategy=\"disabled\"`, and renders in document flow wherever the tag appears - usually in the wrong place.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-notification value=\"3\"></mds-notification>\n<mds-icon id=\"icona-posta\" name=\"mi/baseline/mail\"></mds-icon>\n\n<!-- ✅ CORRECT -->\n<mds-notification target=\"#icona-posta\" value=\"3\"></mds-notification>\n<mds-icon id=\"icona-posta\" name=\"mi/baseline/mail\"></mds-icon>\n```\n\n#### Do Not Use `<mds-notification>` as a Status Dot Without a Count\n\n`<mds-notification>` is a numeric counter badge. For a purely visual status indicator with no count, use [`mds-badge`](../../mds-badge) instead, which is designed for dot, icon, and label status scenarios.\n\n```html\n<!-- 🚫 INCORRECT - abusing notification as a plain dot indicator -->\n<mds-notification target=\"#utente-online\" value=\"0\"></mds-notification>\n\n<!-- ✅ CORRECT - use mds-badge for status dots -->\n<mds-badge variant=\"success\"></mds-badge>\n```\n\n#### Do Not Wrap the Target in a Relative Container and Use `strategy=\"fixed\"`\n\n`strategy=\"fixed\"` anchors the badge to the viewport coordinate system. If the target sits inside a CSS-transformed or `position: relative` parent, `fixed` positioning will not track it correctly. Switch to `strategy=\"absolute\"` and ensure the containing block has a non-static position.\n\n```html\n<!-- 🚫 INCORRECT - fixed badge inside transformed container -->\n<div style=\"transform: translateX(0);\">\n  <mds-notification target=\"#btn-azioni\" value=\"2\" strategy=\"fixed\"></mds-notification>\n  <mds-button id=\"btn-azioni\" label=\"Azioni\"></mds-button>\n</div>\n\n<!-- ✅ CORRECT - absolute strategy with positioned containing block -->\n<div style=\"position: relative;\">\n  <mds-notification target=\"#btn-azioni\" value=\"2\" strategy=\"absolute\"></mds-notification>\n  <mds-button id=\"btn-azioni\" label=\"Azioni\"></mds-button>\n</div>\n```\n\n#### Do Not Pierce Shadow DOM to Style the Inner Dot\n\nThe internal `.dot` element is not a documented `::part()`. Targeting it with `::part(dot)` or deep-selector hacks breaks on any internal refactor. Use the documented `--mds-notification-*` CSS custom properties instead.\n\n```css\n/* 🚫 INCORRECT */\nmds-notification::part(dot) {\n  background-color: purple;\n}\n\n/* ✅ CORRECT */\nmds-notification {\n  --mds-notification-dot-background: rgb(var(--status-warning-05));\n}\n```\n"
       },
       "props": [
+        {
+          "name": "dismissed",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": true,
+          "attr": "dismissed",
+          "reflectToAttr": true,
+          "docs": "Specifies if the notification is dismissed",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "max",
           "type": "number | undefined",
@@ -20311,35 +20251,6 @@
           "required": false,
           "getter": false,
           "setter": false
-        },
-        {
-          "name": "visible",
-          "type": "boolean",
-          "complexType": {
-            "original": "boolean",
-            "resolved": "boolean",
-            "references": {}
-          },
-          "mutable": true,
-          "attr": "visible",
-          "reflectToAttr": true,
-          "docs": "Specifies if the notification is visible",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
-          "values": [
-            {
-              "type": "boolean"
-            }
-          ],
-          "optional": false,
-          "required": false,
-          "getter": false,
-          "setter": false
         }
       ],
       "methods": [],
@@ -23956,9 +23867,9 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container [`<mds-push-notification>`](../../mds-push-notification). It composes an avatar/image, a subject, a relative or formatted timestamp, a message body and an optional dismiss control into one toast-like row.\n\n#### Semantic Behavior\n\n- **Compound child only**: It must be placed as a direct default-slot child of `<mds-push-notification>`; it is not used standalone or mixed with other child types, since the parent animates intro/outro and manages stacking.\n- **Dismiss reports up, removal happens in the parent**: Clicking the built-in close button emits the bubbling `mdsPushNotificationItemClose` event; the parent runs the outro animation and removes the item. The item never removes itself.\n- **Parent-driven visibility lifecycle**: When the last item closes, the parent auto-hides the whole notification area.\n- **Timestamp rendering**: With `dateFormat=\"timeago\"` `datetime` shows a localized relative time (\"2 minutes ago\"); otherwise the value is treated as a date-format string for a static date.\n- **Localization**: The relative-time strings and the dismiss button title are localized (el/en/es/it).\n- **Conditional avatar vs. picture**: An `<mds-avatar>` is rendered when `icon` is set or `preview=\"avatar\"`; when `src` is set and `preview` is not `avatar`, a full-width `<mds-img>` preview is rendered instead.\n- **Slot detection**: The `badge` and `action` named slots are only wired into the layout when matching slotted children exist, so empty slots add no markup.\n\n#### Properties & Visual Configurations\n\n- **`deletable`** (default `true`): Controls whether the dismiss button is shown. Keep it on for user-removable notifications; set `false` for items the user should not close manually.\n- **`preview`**: Pick `avatar` to show the `src` image (or `initials`/`icon` fallback) as a compact round avatar, or `image` (default) to show `src` as a larger inline picture preview.\n- **`initials`**: Provided as the avatar fallback when no image is available; it overrides `tone`/`variant` styling so the user stays visually recognizable.\n- **`dateFormat`**: Use `timeago` for a live relative timestamp, or any date-format token string for a fixed display date.\n\nFor `tone` and `variant`, this component consumes the shared color ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); the values are forwarded to the underlying `<mds-avatar>` and follow the avatar tone/variant set rather than adding component-specific values.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Message Notification\n\nThe minimal form: a message body with an icon and a relative timestamp. Always nest the item inside [`mds-push-notification`](../../mds-push-notification), which manages stacking and animation.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/email\"\n    subject=\"Nuovo messaggio\"\n    message=\"Hai ricevuto 3 nuovi messaggi da account diversi\"\n    datetime=\"2024-06-01T10:30:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Variant for Semantic Status\n\nUse `variant` to communicate meaning - success, warning, error, info - and `tone` to set visual weight. The values are forwarded to the internal `<mds-avatar>`.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/check-circle\"\n    subject=\"Salvataggio completato\"\n    message=\"Il documento e' stato salvato con successo\"\n    datetime=\"2024-06-01T10:31:00\"\n    variant=\"success\"\n    tone=\"strong\"\n  ></mds-push-notification-item>\n\n  <mds-push-notification-item\n    icon=\"mi/baseline/warning\"\n    subject=\"Attenzione\"\n    message=\"La sessione scadra' tra 5 minuti\"\n    datetime=\"2024-06-01T10:32:00\"\n    variant=\"warning\"\n    tone=\"weak\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Non-Dismissable Notification\n\nBind `deletable` to `false` via a framework or JavaScript property to hide the dismiss button for system notifications the user must not close manually.\n\n```html\n<!-- Framework binding (React / Angular / Vue) -->\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/info\"\n    subject=\"Aggiornamento di sistema\"\n    message=\"Il sistema verra' riavviato alle 23:00\"\n    datetime=\"2024-06-01T09:00:00\"\n    variant=\"info\"\n    :deletable=\"false\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n```javascript\n// Vanilla JS property assignment\nconst item = document.querySelector('mds-push-notification-item');\nitem.deletable = false;\n```\n\n#### Action Buttons via the `action` Slot\n\nSlot one or more `<mds-button>` elements into `slot=\"action\"` for in-notification CTAs. Use `size=\"sm\"` to keep the actions compact.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/person\"\n    subject=\"Mario Giannini\"\n    message=\"Ciao, sono Mario, questo e' il mio contatto, buona giornata!\"\n    datetime=\"2024-06-01T10:25:00\"\n    variant=\"primary\"\n    tone=\"strong\"\n  >\n    <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Accetta\"></mds-button>\n    <mds-button slot=\"action\" variant=\"error\" tone=\"weak\" size=\"sm\" label=\"Ignora\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Badge Label via the `badge` Slot\n\nSlot an `<mds-badge>` into `slot=\"badge\"` to show a category or type label above the subject line.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/attach-file\"\n    subject=\"Nuovo allegato\"\n    message=\"Hai ricevuto un nuovo file allegato da Luca Bianchi\"\n    datetime=\"2024-06-01T10:20:00\"\n    variant=\"primary\"\n  >\n    <mds-badge slot=\"badge\" variant=\"amaranth\" tone=\"weak\">pdf</mds-badge>\n    <mds-button slot=\"action\" tone=\"outline\" size=\"sm\" label=\"Scarica\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Image\n\nSet `src` and `preview=\"avatar\"` to display a user photo as a round avatar instead of the default full-width image preview.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    src=\"./avatar-sarah.jpeg\"\n    preview=\"avatar\"\n    subject=\"Sarah Ho\"\n    message=\"Ciao, sono Sarah, questo e' il mio contatto, buona giornata!\"\n    datetime=\"2024-06-01T10:15:00\"\n    variant=\"primary\"\n    tone=\"strong\"\n  >\n    <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Scrivi\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Initials Fallback\n\nWhen no image is available, set `initials` and `preview=\"avatar\"`. The initials override `tone` and `variant` coloring so the user stays visually distinguishable.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    initials=\"MG\"\n    preview=\"avatar\"\n    subject=\"Mario Giannini\"\n    message=\"Ha modificato il documento condiviso\"\n    datetime=\"2024-06-01T10:10:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Inline Image Preview\n\nOmit `preview=\"avatar\"` (or keep the default `image`) and supply `src` to show the image as a larger inline thumbnail - useful for file or media notifications.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    src=\"./book-cover-01.webp\"\n    subject=\"Anteprima immagine\"\n    message=\"La copertina e' stata aggiornata\"\n    datetime=\"2024-06-01T10:05:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Fixed Date Format\n\nUse any `dayjs`-compatible format string as `date-format` to show a static date instead of the default relative \"time ago\" display.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/event\"\n    subject=\"Promemoria riunione\"\n    message=\"La riunione di progetto e' fissata per domani\"\n    datetime=\"2024-06-01T09:00:00\"\n    date-format=\"DD/MM/YYYY\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Listening to the Dismiss Event\n\nListen to `mdsPushNotificationItemClose` to handle cleanup when the user dismisses the item. The parent `<mds-push-notification>` does this automatically, but you can also add your own logic (e.g. marking the notification read in the server).\n\n```javascript\ndocument\n  .querySelector('mds-push-notification-item')\n  .addEventListener('mdsPushNotificationItemClose', (event) => {\n    const { id } = event.detail;\n    markNotificationRead(id);\n  });\n```\n\n#### Styling Customization\n\nCustomize the item only through its documented `--mds-push-notification-item-*` CSS custom properties.\n\n```css\n.app-notifications mds-push-notification-item {\n  --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n  --mds-push-notification-item-message-line-clamp: 3;\n  --mds-push-notification-item-subject-line-clamp: 2;\n  --mds-push-notification-item-icon-background-color: rgb(var(--variant-primary-03));\n  --mds-push-notification-item-icon-color: rgb(var(--tone-neutral));\n}\n```\n",
-        "3. Antipattern": "Common incorrect uses of `<mds-push-notification-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-push-notification-item>` is a compound child that must live inside [`<mds-push-notification>`](../../mds-push-notification). The parent drives entry / exit animation, stacking, and auto-hide when the last item closes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item\n  icon=\"mi/baseline/email\"\n  subject=\"Nuovo messaggio\"\n  message=\"Hai ricevuto un nuovo messaggio\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/email\"\n    subject=\"Nuovo messaggio\"\n    message=\"Hai ricevuto un nuovo messaggio\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Do Not Rely on `deletable=\"false\"` in Plain HTML to Hide the Dismiss Button\n\nThe `deletable` prop defaults to `true`, so omitting the attribute still shows the dismiss button. To hide it, set the prop to `false` via a framework binding or a JavaScript property assignment - do not try to unset it by omitting the attribute.\n\n```html\n<!-- 🚫 INCORRECT - attribute absent but default is true, so dismiss button still shows -->\n<mds-push-notification-item\n  subject=\"Aggiornamento di sistema\"\n  message=\"Il sistema verra' riavviato alle 23:00\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT - JavaScript property set to false -->\n```\n\n```javascript\n// Vanilla JS\ndocument.querySelector('mds-push-notification-item').deletable = false;\n```\n\n```html\n<!-- ✅ CORRECT - framework binding -->\n<mds-push-notification-item\n  subject=\"Aggiornamento di sistema\"\n  message=\"Il sistema verra' riavviato alle 23:00\"\n  :deletable=\"false\"\n></mds-push-notification-item>\n```\n\n#### Do Not Put Content in the Default Slot\n\n`<mds-push-notification-item>` has no default slot. All text content goes through the `message` and `subject` props; interactive content goes into the named `action` or `badge` slots.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item>\n  Hai un nuovo messaggio\n</mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification-item\n  message=\"Hai un nuovo messaggio\"\n  subject=\"Posta in arrivo\"\n></mds-push-notification-item>\n```\n\n#### Do Not Slot Arbitrary Content Into `action` Without `mds-button`\n\nThe `action` slot is designed for `<mds-button>` elements at `size=\"sm\"`. Slotting raw `<button>` or large components breaks layout alignment and loses Magma theming and keyboard semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n  <button slot=\"action\" class=\"btn\">Approva</button>\n</mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n  <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Approva\"></mds-button>\n</mds-push-notification-item>\n```\n\n#### Do Not Mix `icon` and `src` With `preview=\"image\"`\n\nWhen `icon` is set, the component always renders an `<mds-avatar>` for the icon. If `src` is also set and `preview` is not `\"avatar\"`, a full-width `<mds-img>` is rendered as well - producing two media areas side by side, which is almost never the intended layout. Pick one visual mode per notification.\n\n```html\n<!-- 🚫 INCORRECT - both an icon avatar and a full-width image preview render simultaneously -->\n<mds-push-notification-item\n  icon=\"mi/baseline/photo\"\n  src=\"./cover.jpg\"\n  preview=\"image\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT - icon only, no image -->\n<mds-push-notification-item\n  icon=\"mi/baseline/photo\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT - image preview only, no icon -->\n<mds-push-notification-item\n  src=\"./cover.jpg\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n```\n\n#### Do Not Listen for the Native `close` DOM Event\n\nThe component emits `mdsPushNotificationItemClose`, not a native `close`. Listening for `close` or `click` on the dismiss button will not fire reliably because the button is inside shadow DOM.\n\n```javascript\n// 🚫 INCORRECT\nelement.addEventListener('close', handler);\n\n// ✅ CORRECT\nelement.addEventListener('mdsPushNotificationItemClose', handler);\n```\n\n#### Customize via Documented Vars, Not Internal Selectors\n\nThe supported customization surface is `--mds-push-notification-item-*` CSS custom properties and documented shadow parts (`actions`, `content`, `picture`). Targeting shadow-DOM internals via `::part()` on undocumented parts or via `>>>` will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-push-notification-item::part(header) {\n  font-weight: bold;\n}\nmds-push-notification-item >>> .message {\n  color: red;\n}\n\n/* ✅ CORRECT */\nmds-push-notification-item {\n  --mds-push-notification-item-message-line-clamp: 3;\n  --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n}\nmds-push-notification-item::part(content) {\n  gap: var(--spacing-200);\n}\n```\n"
+        "1. Description": "The `<mds-push-notification-item>` web component is a single notification card rendered inside its parent container [`<mds-push-notification>`](../../mds-push-notification). It composes an avatar/image, a subject, a relative or formatted timestamp, a message body and an optional dismiss control into one toast-like row.\n\n#### Semantic Behavior\n\n- **Compound child only**: It must be placed as a direct default-slot child of `<mds-push-notification>`; it is not used standalone or mixed with other child types, since the parent animates intro/outro and manages stacking.\n- **Dismiss reports up, removal happens in the parent**: Clicking the built-in close button emits the bubbling `mdsPushNotificationItemClose` event; the parent runs the outro animation and removes the item. The item never removes itself.\n- **Parent-driven visibility lifecycle**: When the last item closes, the parent auto-hides the whole notification area.\n- **Timestamp rendering**: With `dateFormat=\"timeago\"` `datetime` shows a localized relative time (\"2 minutes ago\"); otherwise the value is treated as a date-format string for a static date.\n- **Localization**: The relative-time strings and the dismiss button title are localized (el/en/es/it).\n- **Conditional avatar vs. picture**: An `<mds-avatar>` is rendered when `icon` is set or `preview=\"avatar\"`; when `src` is set and `preview` is not `avatar`, a full-width `<mds-img>` preview is rendered instead.\n- **Slot detection**: The `badge` and `action` named slots are only wired into the layout when matching slotted children exist, so empty slots add no markup.\n\n#### Properties & Visual Configurations\n\n- **`deletable`** (default `false`): Controls whether the dismiss button is shown. Add it to let the user close the notification manually; leave it off for items the user should not close.\n- **`preview`**: Pick `avatar` to show the `src` image (or `initials`/`icon` fallback) as a compact round avatar, or `image` (default) to show `src` as a larger inline picture preview.\n- **`initials`**: Provided as the avatar fallback when no image is available; it overrides `tone`/`variant` styling so the user stays visually recognizable.\n- **`dateFormat`**: Use `timeago` for a live relative timestamp, or any date-format token string for a fixed display date.\n\nFor `tone` and `variant`, this component consumes the shared color ladders defined in [`projects/stencil/SPEC.md`](../../../../SPEC.md#tone-and-variant-system); the values are forwarded to the underlying `<mds-avatar>` and follow the avatar tone/variant set rather than adding component-specific values.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-push-notification-item>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the variant / tone ladders documented in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md) and the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md).\n\n#### Basic Message Notification\n\nThe minimal form: a message body with an icon and a relative timestamp. Always nest the item inside [`mds-push-notification`](../../mds-push-notification), which manages stacking and animation.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/email\"\n    subject=\"Nuovo messaggio\"\n    message=\"Hai ricevuto 3 nuovi messaggi da account diversi\"\n    datetime=\"2024-06-01T10:30:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Variant for Semantic Status\n\nUse `variant` to communicate meaning - success, warning, error, info - and `tone` to set visual weight. The values are forwarded to the internal `<mds-avatar>`.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/check-circle\"\n    subject=\"Salvataggio completato\"\n    message=\"Il documento e' stato salvato con successo\"\n    datetime=\"2024-06-01T10:31:00\"\n    variant=\"success\"\n    tone=\"strong\"\n  ></mds-push-notification-item>\n\n  <mds-push-notification-item\n    icon=\"mi/baseline/warning\"\n    subject=\"Attenzione\"\n    message=\"La sessione scadra' tra 5 minuti\"\n    datetime=\"2024-06-01T10:32:00\"\n    variant=\"warning\"\n    tone=\"weak\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Dismissable Notification\n\nAdd the `deletable` attribute to show the dismiss button, letting the user close the notification manually. Without it the notification cannot be dismissed by the user - keep it off for system notifications the user must not close.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    deletable\n    icon=\"mi/baseline/email\"\n    subject=\"Nuovo messaggio\"\n    message=\"Hai ricevuto un nuovo messaggio\"\n    datetime=\"2024-06-01T09:00:00\"\n    variant=\"info\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Action Buttons via the `action` Slot\n\nSlot one or more `<mds-button>` elements into `slot=\"action\"` for in-notification CTAs. Use `size=\"sm\"` to keep the actions compact.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/person\"\n    subject=\"Mario Giannini\"\n    message=\"Ciao, sono Mario, questo e' il mio contatto, buona giornata!\"\n    datetime=\"2024-06-01T10:25:00\"\n    variant=\"primary\"\n    tone=\"strong\"\n  >\n    <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Accetta\"></mds-button>\n    <mds-button slot=\"action\" variant=\"error\" tone=\"weak\" size=\"sm\" label=\"Ignora\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Badge Label via the `badge` Slot\n\nSlot an `<mds-badge>` into `slot=\"badge\"` to show a category or type label above the subject line.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/attach-file\"\n    subject=\"Nuovo allegato\"\n    message=\"Hai ricevuto un nuovo file allegato da Luca Bianchi\"\n    datetime=\"2024-06-01T10:20:00\"\n    variant=\"primary\"\n  >\n    <mds-badge slot=\"badge\" variant=\"amaranth\" tone=\"weak\">pdf</mds-badge>\n    <mds-button slot=\"action\" tone=\"outline\" size=\"sm\" label=\"Scarica\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Image\n\nSet `src` and `preview=\"avatar\"` to display a user photo as a round avatar instead of the default full-width image preview.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    src=\"./avatar-sarah.jpeg\"\n    preview=\"avatar\"\n    subject=\"Sarah Ho\"\n    message=\"Ciao, sono Sarah, questo e' il mio contatto, buona giornata!\"\n    datetime=\"2024-06-01T10:15:00\"\n    variant=\"primary\"\n    tone=\"strong\"\n  >\n    <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Scrivi\"></mds-button>\n  </mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Avatar Mode with Initials Fallback\n\nWhen no image is available, set `initials` and `preview=\"avatar\"`. The initials override `tone` and `variant` coloring so the user stays visually distinguishable.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    initials=\"MG\"\n    preview=\"avatar\"\n    subject=\"Mario Giannini\"\n    message=\"Ha modificato il documento condiviso\"\n    datetime=\"2024-06-01T10:10:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Inline Image Preview\n\nOmit `preview=\"avatar\"` (or keep the default `image`) and supply `src` to show the image as a larger inline thumbnail - useful for file or media notifications.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    src=\"./book-cover-01.webp\"\n    subject=\"Anteprima immagine\"\n    message=\"La copertina e' stata aggiornata\"\n    datetime=\"2024-06-01T10:05:00\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Fixed Date Format\n\nUse any `dayjs`-compatible format string as `date-format` to show a static date instead of the default relative \"time ago\" display.\n\n```html\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/event\"\n    subject=\"Promemoria riunione\"\n    message=\"La riunione di progetto e' fissata per domani\"\n    datetime=\"2024-06-01T09:00:00\"\n    date-format=\"DD/MM/YYYY\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Listening to the Dismiss Event\n\nListen to `mdsPushNotificationItemClose` to handle cleanup when the user dismisses the item. The parent `<mds-push-notification>` does this automatically, but you can also add your own logic (e.g. marking the notification read in the server).\n\n```javascript\ndocument\n  .querySelector('mds-push-notification-item')\n  .addEventListener('mdsPushNotificationItemClose', (event) => {\n    const { id } = event.detail;\n    markNotificationRead(id);\n  });\n```\n\n#### Styling Customization\n\nCustomize the item only through its documented `--mds-push-notification-item-*` CSS custom properties.\n\n```css\n.app-notifications mds-push-notification-item {\n  --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n  --mds-push-notification-item-message-line-clamp: 3;\n  --mds-push-notification-item-subject-line-clamp: 2;\n  --mds-push-notification-item-icon-background-color: rgb(var(--variant-primary-03));\n  --mds-push-notification-item-icon-color: rgb(var(--tone-neutral));\n}\n```\n",
+        "3. Antipattern": "Common incorrect uses of `<mds-push-notification-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use the Item Outside Its Parent\n\n`<mds-push-notification-item>` is a compound child that must live inside [`<mds-push-notification>`](../../mds-push-notification). The parent drives entry / exit animation, stacking, and auto-hide when the last item closes.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item\n  icon=\"mi/baseline/email\"\n  subject=\"Nuovo messaggio\"\n  message=\"Hai ricevuto un nuovo messaggio\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification>\n  <mds-push-notification-item\n    icon=\"mi/baseline/email\"\n    subject=\"Nuovo messaggio\"\n    message=\"Hai ricevuto un nuovo messaggio\"\n  ></mds-push-notification-item>\n</mds-push-notification>\n```\n\n#### Do Not Put Content in the Default Slot\n\n`<mds-push-notification-item>` has no default slot. All text content goes through the `message` and `subject` props; interactive content goes into the named `action` or `badge` slots.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item>\n  Hai un nuovo messaggio\n</mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification-item\n  message=\"Hai un nuovo messaggio\"\n  subject=\"Posta in arrivo\"\n></mds-push-notification-item>\n```\n\n#### Do Not Slot Arbitrary Content Into `action` Without `mds-button`\n\nThe `action` slot is designed for `<mds-button>` elements at `size=\"sm\"`. Slotting raw `<button>` or large components breaks layout alignment and loses Magma theming and keyboard semantics.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n  <button slot=\"action\" class=\"btn\">Approva</button>\n</mds-push-notification-item>\n\n<!-- ✅ CORRECT -->\n<mds-push-notification-item subject=\"Richiesta\" message=\"Approva la richiesta di accesso\">\n  <mds-button slot=\"action\" variant=\"success\" tone=\"weak\" size=\"sm\" label=\"Approva\"></mds-button>\n</mds-push-notification-item>\n```\n\n#### Do Not Mix `icon` and `src` With `preview=\"image\"`\n\nWhen `icon` is set, the component always renders an `<mds-avatar>` for the icon. If `src` is also set and `preview` is not `\"avatar\"`, a full-width `<mds-img>` is rendered as well - producing two media areas side by side, which is almost never the intended layout. Pick one visual mode per notification.\n\n```html\n<!-- 🚫 INCORRECT - both an icon avatar and a full-width image preview render simultaneously -->\n<mds-push-notification-item\n  icon=\"mi/baseline/photo\"\n  src=\"./cover.jpg\"\n  preview=\"image\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT - icon only, no image -->\n<mds-push-notification-item\n  icon=\"mi/baseline/photo\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n\n<!-- ✅ CORRECT - image preview only, no icon -->\n<mds-push-notification-item\n  src=\"./cover.jpg\"\n  subject=\"Nuova foto\"\n  message=\"La copertina e' stata aggiornata\"\n></mds-push-notification-item>\n```\n\n#### Do Not Listen for the Native `close` DOM Event\n\nThe component emits `mdsPushNotificationItemClose`, not a native `close`. Listening for `close` or `click` on the dismiss button will not fire reliably because the button is inside shadow DOM.\n\n```javascript\n// 🚫 INCORRECT\nelement.addEventListener('close', handler);\n\n// ✅ CORRECT\nelement.addEventListener('mdsPushNotificationItemClose', handler);\n```\n\n#### Customize via Documented Vars, Not Internal Selectors\n\nThe supported customization surface is `--mds-push-notification-item-*` CSS custom properties and documented shadow parts (`actions`, `content`, `picture`). Targeting shadow-DOM internals via `::part()` on undocumented parts or via `>>>` will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-push-notification-item::part(header) {\n  font-weight: bold;\n}\nmds-push-notification-item >>> .message {\n  color: red;\n}\n\n/* ✅ CORRECT */\nmds-push-notification-item {\n  --mds-push-notification-item-message-line-clamp: 3;\n  --mds-push-notification-item-shadow: var(--shadow-md-sharp);\n}\nmds-push-notification-item::part(content) {\n  gap: var(--spacing-200);\n}\n```\n"
       },
       "props": [
         {
@@ -24034,14 +23945,14 @@
           "mutable": true,
           "attr": "deletable",
           "reflectToAttr": true,
-          "docs": "Specifies if the component is dismissable or not, it should be set to true by default is used with it's parent component `mds-push-notification-items`",
+          "docs": "Specifies if the component is dismissable; when set, a dismiss button is shown.",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -27564,6 +27475,44 @@
         "3. Antipattern": "Common incorrect uses of `<mds-tab-item>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use `<mds-tab-item>` Outside `<mds-tab>`\n\nThe item communicates with its parent through Stencil's internal listener (`mdsTabItemSelect`); used standalone it has no tab-switching behavior and no aria context.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n\n<!-- ✅ CORRECT -->\n<mds-tab>\n  <mds-tab-item label=\"Dettagli\" selected></mds-tab-item>\n  <div slot=\"content\"><p>Contenuto dei dettagli.</p></div>\n</mds-tab>\n```\n\n#### Do Not Wrap `<mds-tab-item>` in a Div or Other Element\n\nThe parent queries direct children with `querySelectorAll('mds-tab-item')`; a wrapper breaks the slot pairing between items and content panels.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tab>\n  <div class=\"tab-group\">\n    <mds-tab-item label=\"Uno\" selected></mds-tab-item>\n    <mds-tab-item label=\"Due\"></mds-tab-item>\n  </div>\n  <div slot=\"content\">...</div>\n  <div slot=\"content\">...</div>\n</mds-tab>\n\n<!-- ✅ CORRECT -->\n<mds-tab>\n  <mds-tab-item label=\"Uno\" selected></mds-tab-item>\n  <mds-tab-item label=\"Due\"></mds-tab-item>\n  <div slot=\"content\">...</div>\n  <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Set `selected=\"false\"` to Deselect\n\n`selected` is a boolean attribute; the string `\"false\"` is truthy in HTML and will keep the item selected. Remove the attribute entirely to deselect.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tab-item label=\"Archivio\" selected=\"false\"></mds-tab-item>\n\n<!-- ✅ CORRECT -->\n<mds-tab-item label=\"Archivio\"></mds-tab-item>\n```\n\n#### Do Not Slot `<mds-icon>` or HTML to Add an Icon\n\n`<mds-tab-item>` has no documented default slot for content; it is a button-like leaf element. Use the `icon` prop to add a glyph.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tab-item>\n  <mds-icon name=\"mi/baseline/settings\"></mds-icon>\n  Impostazioni\n</mds-tab-item>\n\n<!-- ✅ CORRECT -->\n<mds-tab-item label=\"Impostazioni\" icon=\"mi/baseline/settings\"></mds-tab-item>\n```\n\n#### Do Not Override `size` on Individual Items When a Parent Size Is Set\n\nThe parent pushes its `size` down to every child item on load and whenever `size` changes. Setting `size` on individual items is overwritten and creates confusion about the source of truth.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tab size=\"sm\">\n  <mds-tab-item label=\"Uno\" size=\"lg\" selected></mds-tab-item>\n  <mds-tab-item label=\"Due\" size=\"sm\"></mds-tab-item>\n  <div slot=\"content\">...</div>\n  <div slot=\"content\">...</div>\n</mds-tab>\n\n<!-- ✅ CORRECT -->\n<mds-tab size=\"sm\">\n  <mds-tab-item label=\"Uno\" selected></mds-tab-item>\n  <mds-tab-item label=\"Due\"></mds-tab-item>\n  <div slot=\"content\">...</div>\n  <div slot=\"content\">...</div>\n</mds-tab>\n```\n\n#### Do Not Pierce the Shadow DOM to Style the Inner Button\n\nThe only supported customization surface is the `--mds-tab-item-*` CSS custom properties and the documented `button` shadow part. Targeting internals via `::part(button) >>> .button` or undocumented selectors couples your code to the implementation.\n\n```css\n/* 🚫 INCORRECT */\nmds-tab-item::part(button) >>> .text {\n  font-weight: 900;\n}\n\n/* ✅ CORRECT */\nmds-tab-item {\n  --mds-tab-item-selected-background: rgb(var(--variant-primary-02));\n}\nmds-tab-item::part(button) {\n  border-radius: var(--radius-lg);\n}\n```\n\n#### Do Not Mix Content Panels and Tab Items Without a 1-to-1 Pairing\n\nThe parent resolves each content panel by index, matching it to the `mds-tab-item` at the same position. A mismatch (more or fewer `slot=\"content\"` elements than tab items) silently shows the wrong panel.\n\n```html\n<!-- 🚫 INCORRECT - two items, one content panel -->\n<mds-tab>\n  <mds-tab-item label=\"Uno\" selected></mds-tab-item>\n  <mds-tab-item label=\"Due\"></mds-tab-item>\n  <div slot=\"content\"><p>Contenuto unico.</p></div>\n</mds-tab>\n\n<!-- ✅ CORRECT - one content panel per tab item -->\n<mds-tab>\n  <mds-tab-item label=\"Uno\" selected></mds-tab-item>\n  <mds-tab-item label=\"Due\"></mds-tab-item>\n  <div slot=\"content\"><p>Contenuto del tab Uno.</p></div>\n  <div slot=\"content\"><p>Contenuto del tab Due.</p></div>\n</mds-tab>\n```\n"
       },
       "props": [
+        {
+          "name": "animation",
+          "type": "\"fade\" | \"slide\" | undefined",
+          "complexType": {
+            "original": "HorizontalActionsAnimationType",
+            "resolved": "\"fade\" | \"slide\" | undefined",
+            "references": {
+              "HorizontalActionsAnimationType": {
+                "location": "import",
+                "path": "@type/animation",
+                "id": "src/type/animation.ts::HorizontalActionsAnimationType",
+                "referenceLocation": "HorizontalActionsAnimationType"
+              }
+            }
+          },
+          "mutable": false,
+          "attr": "animation",
+          "reflectToAttr": true,
+          "docs": "Reflects the parent tab selection animation (set by mds-tab); drives the\nslide-variant styling without :host-context",
+          "docsTags": [],
+          "values": [
+            {
+              "value": "fade",
+              "type": "string"
+            },
+            {
+              "value": "slide",
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "await",
           "type": "boolean",
@@ -27587,6 +27536,44 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "direction",
+          "type": "\"horizontal\" | \"vertical\" | undefined",
+          "complexType": {
+            "original": "DirectionType",
+            "resolved": "\"horizontal\" | \"vertical\" | undefined",
+            "references": {
+              "DirectionType": {
+                "location": "import",
+                "path": "@component/mds-tab/meta/type",
+                "id": "src/components/mds-tab/meta/type.ts::DirectionType",
+                "referenceLocation": "DirectionType"
+              }
+            }
+          },
+          "mutable": false,
+          "attr": "direction",
+          "reflectToAttr": true,
+          "docs": "Reflects the parent tab layout direction (set by mds-tab); drives the\nvertical layout without :host-context",
+          "docsTags": [],
+          "values": [
+            {
+              "value": "horizontal",
+              "type": "string"
+            },
+            {
+              "value": "vertical",
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "disabled",
           "type": "boolean | undefined",
@@ -29007,6 +28994,32 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "selection",
+          "type": "boolean | undefined",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean | undefined",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "selection",
+          "reflectToAttr": true,
+          "docs": "Reflects the parent table selection state (set by mds-table); drives the\nrow action background without :host-context",
+          "docsTags": [],
+          "values": [
+            {
+              "type": "boolean"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "value",
           "type": "number | string | undefined",
@@ -30198,13 +30211,13 @@
         }
       ],
       "usage": {
-        "1. Description": "The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System. It renders a small text bubble that attaches to a separate trigger element identified by a CSS selector, rather than relying on the native `title` attribute.\n\n#### Semantic Behavior\n\n- **Detached trigger model**: The tooltip is not wrapped around its trigger; the required `target` selector is resolved and the component binds itself to the first matching caller.\n- **Hover-driven visibility**: The bubble appears and disappears as the pointer enters and leaves the trigger.\n- **Visibility is the source of truth**: Setting `visible` programmatically shows or dismisses the bubble, allowing the tooltip to be controlled without a hover.\n- **Live repositioning**: Changing any layout prop (`placement`, `offset`, `shift`, `shiftPadding`, `strategy`, `flip`, `autoPlacement`, `arrow`) recomputes the floating position on the fly.\n- **Text-only default slot**: The default slot is meant for a plain text string (exposed as the `text` shadow part); HTML elements or components should not be slotted in.\n\n#### Properties & Visual Configurations\n\n- **`target`** (required) is the CSS selector of the trigger element the tooltip listens to and anchors against; the first match wins.\n- **`placement`** chooses the preferred side and alignment relative to the caller (e.g. `'top'`, `'bottom-start'`), while **`autoPlacement`** lets the system pick the best side automatically and **`flip`** allows falling back to the opposite side when the preferred one lacks space.\n- **`shift`** keeps the bubble inside the viewport, with **`shiftPadding`** reserving a safe gap from the viewport edges; **`offset`** sets the distance between the bubble and the caller.\n- **`strategy`** selects the CSS positioning strategy: `'fixed'` (default) escapes clipping ancestors, `'absolute'` anchors within the nearest positioned ancestor.\n- **`typography`** picks the text scale of the bubble (`'tip'`, `'caption'`, `'detail'`), where `'tip'` is the default compact hint sizing.\n",
-        "2. Pattern": "Correct and idiomatic ways to use the `<mds-tooltip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the component catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Basic Tooltip on a Button\n\nThe most common form. Give the trigger element an `id` (or any unique CSS selector) and point `target` at it. The tooltip listens for hover events on the trigger and positions itself automatically.\n\n```html\n<mds-button id=\"salva-btn\" label=\"Salva documento\" variant=\"primary\" tone=\"strong\"></mds-button>\n<mds-tooltip target=\"#salva-btn\">Salva le modifiche correnti</mds-tooltip>\n```\n\n#### Tooltip on a Non-Interactive Element\n\n`target` accepts any CSS selector, not just `#id`. Use a class or attribute selector when the trigger is a static element such as a status icon.\n\n```html\n<mds-icon class=\"stato-icona\" name=\"mi/baseline/info\"></mds-icon>\n<mds-tooltip target=\".stato-icona\">Ultima sincronizzazione: oggi alle 08:30</mds-tooltip>\n```\n\n#### Placement and Preferred Side\n\nOverride the default `top` placement with `placement` when layout requires a different side. Set `auto-placement=\"false\"` to lock the side and prevent the system from overriding it.\n\n```html\n<mds-button id=\"dettagli-btn\" label=\"Dettagli\" variant=\"secondary\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#dettagli-btn\" placement=\"right\" auto-placement=\"false\">\n  Apre il pannello laterale con i dettagli completi\n</mds-tooltip>\n```\n\nAccepted values: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`.\n\n#### Flip Fallback When Space is Tight\n\nEnable `flip` so the tooltip moves to the opposite side if the preferred placement collides with the viewport edge. Combine with `auto-placement=\"false\"` to keep a preferred side while allowing a single-axis fallback.\n\n```html\n<mds-button id=\"azione-btn\" label=\"Azione\" variant=\"primary\"></mds-button>\n<mds-tooltip target=\"#azione-btn\" placement=\"top\" auto-placement=\"false\" flip>\n  Esegui l'operazione selezionata\n</mds-tooltip>\n```\n\n#### Viewport-Safe Shift\n\n`shift` (default `true`) slides the tooltip along its axis so it stays inside the viewport. Increase `shift-padding` to keep a wider safe margin from the viewport edges.\n\n```html\n<mds-button id=\"bordo-btn\" label=\"Vicino al bordo\" variant=\"dark\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#bordo-btn\" shift shift-padding=\"24\">\n  Questa azione e' irreversibile\n</mds-tooltip>\n```\n\n#### Custom Offset Distance\n\nIncrease `offset` when additional breathing room between the trigger and the bubble is required - for example inside dense toolbars or on elements with large focus rings.\n\n```html\n<mds-button id=\"info-btn\" label=\"Info\" variant=\"info\" tone=\"weak\"></mds-button>\n<mds-tooltip target=\"#info-btn\" offset=\"20\">\n  Informazioni aggiuntive sul campo\n</mds-tooltip>\n```\n\n#### Programmatic Visibility\n\nSet the `visible` attribute (or property) to control the tooltip without hover. Useful for guided tours, onboarding hints, or error annotations that appear on demand.\n\n```html\n<mds-button id=\"primo-accesso\" label=\"Inizia\" variant=\"primary\"></mds-button>\n<mds-tooltip id=\"hint\" target=\"#primo-accesso\" visible>\n  Benvenuto! Clicca qui per iniziare la configurazione.\n</mds-tooltip>\n\n<script>\n  const hint = document.querySelector('#hint');\n  // Dismiss programmatically when the user acknowledges the hint\n  document.querySelector('#primo-accesso').addEventListener('click', () => {\n    hint.visible = false;\n  });\n</script>\n```\n\n#### Typography Scale\n\n`typography` adjusts the text scale inside the bubble. Use `'tip'` (default) for compact hints, `'caption'` for slightly larger labels, and `'detail'` for the smallest footnote-style text.\n\n```html\n<!-- Default compact hint -->\n<mds-tooltip target=\"#campo-nome\" typography=\"tip\">Massimo 64 caratteri</mds-tooltip>\n\n<!-- Slightly larger label -->\n<mds-tooltip target=\"#campo-data\" typography=\"caption\">Formato: GG/MM/AAAA</mds-tooltip>\n```\n\n#### Positioning Strategy\n\nUse `strategy=\"absolute\"` when the tooltip must be contained within a scrolling ancestor instead of the viewport. The default `strategy=\"fixed\"` escapes any clipping or overflow-hidden parent.\n\n```html\n<!-- Inside a scrollable panel with overflow:hidden ancestors -->\n<mds-tooltip target=\"#voce-lista\" strategy=\"absolute\">Trascina per riordinare</mds-tooltip>\n```\n\n#### Styling Customization\n\nStyle the tooltip only through its documented `--mds-tooltip-*` CSS custom properties. Set them on the host element or a parent selector; use the Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.onboarding-hint mds-tooltip {\n  --mds-tooltip-background: rgb(var(--variant-primary-03));\n  --mds-tooltip-arrow-background: rgb(var(--variant-primary-03));\n  --mds-tooltip-delay: 0.25s;\n  --mds-tooltip-duration: 0.3s;\n  --mds-tooltip-z-index: 5000;\n}\n```\n",
+        "1. Description": "The `<mds-tooltip>` web component is the floating contextual hint of the Magma Design System. It renders a small text bubble that attaches to a separate trigger element identified by a CSS selector, rather than relying on the native `title` attribute.\n\n#### Semantic Behavior\n\n- **Detached trigger model**: The tooltip is not wrapped around its trigger; the required `target` selector is resolved and the component binds itself to the first matching caller.\n- **Hover-driven visibility**: The bubble appears and disappears as the pointer enters and leaves the trigger.\n- **Visibility is the source of truth**: Setting `visible` programmatically shows or dismisses the bubble, allowing the tooltip to be controlled without a hover.\n- **Live repositioning**: Changing any layout prop (`placement`, `offset`, `disableShift`, `shiftPadding`, `strategy`, `flip`, `disableAutoPlacement`, `hideArrow`) recomputes the floating position on the fly.\n- **Text-only default slot**: The default slot is meant for a plain text string (exposed as the `text` shadow part); HTML elements or components should not be slotted in.\n\n#### Properties & Visual Configurations\n\n- **`target`** (required) is the CSS selector of the trigger element the tooltip listens to and anchors against; the first match wins.\n- **`placement`** chooses the preferred side and alignment relative to the caller (e.g. `'top'`, `'bottom-start'`); the system picks the best side automatically by default (**`disableAutoPlacement`** opts out and pins to `placement`) and **`flip`** allows falling back to the opposite side when the preferred one lacks space.\n- the bubble is kept inside the viewport by default (**`disableShift`** opts out), with **`shiftPadding`** reserving a safe gap from the viewport edges; **`offset`** sets the distance between the bubble and the caller.\n- **`strategy`** selects the CSS positioning strategy: `'fixed'` (default) escapes clipping ancestors, `'absolute'` anchors within the nearest positioned ancestor.\n- **`typography`** picks the text scale of the bubble (`'tip'`, `'caption'`, `'detail'`), where `'tip'` is the default compact hint sizing.\n",
+        "2. Pattern": "Correct and idiomatic ways to use the `<mds-tooltip>` component, ordered from most common to most specialized. Patterns assume a working knowledge of the generic stencil rules in [`projects/stencil/SPEC.md`](../../../../SPEC.md) and the component catalogue in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md).\n\n#### Basic Tooltip on a Button\n\nThe most common form. Give the trigger element an `id` (or any unique CSS selector) and point `target` at it. The tooltip listens for hover events on the trigger and positions itself automatically.\n\n```html\n<mds-button id=\"salva-btn\" label=\"Salva documento\" variant=\"primary\" tone=\"strong\"></mds-button>\n<mds-tooltip target=\"#salva-btn\">Salva le modifiche correnti</mds-tooltip>\n```\n\n#### Tooltip on a Non-Interactive Element\n\n`target` accepts any CSS selector, not just `#id`. Use a class or attribute selector when the trigger is a static element such as a status icon.\n\n```html\n<mds-icon class=\"stato-icona\" name=\"mi/baseline/info\"></mds-icon>\n<mds-tooltip target=\".stato-icona\">Ultima sincronizzazione: oggi alle 08:30</mds-tooltip>\n```\n\n#### Placement and Preferred Side\n\nOverride the default `top` placement with `placement` when layout requires a different side. Add `disable-auto-placement` to lock the side and prevent the system from overriding it.\n\n```html\n<mds-button id=\"dettagli-btn\" label=\"Dettagli\" variant=\"secondary\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#dettagli-btn\" placement=\"right\" disable-auto-placement>\n  Apre il pannello laterale con i dettagli completi\n</mds-tooltip>\n```\n\nAccepted values: `top`, `top-start`, `top-end`, `bottom`, `bottom-start`, `bottom-end`, `left`, `left-start`, `left-end`, `right`, `right-start`, `right-end`.\n\n#### Flip Fallback When Space is Tight\n\nEnable `flip` so the tooltip moves to the opposite side if the preferred placement collides with the viewport edge. Combine with `disable-auto-placement` to keep a preferred side while allowing a single-axis fallback.\n\n```html\n<mds-button id=\"azione-btn\" label=\"Azione\" variant=\"primary\"></mds-button>\n<mds-tooltip target=\"#azione-btn\" placement=\"top\" disable-auto-placement flip>\n  Esegui l'operazione selezionata\n</mds-tooltip>\n```\n\n#### Viewport-Safe Shift\n\nBy default the tooltip slides along its axis so it stays inside the viewport (set `disable-shift` to opt out). Increase `shift-padding` to keep a wider safe margin from the viewport edges.\n\n```html\n<mds-button id=\"bordo-btn\" label=\"Vicino al bordo\" variant=\"dark\" tone=\"outline\"></mds-button>\n<mds-tooltip target=\"#bordo-btn\" shift-padding=\"24\">\n  Questa azione e' irreversibile\n</mds-tooltip>\n```\n\n#### Custom Offset Distance\n\nIncrease `offset` when additional breathing room between the trigger and the bubble is required - for example inside dense toolbars or on elements with large focus rings.\n\n```html\n<mds-button id=\"info-btn\" label=\"Info\" variant=\"info\" tone=\"weak\"></mds-button>\n<mds-tooltip target=\"#info-btn\" offset=\"20\">\n  Informazioni aggiuntive sul campo\n</mds-tooltip>\n```\n\n#### Programmatic Visibility\n\nSet the `visible` attribute (or property) to control the tooltip without hover. Useful for guided tours, onboarding hints, or error annotations that appear on demand.\n\n```html\n<mds-button id=\"primo-accesso\" label=\"Inizia\" variant=\"primary\"></mds-button>\n<mds-tooltip id=\"hint\" target=\"#primo-accesso\" visible>\n  Benvenuto! Clicca qui per iniziare la configurazione.\n</mds-tooltip>\n\n<script>\n  const hint = document.querySelector('#hint');\n  // Dismiss programmatically when the user acknowledges the hint\n  document.querySelector('#primo-accesso').addEventListener('click', () => {\n    hint.visible = false;\n  });\n</script>\n```\n\n#### Typography Scale\n\n`typography` adjusts the text scale inside the bubble. Use `'tip'` (default) for compact hints, `'caption'` for slightly larger labels, and `'detail'` for the smallest footnote-style text.\n\n```html\n<!-- Default compact hint -->\n<mds-tooltip target=\"#campo-nome\" typography=\"tip\">Massimo 64 caratteri</mds-tooltip>\n\n<!-- Slightly larger label -->\n<mds-tooltip target=\"#campo-data\" typography=\"caption\">Formato: GG/MM/AAAA</mds-tooltip>\n```\n\n#### Positioning Strategy\n\nUse `strategy=\"absolute\"` when the tooltip must be contained within a scrolling ancestor instead of the viewport. The default `strategy=\"fixed\"` escapes any clipping or overflow-hidden parent.\n\n```html\n<!-- Inside a scrollable panel with overflow:hidden ancestors -->\n<mds-tooltip target=\"#voce-lista\" strategy=\"absolute\">Trascina per riordinare</mds-tooltip>\n```\n\n#### Styling Customization\n\nStyle the tooltip only through its documented `--mds-tooltip-*` CSS custom properties. Set them on the host element or a parent selector; use the Magma color tokens via `rgb(var(--<token>))` so dark mode and high-contrast modes keep working.\n\n```css\n.onboarding-hint mds-tooltip {\n  --mds-tooltip-background: rgb(var(--variant-primary-03));\n  --mds-tooltip-arrow-background: rgb(var(--variant-primary-03));\n  --mds-tooltip-delay: 0.25s;\n  --mds-tooltip-duration: 0.3s;\n  --mds-tooltip-z-index: 5000;\n}\n```\n",
         "3. Antipattern": "Common incorrect uses of `<mds-tooltip>`. Each entry pairs the wrong form with the right one and a one-line reason. System-wide rules (boolean-as-string, shadow piercing, Tailwind color utilities, raw native event listening) live in [`docs/COMPONENTS.md`](../../../../../../docs/COMPONENTS.md#system-level-anti-patterns) - they apply here too but are not repeated.\n\n#### Do Not Use a Bare ID String as `target`\n\nBefore Magma 4.0 the `target` attribute accepted a bare id without the `#` prefix. This is no longer valid; the value is now passed directly to `querySelector`, so a CSS selector is required.\n\n```html\n<!-- 🚫 INCORRECT (Magma 3.x style) -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"hint-trigger\">Testo di aiuto</mds-tooltip>\n\n<!-- ✅ CORRECT (Magma 4.x querySelector selector) -->\n<span id=\"hint-trigger\">Aiuto</span>\n<mds-tooltip target=\"#hint-trigger\">Testo di aiuto</mds-tooltip>\n```\n\n#### Do Not Slot HTML Elements or Components\n\nThe default slot is text-only. Nesting HTML elements or Magma components breaks the inner layout and may produce unexpected rendering because the slot is wrapped in `<mds-text>`.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tooltip target=\"#voce\">\n  <mds-icon name=\"mi/baseline/warning\"></mds-icon>\n  <strong>Attenzione:</strong> campo obbligatorio\n</mds-tooltip>\n\n<!-- ✅ CORRECT -->\n<mds-tooltip target=\"#voce\">Attenzione: campo obbligatorio</mds-tooltip>\n```\n\n#### Do Not Wrap the Trigger Inside the Tooltip\n\n`<mds-tooltip>` uses a detached trigger model - the tooltip is placed as a sibling in the DOM and linked via `target`, not wrapped around its trigger. Nesting the trigger breaks the floating position logic.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tooltip target=\"#btn\">\n  <mds-button id=\"btn\" label=\"Elimina\"></mds-button>\n  Elimina il record selezionato\n</mds-tooltip>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#btn\">Elimina il record selezionato</mds-tooltip>\n```\n\n#### Do Not Set `visible=\"false\"` to Hide the Tooltip\n\n`visible` is a boolean attribute; setting it to the string `\"false\"` is truthy in HTML and keeps the tooltip visible. Remove the attribute (or set the property to `false`) to hide it.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-tooltip target=\"#campo\" visible=\"false\">Testo nascosto</mds-tooltip>\n\n<!-- ✅ CORRECT -->\n<mds-tooltip target=\"#campo\">Testo nascosto</mds-tooltip>\n```\n\n```js\n// ✅ CORRECT (programmatic)\ndocument.querySelector('mds-tooltip').visible = false;\n```\n\n#### Do Not Pierce the Shadow DOM to Style Internal Parts\n\nThe only supported customization surface is the set of `--mds-tooltip-*` CSS custom properties and the documented `text` shadow part. Targeting undocumented internal selectors couples your code to the implementation and will break on minor releases.\n\n```css\n/* 🚫 INCORRECT */\nmds-tooltip >>> .text {\n  font-style: italic;\n}\nmds-tooltip::part(arrow) {\n  fill: red;\n}\n\n/* ✅ CORRECT */\nmds-tooltip {\n  --mds-tooltip-background: rgb(var(--variant-primary-03));\n  --mds-tooltip-delay: 0.5s;\n}\nmds-tooltip::part(text) {\n  font-style: italic;\n}\n```\n\n#### Do Not Replace `<mds-tooltip>` with a Native `title` Attribute\n\nThe native `title` tooltip is not keyboard-accessible, not styleable, and not announced consistently by screen readers on touch devices. Use `<mds-tooltip>` for all contextual hints.\n\n```html\n<!-- 🚫 INCORRECT -->\n<mds-button label=\"Elimina\" title=\"Elimina il record selezionato\"></mds-button>\n\n<!-- ✅ CORRECT -->\n<mds-button id=\"elimina-btn\" label=\"Elimina\" variant=\"error\" tone=\"text\"></mds-button>\n<mds-tooltip target=\"#elimina-btn\">Elimina il record selezionato</mds-tooltip>\n```\n"
       },
       "props": [
         {
-          "name": "autoPlacement",
+          "name": "disableAutoPlacement",
           "type": "boolean",
           "complexType": {
             "original": "boolean",
@@ -30212,16 +30225,45 @@
             "references": {}
           },
           "mutable": false,
-          "attr": "auto-placement",
+          "attr": "disable-auto-placement",
           "reflectToAttr": true,
-          "docs": "If set, the component will be placed automatically near it's caller.",
+          "docs": "If set, the component will not be placed automatically near it's caller.",
           "docsTags": [
             {
               "name": "default",
-              "text": "true"
+              "text": "false"
             }
           ],
-          "default": "true",
+          "default": "false",
+          "values": [
+            {
+              "type": "boolean"
+            }
+          ],
+          "optional": false,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
+        {
+          "name": "disableShift",
+          "type": "boolean",
+          "complexType": {
+            "original": "boolean",
+            "resolved": "boolean",
+            "references": {}
+          },
+          "mutable": false,
+          "attr": "disable-shift",
+          "reflectToAttr": false,
+          "docs": "If set, the component will not be kept inside the viewport.",
+          "docsTags": [
+            {
+              "name": "default",
+              "text": "false"
+            }
+          ],
+          "default": "false",
           "values": [
             {
               "type": "boolean"
@@ -30371,35 +30413,6 @@
           "getter": false,
           "setter": false
         },
-        {
-          "name": "shift",
-          "type": "boolean",
-          "complexType": {
-            "original": "boolean",
-            "resolved": "boolean",
-            "references": {}
-          },
-          "mutable": false,
-          "attr": "shift",
-          "reflectToAttr": false,
-          "docs": "If set, the component will be kept inside the viewport.",
-          "docsTags": [
-            {
-              "name": "default",
-              "text": "true"
-            }
-          ],
-          "default": "true",
-          "values": [
-            {
-              "type": "boolean"
-            }
-          ],
-          "optional": false,
-          "required": false,
-          "getter": false,
-          "setter": false
-        },
         {
           "name": "shiftPadding",
           "type": "number",
@@ -31195,6 +31208,44 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "appearance",
+          "type": "\"depth\" | \"none\" | undefined",
+          "complexType": {
+            "original": "TreeAppearance",
+            "resolved": "\"depth\" | \"none\" | undefined",
+            "references": {
+              "TreeAppearance": {
+                "location": "import",
+                "path": "@type/tree",
+                "id": "src/type/tree.ts::TreeAppearance",
+                "referenceLocation": "TreeAppearance"
+              }
+            }
+          },
+          "mutable": false,
+          "attr": "appearance",
+          "reflectToAttr": true,
+          "docs": "Reflects the parent tree appearance (set by mds-tree); drives the depth/none\nlayout without :host-context",
+          "docsTags": [],
+          "values": [
+            {
+              "value": "depth",
+              "type": "string"
+            },
+            {
+              "value": "none",
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "async",
           "type": "boolean | undefined",
@@ -31360,6 +31411,44 @@
           "getter": false,
           "setter": false
         },
+        {
+          "name": "togglePosition",
+          "type": "\"left\" | \"right\" | undefined",
+          "complexType": {
+            "original": "ButtonIconPositionType",
+            "resolved": "\"left\" | \"right\" | undefined",
+            "references": {
+              "ButtonIconPositionType": {
+                "location": "import",
+                "path": "@type/button",
+                "id": "src/type/button.ts::ButtonIconPositionType",
+                "referenceLocation": "ButtonIconPositionType"
+              }
+            }
+          },
+          "mutable": false,
+          "attr": "toggle-position",
+          "reflectToAttr": true,
+          "docs": "Reflects the parent tree toggle icon position (set by mds-tree); drives the\ntoggle-icon layout without :host-context",
+          "docsTags": [],
+          "values": [
+            {
+              "value": "left",
+              "type": "string"
+            },
+            {
+              "value": "right",
+              "type": "string"
+            },
+            {
+              "type": "undefined"
+            }
+          ],
+          "optional": true,
+          "required": false,
+          "getter": false,
+          "setter": false
+        },
         {
           "name": "truncate",
           "type": "\"all\" | \"none\" | \"word\" | undefined",
@@ -31432,6 +31521,28 @@
           "docs": "Expands the tree item, revealing its children.",
           "docsTags": []
         },
+        {
+          "name": "refreshActions",
+          "returns": {
+            "type": "Promise<void>",
+            "docs": ""
+          },
+          "complexType": {
+            "signature": "() => Promise<void>",
+            "parameters": [],
+            "references": {
+              "Promise": {
+                "location": "global",
+                "id": "global::Promise"
+              }
+            },
+            "return": "Promise<void>"
+          },
+          "signature": "refreshActions() => Promise<void>",
+          "parameters": [],
+          "docs": "`internal` Re-resolves the effective actions; called by mds-tree when its own\nactions changes so items that inherit it stay in sync.",
+          "docsTags": []
+        },
         {
           "name": "updateLang",
           "returns": {
@@ -32878,11 +32989,6 @@
       "docstring": "",
       "path": "src/components/mds-modal/meta/types.ts"
     },
-    "src/components/mds-modal/meta/types.ts::ModalAnimationStateType": {
-      "declaration": "export type ModalAnimationStateType = 'intro' | 'none' | 'outro';",
-      "docstring": "",
-      "path": "src/components/mds-modal/meta/types.ts"
-    },
     "src/components/mds-modal/meta/types.ts::ModalAnimationStyleType": {
       "declaration": "export type ModalAnimationStyleType = 'slide' | 'custom' | '3d';",
       "docstring": "",
@@ -32934,7 +33040,7 @@
       "path": "src/event-detail/preference.ts"
     },
     "src/type/preference.ts::ConsumptionModeType": {
-      "declaration": "\"high\" | \"medium\" | \"low\"",
+      "declaration": "\"low\" | \"medium\" | \"high\"",
       "docstring": "",
       "path": "src/type/preference.ts"
     },
@@ -32954,7 +33060,7 @@
       "path": "src/type/preference.ts"
     },
     "src/type/preference.ts::PreferenceThemeTransitionType": {
-      "declaration": "\"none\" | \"smooth\" | \"flash\"",
+      "declaration": "\"none\" | \"flash\" | \"smooth\"",
       "docstring": "",
       "path": "src/type/preference.ts"
     },