@stisla/style 3.0.0-beta.8

package/LICENSE

@@ -0,0 +1,9 @@
+MIT License
+
+Copyright (C) 2019 Muhamad Nauval Azhar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

package/README.md

@@ -0,0 +1,16 @@
+# @stisla/style
+
+The framework-agnostic style layer for [Stisla](https://github.com/stisla/stisla): the Tailwind `@theme` foundation (`theme.css`), the per-component BEM CSS source, and a pure-JS class composer. `@stisla/css` is built from this, and the framework wrappers (`@stisla/react`, …) consume the composer.
+
+## Install
+
+```sh
+npm install @stisla/style
+```
+
+```js
+import { composer, button } from "@stisla/style";
+import "@stisla/style/theme.css"; // the @theme foundation — compile with Tailwind v4
+```
+
+Docs and source: https://github.com/stisla/stisla

package/dist/accordion/accordion.css

@@ -0,0 +1,194 @@
+/* @stisla/style — Accordion. Ported from src/scss/components/_accordion.scss. A stack of collapsible
+ * panels: closed items sit transparent on the frame, opening an item raises it as a soft chip
+ * (--color-surface-2 fill + --color-border rim) with a divider between heading and body. State lives
+ * in [data-state="open|closed"] on the item + [aria-expanded] on the trigger. References the @theme
+ * tokens: colors var(--color-*), sizes/spacing --spacing(n), type var(--font-weight-*) /
+ * var(--leading-*), radius var(--radius-*), shadow var(--shadow-*); only no-namespace customs use
+ * --st-* (border-width, duration). Knobs are --accordion-*. The height-transition on open ships with
+ * the JS layer; CSS here shows the resting open/closed states. @layer components.
+ * Authoring rules: ../../../../PORTING.md */
+
+@layer components {
+  /* Geometry — large frame, so radius-lg. With the --spacing(1) wrapper inset the inner item lands
+     at a smaller concentric radius, so the open chip reads like a normal rounded element framed by a
+     softer outer rim. The radius + padding knobs are re-read in the concentric item-radius calc, so
+     their defaults repeat. */
+  .accordion {
+    display: flex;
+    flex-direction: column;
+    gap: var(--accordion-gap, --spacing(1));
+    width: 100%;
+    padding: var(--accordion-padding-block, --spacing(1))
+      var(--accordion-padding-inline, --spacing(1));
+    background-color: var(--accordion-bg, var(--color-surface));
+    border: var(--accordion-border-width, var(--st-border-width)) solid
+      var(--accordion-border-color, var(--color-border));
+    border-radius: var(--accordion-radius, var(--radius-lg));
+    box-shadow: var(--accordion-shadow, var(--shadow-md));
+  }
+
+  /* Item carries a transparent border at rest so the chip-out on open doesn't reflow the row
+     (border-width stays constant in both states). overflow: hidden lets the header background fill
+     the chip without bleeding past the rounded edge while the body is hidden. */
+  .accordion__item {
+    border: var(--st-border-width) solid transparent;
+    border-radius: calc(
+      var(--accordion-radius, var(--radius-lg)) -
+        var(--accordion-padding-inline, --spacing(1))
+    );
+    overflow: hidden;
+    transition:
+      background-color var(--transition-duration-fast) ease,
+      border-color var(--transition-duration-fast) ease;
+  }
+
+  .accordion__item[data-state="open"] {
+    background-color: var(--accordion-item-open-bg, var(--color-surface-2));
+    border-color: var(--accordion-item-open-border-color, var(--color-border));
+  }
+
+  /* The <h3> (or h2/h4…) wrapping the trigger — the section sub-header, present for screen-reader
+     navigation. Pure structural wrapper; the trigger inside owns all the visual treatment. */
+  .accordion__heading {
+    margin: 0;
+  }
+
+  .accordion__trigger {
+    display: flex;
+    align-items: center;
+    gap: --spacing(3);
+    width: 100%;
+    padding-block: var(--accordion-trigger-padding-block, --spacing(3));
+    padding-inline: var(--accordion-trigger-padding-inline, --spacing(4));
+    font: inherit;
+    font-size: var(--accordion-trigger-font-size, inherit);
+    font-weight: var(
+      --accordion-trigger-font-weight,
+      var(--font-weight-medium)
+    );
+    text-align: start;
+    color: var(--accordion-trigger-color, var(--color-foreground));
+    background-color: var(--accordion-trigger-bg, transparent);
+    border: 0;
+    border-bottom: var(--st-border-width) solid transparent;
+    /* Round the top corners to the item radius so the inset focus ring follows the curve instead of
+       being clipped square by the item's overflow: hidden. (Bottom corners round only when the item
+       is closed — see below.) */
+    border-start-start-radius: calc(
+      var(--accordion-radius, var(--radius-lg)) -
+        var(--accordion-padding-inline, --spacing(1))
+    );
+    border-start-end-radius: calc(
+      var(--accordion-radius, var(--radius-lg)) -
+        var(--accordion-padding-inline, --spacing(1))
+    );
+    cursor: pointer;
+    transition:
+      background-color var(--transition-duration-fast) ease,
+      border-color var(--transition-duration-fast) ease;
+  }
+
+  .accordion__trigger :is(svg, i) {
+    width: --spacing(4.5);
+    height: --spacing(4.5);
+    flex-shrink: 0;
+    color: var(--alert-icon-color, var(--color-muted-foreground));
+  }
+
+  .accordion__trigger:focus-visible {
+    outline: 2px solid var(--accordion-ring, var(--color-ring));
+    outline-offset: -2px;
+  }
+
+  .accordion__trigger:disabled {
+    color: var(--color-muted-foreground);
+    cursor: not-allowed;
+  }
+
+  /* Hover paint applies only to closed items — the open chip already signals state via surface-2 +
+     rim + divider, so the open header is removed from the hover cascade entirely. The
+     `> .accordion__heading >` step matches the ARIA heading wrapper and fences scope: a nested
+     accordion inside an open item's body sits deeper, under its own heading, so it won't inherit. */
+  .accordion__item[data-state="closed"]
+    > .accordion__heading
+    > .accordion__trigger:hover:not(:disabled) {
+    background-color: var(--accordion-trigger-bg-hover, var(--color-accent));
+  }
+
+  /* Closed item: the header is the whole chip, so round its bottom corners too (the open header
+     keeps square bottoms where it meets the body) — keeps the focus ring fully rounded. */
+  .accordion__item[data-state="closed"]
+    > .accordion__heading
+    > .accordion__trigger {
+    border-end-start-radius: calc(
+      var(--accordion-radius, var(--radius-lg)) -
+        var(--accordion-padding-inline, --spacing(1))
+    );
+    border-end-end-radius: calc(
+      var(--accordion-radius, var(--radius-lg)) -
+        var(--accordion-padding-inline, --spacing(1))
+    );
+  }
+
+  /* Open item: divider line between the trigger and the body emerges. */
+  .accordion__item[data-state="open"]
+    > .accordion__heading
+    > .accordion__trigger {
+    border-bottom-color: var(
+      --accordion-trigger-divider-color,
+      var(--color-border)
+    );
+  }
+
+  .accordion__icon {
+    flex-shrink: 0;
+    /* Pushed to the end of the trigger row; the title text packs to the start. Auto margin rather
+       than justify-content: space-between, so anything else added groups at the start. */
+    margin-inline-start: auto;
+    width: var(--accordion-icon-size, --spacing(4));
+    height: var(--accordion-icon-size, --spacing(4));
+    color: var(--accordion-icon-color, currentColor);
+    transition: transform
+      var(--accordion-icon-transition-duration, var(--transition-duration-fast)) ease;
+  }
+
+  .accordion__item[data-state="open"]
+    > .accordion__heading
+    > .accordion__trigger
+    > .accordion__icon {
+    transform: rotate(180deg);
+  }
+
+  /* The body is a pure container with no padding — the JS height-transition animates this element,
+     and padding on the animating element causes content reflow during the transition. Padding sits
+     on the inner element so it stays at its natural size while the body clips it via overflow. */
+  .accordion__body {
+    color: var(--accordion-body-color, var(--color-foreground));
+  }
+
+  .accordion__body-inner {
+    padding-block: var(--accordion-body-padding-block, --spacing(3));
+    padding-inline: var(--accordion-body-padding-inline, --spacing(4));
+  }
+
+  /* CSS-only collapse; the JS layer swaps in a measured height transition. */
+  .accordion__item[data-state="closed"] > .accordion__body {
+    display: none;
+  }
+
+  /* === Flush === drop the frame border + shadow so the accordion fades into its parent surface
+     (a card or page section). Root padding stays — items still chip out concentrically when opened;
+     the parent owns inter-block spacing in flush contexts. */
+  .accordion--flush {
+    border: 0;
+    box-shadow: none;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .accordion__item,
+    .accordion__trigger,
+    .accordion__icon {
+      transition: none;
+    }
+  }
+}

package/dist/alert/alert.css

@@ -0,0 +1,138 @@
+/* @stisla/style — Alert. Ported from src/scss/components/_alert.scss. References the Tailwind
+ * @theme tokens (var(--color-*), --spacing(n), var(--text-*) / var(--font-weight-*) /
+ * var(--leading-*), var(--radius-*), --alpha() for tints). Only no-namespace customs use
+ * --st-* (border-width). Tone is REQUIRED for visible chrome. Knobs are --alert-*. @layer components. */
+
+@layer components {
+  .alert {
+    display: flex;
+    align-items: center;
+    gap: --spacing(2.5);
+    width: 100%;
+    min-height: --spacing(11);
+    padding-block: var(--alert-padding-block, --spacing(2.5));
+    padding-inline: var(--alert-padding-inline, --spacing(4));
+    line-height: var(--leading-none);
+    color: var(--alert-color, var(--color-foreground));
+    background: var(--alert-bg, transparent);
+    border: var(--alert-border-width, var(--st-border-width)) solid
+      var(--alert-border-color, transparent);
+    border-radius: var(--alert-radius, var(--radius-md));
+  }
+
+  /* Leading icon: any direct <svg>/<i> child (same convention as .button). */
+  .alert > :is(svg, i) {
+    width: --spacing(4.5);
+    height: --spacing(4.5);
+    flex-shrink: 0;
+    color: var(--alert-icon-color, var(--color-muted-foreground));
+  }
+
+  /* === Parts === */
+  .alert__title {
+    margin: 0;
+    font-size: var(--text-sm);
+    font-weight: var(--font-weight-semibold);
+    line-height: var(--leading-normal);
+    color: var(--color-foreground);
+  }
+  .alert__description {
+    margin: 0;
+    font-size: var(--text-sm);
+    line-height: var(--leading-normal);
+    color: var(--color-muted-foreground);
+  }
+  .alert__action {
+    display: flex;
+    align-items: center;
+    gap: --spacing(1.5);
+    margin-inline-start: auto;
+  }
+  .alert__link {
+    color: var(--alert-link-color, var(--color-primary));
+    font-weight: var(--font-weight-medium);
+    text-decoration: underline;
+    text-underline-offset: 2px;
+  }
+
+  /* === Layout switch — heading + description === */
+  .alert:has(.alert__description) {
+    --alert-padding-block: --spacing(4);
+    display: grid;
+    grid-template-columns: auto 1fr auto;
+    column-gap: --spacing(2.5);
+    row-gap: 0;
+    align-items: start;
+    min-height: 0;
+
+    > :is(svg, i) {
+      grid-column: 1;
+      grid-row: 1;
+      align-self: center;
+    }
+    .alert__title {
+      grid-column: 2;
+      grid-row: 1;
+      line-height: var(--leading-none);
+    }
+    .alert__description {
+      grid-column: 2;
+      grid-row: 2;
+    }
+    .alert__action {
+      grid-column: 3;
+      grid-row: 1 / span 2;
+      align-self: center;
+      margin-inline-start: 0;
+    }
+
+    &:not(:has(> :is(svg, i))) {
+      grid-template-columns: 1fr auto;
+      .alert__title,
+      .alert__description {
+        grid-column: 1;
+      }
+      .alert__action {
+        grid-column: 2;
+      }
+    }
+  }
+
+  /* === Tone modifiers ===
+   * Neutral wears the surface look; intents tint bg 7% + border 40% (via --alpha) and color
+   * the icon + link with the intent. Body text stays --color-foreground. */
+  .alert--neutral {
+    --alert-bg: var(--color-surface);
+    --alert-border-color: var(--color-border);
+  }
+  .alert--primary {
+    --alert-bg: --alpha(var(--color-primary) / 7%);
+    --alert-border-color: --alpha(var(--color-primary) / 40%);
+    --alert-icon-color: var(--color-primary);
+    --alert-link-color: var(--color-primary);
+  }
+  .alert--success {
+    --alert-bg: --alpha(var(--color-success) / 7%);
+    --alert-border-color: --alpha(var(--color-success) / 40%);
+    --alert-icon-color: var(--color-success);
+    --alert-link-color: var(--color-success);
+  }
+  .alert--warning {
+    --alert-bg: --alpha(var(--color-warning) / 7%);
+    --alert-border-color: --alpha(var(--color-warning) / 40%);
+    --alert-icon-color: var(--color-warning);
+    --alert-link-color: var(--color-warning);
+  }
+  .alert--danger {
+    --alert-bg: --alpha(var(--color-danger) / 7%);
+    --alert-border-color: --alpha(var(--color-danger) / 40%);
+    --alert-icon-color: var(--color-danger);
+    --alert-link-color: var(--color-danger);
+  }
+  .alert--info {
+    --alert-bg: --alpha(var(--color-info) / 7%);
+    --alert-border-color: --alpha(var(--color-info) / 40%);
+    --alert-icon-color: var(--color-info);
+    --alert-link-color: var(--color-info);
+  }
+}

package/dist/autocomplete/autocomplete.css

@@ -0,0 +1,193 @@
+/* @stisla/style — Autocomplete. Ported from src/scss/components/_autocomplete.scss + the
+ * form-field-base & menu-* mixins. An <input> that suggests options as the user types (no chips, no
+ * tagging); picking a suggestion replaces the typed text. The field reuses the form-field-base shape
+ * (duplicated here with --autocomplete-*, keep in sync with input/select/textarea) and the popup
+ * reuses the shared menu-surface recipe (expanded inline with --autocomplete-*). References the
+ * @theme tokens: colors var(--color-*), sizes/spacing --spacing(n), type var(--text-*) /
+ * var(--leading-*) / var(--font-weight-*), radius var(--radius-*), shadow var(--shadow-*); only
+ * no-namespace customs use --st-* (border-width, duration, z-index). The popup z-index routes through
+ * the z-index scale (--z-index-dropdown). Keyboard focus is [data-highlighted] (recast from the legacy
+ * is-* class per the no-is-* convention). Knobs are --autocomplete-*. The suggest/filter/select
+ * behavior ships with the JS layer. @layer components. Authoring rules: ../../../../PORTING.md */
+
+@layer components {
+  /* === Field === the form-field-base shape. */
+  .autocomplete {
+    display: block;
+    width: 100%;
+    height: var(--autocomplete-height, --spacing(9));
+    padding-block: var(--autocomplete-padding-block, 0);
+    padding-inline: var(--autocomplete-padding-inline, --spacing(2.5));
+    font-family: inherit;
+    font-size: var(--autocomplete-font-size, var(--text-sm));
+    font-weight: var(--font-weight-normal);
+    line-height: var(--leading-tight);
+    color: var(--autocomplete-color, var(--color-foreground));
+    background-color: var(--autocomplete-bg, var(--color-surface));
+    border: var(--autocomplete-border-width, var(--st-border-width)) solid
+      var(--autocomplete-border-color, var(--color-border-strong));
+    border-radius: var(--autocomplete-radius, var(--radius-md));
+    appearance: none;
+    transition:
+      border-color var(--transition-duration-fast) ease,
+      box-shadow var(--transition-duration-fast) ease,
+      background-color var(--transition-duration-fast) ease;
+
+    /* iOS Safari zooms when a focused field's font-size < 16px and never zooms back. */
+    @media (pointer: coarse) {
+      font-size: var(--autocomplete-font-size, var(--text-base));
+    }
+
+    &::placeholder {
+      color: var(--autocomplete-placeholder, var(--color-muted-foreground));
+      opacity: 1;
+    }
+
+    &:hover:not(:disabled, :focus-visible, [aria-invalid="true"], :user-invalid) {
+      border-color: color-mix(in oklch, var(--color-border-strong) 80%, var(--color-foreground));
+    }
+
+    &:focus-visible {
+      outline: none;
+      border-color: var(--color-primary);
+      box-shadow: 0 0 0 3px color-mix(in oklch, var(--color-ring) 25%, transparent);
+    }
+
+    &[aria-invalid="true"],
+    &:user-invalid {
+      border-color: var(--color-danger);
+    }
+    &[aria-invalid="true"]:focus-visible,
+    &:user-invalid:focus-visible {
+      border-color: var(--color-danger);
+      box-shadow: 0 0 0 3px color-mix(in oklch, var(--color-danger) 25%, transparent);
+    }
+
+    &:disabled {
+      opacity: 0.55;
+      cursor: not-allowed;
+    }
+
+    &[readonly]:not(:disabled) {
+      background-color: var(--color-surface-2);
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+      transition: none;
+    }
+  }
+
+  /* === Popup === the menu-surface recipe, absolutely positioned under the field. */
+  .autocomplete__popup {
+    padding: var(--autocomplete-padding-block, --spacing(1)) var(--autocomplete-padding-inline, --spacing(1));
+    font-size: var(--autocomplete-font-size, var(--text-sm));
+    line-height: var(--leading-normal);
+    color: var(--autocomplete-color, var(--color-foreground));
+    background-color: var(--autocomplete-bg, var(--color-surface));
+    border: var(--autocomplete-border-width, var(--st-border-width)) solid
+      var(--autocomplete-popup-border-color, var(--color-border));
+    border-radius: var(--autocomplete-radius, var(--radius-md));
+    box-shadow: var(--autocomplete-shadow, var(--shadow-md));
+    position: absolute;
+    top: 0;
+    left: 0;
+    z-index: var(--autocomplete-z-index, var(--z-index-dropdown));
+    display: flex;
+    flex-direction: column;
+    gap: var(--autocomplete-item-gap, --spacing(0.5));
+    margin: 0;
+    list-style: none;
+    overflow-y: auto;
+  }
+
+  .autocomplete__popup[hidden] {
+    display: none;
+  }
+
+  /* === Item === the menu-item recipe; gap reset to 0 because search-highlight <mark> splits the
+     label into inline nodes, and a non-zero flex gap would paint whitespace between them. */
+  .autocomplete__item {
+    display: flex;
+    align-items: center;
+    gap: 0;
+    width: 100%;
+    min-height: var(--autocomplete-item-min-height, --spacing(8));
+    padding: var(--autocomplete-item-padding-block, --spacing(0.5))
+      var(--autocomplete-item-padding-inline, --spacing(3));
+    font: inherit;
+    color: var(--autocomplete-color, var(--color-foreground));
+    text-align: start;
+    text-decoration: none;
+    background-color: transparent;
+    border: 0;
+    border-radius: var(
+      --autocomplete-item-radius,
+      calc(var(--autocomplete-radius, var(--radius-md)) - var(--autocomplete-padding-inline, --spacing(1)))
+    );
+    cursor: pointer;
+    user-select: none;
+    transition:
+      background-color var(--transition-duration-fast) ease,
+      color var(--transition-duration-fast) ease;
+  }
+
+  .autocomplete__item:hover,
+  .autocomplete__item[data-highlighted] {
+    color: var(--autocomplete-item-color-hover, var(--color-accent-foreground));
+    background-color: var(--autocomplete-item-bg-hover, var(--color-accent));
+  }
+
+  /* Search match highlight — the JS wraps each matching run in <mark>; just weight, no fill (a box
+     per matched character reads noisy in a list). */
+  .autocomplete__item mark {
+    background: none;
+    color: inherit;
+    font-weight: var(--autocomplete-mark-font-weight, var(--font-weight-semibold));
+  }
+
+  /* Empty / no-results row — a disabled, non-interactive italic item. */
+  .autocomplete__empty {
+    display: flex;
+    align-items: center;
+    gap: 0;
+    width: 100%;
+    min-height: var(--autocomplete-item-min-height, --spacing(8));
+    padding: var(--autocomplete-item-padding-block, --spacing(0.5))
+      var(--autocomplete-item-padding-inline, --spacing(3));
+    font: inherit;
+    color: var(--autocomplete-item-color-disabled, var(--color-muted-foreground));
+    background-color: transparent;
+    border: 0;
+    border-radius: var(
+      --autocomplete-item-radius,
+      calc(var(--autocomplete-radius, var(--radius-md)) - var(--autocomplete-padding-inline, --spacing(1)))
+    );
+    pointer-events: none;
+    cursor: default;
+    font-style: italic;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .autocomplete__item {
+      transition: none;
+    }
+  }
+
+  /* === Sizes (base = md) === */
+  .autocomplete--sm {
+    --autocomplete-radius: var(--radius-sm);
+    --autocomplete-height: --spacing(7);
+    --autocomplete-padding-inline: --spacing(2);
+    --autocomplete-font-size: var(--text-xs);
+    @media (pointer: coarse) {
+      --autocomplete-font-size: var(--text-base);
+    }
+  }
+
+  .autocomplete--lg {
+    --autocomplete-radius: var(--radius-lg);
+    --autocomplete-height: --spacing(11);
+    --autocomplete-padding-inline: --spacing(3.5);
+    --autocomplete-font-size: var(--text-base);
+  }
+}

package/dist/avatar/avatar.css

@@ -0,0 +1,142 @@
+/* @stisla/style — Avatar. Ported from src/scss/components/_avatar.scss. Initials / image / icon in a
+ * rounded-square (or circle) tile, with an optional corner indicator. References the @theme tokens
+ * (colors var(--color-*), spacing/sizes --spacing(n), type var(--text-*) / var(--font-weight-*) /
+ * var(--leading-*), radius var(--radius-*)); only no-namespace customs use --st-* (duration). Knobs
+ * are --avatar-*. Sizes compact/roomy/spacious → sm/lg/xl.
+ *
+ * Image loading: the optional avatar.js preloader writes data-status on the root and CSS reveals the
+ * image only on "loaded". DEFERRED (vanilla-JS pass) — for a known-good static <img>, set
+ * data-status="loaded" inline to reveal it without JS. The pill radius is a literal 9999px (the radius
+ * scale is sm/md/lg only; same precedent as .button--icon-round). @layer components.
+ * Authoring rules: ../../../../PORTING.md */
+
+@layer components {
+  .avatar {
+    position: relative;
+    display: inline-flex;
+    flex-shrink: 0;
+    align-items: center;
+    justify-content: center;
+    width: var(--avatar-size, --spacing(10));
+    height: var(--avatar-size, --spacing(10));
+    font-family: inherit;
+    font-size: var(--avatar-font-size, var(--text-sm));
+    font-weight: var(--avatar-font-weight, var(--font-weight-semibold));
+    line-height: var(--leading-none);
+    color: var(--avatar-color, var(--color-neutral-foreground));
+    background: var(--avatar-bg, var(--color-neutral));
+    border-radius: var(--avatar-radius, var(--radius-md));
+    vertical-align: middle;
+    user-select: none;
+    /* No overflow: hidden on the root — the image clips itself via border-radius + object-fit, so the
+       indicator can translate past the corner without being chopped. Ring is off by default (width 0;
+       .avatar-group turns it on). */
+    box-shadow: 0 0 0 var(--avatar-ring-width, 0) var(--avatar-ring-color, var(--color-background));
+  }
+
+  /* === Image === absolutely positioned over the fallback; hidden until data-status flips to
+   * "loaded" so the fallback paints during idle / loading / error. */
+  .avatar__image {
+    position: absolute;
+    inset: 0;
+    width: 100%;
+    height: 100%;
+    object-fit: cover;
+    border-radius: inherit;
+    opacity: 0;
+    transition: opacity var(--transition-duration-fast) ease-out;
+  }
+
+  .avatar[data-status="loaded"] .avatar__image {
+    opacity: 1;
+  }
+
+  /* === Fallback === sized to the root via the flex parent so it fills cleanly in document flow. */
+  .avatar__fallback {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    width: 100%;
+    height: 100%;
+    border-radius: inherit;
+  }
+
+  /* Inline icons in the fallback scale to its font-size (em-relative, same as .button / .badge). */
+  .avatar__fallback :is(svg, i) {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+  }
+
+  /* === Size modifiers (base = md) === */
+  .avatar--sm {
+    --avatar-size: --spacing(8);
+    --avatar-font-size: var(--text-xs);
+  }
+  .avatar--lg {
+    --avatar-size: --spacing(12);
+    --avatar-font-size: var(--text-base);
+  }
+  .avatar--xl {
+    --avatar-size: --spacing(16);
+    --avatar-font-size: var(--text-xl);
+  }
+
+  /* === Shape === default is rounded square; circle is the modifier. */
+  .avatar--circle {
+    --avatar-radius: 9999px;
+  }
+
+  /* === Indicator === a small pip pinned to a corner (status dot, counter, verified mark). Ring
+   * punches it out of the avatar surface so it reads as a separate object. Default position bottom-end;
+   * the 25% translate lifts it half-out so the ring reads as a clean separator. */
+  .avatar__indicator {
+    position: absolute;
+    bottom: 0;
+    inset-inline-end: 0;
+    transform: translate(25%, 25%);
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--avatar-indicator-size, --spacing(2.5));
+    height: var(--avatar-indicator-size, --spacing(2.5));
+    padding: 0 0.25em;
+    font-size: var(--avatar-indicator-font-size, 0.625rem);
+    font-weight: var(--font-weight-semibold);
+    line-height: var(--leading-none);
+    color: var(--avatar-indicator-color, var(--color-success-foreground));
+    background: var(--avatar-indicator-bg, var(--color-success));
+    border-radius: 9999px;
+    box-shadow: 0 0 0 var(--avatar-indicator-ring-width, 2px)
+      var(--avatar-indicator-ring-color, var(--color-background));
+    z-index: 1;
+  }
+
+  .avatar__indicator :is(svg, i) {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+  }
+
+  /* Position modifier — flip to top-end. (--bottom is the base default, available as explicit markup.) */
+  .avatar__indicator--top {
+    top: 0;
+    bottom: auto;
+    transform: translate(25%, -25%);
+  }
+
+  /* Indicator sizes — pip diameter + font-size retune together so a digit or icon stays legible. The
+     font sizes are a deliberate sub-type-scale micro-progression (kept literal). */
+  .avatar__indicator--sm {
+    --avatar-indicator-size: --spacing(2);
+    --avatar-indicator-font-size: 0.5rem;
+  }
+  .avatar__indicator--lg {
+    --avatar-indicator-size: --spacing(3.5);
+    --avatar-indicator-font-size: 0.625rem;
+  }
+  .avatar__indicator--xl {
+    --avatar-indicator-size: --spacing(4.5);
+    --avatar-indicator-font-size: var(--text-xs); /* 12px — the one pip size with a type token */
+  }
+}