ionbase-ui 0.27.0 → 0.29.0

package/dist/meta/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.27.0",
+  "version": "0.29.0",
   "usage": "Pick a component here, then read dist/meta/<Name>.json for its full contract.",
   "hooks": [
     "useToast"
@@ -119,7 +119,7 @@
       "hasIntent": true
     },
     "AvatarGradient": {
-      "summary": "Avatar's initials-only sibling: a lit, bevelled disc in one of eight colours, for people with no photo.",
+      "summary": "Avatar's initials-only sibling: a tinted, bevelled disc in one of seven colours, for people with no photo.",
       "status": "stable",
       "variants": {
         "size": [
@@ -135,8 +135,7 @@
           "pink",
           "orange",
           "green",
-          "red",
-          "light"
+          "red"
         ]
       },
       "detail": "dist/meta/AvatarGradient.json",

package/dist/meta/patterns/index.json

@@ -1,6 +1,6 @@
 {
   "package": "ionbase-ui",
-  "version": "0.27.0",
+  "version": "0.29.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

@@ -1,8 +1,9 @@
 /*
  * Avatar Gradient
  *
- * Measured from Figma `Avatar Gradient` (1054:305). Circle only — the set has
- * no Shape axis, because a gradient this directional does not survive a corner.
+ * 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:
  *
@@ -11,19 +12,24 @@
  *   medium  40   type 16/24 medium
  *   large   48   type 20/32 medium
  *
- * EVERY GRADIENT IS A PAIR ALREADY IN THE PALETTE
+ * IT USED TO BE THE OTHER WAY UP, AND THE CONTRAST GATE IS WHY IT IS NOT
  *
- * `--color-<hue>-500` to `--color-<hue>-600`, and `light` is gray 100 to 200.
- * Nothing here needed a new token, which is worth stating because the opposite
- * would have been the expensive outcome: eight bespoke gradient tokens that
- * Figma owns and this repo could only copy.
+ * 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.
  *
- * The middle stop is the arithmetic midpoint of the two ends, sitting at 60%
- * rather than 50%. That offset is the whole shape of it — a plain two-stop
- * gradient puts the midpoint at 50% and reads flatter. `color-mix` is how the
- * midpoint stays derived from the pair instead of being a third literal, and
- * it is also the only way to write it at all: `color-no-hex` forbids the hex,
- * and there is no token for a value halfway between two tokens.
+ * 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);
@@ -32,19 +38,24 @@
   --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-500);
-  --ion-avatar-gradient-to: var(--color-gray-600);
+  --ion-avatar-gradient-from: var(--color-gray-300);
+  --ion-avatar-gradient-mid: var(--color-gray-200);
+  --ion-avatar-gradient-to: var(--color-gray-50);
 
   /*
-   * White, from the primitive ramp rather than `--text-on-color`.
+   * The initials, from the primitive ramp rather than a semantic text token.
    *
-   * NOT AN OVERSIGHT, AND DO NOT "FIX" IT TO THE SEMANTIC TOKEN. The surface
-   * under this text is built from primitives, so it does not theme; the dark
-   * theme flips `--text-on-color` to black, which would put black initials on
-   * an unchanged mid-blue disc. A foreground has to theme exactly as much as
-   * the background it sits on, and this one sits on a background that does not.
+   * 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-base-white);
+  --ion-avatar-gradient-text: var(--color-gray-600);
 
   /*
    * The sheen: a white radial highlight low and centre, over the linear
@@ -56,28 +67,21 @@
   --ion-avatar-gradient-sheen-mid: 3.6%;
 
   /*
-   * Bevel and lift.
+   * 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 five, which is the same trade
+   * 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.
-   *
-   * All three offsets are derived from the box rather than written four times:
-   * Figma scales the effect with the component, so the arithmetic IS the
-   * design. S/24 and S/12 for the inner shade, S/48 for the top highlight, and
-   * S/16 and S/6 for the drop.
    */
-  --ion-avatar-gradient-elevation:
-    inset 0 calc(-1 * var(--ion-avatar-gradient-size) / 24)
-      calc(var(--ion-avatar-gradient-size) / 12) 0 rgb(0 0 0 / 12%),
-    inset 0 calc(var(--ion-avatar-gradient-size) / 48)
-      calc(var(--ion-avatar-gradient-size) / 48 * 1.4) 0 rgb(255 255 255 / 24%),
-    0 calc(var(--ion-avatar-gradient-size) / 16)
-      calc(var(--ion-avatar-gradient-size) / 6) 0 rgb(13 15 23 / 12%);
+  --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;
@@ -90,13 +94,17 @@
   color: var(--ion-avatar-gradient-text);
 
   /*
-   * The flat colour under the gradient is the `from` end, and that choice is
+   * 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 lightest part of the disc — so it is also the worst
-   * case for white text, which is what makes `verify-contrast` measure the
-   * pairing that actually needs measuring rather than a flattering one.
+   * 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-from);
+  background-color: var(--ion-avatar-gradient-to);
   background-image:
     radial-gradient(
       55.556% 64.103% at 50% 70.513%,
@@ -107,15 +115,10 @@
     linear-gradient(
       180deg,
       var(--ion-avatar-gradient-from) 0%,
-      color-mix(
-          in srgb,
-          var(--ion-avatar-gradient-from),
-          var(--ion-avatar-gradient-to)
-        )
-        60%,
+      var(--ion-avatar-gradient-mid) 60%,
       var(--ion-avatar-gradient-to) 100%
     );
-  box-shadow: var(--ion-avatar-gradient-elevation);
+  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);
@@ -143,10 +146,16 @@
 }
 
 /*
- * The eight colours. Each declares its own `color` and `background-color`
+ * 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,
@@ -156,71 +165,54 @@
 .ion-avatar-gradient--green,
 .ion-avatar-gradient--red {
   color: var(--ion-avatar-gradient-text);
-  background-color: var(--ion-avatar-gradient-from);
+  background-color: var(--ion-avatar-gradient-to);
 }
 
 .ion-avatar-gradient--slate {
-  --ion-avatar-gradient-from: var(--color-gray-500);
-  --ion-avatar-gradient-to: var(--color-gray-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-blue-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-purple-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-pink-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-orange-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-green-600);
+  --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-500);
-  --ion-avatar-gradient-to: var(--color-red-600);
-}
-
-/*
- * Light is the odd one and gets dark text, a stronger sheen and a gentler
- * bevel — Figma halves the shade to 5% and doubles the highlight to 50%,
- * because the same values that read as depth on a saturated disc read as dirt
- * on a near-white one.
- *
- * Its text is `--color-gray-900`, not `--text-default`, for exactly the reason
- * the seven colours use `--color-base-white` rather than `--text-on-color`.
- * The first pass used the semantic token here and the contrast gate caught it
- * in the dark theme at 1.05:1 — `--text-default` themes to near-white while
- * `--color-gray-100` underneath it does not, so the initials disappeared. A
- * foreground has to theme exactly as much as the background it sits on.
- */
-.ion-avatar-gradient--light {
-  --ion-avatar-gradient-from: var(--color-gray-100);
-  --ion-avatar-gradient-to: var(--color-gray-200);
-  --ion-avatar-gradient-text: var(--color-gray-900);
-  --ion-avatar-gradient-sheen: 32%;
-  --ion-avatar-gradient-sheen-mid: 6.4%;
-  --ion-avatar-gradient-elevation:
-    inset 0 calc(-1 * var(--ion-avatar-gradient-size) / 24)
-      calc(var(--ion-avatar-gradient-size) / 12) 0 rgb(0 0 0 / 5%),
-    inset 0 calc(var(--ion-avatar-gradient-size) / 48)
-      calc(var(--ion-avatar-gradient-size) / 48 * 1.4) 0 rgb(255 255 255 / 50%),
-    0 calc(var(--ion-avatar-gradient-size) / 16)
-      calc(var(--ion-avatar-gradient-size) / 6) 0 rgb(13 15 23 / 12%);
-
-  color: var(--ion-avatar-gradient-text);
-  background-color: var(--ion-avatar-gradient-from);
+  --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/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/scroll-progress.css

@@ -1,7 +1,9 @@
 /*
  * Scroll Progress
  *
- * Measured from Figma `Line` / `Progress` / `Progress Heading` (191:927).
+ * Measured from Figma `Line` / `Progress` (191:968) / `Progress Heading`
+ * (191:1021), re-synced August 2026 after the sizes, colours and spacing were
+ * retuned on the canvas.
  *
  * FIGMA SPECIFIES STATES, NOT SCROLL-TRACKING
  *
@@ -13,11 +15,20 @@
  * scrolls, whether the page is one document or many, and how "the active
  * section" is defined are all facts only the consuming app has.
  *
- * TICKS ARE 2px, NOT 1px — MEASURED, NOT A TYPO
+ * TICKS ARE 2px TALL AND 24px WIDE, WITH ROUND ENDS
  *
  * Figma's `Line` stroke is 2, `border-width/thick`, not `/default`. Easy to
  * misread as a mistake since every hairline elsewhere in the system is 1px;
- * checked against the node rather than assumed.
+ * checked against the node rather than assumed. The instances are 24px wide
+ * (`spacing/24`) even though the `Line` component's own frame is still 32 —
+ * the instance override is what renders, and it is what this file follows.
+ * The stroke is `stroke-linecap="round"`, hence `--radius-full`.
+ *
+ * THE PERCENTAGE IS TWO TYPE SIZES, NOT ONE
+ *
+ * The number sits on `type/body-sm` and the `%` sign a rung down on
+ * `type/caption`. It looks like a rendering artefact in the Figma export and
+ * is not — the two spans carry different bound size variables.
  *
  * THE FLYOUT IS A DISCLOSURE, NOT A MENU
  *
@@ -59,25 +70,37 @@
   outline-offset: 2px;
 }
 
+/*
+ * `--text-tertiary` in every state. The rail used to lift to
+ * `--text-secondary` on hover; the retuned `Status=Hover` variant keeps the
+ * percentage tertiary and lets the panel opening be the whole feedback, so
+ * that rule is gone rather than kept as a local invention.
+ */
 .ion-scroll-progress__percent {
   color: var(--text-tertiary);
   font-family: var(--font-family-sans);
   font-size: var(--type-body-sm);
   line-height: var(--type-body-sm-line-height);
-  transition: color var(--ion-duration-base) var(--ion-ease-out);
+  text-align: center;
+}
+
+.ion-scroll-progress__percent-sign {
+  font-size: var(--type-caption);
+  line-height: var(--type-caption-line-height);
 }
 
 .ion-scroll-progress__rail {
   display: flex;
   flex-direction: column;
   align-items: center;
-  gap: var(--spacing-12);
+  gap: var(--spacing-8);
 }
 
 .ion-scroll-progress__tick {
-  width: var(--spacing-32);
+  width: var(--spacing-24);
   height: var(--border-width-thick);
   background-color: var(--border-strong);
+  border-radius: var(--radius-full);
   transition: background-color var(--ion-duration-base) var(--ion-ease-out);
 }
 
@@ -85,22 +108,31 @@
   background-color: var(--border-stronger);
 }
 
-@media (hover: hover) {
-  .ion-scroll-progress__trigger:hover .ion-scroll-progress__percent {
-    color: var(--text-secondary);
-  }
-}
-
-.ion-scroll-progress__trigger[data-hovered='true']
-  .ion-scroll-progress__percent {
-  color: var(--text-secondary);
-}
-
 /*
  * Hidden via visibility + opacity, not `display: none` — the transition needs
  * a property to animate, and `visibility` still pulls the panel's buttons out
  * of tab order and the accessibility tree while closed, same as a native
  * `<details>` collapses its content.
+ *
+ * `width`, not `min-width`: Figma fixes the panel at 220 and truncates each
+ * row rather than letting a long heading widen the flyout — see the ellipsis
+ * on `__heading`.
+ *
+ * CAPPED AT 60vh, THE SAME RUNG AS THE POPOVER BODY
+ *
+ * Figma draws seven rows and stops, because a Figma frame has no viewport to
+ * overflow. A real document index is as long as the document, and an
+ * uncapped centred panel grows off both edges of the screen at once — the
+ * rows a reader most wants are the ones that leave first. `60vh` is not a new
+ * number: `.ion-popover__body` already caps against the viewport at exactly
+ * that, and this is the same problem.
+ *
+ * `overscroll-behavior: contain` matters more here than in most flyouts. This
+ * component reports reading position, so letting a wheel gesture chain into
+ * the document once the list bottoms out would scroll the page — and move the
+ * very percentage the reader opened the panel to act on. Keyboard users are
+ * unaffected either way: the rows are real buttons in tab order, so Tab
+ * scrolls each one into view without touching the wheel.
  */
 .ion-scroll-progress__panel {
   position: absolute;
@@ -109,12 +141,16 @@
   z-index: 10;
   display: flex;
   flex-direction: column;
-  gap: var(--spacing-12);
-  min-width: 220px;
+  gap: var(--spacing-4);
+  width: 220px;
+  max-height: 60vh;
+  overflow-y: auto;
+  overscroll-behavior: contain;
   padding: var(--spacing-8);
   background-color: var(--surface-default);
   border: var(--border-width-default) solid var(--border-default);
   border-radius: var(--radius-md);
+  box-shadow: var(--ion-shadow-shadow-md);
   opacity: 0;
   visibility: hidden;
   pointer-events: none;
@@ -132,39 +168,60 @@
   transform: translateY(-50%) translateX(0);
 }
 
+/*
+ * `display: block`, not `flex`: `text-overflow: ellipsis` does not apply to an
+ * anonymous flex item, so a flex row here would clip the label with no ellipsis
+ * at all. Padding plus the body-sm line height gives Figma's 32px row exactly.
+ *
+ * `flex-shrink: 0` is what makes the panel's `max-height` scroll instead of
+ * squash, and the reason is not obvious. A column flex item is normally
+ * protected from shrinking past its content by the automatic minimum size —
+ * but that protection is dropped for any item whose `overflow` is not
+ * `visible`, and the ellipsis above sets `overflow: hidden` on every row. So
+ * the rows would have compressed toward 0 to fit the cap, and the panel would
+ * never have overflowed at all.
+ */
 .ion-scroll-progress__heading {
-  display: flex;
-  align-items: center;
-  padding: var(--spacing-2) var(--spacing-8);
+  display: block;
+  flex-shrink: 0;
+  width: 100%;
+  padding: var(--spacing-6) var(--spacing-8);
   background-color: transparent;
   border: var(--border-width-default) solid transparent;
   border-radius: var(--radius-md);
-  color: var(--text-secondary);
+  color: var(--text-tertiary);
   font-family: var(--font-family-sans);
   font-size: var(--type-body-sm);
   line-height: var(--type-body-sm-line-height);
   font-weight: var(--font-weight-regular);
   text-align: left;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
   cursor: pointer;
   transition:
     background-color var(--ion-duration-base) var(--ion-ease-out),
-    border-color var(--ion-duration-base) var(--ion-ease-out);
+    border-color var(--ion-duration-base) var(--ion-ease-out),
+    color var(--ion-duration-base) var(--ion-ease-out);
 }
 
 @media (hover: hover) {
   .ion-scroll-progress__heading:hover {
     background-color: var(--surface-muted);
     border-color: var(--border-strong);
+    color: var(--text-default);
   }
 }
 
 .ion-scroll-progress__heading[data-hovered='true'] {
   background-color: var(--surface-muted);
   border-color: var(--border-strong);
+  color: var(--text-default);
 }
 
 .ion-scroll-progress__heading--selected {
   background-color: var(--surface-muted);
+  color: var(--text-secondary);
 }
 
 .ion-scroll-progress__heading:focus-visible {