@supersoniks/concorde 5.0.0 → 5.0.2

package/src/core/components/ui/card/card.md

@@ -1,97 +1,152 @@
 # Card
 
+A **surface** for grouped content: padding, radius, shadow, and semantic **`type`** colors via shared theme tokens. Compose **`sonic-card-header`**, **`sonic-card-main`**, and **`sonic-card-footer`** inside the card, or put any markup in the default slot.
+
+Default **`type`** is `base` (page background). Use `light` for a subtle gray panel, `invert` / `neutral` for high-contrast blocks, and `primary`, `info`, `success`, `warning`, or `danger` for tinted surfaces (divider tokens apply on colored types).
+
 ## Type
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-3 gap-3">
-    <sonic-card type="base">Base</sonic-card>
-    <sonic-card type="light">Light</sonic-card>
-    <sonic-card type="primary">Primary</sonic-card>
-    <sonic-card type="warning">Warning</sonic-card>
-    <sonic-card type="danger">Danger</sonic-card>
-    <sonic-card type="success">Success</sonic-card>
-    <sonic-card type="info">Info</sonic-card>
-    <sonic-card type="neutral">Neutral</sonic-card>
-    <sonic-card type="invert">Invert</sonic-card>
-  </div>
+    <div class="flex flex-wrap gap-3">
+      <sonic-card type="base" class="min-w-[8rem]">Base</sonic-card>
+      <sonic-card type="light" class="min-w-[8rem]">Light</sonic-card>
+      <sonic-card type="primary" class="min-w-[8rem]">Primary</sonic-card>
+      <sonic-card type="info" class="min-w-[8rem]">Info</sonic-card>
+      <sonic-card type="success" class="min-w-[8rem]">Success</sonic-card>
+      <sonic-card type="warning" class="min-w-[8rem]">Warning</sonic-card>
+      <sonic-card type="danger" class="min-w-[8rem]">Danger</sonic-card>
+      <sonic-card type="neutral" class="min-w-[8rem]">Neutral</sonic-card>
+      <sonic-card type="invert" class="min-w-[8rem]">Invert</sonic-card>
+    </div>
   </template>
 </sonic-code>
 
 ## Header
+
+Quick titles with **`label`** and **`description`** attributes, or full control through the default slot. **`slot="suffix"`** aligns badges or actions on the right; suffix content does not shrink when the title wraps.
+
 <sonic-code>
   <template>
-  <div class="grid grid-cols-1 gap-3">
-    <sonic-card >
-      <sonic-card-header label="Header simple, titre géré via l'attribut : label" description="Description via l'attribut : description">
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="neutral">
-      <sonic-card-header label="Header composé">
-        <sonic-card-header-description>Description rendu via le composant : "sonic-card-header-description"</sonic-card-header-description>
-        <div  slot="suffix" class="flex">
-          Suffix
-        </div>
-      </sonic-card-header>
-    </sonic-card>
-    <sonic-card type="invert">
-      <sonic-card-header>
-        <div>Header custom</div>
-        <div class="text-lg text-danger">Tout le contenu excepté l'icône ✈ passe par le slot du header</div>
-        <span slot="suffix" >✈</span>
-      </sonic-card-header>
-    </sonic-card>
-  </div>
+    <div class="grid gap-4 max-w-xl">
+      <sonic-card>
+        <sonic-card-header
+          label="Account settings"
+          description="Manage your profile and preferences."
+        ></sonic-card-header>
+        <p class="m-0 text-sm opacity-80">Body content goes in the card slot or in <code>sonic-card-main</code>.</p>
+      </sonic-card>
+
+      <sonic-card type="neutral">
+        <sonic-card-header label="Notifications">
+          <sonic-card-header-description>
+            Choose what we email you about.
+          </sonic-card-header-description>
+          <sonic-badge slot="suffix"  type="warning" size="xs">3 new</sonic-badge>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card>
+        <sonic-card-header label="Team workspace" description="Shared with 12 members">
+          <sonic-button
+            slot="suffix"
+            shape="circle"
+            variant="outline"
+            size="sm"
+            type="default"
+            icon
+            data-aria-label="Workspace settings"
+          >
+            <sonic-icon library="iconoir" name="settings"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+
+      <sonic-card type="primary">
+        <sonic-card-header>
+          <div>Custom header</div>
+          <sonic-card-header-description>
+            Use the header slot when attributes are not enough.
+          </sonic-card-header-description>
+          <sonic-button slot="suffix" shape="circle" variant="ghost" size="sm" type="primary" icon>
+            <sonic-icon library="iconoir" name="nav-arrow-right"></sonic-icon>
+          </sonic-button>
+        </sonic-card-header>
+      </sonic-card>
+    </div>
   </template>
 </sonic-code>
 
