ionbase-ui 0.26.0 → 0.28.0

package/dist/meta/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "usage": "Pick a component here, then read dist/meta/<Name>.json for its full contract.",
   "hooks": [
     "useToast"
@@ -97,11 +97,50 @@
         "shape": [
           "circle",
           "square"
+        ],
+        "topIndicator": [
+          "neutral",
+          "primary",
+          "success",
+          "warning",
+          "error",
+          "information"
+        ],
+        "bottomIndicator": [
+          "neutral",
+          "primary",
+          "success",
+          "warning",
+          "error",
+          "information"
         ]
       },
       "detail": "dist/meta/Avatar.json",
       "hasIntent": true
     },
+    "AvatarGradient": {
+      "summary": "Avatar's initials-only sibling: a tinted, bevelled disc in one of seven colours, for people with no photo.",
+      "status": "stable",
+      "variants": {
+        "size": [
+          "sm",
+          "md",
+          "lg",
+          "mini"
+        ],
+        "color": [
+          "slate",
+          "blue",
+          "violet",
+          "pink",
+          "orange",
+          "green",
+          "red"
+        ]
+      },
+      "detail": "dist/meta/AvatarGradient.json",
+      "hasIntent": true
+    },
     "AvatarGroup": {
       "summary": "Overlapping Avatars with a `+N` overflow, for showing several people in one row's width.",
       "status": "stable",

package/dist/meta/patterns/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "usage": "A pattern is a documented composition of components, not a component. Read one here, then read the contracts of what it composes.",
   "patterns": {
     "DataTable": {

package/dist/styles/avatar-gradient.css

@@ -0,0 +1,218 @@
+/*
+ * Avatar Gradient
+ *
+ * Measured from Figma `Avatar Gradient` (1054:305), re-read after the
+ * 2026-08-28 redesign. Circle only — the set has no Shape axis, because a
+ * gradient this directional does not survive a corner.
+ *
+ * Sizes and the type ramp are Avatar's, including regular weight at Mini:
+ *
+ *   mini    24   type 12/18 regular
+ *   small   32   type 14/20 medium
+ *   medium  40   type 16/24 medium
+ *   large   48   type 20/32 medium
+ *
+ * IT USED TO BE THE OTHER WAY UP, AND THE CONTRAST GATE IS WHY IT IS NOT
+ *
+ * The first version was a saturated disc — `color/<hue>/500` to `/600` — with
+ * white initials. Four of the seven failed WCAG AA at 3.5 to 3.8:1, and the fix
+ * was made in Figma rather than here: the disc is now a pale tint and the
+ * initials carry the colour. Do not "restore" the saturated version. It is not
+ * a style preference that changed.
+ *
+ * THREE RUNGS, THREE TOKENS
+ *
+ *   0%    color/<hue>/300   the deepest tint, at the TOP
+ *   60%   color/<hue>/200
+ *   100%  color/<hue>/50    nearly white, at the bottom
+ *
+ * Every stop is variable-bound in Figma, so all three are real tokens and the
+ * `color-mix` midpoint the old two-rung version needed is gone. Slate is the
+ * gray ramp; every other colour is its own hue at the same three rungs, which
+ * is what makes this a system rather than seven pictures.
+ */
+.ion-avatar-gradient {
+  --ion-avatar-gradient-size: var(--spacing-40);
+  --ion-avatar-gradient-font-size: var(--type-body);
+  --ion-avatar-gradient-line-height: var(--type-body-line-height);
+  --ion-avatar-gradient-font-weight: var(--font-weight-medium);
+
+  /* Slate, which is also the block default — Figma's default variant. */
+  --ion-avatar-gradient-from: var(--color-gray-300);
+  --ion-avatar-gradient-mid: var(--color-gray-200);
+  --ion-avatar-gradient-to: var(--color-gray-50);
+
+  /*
+   * The initials, from the primitive ramp rather than a semantic text token.
+   *
+   * NOT AN OVERSIGHT, AND DO NOT "FIX" IT TO `--text-*`. The disc under this
+   * text is built from primitives, so it does not theme; a semantic foreground
+   * would flip in the dark theme and leave the background alone. An earlier
+   * draft did exactly that and the contrast gate caught it at 1.05:1. A
+   * foreground has to theme exactly as much as the background it sits on.
+   *
+   * In Figma these are bound to a `palette/1`..`palette/7` collection the token
+   * export does not yet cover. Each one resolves to the primitive named here,
+   * so nothing is lost today — see AGENTS.md.
+   */
+  --ion-avatar-gradient-text: var(--color-gray-600);
+
+  /*
+   * The sheen: a white radial highlight low and centre, over the linear
+   * gradient. Identical in proportion at all four sizes — Figma expresses it as
+   * a userSpaceOnUse radial scaled per size, and the ratios come out the same
+   * to three decimals, so it is written once as percentages.
+   */
+  --ion-avatar-gradient-sheen: 18%;
+  --ion-avatar-gradient-sheen-mid: 3.6%;
+
+  /*
+   * Bevel. Two inner shadows and no drop shadow — the redesign dropped the
+   * lift, and these no longer scale with the box the way they did: Figma now
+   * carries the same 1px / -2px offsets at all four sizes.
+   *
+   * A LOCAL, BECAUSE A RAW COLOUR IN A `box-shadow` DECLARATION IS BANNED — and
+   * the ban is right. Its reason is that a raw colour is a place dark mode has
+   * to be fixed by hand, once per occurrence; naming it here makes this file
+   * exactly one such place instead of four, which is the same trade
+   * `elevation.css` makes for the shared ramp. These are local Figma effects,
+   * not effect STYLES, so they are not in that ramp and cannot be: the exporter
+   * only sees named styles, and there is nothing here for it to name.
+   */
+  --ion-avatar-gradient-bevel:
+    inset 0 -2px 4px 0 rgb(0 0 0 / 12%),
+    inset 0 1px 1.4px 0 rgb(255 255 255 / 24%);
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  overflow: hidden;
+  width: var(--ion-avatar-gradient-size);
+  height: var(--ion-avatar-gradient-size);
+  border-radius: var(--radius-full);
+  color: var(--ion-avatar-gradient-text);
+
+  /*
+   * The flat colour under the gradient is the `to` end, and that choice is
+   * load-bearing twice over. It is the fallback if `background-image` never
+   * paints, and it is the palest part of the disc — so it is also the worst
+   * case for the dark initials, which is what makes `verify-contrast` measure
+   * the pairing that actually needs measuring rather than a flattering one.
+   *
+   * It was the `from` end before the redesign, for the same reason read the
+   * other way round: the text was white then, so its worst case was the
+   * lightest stop it sat on. Flip this if the disc is ever inverted again.
+   */
+  background-color: var(--ion-avatar-gradient-to);
+  background-image:
+    radial-gradient(
+      55.556% 64.103% at 50% 70.513%,
+      rgb(255 255 255 / var(--ion-avatar-gradient-sheen)) 0%,
+      rgb(255 255 255 / var(--ion-avatar-gradient-sheen-mid)) 60%,
+      rgb(255 255 255 / 0%) 100%
+    ),
+    linear-gradient(
+      180deg,
+      var(--ion-avatar-gradient-from) 0%,
+      var(--ion-avatar-gradient-mid) 60%,
+      var(--ion-avatar-gradient-to) 100%
+    );
+  box-shadow: var(--ion-avatar-gradient-bevel);
+  font-family: var(--font-family-sans);
+  font-size: var(--ion-avatar-gradient-font-size);
+  line-height: var(--ion-avatar-gradient-line-height);
+  font-weight: var(--ion-avatar-gradient-font-weight);
+  user-select: none;
+}
+
+.ion-avatar-gradient--mini {
+  --ion-avatar-gradient-size: var(--spacing-24);
+  --ion-avatar-gradient-font-size: var(--type-caption);
+  --ion-avatar-gradient-line-height: var(--type-caption-line-height);
+  --ion-avatar-gradient-font-weight: var(--font-weight-regular);
+}
+
+.ion-avatar-gradient--sm {
+  --ion-avatar-gradient-size: var(--spacing-32);
+  --ion-avatar-gradient-font-size: var(--type-body-sm);
+  --ion-avatar-gradient-line-height: var(--type-body-sm-line-height);
+}
+
+.ion-avatar-gradient--lg {
+  --ion-avatar-gradient-size: var(--spacing-48);
+  --ion-avatar-gradient-font-size: var(--type-body-lg);
+  --ion-avatar-gradient-line-height: var(--type-body-lg-line-height);
+}
+
+/*
+ * The seven colours. Each declares its own `color` and `background-color`
+ * rather than inheriting them from the block: the contrast gate pairs what one
+ * rule declares, and a colour it has to find on a different scope resolves
+ * through the cascade to something that never renders together.
+ *
+ * All seven take `600`, including pink. It took `700` here until the 2026-08-28
+ * primitive re-export, and that was not a design choice — the pink ramp shifted
+ * down a rung, so the value this component wants (#c3135c) simply moved from
+ * `700` to `600`. Renaming under a stable name is the failure the token
+ * pipeline is built to catch; it caught this one.
+ */
+.ion-avatar-gradient--slate,
+.ion-avatar-gradient--blue,
+.ion-avatar-gradient--violet,
+.ion-avatar-gradient--pink,
+.ion-avatar-gradient--orange,
+.ion-avatar-gradient--green,
+.ion-avatar-gradient--red {
+  color: var(--ion-avatar-gradient-text);
+  background-color: var(--ion-avatar-gradient-to);
+}
+
+.ion-avatar-gradient--slate {
+  --ion-avatar-gradient-from: var(--color-gray-300);
+  --ion-avatar-gradient-mid: var(--color-gray-200);
+  --ion-avatar-gradient-to: var(--color-gray-50);
+  --ion-avatar-gradient-text: var(--color-gray-600);
+}
+
+.ion-avatar-gradient--blue {
+  --ion-avatar-gradient-from: var(--color-blue-300);
+  --ion-avatar-gradient-mid: var(--color-blue-200);
+  --ion-avatar-gradient-to: var(--color-blue-50);
+  --ion-avatar-gradient-text: var(--color-blue-600);
+}
+
+.ion-avatar-gradient--violet {
+  --ion-avatar-gradient-from: var(--color-purple-300);
+  --ion-avatar-gradient-mid: var(--color-purple-200);
+  --ion-avatar-gradient-to: var(--color-purple-50);
+  --ion-avatar-gradient-text: var(--color-purple-600);
+}
+
+.ion-avatar-gradient--pink {
+  --ion-avatar-gradient-from: var(--color-pink-300);
+  --ion-avatar-gradient-mid: var(--color-pink-200);
+  --ion-avatar-gradient-to: var(--color-pink-50);
+  --ion-avatar-gradient-text: var(--color-pink-600);
+}
+
+.ion-avatar-gradient--orange {
+  --ion-avatar-gradient-from: var(--color-orange-300);
+  --ion-avatar-gradient-mid: var(--color-orange-200);
+  --ion-avatar-gradient-to: var(--color-orange-50);
+  --ion-avatar-gradient-text: var(--color-orange-600);
+}
+
+.ion-avatar-gradient--green {
+  --ion-avatar-gradient-from: var(--color-green-300);
+  --ion-avatar-gradient-mid: var(--color-green-200);
+  --ion-avatar-gradient-to: var(--color-green-50);
+  --ion-avatar-gradient-text: var(--color-green-600);
+}
+
+.ion-avatar-gradient--red {
+  --ion-avatar-gradient-from: var(--color-red-300);
+  --ion-avatar-gradient-mid: var(--color-red-200);
+  --ion-avatar-gradient-to: var(--color-red-50);
+  --ion-avatar-gradient-text: var(--color-red-600);
+}

package/dist/styles/avatar.css

@@ -1,52 +1,116 @@
 /*
  * Avatar
  *
- * Measured from Figma `Avatar` (77:22248) and `Avatar Group`.
+ * Measured from Figma `Avatar` (74:164) and `Avatar Group` (74:279).
  *
- *   mini    24   type 12/18   icon 12   square radius/xs
- *   small   32   type 14/20   icon 16   square radius/sm
- *   medium  40   type 16/24   icon 20   square radius/md
- *   large   48   type 20/32   icon 24   square radius/md
+ *   mini    24   type 12/18 regular   icon 12   square radius/xs
+ *   small   32   type 14/20 medium    icon 16   square radius/sm
+ *   medium  40   type 16/24 medium    icon 20   square radius/md
+ *   large   48   type 20/32 medium    icon 24   square radius/md
  *
  * Circle is radius/full at every size; square steps up with the box, which is
  * concentric-corner arithmetic rather than one shared corner.
  *
- * Surface is surface/muted with a 1px border/strong at every size and type —
- * the border is what separates overlapping avatars in a group, so it is not
- * decoration and must not be dropped.
+ * Two things here were wrong against Figma until the 2026-08-27 re-export, and
+ * both were invisible because they are one token apart from something plausible:
+ *
+ *   Large used `type/h5` (20/28). The style Figma applies is Body/Large
+ *   Emphasis (20/32). Same font-size, four pixels of leading apart.
+ *
+ *   Mini used font-weight/medium. Figma's Mini is the Caption style, which is
+ *   font-weight/regular. Every other size is Emphasis and stays medium.
+ *
+ * Surface and border depend on the Type variant, which is the other correction:
+ * Character and Icon sit on surface/muted behind border/strong, but Image sits
+ * on surface/placeholder behind border/subtle — a photo needs a quieter frame
+ * than an empty box does. The border is what separates overlapping avatars in a
+ * group, so it is not decoration and must not be dropped from either.
+ *
+ * THE ROOT DOES NOT CLIP, AND THAT IS LODAD-BEARING
+ *
+ * `.ion-avatar__media` carries the surface, the border and the `overflow` that
+ * crops the photo. The root carries only geometry. They cannot be the same box:
+ * an indicator sits in a corner that is OUTSIDE a circle's clip path, so a root
+ * that clipped the image would slice the indicator in half. Figma draws it the
+ * same way — an unclipped frame around a clipped `Media` child, with the ring
+ * and the indicators as siblings of it.
  */
 .ion-avatar {
   --ion-avatar-size: var(--spacing-40);
   --ion-avatar-radius: var(--radius-md);
   --ion-avatar-font-size: var(--type-body);
   --ion-avatar-line-height: var(--type-body-line-height);
+  --ion-avatar-font-weight: var(--font-weight-medium);
   --ion-avatar-icon: var(--icon-size-md);
+  --ion-avatar-surface: var(--surface-muted);
+  --ion-avatar-border: var(--border-strong);
+
+  /* Ring and indicator geometry, indexed by size the way everything else is. */
+  --ion-avatar-ring-width: var(--border-width-thick);
+  --ion-avatar-indicator-size: var(--spacing-14);
+
+  /*
+   * 1.5px, and it cannot be a token: the border ladder is 1 / 2 / 4 and Figma
+   * puts a half-step here so the 14px indicator keeps the same visual gap the
+   * 16px one gets from 2px. Written once, as a local, rather than inline —
+   * a raw length in a `border-width` declaration is a theming bug everywhere
+   * else in this system and the lint rule is right to say so.
+   */
+  --ion-avatar-indicator-ring: 1.5px;
+
+  /*
+   * The glyph inside the top indicator: 11 / 10 / 8 / 6 against a 16 / 14 / 12
+   * / 8 dot. Not a ratio and not a rung on the icon ladder — Figma tuned these
+   * four by eye, and the smallest is below anything `--icon-size-*` carries.
+   */
+  --ion-avatar-indicator-icon: 10px;
 
+  position: relative;
   display: inline-flex;
-  align-items: center;
-  justify-content: center;
   flex-shrink: 0;
-  overflow: hidden;
   width: var(--ion-avatar-size);
   height: var(--ion-avatar-size);
-  background-color: var(--surface-muted);
-  border-style: solid;
-  border-width: var(--border-width-default);
-  border-color: var(--border-strong);
   border-radius: var(--ion-avatar-radius);
   color: var(--text-tertiary);
   font-family: var(--font-family-sans);
   font-size: var(--ion-avatar-font-size);
   line-height: var(--ion-avatar-line-height);
-  font-weight: var(--font-weight-medium);
+  font-weight: var(--ion-avatar-font-weight);
   user-select: none;
 }
 
+.ion-avatar__media {
+  position: absolute;
+  inset: 0;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  overflow: hidden;
+  background-color: var(--ion-avatar-surface);
+  border-style: solid;
+  border-width: var(--border-width-default);
+  border-color: var(--ion-avatar-border);
+  border-radius: inherit;
+}
+
+/* Figma's `Type=Image`: a photo gets the placeholder surface and the quiet
+ * border. Applied from `showImage`, not from `src`, so a 404 that falls back
+ * to initials also falls back to the Character variant's frame. */
+.ion-avatar--image {
+  --ion-avatar-surface: var(--surface-placeholder);
+  --ion-avatar-border: var(--border-subtle);
+}
+
 .ion-avatar--mini {
   --ion-avatar-size: var(--spacing-24);
   --ion-avatar-radius: var(--radius-xs);
   --ion-avatar-font-size: var(--type-caption);
   --ion-avatar-line-height: var(--type-caption-line-height);
+  --ion-avatar-font-weight: var(--font-weight-regular);
+  --ion-avatar-ring-width: var(--border-width-default);
+  --ion-avatar-indicator-size: var(--spacing-8);
+  --ion-avatar-indicator-ring: var(--border-width-default);
+  --ion-avatar-indicator-icon: 6px;
 
   /*
    * `2xs`, not `xs` — this is 12 and must stay 12.
@@ -64,21 +128,28 @@
   --ion-avatar-font-size: var(--type-body-sm);
   --ion-avatar-line-height: var(--type-body-sm-line-height);
   --ion-avatar-icon: var(--icon-size-sm);
+  --ion-avatar-ring-width: var(--border-width-default);
+  --ion-avatar-indicator-size: var(--spacing-12);
+  --ion-avatar-indicator-ring: var(--border-width-default);
+  --ion-avatar-indicator-icon: 8px;
 }
 
 /* Large shares Medium's corner — the square ladder stops climbing at radius/md. */
 .ion-avatar--lg {
   --ion-avatar-size: var(--spacing-48);
-  --ion-avatar-font-size: var(--type-h5);
-  --ion-avatar-line-height: var(--type-h5-line-height);
+  --ion-avatar-font-size: var(--type-body-lg);
+  --ion-avatar-line-height: var(--type-body-lg-line-height);
   --ion-avatar-icon: var(--icon-size-lg);
+  --ion-avatar-indicator-size: var(--spacing-16);
+  --ion-avatar-indicator-ring: var(--border-width-thick);
+  --ion-avatar-indicator-icon: 11px;
 }
 
 .ion-avatar--circle {
   --ion-avatar-radius: var(--radius-full);
 }
 
-/* The image fills the box and is cropped by `overflow: hidden` on the parent,
+/* The image fills the box and is cropped by `overflow: hidden` on the media,
  * so it inherits the corner without repeating it. */
 .ion-avatar__image {
   width: 100%;
@@ -99,6 +170,101 @@
   height: var(--ion-avatar-icon);
 }
 
+/*
+ * Ring — Figma's `Show Ring`.
+ *
+ * Drawn INSIDE the avatar's own edge, over the media, at the same size as the
+ * box. Not an `outline` and not a `box-shadow` spread: both of those sit
+ * outside the element and would change the avatar's footprint, which breaks the
+ * group's overlap arithmetic and any layout that measured the avatar. Figma
+ * draws a same-size overlay, so this does too.
+ */
+.ion-avatar__ring {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  border-style: solid;
+  border-width: var(--ion-avatar-ring-width);
+  border-color: var(--surface-primary);
+  border-radius: inherit;
+}
+
+/*
+ * Indicators — Figma's `Show Top Indicator` / `Show Bottom Indicator`, each an
+ * instance of the `Status Indicator` component (1008:1764).
+ *
+ * Both sit flush in a corner: Figma's `left` is size minus indicator at every
+ * size and shape, which is `right: 0`. The border is `ring/offset`, so the dot
+ * reads as separate from the photo underneath it rather than as part of it —
+ * that is why it is a border and not a gap.
+ */
+.ion-avatar__indicator {
+  position: absolute;
+  right: 0;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--ion-avatar-indicator-size);
+  height: var(--ion-avatar-indicator-size);
+  border-style: solid;
+  border-width: var(--ion-avatar-indicator-ring);
+  border-color: var(--ring-offset);
+  border-radius: var(--radius-full);
+}
+
+.ion-avatar__indicator--top {
+  top: 0;
+}
+
+.ion-avatar__indicator--bottom {
+  bottom: 0;
+}
+
+.ion-avatar__indicator svg {
+  width: var(--ion-avatar-indicator-icon);
+  height: var(--ion-avatar-indicator-icon);
+}
+
+/*
+ * The six intents, spelled the same way Badge and Alert spell them. Colour and
+ * surface are declared together per intent rather than hoisted to the block:
+ * the contrast gate pairs what one rule declares, and a foreground it has to
+ * find on a different element resolves to the block's `--text-tertiary` and
+ * measures a pairing that never renders.
+ */
+.ion-avatar__indicator--neutral,
+.ion-avatar__indicator--primary,
+.ion-avatar__indicator--success,
+.ion-avatar__indicator--warning,
+.ion-avatar__indicator--error,
+.ion-avatar__indicator--information {
+  color: var(--text-on-color);
+}
+
+.ion-avatar__indicator--neutral {
+  background-color: var(--surface-inverse);
+}
+
+.ion-avatar__indicator--primary {
+  background-color: var(--surface-primary);
+}
+
+.ion-avatar__indicator--success {
+  background-color: var(--surface-success);
+}
+
+.ion-avatar__indicator--warning {
+  background-color: var(--surface-warning);
+}
+
+.ion-avatar__indicator--error {
+  background-color: var(--surface-error);
+}
+
+.ion-avatar__indicator--information {
+  background-color: var(--surface-information);
+}
+
 /*
  * Avatar Group
  *

package/dist/styles/button.css

@@ -17,16 +17,29 @@
   --ion-button-elevation: var(--ion-shadow-none);
 
   /*
-   * ELEVATION IS INDEXED BY SIZE, NOT BY VARIANT
+   * ELEVATION IS INDEXED BY SIZE; THE VARIANT PICKS THE FAMILY
    *
-   * Measured: Primary Brand, Primary Neutral, Secondary and Destructive all sit
-   * on the same rung at a given size — Small is `xs`, Medium `sm`, Large `lg`.
-   * The variant chooses only the *family* it presses into, so these are slots
-   * the size modifiers reassign and the variants select from. This replaces the
+   * Each of these is a rung reassigned by the size modifiers, and a variant
+   * selects one. That is the whole structure — no variant restates a shadow
+   * value, and no size modifier knows which variant is asking. It replaces the
    * old per-variant `button-raised` / `button-surface` pair, which encoded a
    * distinction Figma no longer draws.
+   *
+   * `raised` and `shadow` are two DIFFERENT rest families, and which one a
+   * variant takes is a real design decision rather than a spelling of the same
+   * idea. `Raised/Lifted` is embossed — two inset highlights that read as a
+   * bevel — and it only works over a solid, saturated fill. `Shadow` is a plain
+   * drop shadow. The two light-surfaced variants, Secondary and Primary Soft,
+   * are on `shadow`; the four solid ones are on `raised`. Measured across all
+   * four sizes of both Figma sets on 2026-08-28.
+   *
+   * The two ramps are not the same shape, which is the trap here. `raised` runs
+   * xs / sm / lg / lg, but `shadow` runs xs / sm / md / md — Large and XLarge
+   * share `Shadow/md`, where the raised family jumps to `lg`. Assuming one ramp
+   * from the other puts Large one rung too heavy.
    */
   --ion-button-raised: var(--ion-shadow-raised-lifted-sm);
+  --ion-button-shadow: var(--ion-shadow-shadow-sm);
   --ion-button-inset-lifted: var(--ion-shadow-inset-lifted-sm);
   --ion-button-inset-flush: var(--ion-shadow-inset-flush-sm);
 
@@ -137,6 +150,7 @@
   --ion-button-font-size: var(--type-body-sm);
   --ion-button-line-height: var(--type-body-sm-line-height);
   --ion-button-raised: var(--ion-shadow-raised-lifted-xs);
+  --ion-button-shadow: var(--ion-shadow-shadow-xs);
   --ion-button-inset-lifted: var(--ion-shadow-inset-lifted-xs);
   --ion-button-inset-flush: var(--ion-shadow-inset-flush-xs);
 }
@@ -149,6 +163,9 @@
   --ion-button-font-size: var(--type-body-md);
   --ion-button-line-height: var(--type-body-md-line-height);
   --ion-button-raised: var(--ion-shadow-raised-lifted-lg);
+
+  /* `md`, not `lg` — the shadow ramp tops out a rung below the raised one. */
+  --ion-button-shadow: var(--ion-shadow-shadow-md);
   --ion-button-inset-lifted: var(--ion-shadow-inset-lifted-lg);
   --ion-button-inset-flush: var(--ion-shadow-inset-flush-lg);
 }
@@ -179,13 +196,15 @@
  * the one rung where the icon does NOT run ahead of its label (24 vs 20, where
  * Large is 24 vs 18). Reproduced as measured.
  *
- * Elevation reuses the `lg` rungs, and this is where "there is no xl rung" would
- * be the easy wrong answer. `Raised/Lifted/xl` and `Raised/Flush/xl` DO exist as
- * effect styles — it is the *inset* families that stop at lg, so there is no
- * complete xl rung to press into. Figma binds Raised/Lifted/lg, Inset/Lifted/lg
- * and Inset/Flush/lg on XLarge exactly as on Large. These three lines restate
+ * Elevation reuses the Large rungs, and this is where "there is no xl rung"
+ * would be the easy wrong answer. `Raised/Lifted/xl` and `Raised/Flush/xl` DO
+ * exist as effect styles — it is the *inset* families that stop at lg, so there
+ * is no complete xl rung to press into. Figma binds Raised/Lifted/lg,
+ * Inset/Lifted/lg and Inset/Flush/lg on XLarge exactly as on Large, and
+ * `Shadow/md` for the two shadow-family variants — also exactly as on Large,
+ * even though `Shadow/lg` and `Shadow/xl` both exist. These four lines restate
  * the inherited defaults on purpose, so the next reader does not have to go and
- * check which half of the family exists.
+ * check which half of each family exists.
  */
 .ion-button--xl {
   --ion-button-size: var(--spacing-56);
@@ -195,6 +214,7 @@
   --ion-button-font-size: var(--type-body-lg);
   --ion-button-line-height: var(--type-body-lg-line-height);
   --ion-button-raised: var(--ion-shadow-raised-lifted-lg);
+  --ion-button-shadow: var(--ion-shadow-shadow-md);
   --ion-button-inset-lifted: var(--ion-shadow-inset-lifted-lg);
   --ion-button-inset-flush: var(--ion-shadow-inset-flush-lg);
 }
@@ -232,9 +252,9 @@
  *
  * HOVER DOES NOT CHANGE ELEVATION — only the surface colour moves. Measured:
  * every Hover variant in Figma carries the same effect style as its Default,
- * across all four elevated types. Reproduced as measured rather than preserved
- * from the old `button-raised-hover` step, which encodes a difference the
- * current design no longer draws.
+ * across all six elevated types and both Figma sets. Reproduced as measured
+ * rather than preserved from the old `button-raised-hover` step, which encodes
+ * a difference the current design no longer draws.
  */
 
 /* Primary Brand Variant */
@@ -314,10 +334,12 @@
  * (secondary). Measured on all four sizes.
  *
  * Elevation presses flush like Secondary, not lifted like Brand — a tinted
- * surface has too little contrast for the lifted inset to register.
+ * surface has too little contrast for the lifted inset to register. It rests on
+ * the `shadow` family for the same reason: the embossed `Raised/Lifted` bevel
+ * needs a solid saturated fill under it, and a subtle tint is not one.
  */
 .ion-button--primary-soft {
-  --ion-button-elevation: var(--ion-button-raised);
+  --ion-button-elevation: var(--ion-button-shadow);
   --ion-button-pressed: var(--ion-button-inset-flush);
 
   background-color: var(--surface-primary-subtle);
@@ -343,9 +365,16 @@
   border-color: var(--border-primary);
 }
 
-/* Secondary Variant — presses flush, losing its lift; brand and destructive keep theirs. */
+/*
+ * Secondary Variant — presses flush, losing its lift; brand and destructive keep
+ * theirs.
+ *
+ * Rests on the `shadow` family, not `raised`. Figma moved it there along with
+ * Primary Soft: both sit on a light surface, and `Raised/Lifted`'s inset
+ * highlight reads as a smudge over white rather than as a bevel.
+ */
 .ion-button--secondary {
-  --ion-button-elevation: var(--ion-button-raised);
+  --ion-button-elevation: var(--ion-button-shadow);
   --ion-button-pressed: var(--ion-button-inset-flush);
 
   background-color: var(--surface-default);

package/dist/styles/index.css

@@ -39,6 +39,7 @@
 @import url('./toggle.css');
 @import url('./menu.css');
 @import url('./avatar.css');
+@import url('./avatar-gradient.css');
 @import url('./header.css');
 @import url('./logo.css');
 @import url('./table.css');