@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -1,57 +1,80 @@
 # Switch
 
-## Size
+**`sonic-switch`** is a toggle-styled [Checkbox](/core/components/ui/form/checkbox) in `unique` mode: when on, it stores its `value` under `name` in the **`formDataProvider`** data; when off, it stores `null`. Switches sharing a `name` behave as one choice, so give independent switches distinct names. Label goes in the default slot or `label`, helper text in the `description` slot.
+
+## Basic example
+
 <sonic-code>
   <template>
-    <div class="grid gap-2" formDataProvider="switchSizeExemple">
-      <sonic-switch name="size2xs" value="2xs" size="2xs">2xs switch</sonic-switch>
-      <sonic-switch name="sizexs" value="xs" size="xs">xs switch</sonic-switch>
-      <sonic-switch name="sizesm" value="sm" size="sm">sm switch</sonic-switch>
-      <sonic-switch name="size" value="default" >default switch</sonic-switch>
-      <sonic-switch name="sizelg" value="lg" size="lg">lg switch</sonic-switch>
-      <sonic-switch name="sizexl" value="xl" size="xl">xl switch</sonic-switch>
-      <sonic-switch name="size2xl" value="2xl" size="2xl">2xl switch</sonic-switch>
+    <div formDataProvider="switch-basic-demo" class="grid gap-2">
+      <sonic-switch name="notifications" value="on" checked>
+        Notifications
+        <span slot="description">Get an alert when your gate changes.</span>
+      </sonic-switch>
+      <div>Value: <sonic-value dataProvider="switch-basic-demo" key="notifications"></sonic-value></div>
     </div>
   </template>
 </sonic-code>
 
-## Checked
-<sonic-code>
-  <template>
-  <sonic-switch checked
-    >Already checked switch
-  </sonic-switch>
-  </template>
-</sonic-code>
+## Size
 
-## Disabled
-<sonic-code>
-  <template>
-  <sonic-switch disabled
-    >Disabled switch
-  </sonic-switch>
-  </template>
-</sonic-code>
+With no `size`, the switch follows `md` (1rem).
 
-## Disabled and checked
 <sonic-code>
   <template>
-  <sonic-switch disabled checked
-    >Disabled but already checked switch
-  </sonic-switch>
+    <div class="grid gap-2">
+      <sonic-switch size="2xs">2xs</sonic-switch>
+      <sonic-switch size="xs">xs</sonic-switch>
+      <sonic-switch size="sm">sm</sonic-switch>
+      <sonic-switch>Default</sonic-switch>
+      <sonic-switch size="lg">lg</sonic-switch>
+      <sonic-switch size="xl">xl</sonic-switch>
+      <sonic-switch size="2xl">2xl</sonic-switch>
+    </div>
   </template>
 </sonic-code>
 
-## switch with link
+## Checked and disabled
+
+`checked` sets the initial state. `disabled` blocks interaction and dims the control.
+
 <sonic-code>
   <template>
-  <sonic-switch name="link" value="link">switch with <sonic-link href="#" class="underline text-info">link</sonic-link>
+    <div class="grid gap-2">
+      <sonic-switch checked>Checked</sonic-switch>
+      <sonic-switch disabled>Disabled</sonic-switch>
+      <sonic-switch disabled checked>Disabled and checked</sonic-switch>
+      <sonic-switch>I accept the <sonic-link href="#" class="underline">terms</sonic-link></sonic-switch>
+    </div>
   </template>
 </sonic-code>
 
+## Filtering a list
+
+On, the switch writes `status=delayed` to the store used as `dataFilterProvider` by a `sonic-queue`; off, it writes `null` and the filter is dropped.
+
+<docs-lit-demo for="docs-flight-delayed-switch-demo"></docs-lit-demo>
+
+## API reference
 
-## Example of use — blacklist + queue
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `name` | string | Key in the form data (dot notation supported) |
+| `value` | string | Value stored when on |
+| `formDataProvider` | string | Form data id; inherited from the closest ancestor when omitted |
+| `checked` | boolean | Initial state |
+| `unsetOnDisconnect` | boolean | Removes the value from the data when the element is removed |
+| `label` | string (HTML) | Label, rendered before the default slot |
+| `description` | string (HTML) | Helper text, rendered in the `description` slot |
+| `size` | `2xs` … `2xl` · `inherit` (default `md`) | Font size and track size |
+| `disabled` | boolean | Blocks interaction |
+| `required` | boolean | Native validation on form submit |
+| `autofocus` | boolean | Focuses the input on load |
+| `data-aria-label` · `data-aria-labelledby` | string | Forwarded to the inner input as `aria-label` / `aria-labelledby` |
 