+`label` and `description` accept HTML (rendered as markup). Prefer plain text when possible; use the slot for structured content.
+
 ## Main
+
+Optional wrapper for the primary content area (typography, media, forms).
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-main >
-      <h3>Main area</h3>
-      <p>Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-      <iframe width="560" height="315" src="https://www.youtube.com/embed/aqz-KE-bpKQ" title="Big Buck Bunny (Blender Foundation)" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>
-    </sonic-card-main>
-  </sonic-card>
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Release notes" description="Version 2.4"></sonic-card-header>
+      <sonic-card-main>
+        <p class="mt-0">
+          Improved performance on large lists and fixed an issue with keyboard navigation in menus.
+        </p>
+        <sonic-divider></sonic-divider>
+        <p class="mb-0 text-sm opacity-80">See the changelog for details.</p>
+      </sonic-card-main>
+    </sonic-card>
   </template>
 </sonic-code>
 
 ## Footer
+
+Optional footer for actions, metadata, or secondary text.
+
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-footer >
-      <div >
-        <h4 class="mb-0">Footer area</h4>
-        <small>Debitis deleniti eligendi natus dolorem aufdh.</small>
-        <div>
-          🛫 ✈ ✈ ✈ ✈ ✈ 🛬
+    <sonic-card class="max-w-xl">
+      <sonic-card-header label="Confirm deletion"></sonic-card-header>
+      <sonic-card-main>
+        <p class="m-0">This project and all of its data will be removed permanently.</p>
+      </sonic-card-main>
+      <sonic-card-footer>
+      <sonic-divider></sonic-divider>
+        <div class="flex flex-wrap gap-2 justify-end">
+          <sonic-button variant="ghost" size="sm">Cancel</sonic-button>
+          <sonic-button type="danger" size="sm">Delete</sonic-button>
         </div>
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>
 
+## Full example
+
+Header, media, body, and footer together.
 
-## Example of use
 <sonic-code>
   <template>
-  <sonic-card >
-    <sonic-card-header label="Header" description="Header description">
-      <sonic-icon library="iconoir" name="nav-arrow-right" slot="suffix" ></sonic-icon>
-    </sonic-card-header>
-    <sonic-card-main >
-      <sonic-image rounded ratio="11/4" src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg">
-      </sonic-image>
-      <p><b>Main</b> - Lorem ipsum dolor sit, amet consectetur adipisicing elit. Iure id dolor debitis deleniti eligendi natus dolorem a commodi sunt dicta? Ipsa asperiores magni consequuntur dolor voluptatibus. Maxime, nemo? Facere, odio.</p>
-    </sonic-card-main>
-    <sonic-card-footer>
-      <div>
-        <i>Footer</i> - Amet consectetur adipisicing
-      </div>
-    </sonic-card-footer>
-  </sonic-card>
+    <sonic-card class="max-w-md">
+      <sonic-card-header label="Featured route" description="San Francisco → New York">
+        <sonic-icon slot="suffix" library="iconoir" name="airplane"></sonic-icon>
+      </sonic-card-header>
+      <sonic-card-main>
+        <sonic-image
+          rounded
+          ratio="16/9"
+          src="https://images.unsplash.com/photo-1436491865332-7a61a109cc05?w=800&q=80"
+          alt=""
+        ></sonic-image>
+        <p class="mb-0">
+          Nonstop flight with flexible dates. Prices shown include taxes and fees.
+        </p>
+      </sonic-card-main>
+      <sonic-card-footer>
+        <div class="flex items-center justify-between gap-3 flex-wrap">
+          <span class="text-sm font-semibold">From $249</span>
+          <sonic-button type="primary" size="sm">Book</sonic-button>
+        </div>
+      </sonic-card-footer>
+    </sonic-card>
   </template>
 </sonic-code>

package/src/core/components/ui/divider/divider.ts

@@ -6,12 +6,13 @@ import {
   query,
 } from "lit/decorators.js";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { Size } from "@supersoniks/concorde/core/components/ui/_css/size";
 const tagName = "sonic-divider";
 @customElement(tagName)
 export class Divider extends LitElement {
   static styles = [
     css`
-      :host { 
+      :host {
         --sc-divider-my: 0.5rem;
         --sc-divider-mx: 0;
         --sc-divider-border-width: max(
@@ -150,14 +151,8 @@ export class Divider extends LitElement {
   divider!: HTMLDivElement;
 
   @property({ type: String }) label = "";
-  @property({ type: String, reflect: true }) size?:
-    | "2xs"
-    | "xs"
-    | "sm"
-    | "md"
-    | "lg"
-    | "xl"
-    | "2xl";
+  @property({ type: String, reflect: true }) size?: Size;
+
   @property({ type: String, reflect: true }) align:
     | "left"
     | "right"

package/src/core/components/ui/form/fieldset/legend-description.ts

@@ -6,7 +6,7 @@ export class LegendDescription extends LitElement {
   static styles = [
     css`
       :host {
-        font-size: 1.15rem;
+        font-size: 1.125rem;
         line-height: 1.2;
         display: block;
         color: var(--sc-base-500, var(--sc-base-content, #000));

package/src/core/components/ui/form/fieldset/legend.ts

@@ -11,7 +11,7 @@ export class Legend extends LitElement {
   static styles = [
     css`
       :host {
-        --sc-legend-font-size: 1.5rem;
+        --sc-legend-font-size: 1.25rem;
         --sc-legend-font-weight: var(--sc-font-weight-base, 400);
         --sc-legend-font-style: var(--sc-headings-font-style, normal);
         --sc-legend-family: var(

package/src/core/components/ui/form/input/input.md

@@ -2,7 +2,7 @@
 
 <sonic-button type="info" size="sm" target="_blank" href="https://www.w3schools.com/tags/tag_input.asp#midcontentadcontainer">
   <sonic-icon library="iconoir" name="open-new-window" slot="prefix" ></sonic-icon>
-  Native attibutes list
+  Native attributes list
 </sonic-button>
 
 ## Label

package/src/core/components/ui/form/input/input.ts

@@ -16,7 +16,14 @@ import {
 import FormElement from "@supersoniks/concorde/core/mixins/FormElement";
 import FormInput from "@supersoniks/concorde/core/mixins/FormInput";
 import { classMap } from "lit/directives/class-map.js";
-import { fontSize } from "@supersoniks/concorde/core/components/ui/_css/size";
+import {
+  fontSize,
+  Size,
+} from "@supersoniks/concorde/core/components/ui/_css/size";
+import {
+  resolveUiLabel,
+  uiAriaLabels,
+} from "@supersoniks/concorde/core/components/ui/_i18n/ui-aria-labels";
 import { unsafeHTML } from "lit/directives/unsafe-html.js";
 
 /**
@@ -48,14 +55,7 @@ export class Input extends FormInput(FormElement(LitElement)) {
   /**
    * Taille du composant, implique notamment des modifications de typo et de marge interne
    */
-  @property({ type: String, reflect: true }) size?:
-    | "2xs"
-    | "xs"
-    | "sm"
-    | "md"
-    | "lg"
-    | "xl"
-    | "2xl";
+  @property({ type: String, reflect: true }) size?: Size;
   @property({ type: String }) inputmode?: string;
   @property({ type: String }) list?: string;
   @property({ type: String }) placeholder?: string;
@@ -163,7 +163,7 @@ export class Input extends FormInput(FormElement(LitElement)) {
     if (this.changeTimeoutId) clearTimeout(this.changeTimeoutId);
     this.changeTimeoutId = setTimeout(
       () => super.handleChange(e),
-      parseInt(this.getAttribute("inputDelayMs") || "0")
+      parseInt(this.getAttribute("inputDelayMs") || "0"),
     );
   }
 
@@ -212,8 +212,8 @@ export class Input extends FormInput(FormElement(LitElement)) {
     //let labelStarSuffix = this.label && this.required && this.label.indexOf("*") == -1 ? " *" : "";
     return html`
       <label for="${this.id || "form-element"}" class="${
-      this.hasLabel ? "form-label" : "hidden"
-    }"
+        this.hasLabel ? "form-label" : "hidden"
+      }"
         >${this.label ? unsafeHTML(this.label /*+ labelStarSuffix*/) : ""}<slot
           name="label"
           @slotchange=${this.hasSlotOrProps}
@@ -221,8 +221,8 @@ export class Input extends FormInput(FormElement(LitElement)) {
       ></label>
 
       <div @click=${this.inlineContentFocus} class="form-control ${classMap(
-      slotClasses
-    )}">
+        slotClasses,
+      )}">
         <div part="content" class="${
           this.inlineContent ? "form-element form-element-wrapper" : "contents"
         }">
@@ -263,7 +263,11 @@ export class Input extends FormInput(FormElement(LitElement)) {
                       shape="circle"
                       class="password-toggle"
                       @click=${this.togglePasswordVisibility}
-                      data-aria-label="Toggle password visibility"
+                      .ariaLabel=${resolveUiLabel(
+                        this.isPassword
+                          ? uiAriaLabels.showPassword
+                          : uiAriaLabels.hidePassword,
+                      )}
                       variant="unstyled"
                     >
                       <sonic-icon

package/src/core/components/ui/form/textarea/textarea.md

@@ -2,7 +2,7 @@
 
 <sonic-button type="info" size="sm" target="_blank" href="https://www.w3schools.com/tags/tag_textarea.asp#midcontentadcontainer">
   <sonic-icon library="iconoir" name="open-new-window" slot="prefix" ></sonic-icon>
-  Native attibutes list
+  Native attributes list
 </sonic-button>
 
 

package/src/core/components/ui/image/image.md

@@ -1,107 +1,201 @@
 # Image
 
+Responsive **`<img>`** wrapper: aspect ratio, `object-fit: cover`, rounded corners, and optional fade-in on load. The host uses a light placeholder background (`--sc-placeholder-bg`) until the file is ready. Default **`loading`** is `lazy`; set **`loading="eager"`** for above-the-fold heroes.
+
 ## Rounded
 
+Omit `rounded` for square corners. Boolean **`rounded`** uses the theme token `--sc-rounded`. Sizes: **`sm`**, **`md`**, **`lg`**, **`xl`**, **`full`** (circle — pair with `ratio="1/1"`), **`none`** (explicit reset).
+
 <sonic-code>
   <template>
-    <div class="grid gap-8 grid-cols-3 items-center">
-      <sonic-image
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-        ratio="1/1"
-      >
-      </sonic-image>
-      <sonic-image
-        rounded="sm"
-        ratio="1/1"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
-      <sonic-image
-        rounded
-        ratio="1/1"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
-      <sonic-image
-        rounded="md"
-        ratio="1/1"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
-      <sonic-image
-        rounded="lg"
-        ratio="1/1"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
-      <sonic-image
-        rounded="full"
-        ratio="1/1"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
+    <div class="grid gap-6 grid-cols-3  lg:grid-cols-4 items-end text-center text-xs ">
+      <div>
+        <sonic-image
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">default</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="sm"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">sm</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">rounded</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="md"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">md</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="lg"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">lg</p>
+      </div>
+      <div>
+        <sonic-image
+          rounded="xl"
+          ratio="1/1"
+          src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+        ></sonic-image>
+        <p class="mt-2">xl</p>
+      </div>
+      <div >
+        <div >
+          <sonic-image
+            rounded="full"
+            ratio="1/1"
+            src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+          ></sonic-image>
+          <p class="mt-2">full</p>
+        </div>
+      </div>
     </div>
   </template>
 </sonic-code>
 
-## Ratio
+## Aspect ratio
+
+**`ratio`** sets CSS `aspect-ratio` on the image (default **`auto`**). The image still fills the host width (`width: 100%`).
 
 <sonic-code>
   <template>
     <div class="grid gap-8 grid-cols-2 items-center">
       <sonic-image
         src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
+      ></sonic-image>
       <sonic-image
         ratio="16/9"
         src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
+      ></sonic-image>
       <sonic-image
         ratio="1/1"
         src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
+      ></sonic-image>
       <sonic-image
         ratio="2/3"
         src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      >
-      </sonic-image>
+      ></sonic-image>
     </div>
   </template>
 </sonic-code>
 
 ## Object position
 
+**`objectPosition`** maps to CSS `object-position` (default **`center center`**). Useful on wide crops when the subject sits off-center.
+
 <sonic-code>
   <template>
     <div class="grid gap-8 grid-cols-2 items-center">
       <sonic-image
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
         ratio="11/4"
-      >
-      </sonic-image>
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
       <sonic-image
         objectPosition="center top"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
         ratio="11/4"
-      >
-      </sonic-image>
+        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
     </div>
   </template>
 </sonic-code>
 
 ## Cover
 
+**`cover`** stretches the image to fill a **positioned** parent (`position: relative` + fixed height or inset). Aspect ratio on the host is ignored while `cover` is set.
+
 <sonic-code>
   <template>
-    <div class="h-96 relative">
+    <div class="h-96 relative rounded-lg overflow-hidden">
       <sonic-image
         cover
         src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+      ></sonic-image>
+    </div>
+  </template>
+</sonic-code>
+
+## Load transition
+
+Set **`transition`** to **`fade`** (default when the attribute is present) or **`fade-scale-out`**. The image stays at `opacity: 0` until the browser fires **`load`**, then the **`loaded`** class runs the animation. Changing `src` on an existing element does not replay the effect — mount a new `sonic-image` when you need another entrance (galleries, infinite scroll).
+
+Click **Add image** to append small thumbnails and replay the transition. **Clear** resets the row.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2 mb-4">
+      <sonic-button
+        size="sm"
+        onclick="(function () {
+          var host = document.getElementById('sonic-image-transition-host');
+          var img = document.createElement('sonic-image');
+          img.transition = 'fade';
+          img.ratio = '1/1';
+          img.rounded = 'md';
+          img.loading = 'eager';
+          img.style.width = '5rem';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          host.appendChild(img);
+        })()"
+      >
+        Add image (fade)
+      </sonic-button>
+      <sonic-button
+        size="sm"
+        variant="outline"
+        onclick="(function () {
+          var host = document.getElementById('sonic-image-transition-host');
+          var img = document.createElement('sonic-image');
+          img.transition = 'fade-scale-out';
+          img.ratio = '1/1';
+          img.rounded = 'md';
+          img.loading = 'eager';
+          img.style.width = '5rem';
+          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          host.appendChild(img);
+        })()"
+      >
+        Add image (fade-scale-out)
+      </sonic-button>
+      <sonic-button
+        size="sm"
+        variant="ghost"
+        onclick="document.getElementById('sonic-image-transition-host').replaceChildren()"
       >
-      </sonic-image>
+        Clear
+      </sonic-button>
     </div>
+    <div id="sonic-image-transition-host" class="flex flex-wrap gap-2 min-h-[5rem]"></div>
+  </template>
+</sonic-code>
+
+## Accessibility and parts
+
+Always set meaningful **`alt`** text (empty string only for decorative images). 
+
+<sonic-code>
+  <template>
+    <sonic-image
+      rounded="md"
+      ratio="16/9"
+      alt="Concorde aircraft in flight"
+      src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
+    ></sonic-image>
   </template>
 </sonic-code>