-Same mock filter as [Checkbox](#core/components/ui/form/checkbox/checkbox.md/checkbox); switches can enable several flags (comma-separated in the query).
+| Slot | Description |
+|------|-------------|
+| *(default)* | Label content (text, links) |
+| `description` | Helper text under the label |
 
-<docs-lit-demo for="docs-joke-blacklist-switch-demo"></docs-lit-demo>
+Fires a `change` event on each click.

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

@@ -1,65 +1,82 @@
 # Textarea
 
-<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 attributes list
-</sonic-button>
+**`sonic-textarea`** wraps a native `<textarea>` with a label, a description and Concorde sizes. Native attributes (`rows`, `cols`, `maxlength`, `wrap`, …) are passed through. Bind the value to a store with **`formDataProvider`** and **`name`**, set on the field or on an ancestor.
 
+## Basic example
 
-## Label
 <sonic-code>
   <template>
-  <sonic-textarea label="Label"></sonic-textarea>
+    <sonic-textarea label="Comments to the crew" placeholder="Write your message" description="Plain text only."></sonic-textarea>
   </template>
 </sonic-code>
 
-## Placeholder
-<sonic-code>
-  <template>
-  <sonic-textarea placeholder="placeholder"></sonic-textarea>
-  </template>
-</sonic-code>
+## Rows and resize
 
-## Value
-<sonic-code>
-  <template>
-  <sonic-textarea value="value"></sonic-textarea>
-  </template>
-</sonic-code>
+`rows` sets the visible height. With no `resize`, the user can resize vertically only.
 
-## Required
 <sonic-code>
   <template>
-  <sonic-textarea required label="Feedback on blur" placeholder="required" ></sonic-textarea>
+    <div class="grid gap-3">
+      <sonic-textarea rows="6" label="Six rows"></sonic-textarea>
+      <sonic-textarea resize="none" label="Not resizable"></sonic-textarea>
+    </div>
   </template>
 </sonic-code>
 
-## Rows
-<sonic-code>
-  <template>
-  <sonic-textarea rows="8"></sonic-textarea>
-  </template>
-</sonic-code>
+## Size and status
+
+With no `size`, the textarea uses `md`. `status` colors the field; it defaults to `default`.
 
-## Description
 <sonic-code>
   <template>
-  <sonic-textarea  description="Description goes here" ></sonic-textarea>
+    <div class="grid gap-3">
+      <sonic-textarea rows="1" size="2xs" value="2xs"></sonic-textarea>
+      <sonic-textarea rows="1" size="xs" value="xs"></sonic-textarea>
+      <sonic-textarea rows="1" size="sm" value="sm"></sonic-textarea>
+      <sonic-textarea rows="1" value="default"></sonic-textarea>
+      <sonic-textarea rows="1" size="lg" value="lg"></sonic-textarea>
+      <sonic-textarea rows="1" size="xl" value="xl"></sonic-textarea>
+      <sonic-textarea rows="1" size="2xl" value="2xl"></sonic-textarea>
+      <sonic-textarea rows="1" status="success" value="success"></sonic-textarea>
+      <sonic-textarea rows="1" status="error" value="error"></sonic-textarea>
+      <sonic-textarea rows="1" status="warning" value="warning"></sonic-textarea>
+      <sonic-textarea rows="1" status="info" value="info"></sonic-textarea>
+    </div>
   </template>
 </sonic-code>
 
+## Validation
+
+`required`, `minlength` and `maxlength` are checked by the browser. Feedback styles apply once the field is `touched` (after blur).
 
-## Size
 <sonic-code>
   <template>
-  <div class="grid gap-4">
-    <sonic-textarea size="2xs" value="2xs"></sonic-textarea>
-    <sonic-textarea size="xs" value="xs"></sonic-textarea>
-    <sonic-textarea size="sm" value="sm"></sonic-textarea>
-    <sonic-textarea value="md / default"></sonic-textarea>
-    <sonic-textarea size="lg" value="lg"></sonic-textarea>
-    <sonic-textarea size="xl" value="xl"></sonic-textarea>
-    <sonic-textarea size="2xl" value="2xl"></sonic-textarea>
-  </div>
+    <sonic-textarea required minlength="10" label="Special assistance request" placeholder="At least 10 characters"></sonic-textarea>
   </template>
 </sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `name` | string | Key in the form store (dot notation allowed) |
+| `value` | string | Initial value |
+| `formDataProvider` | string | Store id; inherited from the closest ancestor |
+| `label` | string (HTML) | Label; or use the `label` slot |
+| `description` | string (HTML) | Help text under the field; or use the `description` slot |
+| `placeholder` | string | Native placeholder |
+| `size` | `2xs` … `2xl` (default `md`) | Typography and padding |
+| `status` | `default` · `success` · `error` · `warning` · `info` | Field color |
+| `rows` · `cols` | number | Native dimensions |
+| `minlength` · `maxlength` | number | Native length constraints |
+| `wrap` | `soft` · `hard` | Native wrapping |
+| `resize` | `vertical` · `horizontal` · `both` · `none` · `block` · `inline` (default `vertical`) | CSS resize handle |
+| `required` · `disabled` · `readonly` · `autofocus` | boolean | Native flags |
+| `autocomplete` · `tabindex` | native | Passed to the inner `<textarea>` |
+| `data-aria-label` · `data-aria-labelledby` | string | Forwarded as `aria-label` and `aria-labelledby` |
+| `unsetOnDisconnect` | boolean | Clears the store value when the element is removed |
+
+| Slot | Description |
+|------|-------------|
+| `label` | Rich label content |
+| `description` | Rich help text |

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

@@ -1,62 +1,64 @@
 # Group
 
-**`sonic-group`** lays out slotted **`sonic-button`** · **`sonic-input`** and **`sonic-select`** controls in a single horizontal row with **shared corner radius** (first / middle / last items). Optional **`label`** and **`description`** follow form field styling. Use it for **button groups**, **radio rows**, or **input + action** toolbars.
+**`sonic-group`** lays out `sonic-button` · `sonic-input` and `sonic-select` controls in one row with a **shared corner radius**: only the outer corners of the first and last items stay rounded. Use it for button groups, radio rows or a field with an attached action. Optional `label` and `description` follow form field styling.
 
 ## Radio group
 
-Pair with **`sonic-button`** **`radio`** and a shared **`name`**; ancestor **`formDataProvider`** stores the selected **`value`**.
+Give each `sonic-button` the `radio` attribute and a shared `name`. The selected `value` is written to the `formDataProvider` set on the group (inherited by the buttons).
 
 <sonic-code>
   <template>
-    <sonic-group formDataProvider="subscriptionData">
-      <sonic-button radio name="subscription" value="standard" type="default">😎 Standard</sonic-button>
-      <sonic-button radio checked name="subscription" value="premium" type="default">⭐ Premium</sonic-button>
-      <sonic-button radio name="subscription" value="diamond" type="default">💎 Diamond</sonic-button>
+    <sonic-group formDataProvider="groupPlanDemo">
+      <sonic-button radio name="plan" value="free" type="default">Free</sonic-button>
+      <sonic-button radio checked name="plan" value="pro" type="default">Pro</sonic-button>
+      <sonic-button radio name="plan" value="team" type="default">Team</sonic-button>
     </sonic-group>
   </template>
 </sonic-code>
 
 ## Button group
 
-Adjacent link or action buttons without merging into one control.
+Adjacent action buttons that stay independent controls.
 
 <sonic-code>
   <template>
     <sonic-group>
-      <sonic-button type="info" target="_blank" href="https://wwws.airfrance.fr/">🗼 Air France</sonic-button>
-      <sonic-button type="success" target="_blank" href="https://www.airtahitinui.com/">🌴 Air Tahiti</sonic-button>
-      <sonic-button type="danger" target="_blank" href="https://www.aircorsica.com/">💣 Air Corsica</sonic-button>
+      <sonic-button type="default">
+        <sonic-icon library="iconoir" name="align-left"></sonic-icon>
+      </sonic-button>
+      <sonic-button type="default">
+        <sonic-icon library="iconoir" name="align-center"></sonic-icon>
+      </sonic-button>
+      <sonic-button type="default">
+        <sonic-icon library="iconoir" name="align-right"></sonic-icon>
+      </sonic-button>
     </sonic-group>
   </template>
 </sonic-code>
 
-## Input actions prefix
+## Field with action
 
-Action control before the field. **`label`** or **`description`** on **`sonic-group`** annotate the row.
+Put the action before or after the field. `label` and `description` annotate the whole row.
 
 <sonic-code>
   <template>
-      <sonic-group label="Label" description="Description">
-        <sonic-button type="info" shape="square">
-          <sonic-icon library="iconoir" name="info-empty"></sonic-icon>
+    <div class="grid gap-4 max-w-md">
+      <sonic-group label="Search" description="Type a flight number, then confirm.">
+        <sonic-input placeholder="CN 001"></sonic-input>
+        <sonic-button type="primary" shape="square">
+          <sonic-icon library="iconoir" name="search"></sonic-icon>
         </sonic-button>
-        <sonic-input></sonic-input>
       </sonic-group>
-  </template>
-</sonic-code>
-
-## Input actions suffix
-
-Field first, action after (submit, validate, etc.).
-
-<sonic-code>
-  <template>
-      <sonic-group label="Label" description="Description">
-        <sonic-input></sonic-input>
-        <sonic-button type="primary" shape="square">
-          <sonic-icon library="iconoir" name="check"></sonic-icon>
+      <sonic-group label="Extra baggage">
+        <sonic-button type="default" shape="square">
+          <sonic-icon library="iconoir" name="minus"></sonic-icon>
+        </sonic-button>
+        <sonic-input type="number" value="1"></sonic-input>
+        <sonic-button type="default" shape="square">
+          <sonic-icon library="iconoir" name="plus"></sonic-icon>
         </sonic-button>
       </sonic-group>
+    </div>
   </template>
 </sonic-code>
 
@@ -64,12 +66,12 @@ Field first, action after (submit, validate, etc.).
 
 | Attribute | Values | Description |
 |----------|---------|-------------|
-| `label` | string (HTML) | Label above the row; **`slot="label"`** overrides / extends |
-| `description` | string (HTML) | Help text below the row; **`slot="description"`** overrides / extends |
-| `alignItems` | CSS align-items (default `center`) | Cross-axis alignment of the main flex row |
+| `label` | string (HTML) | Label above the row; content of `slot="label"` is appended |
+| `description` | string (HTML) | Help text below the row; content of `slot="description"` replaces it |
+| `alignItems` | CSS `align-items` value (default `center`) | Cross-axis alignment of the row |
 
 | Slot | Description |
 |------|-------------|
-| *(default)* | **`sonic-button`** · **`sonic-input`** · **`sonic-select`** in visual order |
+| *(default)* | `sonic-button` · `sonic-input` · `sonic-select` in visual order |
 | `label` | Custom label markup |
 | `description` | Custom description markup |

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

@@ -139,7 +139,7 @@ Use **`library="custom"`** with SVG files on your origin. On an ancestor (for ex
 
 ## Size
 
-Omit **`size`** for the default scale (`1em` height). Larger steps use **`3xl`**.
+Omit **`size`** for the default scale (`1em` height, inherited from the font size). Steps go from `2xs` to `3xl`.
 
 <sonic-code>
   <template>
@@ -194,8 +194,8 @@ On connect, the host sets **`aria-hidden="true"`**. Treat icons as decorative un
 
 <sonic-code>
   <template>
-    <sonic-button type="neutral" variant="outline" shape="circle" aria-label="User profile">
-      <sonic-icon library="iconoir" name="user"></sonic-icon>
+    <sonic-button type="neutral" variant="outline" shape="circle" aria-label="Flight details">
+      <sonic-icon library="iconoir" name="airplane"></sonic-icon>
     </sonic-button>
   </template>
 </sonic-code>
@@ -207,7 +207,7 @@ On connect, the host sets **`aria-hidden="true"`**. Treat icons as decorative un
 | `name` | string | Icon id in the core bundle or in the remote library |
 | `library` | `heroicons` · `iconoir` · `feathers` · `lucide` · `material` · `fontAwesome` · `custom` | CDN or custom template; omit for bundled core icons |
 | `prefix` | string | Library-specific variant; defaults per library when empty |
-| `size` | `2xs` · `xs` · `sm` · `lg` · `xl` · `2xl` · `3xl` (default `md`) | `em`-based SVG scale on the host |
+| `size` | `2xs` · `xs` · `sm` · `lg` · `xl` · `2xl` · `3xl` (default `1em`, no attribute) | `em`-based SVG scale on the host |
 
 Ancestor attributes (for **`library="custom"`** only): **`customIconLibraryPath`** (URL template with **`$prefix`** and **`$name`**) and **`customIconDefaultPrefix`**. May be set on **`sonic-scope`**, theme roots, or globally in the document.
 

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

@@ -1,70 +1,41 @@
 # Image
 
-**`sonic-image`** wraps a responsive **`<img>`** with aspect ratio, `object-fit: cover`, optional rounded corners, and load transitions. The host shows a placeholder background (`--sc-placeholder-bg`) until the asset loads. Default **`loading`** is `lazy`; use **`loading="eager"`** for above-the-fold heroes.
+**`sonic-image`** wraps a responsive `<img>` with aspect ratio, `object-fit: cover`, optional rounded corners and a load transition. The host shows a placeholder background (`--sc-placeholder-bg`) until the file loads. With no `loading`, the image is `lazy`; set `loading="eager"` for above-the-fold images.
 
 ## 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).
+With no `rounded`, corners are square. Boolean `rounded` uses the theme token `--sc-rounded`; `full` draws a circle when paired with `ratio="1/1"`.
 
 <sonic-code>
   <template>
-    <div class="grid gap-6 grid-cols-3  lg:grid-cols-4 items-end text-center text-xs ">
+    <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>
+        <sonic-image ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded="sm" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded="md" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded="lg" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded="xl" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></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>
+        <sonic-image rounded="full" ratio="1/1" src="/img/concorde/plane_04.jpg" alt="Concorde on the apron"></sonic-image>
+        <p class="mt-2">full</p>
       </div>
     </div>
   </template>
@@ -72,70 +43,47 @@ Omit `rounded` for square corners. Boolean **`rounded`** uses the theme token `-
 
 ## Aspect ratio
 
-**`ratio`** sets CSS `aspect-ratio` on the image (default **`auto`**). The image still fills the host width (`width: 100%`).
+`ratio` sets CSS `aspect-ratio` on the image (default `auto`). The image always fills the host width.
 
 <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
-        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
-        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
-        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 src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="16/9" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="1/1" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></sonic-image>
+      <sonic-image ratio="2/3" src="/img/concorde/plane_12.jpg" alt="Concorde at the gate"></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.
+`objectPosition` maps to CSS `object-position` (default `center center`). Use it on wide crops when the subject sits off-center.
 
 <sonic-code>
   <template>
     <div class="grid gap-8 grid-cols-2 items-center">
-      <sonic-image
-        ratio="11/4"
-        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"
-        ratio="11/4"
-        src="https://thegoodlife.fr/wp-content/uploads/sites/2/2022/03/compagnies-aeriennes-nostalgie-coeur-insert-03-dr.jpg"
-      ></sonic-image>
+      <sonic-image ratio="11/4" src="/img/concorde/plane_11.jpg" alt="Concorde flying over a field"></sonic-image>
+      <sonic-image objectPosition="center top" ratio="11/4" src="/img/concorde/plane_11.jpg" alt="Concorde flying over a field"></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.
+`cover` stretches the image over a **positioned** parent (`position: relative` with a height). `ratio` is ignored while `cover` is set.
 
 <sonic-code>
   <template>
     <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>
+      <sonic-image cover src="/img/concorde/plane_10.jpg" alt="Concorde fleet parked in a star"></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.
+Set `transition` to `fade` or `fade-scale-out`. The image stays transparent until the browser fires `load`, then animates in. **Changing `src` on an existing element does not replay the effect**: mount a new `sonic-image` instead (galleries, infinite scroll).
 
 <sonic-code>
   <template>
@@ -150,7 +98,8 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
           img.rounded = 'md';
           img.loading = 'eager';
           img.style.width = '8rem';
-          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
+          img.src = '/img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
           host.appendChild(img);
         })()"
       >
@@ -167,7 +116,8 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
           img.rounded = 'md';
           img.loading = 'eager';
           img.style.width = '8rem';
-          img.src = 'https://picsum.photos/seed/' + Date.now() + '/120/120';
+          var pics = ['01', '03', '04', '05', '06', '07', '08', '09', '10', '11', '12', '13'];
+          img.src = '/img/concorde/plane_' + pics[host.childElementCount % pics.length] + '.jpg';
           host.appendChild(img);
         })()"
       >
@@ -185,17 +135,17 @@ Click **Add image** to append small thumbnails and replay the transition. **Clea
   </template>
 </sonic-code>
 
-## Accessibility and parts
+## Accessibility
 
-Always set meaningful **`alt`** text (empty string only for decorative images). 
+Always set a meaningful `alt`. Use `alt=""` 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"
+      alt="Crowd gathered around Concorde at night"
+      src="/img/concorde/plane_07.jpg"
     ></sonic-image>
   </template>
 </sonic-code>
@@ -205,29 +155,13 @@ Always set meaningful **`alt`** text (empty string only for decorative images).
 | Attribute | Values | Description |
 |----------|---------|-------------|
 | `src` | URL | Image URL passed to `<img src>` |
-| `alt` | string | Accessible description; use `""` only for decorative images |
-| `loading` | `lazy` (default), `eager` | Native lazy loading |
-| `ratio` | CSS ratio, `auto` (default) | Host `aspect-ratio` on the image (ignored when `cover` is set) |
-| `rounded` | `none` (default), boolean, `base`, `sm`, `md`, `lg`, `xl`, `full` | Corner radius from theme tokens; `full` is a circle (often with `ratio="1/1"`) |
-| `objectPosition` | CSS position | Maps to `object-position` (default `center center`) |
-| `imageRendering` | CSS value | Maps to `image-rendering` (default `auto`) |
-| `cover` | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
-| `transition` | `fade`, `fade-scale-out` | Opacity (and scale) animation after `load`; remount to replay on `src` change |
-
-No slots — content is driven entirely by attributes on the inner `<img>`.
-
-## API reference
-
-| Attribute | Values | Description |
-|----------|---------|-------------|
-| `src` | URL | Image URL passed to `<img src>` |
-| `alt` | string | Accessible description; use `""` only for decorative images |
-| `loading` | `lazy` (default), `eager` | Native lazy loading |
-| `ratio` | CSS ratio, `auto` (default) | Host `aspect-ratio` on the image (ignored when `cover` is set) |
-| `rounded` | `none` (default), boolean, `base`, `sm`, `md`, `lg`, `xl`, `full` | Corner radius from theme tokens; `full` is a circle (often with `ratio="1/1"`) |
-| `objectPosition` | CSS position | Maps to `object-position` (default `center center`) |
-| `imageRendering` | CSS value | Maps to `image-rendering` (default `auto`) |
-| `cover` | boolean | Absolutely fills a positioned parent; host aspect ratio is ignored |
-| `transition` | `fade`, `fade-scale-out` | Opacity (and scale) animation after `load`; remount to replay on `src` change |
-
-No slots — content is driven entirely by attributes on the inner `<img>`.
+| `alt` | string | Accessible description; `""` only for decorative images |
+| `loading` | `lazy` (default) · `eager` | Native lazy loading |
+| `ratio` | CSS ratio (default `auto`) | `aspect-ratio` of the image; ignored when `cover` is set |
+| `rounded` | `none` (default) · boolean · `base` · `sm` · `md` · `lg` · `xl` · `full` | Corner radius from theme tokens |
+| `objectPosition` | CSS position (default `center center`) | Maps to `object-position` |
+| `imageRendering` | CSS value (default `auto`) | Maps to `image-rendering` |
+| `cover` | boolean | Absolutely fills a positioned parent |
+| `transition` | `fade` · `fade-scale-out` | Entrance animation after `load`; not replayed on `src` change |
+
+No slots.