@felloinnovations/brand-kit 0.4.0 → 0.5.0

package/design-system/components/HoverCard/README.md

@@ -0,0 +1,114 @@
+What a chart mark holds, shown on hover or focus: Seth's North chart tip, with a caret on the mark it belongs to.
+
+## Use it when
+
+- A bar, a point, a tick or a square holds more than its mark can say (the week, the count, what it is made of).
+- The person reads a chart by moving across it, and each mark answers as they pass.
+- A short summary should sit by a mark without opening anything (a goal met on a day).
+
+## Not for
+
+- A control's name: use `Tooltip`.
+- Content someone acts on beyond one ask (a field, several acts): use `Popover`.
+- The only place a number lives: what a hover card says must also be reachable without hovering (the chart's own
+  table, a list, or the card on focus and tap).
+- A thing's full detail: use `Panel`.
+
+## Anatomy
+
+- The card (`ws-hover-card`): `--ws-raised` ground, 8 px corners, the 0.5 px hairline and the tip drop
+  (`--ws-shadow-hairline`, `--ws-shadow-tip`), 12 above, 14 at the sides, 10 below. At least 168 wide; it grows with
+  its words up to 440, then a label wraps. 12 px body words. The rhythm is North's:
+- Eyebrow 16 (`ws-hover-card__eyebrow`): an 8 px swatch with 2 px corners (`ws-hover-card__swatch`) and 11 px muted
+  words, 6 apart, 2 above the title.
+- Title 20 (`ws-hover-card__title`): 16 / 20 semibold navy, 8 above the rows.
+- Rows 22 (`ws-hover-card__row`): an 18 px line with 2 above and below; an optional swatch, the label
+  (`ws-hover-card__label`) taking the room, 28 clear of its value (the 8 px gap plus 20 of its own, North's row), the
+  value (`ws-hover-card__value`) navy semibold and tabular.
+  A label that wraps keeps its swatch and value on its first line; a number never wraps.
+- Rule row (`ws-hover-card__row--rule`): a total or the next section, 8 above and 8 below a hairline that runs the
+  card's full width; its label navy medium.
+- Ask foot (`ws-hover-card__foot`): a full-width strip under a hairline, 8 / 14 inside, 12 / 16 medium navy words, its
+  bottom corners the card's; the card drops its own bottom room. 40 tall on touch.
+- Caret (on `--above` and `--below`): an 8 px square turned 45, its two outer edges drawn and only its outer half
+  shown, so the card's edge runs on to the point and nothing inside the card (the foot, its tint, its ring) is covered.
+
+## Variants and sizes
+
+| Class | Look |
+| --- | --- |
+| `ws-hover-card` | The full card: eyebrow, title, rows, rules, foot |
+| `ws-hover-card--compact` | North's point card: 8 / 10 inside, 6 px corners, a 12 / 16 semibold title over an 11 / 13 line (`ws-hover-card__line`), 2 apart |
+| `ws-hover-card--above` | Placed on a mark: the card 8 over the point the chart sets (`left`, `top`), its caret reaching down to it |
+| `ws-hover-card--below` | The same 8 under the point, caret up |
+| `ws-hover-card--start`, `--end` | Near a side, the caret moves to 20% or 80% and the card with it, so it never runs off (North P3) |
+
+## States
+
+- **Hidden**: not drawn; the chart renders it for the mark under the pointer or in focus.
+- **Shown** (North's chart tip, js@484880): it pops out of .9 and 6 px toward its mark (`--ws-rise`), from the
+  caret's corner, on the pop spring (`--ws-spring-pop`, .35 / .1); its parts settle in after it, 45 ms apart
+  (`--ws-stagger-row`), each over `--ws-duration-settle` on `--ws-ease-soft` out of a 3 px blur (`ws-settle`).
+- **Following**: as the pointer moves along a chart it glides to the next mark on the follow spring (.22 / 0, never a
+  bounce), never in jumps. `ws-hover-card--follow` does it in CSS (`--ws-spring-follow` on `left` and `top`) for an app
+  that only sets them; an app that springs it itself (`springs.follow`) leaves the class off.
+- **Grace**: it stays 180 ms (`--ws-hover-grace`) after the pointer leaves its mark, so a gap between bars never
+  flickers it.
+- **Leaving** (`data-leaving`): it fades to .94 and 4 px over `--ws-duration-exit` (120 ms), faster than it came;
+  remove it 120 ms later.
+- **Foot**: hover tints it with the navy wash, and the caret under it with it, so the strip and its point stay one
+  surface; focus draws the ring inside it.
+- **Long label**: wraps; the value stays on the first line.
+
+## Behaviour
+
+- Keyboard: each mark that has a card is focusable (or the chart moves a focus mark with the arrow keys); the card
+  shows for the focused mark. Escape hides it.
+- Pointer: shows on the mark, follows along the chart, stays for the grace.
+- Touch: a tap on a mark shows its card; a tap elsewhere hides it. The foot is 40 tall.
+- Placement: the chart sets `left` and `top` to the point inside its own positioned box; `--start` or `--end` near a
+  side. Inside a box that clips, portal it to the page.
+- Reduced motion: it appears and goes in place; it moves to the next mark at once.
+- The preview's last stack is live: point along the bars.
+
+## Content
+
+- The eyebrow names the mark (the week, the person, the series), with its colour.
+- The title is the mark's one figure, in words if it helps ("26 calls").
+- Rows say what the figure is made of, largest first; a rule row ends with the total or the comparison.
+- The foot asks one question about this mark ("Ask about this week").
+
+## Rules
+
+- Every swatch is the mark's own chart colour; the words stay the word tones (AA on the raised ground).
+- No more than five rows; a longer breakdown belongs in the chart's table.
+- Its words are never the only place the figures live.
+- A card that holds the ask foot (a button) is `role="dialog"` with an `aria-label`, never `role="tooltip"`: a tooltip
+  holds nothing to press. A card with only words (`--compact`) is `role="tooltip"`.
+
+## Source
+
+**Derived from**: Seth's North chart tip (style1.css:208-220: min 168, 12 / 14 / 10, eyebrow 16, title 20 + 8, rows 22,
+full-width rules; :561-562 the ask foot; :386-398 the point card, the caret and the 80% edge anchor; js@484880 the pop,
+follow, grace and the 45 ms row stagger). **Precedent**: new in 0.5.0; the kit's `Tooltip` was a one-line label only.
+
+## Markup
+
+```html
+<div style="position: relative;">
+  <!-- the chart's marks; the card is placed at the open mark's point -->
+  <div class="ws-hover-card ws-hover-card--above" role="dialog" aria-label="Week of 20 October" style="left: 58%; top: 74%;">
+    <span class="ws-hover-card__eyebrow"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--color-text-heading);"></span>Week of 20 October</span>
+    <span class="ws-hover-card__title">26 calls</span>
+    <span class="ws-hover-card__row"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-finished);"></span><span class="ws-hover-card__label">Answered</span><span class="ws-hover-card__value">19</span></span>
+    <span class="ws-hover-card__row"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-under-half);"></span><span class="ws-hover-card__label">Missed</span><span class="ws-hover-card__value">7</span></span>
+    <span class="ws-hover-card__row ws-hover-card__row--rule"><span class="ws-hover-card__label">Team average</span><span class="ws-hover-card__value">31</span></span>
+    <button type="button" class="ws-hover-card__foot">Ask about this week</button>
+  </div>
+</div>
+```
+
+## Styles
+
+`HoverCard/style.css`, built into `bundle.css` and `fello.css`. Tokens only, so it turns dark with the page; the
+swatches take the chart colours through `--ws-hover-card-swatch`.

package/design-system/components/HoverCard/preview.html

@@ -0,0 +1,107 @@
+<!-- @dsCard group="Overlays" height=660 -->
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>HoverCard</title>
+<link rel="stylesheet" href="../../tokens.css">
+<link rel="stylesheet" href="../bundle.css">
+</head>
+<body>
+<div class="ws-stage">
+
+  <div class="ws-stack" style="width: 420px;">
+    <span class="ws-muted">Over a bar: eyebrow, title, rows, a rule row and the ask foot; the caret on the bar's top</span>
+    <div role="group" aria-label="Calls by week, with the week of 20 October open" style="position: relative; height: 320px; border-bottom: var(--ws-line) solid var(--ws-edge-slot);">
+      <span style="position: absolute; bottom: 0; left: 8%; width: 12%; height: 30%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <span style="position: absolute; bottom: 0; left: 30%; width: 12%; height: 40%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <span style="position: absolute; bottom: 0; left: 52%; width: 12%; height: 26%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--color-text-heading);"></span>
+      <span style="position: absolute; bottom: 0; left: 74%; width: 12%; height: 34%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <div class="ws-hover-card ws-hover-card--above" role="dialog" aria-label="Week of 20 October" style="left: 58%; top: 74%;">
+        <span class="ws-hover-card__eyebrow"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--color-text-heading);"></span>Week of 20 October</span>
+        <span class="ws-hover-card__title">26 calls</span>
+        <span class="ws-hover-card__row"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-finished);"></span><span class="ws-hover-card__label">Answered</span><span class="ws-hover-card__value">19</span></span>
+        <span class="ws-hover-card__row"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-under-half);"></span><span class="ws-hover-card__label">Missed</span><span class="ws-hover-card__value">7</span></span>
+        <span class="ws-hover-card__row ws-hover-card__row--rule"><span class="ws-hover-card__label">Team average</span><span class="ws-hover-card__value">31</span></span>
+        <button type="button" class="ws-hover-card__foot">Ask about this week</button>
+      </div>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 420px;">
+    <span class="ws-muted">A point card over a dot; near the right edge its caret moves to 80% so it stays inside</span>
+    <div role="img" aria-label="Replies by day" style="position: relative; height: 180px; border-bottom: var(--ws-line) solid var(--ws-edge-slot);">
+      <span style="position: absolute; left: 30%; top: 70%; width: var(--space-xs); height: var(--space-xs); border-radius: var(--radius-full); background: var(--color-text-heading); translate: -50% -50%;"></span>
+      <div class="ws-hover-card ws-hover-card--compact ws-hover-card--above" role="tooltip" style="left: 30%; top: calc(70% - var(--space-xxs));">
+        <span class="ws-hover-card__title">Tuesday</span>
+        <span class="ws-hover-card__line">4 replies, 2 within the hour</span>
+      </div>
+      <span style="position: absolute; left: 92%; top: 40%; width: var(--space-xs); height: var(--space-xs); border-radius: var(--radius-full); background: var(--color-text-heading); translate: -50% -50%;"></span>
+      <div class="ws-hover-card ws-hover-card--compact ws-hover-card--above ws-hover-card--end" role="tooltip" style="left: 92%; top: calc(40% - var(--space-xxs));">
+        <span class="ws-hover-card__title">Sunday</span>
+        <span class="ws-hover-card__line">1 reply</span>
+      </div>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 420px;">
+    <span class="ws-muted">Below its mark, and at rest beside a chart; a long label wraps, the number never does</span>
+    <div style="position: relative; height: 40px;">
+      <span style="position: absolute; left: 20%; top: 0; width: var(--space-xs); height: var(--space-xs); border-radius: var(--radius-full); background: var(--ws-chart-finished); translate: -50% 0;"></span>
+      <div class="ws-hover-card ws-hover-card--compact ws-hover-card--below ws-hover-card--start" role="tooltip" style="left: 20%; top: var(--space-xs);">
+        <span class="ws-hover-card__title">Goal met on 14 October</span>
+      </div>
+    </div>
+    <div class="ws-hover-card" style="margin-top: var(--space-xl);">
+      <span class="ws-hover-card__eyebrow"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-finished);"></span>October</span>
+      <span class="ws-hover-card__title">82%</span>
+      <span class="ws-hover-card__row"><span class="ws-hover-card__label">Calls answered within five minutes of the lead coming in from Zillow or the website</span><span class="ws-hover-card__value">41 of 50</span></span>
+      <span class="ws-hover-card__row"><span class="ws-hover-card__label">Later</span><span class="ws-hover-card__value">9</span></span>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 420px;" data-live>
+    <span class="ws-muted">Live: point along the bars. The card pops out of .9 on the pop spring, its rows settling in 45 ms apart, then glides from bar to bar on the follow spring (--follow); 180 ms after the pointer leaves it goes, over .12 s</span>
+    <div id="hc-live" role="group" aria-label="Calls by week" style="position: relative; height: 240px; border-bottom: var(--ws-line) solid var(--ws-edge-slot);">
+      <span data-week="Week of 29 September" data-calls="18" data-answered="12" style="position: absolute; bottom: 0; left: 8%; width: 12%; height: 40%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <span data-week="Week of 6 October" data-calls="24" data-answered="17" style="position: absolute; bottom: 0; left: 30%; width: 12%; height: 54%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <span data-week="Week of 13 October" data-calls="15" data-answered="11" style="position: absolute; bottom: 0; left: 52%; width: 12%; height: 34%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--ws-chart-navy-fade);"></span>
+      <span data-week="Week of 20 October" data-calls="26" data-answered="19" style="position: absolute; bottom: 0; left: 74%; width: 12%; height: 60%; border-radius: var(--ws-radius-bar) var(--ws-radius-bar) 0 0; background: var(--color-text-heading);"></span>
+    </div>
+  </div>
+  <script>
+    (() => {
+      const chart = document.getElementById('hc-live');
+      let card = null, leave = 0;
+      const place = (bar) => {
+        const x = parseFloat(bar.style.left) + parseFloat(bar.style.width) / 2;
+        card.style.left = `${x}%`;
+        card.style.top = `${100 - parseFloat(bar.style.height)}%`;
+        card.classList.toggle('ws-hover-card--start', x < 25);
+        card.classList.toggle('ws-hover-card--end', x > 75);
+        card.querySelector('.ws-hover-card__title').textContent = `${bar.dataset.calls} calls`;
+        card.querySelector('[data-words]').textContent = bar.dataset.week;
+        card.querySelector('.ws-hover-card__value').textContent = bar.dataset.answered;
+      };
+      for (const bar of chart.children) bar.addEventListener('pointerenter', () => {
+        clearTimeout(leave);
+        if (!card || card.hasAttribute('data-leaving')) {
+          card?.remove();
+          card = document.createElement('div');
+          card.className = 'ws-hover-card ws-hover-card--above ws-hover-card--follow';
+          card.setAttribute('role', 'tooltip');
+          card.innerHTML = '<span class="ws-hover-card__eyebrow"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--color-text-heading);"></span><span data-words></span></span><span class="ws-hover-card__title"></span><span class="ws-hover-card__row"><span class="ws-hover-card__swatch" style="--ws-hover-card-swatch: var(--ws-chart-finished);"></span><span class="ws-hover-card__label">Answered</span><span class="ws-hover-card__value"></span></span>';
+          place(bar);
+          chart.append(card);
+        } else place(bar);
+      });
+      chart.addEventListener('pointerleave', () => {
+        clearTimeout(leave);
+        leave = setTimeout(() => { const c = card; c?.setAttribute('data-leaving', ''); setTimeout(() => c?.remove(), 120); }, 180);
+      });
+    })();
+  </script>
+
+</div>
+</body>
+</html>

package/design-system/components/HoverCard/style.css

@@ -0,0 +1,59 @@
+/* ---- HoverCard: what a chart mark holds, on hover or focus, Seth's North chart tip (N:209-220): eyebrow 16, title 20 and 8
+   under, rows 22, full-width rules; placed over a mark, a caret points at it ---- */
+/* The card: 12 / 14 / 10 inside, at least 168 wide, 8 px corners, the hairline and the tip drop, 12 px body words. It
+   grows with its words up to the panel width; a label wraps, a number never does. --ws-hover-card-anchor is where the
+   caret sits along its edge (50%, or 20% / 80% near a side, North P3). */
+.ws-hover-card { --ws-hover-card-x: var(--space-sm-plus); --ws-hover-card-anchor: 50%; position: relative; display: flex; flex-direction: column; width: max-content; min-width: calc(var(--space-8xl) + var(--space-xs)); max-width: min(var(--ws-thing-width), calc(100vw - var(--space-xl))); padding: var(--space-sm) var(--ws-hover-card-x) var(--space-xs-plus); border-radius: var(--ws-radius-card); background: var(--ws-raised); box-shadow: var(--ws-shadow-hairline), var(--ws-shadow-tip); font-size: var(--ws-text-dense); line-height: var(--ws-leading-control); color: var(--color-text-body); }
+/* Eyebrow 16: 11 px muted words after an 8 px swatch, 6 apart, 2 above the title. */
+.ws-hover-card__eyebrow { display: flex; align-items: center; gap: var(--space-xxs-plus); margin-bottom: var(--space-3xs); font-size: var(--ws-text-micro); line-height: var(--space-md); color: var(--color-text-muted); }
+.ws-hover-card__swatch { flex-shrink: 0; width: var(--space-xs); height: var(--space-xs); border-radius: var(--ws-radius-chip); background: var(--ws-hover-card-swatch, currentColor); }
+/* Title 20: 16 / 20 semibold navy, 8 above the rows. */
+.ws-hover-card__title { margin-bottom: var(--space-xs); font-size: var(--font-size-md); line-height: var(--ws-leading-row); font-weight: 600; color: var(--color-text-heading); font-variant-numeric: tabular-nums; }
+/* Rows 22: an 18 px line and 2 above and below; the label takes the room and keeps 20 of its own past the 8 px gap, so
+   it ends 28 clear of its value (navy semibold). A label that wraps keeps its swatch and value on its first line. */
+.ws-hover-card__row { display: flex; align-items: flex-start; gap: var(--space-xs); padding-block: var(--space-3xs); }
+.ws-hover-card__row > .ws-hover-card__swatch { margin-block: calc((var(--ws-leading-control) - var(--space-xs)) / 2); }
+.ws-hover-card__label { flex: 1; min-width: 0; padding-right: var(--ws-card-inset); }
+.ws-hover-card__value { flex-shrink: 0; font-weight: 600; color: var(--color-text-heading); font-variant-numeric: tabular-nums; white-space: nowrap; }
+/* A rule row (a total, the next section): 8 above and 8 below a hairline that runs the card's full width. */
+.ws-hover-card__row--rule { margin: var(--space-xxs-plus) calc(var(--ws-hover-card-x) * -1) 0; padding: var(--space-xs) var(--ws-hover-card-x) var(--space-3xs); border-top: var(--ws-hairline) solid var(--ws-edge-card); }
+.ws-hover-card__row--rule .ws-hover-card__label { font-weight: 500; color: var(--color-text-heading); }
+/* The ask foot: a full-width strip under a hairline that asks about this mark; the card drops its own bottom room. */
+.ws-hover-card:has(> .ws-hover-card__foot) { padding-bottom: 0; }
+.ws-hover-card__foot { display: flex; align-items: center; gap: var(--space-xxs-plus); margin: var(--space-xs) calc(var(--ws-hover-card-x) * -1) 0; padding: var(--space-xs) var(--ws-hover-card-x); border: 0; border-top: var(--ws-hairline) solid var(--ws-edge-card); border-radius: 0 0 var(--ws-radius-card) var(--ws-radius-card); background: none; font-size: var(--ws-text-dense); line-height: var(--space-md); font-weight: 500; color: var(--color-text-heading); text-align: left; cursor: pointer; transition: background-color var(--ws-duration-hover) var(--ws-ease-soft); }
+.ws-hover-card__foot:focus-visible { outline-offset: calc(var(--ws-focus-width) * -1); }
+@media (hover: hover) { .ws-hover-card__foot:hover { background: var(--ws-hover); } }
+@media (pointer: coarse) { .ws-hover-card__foot { min-height: var(--ws-touch); } }
+/* --compact: the point card (N:388): 8 / 10 inside, 6 px corners, a 12 px semibold title over an 11 px line, 2 apart. */
+.ws-hover-card--compact { gap: var(--space-3xs); min-width: 0; padding: var(--space-xs) var(--space-xs-plus); border-radius: var(--ws-radius-row); }
+.ws-hover-card--compact .ws-hover-card__title { margin-bottom: 0; font-size: var(--ws-text-dense); line-height: var(--space-md); }
+.ws-hover-card__line { font-size: var(--ws-text-micro); line-height: var(--ws-leading-micro); color: var(--color-text-body); }
+/* Placed on a mark: the chart sets left and top to the point (style), --above lifts the card 8 over it, --below drops it
+   8 under; the caret (an 8 px square turned 45, its two outer edges drawn, clipped to its outer half so it never
+   paints over the foot, its tint or its focus ring) continues the card's edge to the point.
+   --start and --end move the caret to 20% / 80% near a side, so the card never runs off it. */
+.ws-hover-card--above, .ws-hover-card--below { position: absolute; z-index: var(--z-dropdown); }
+.ws-hover-card--above { translate: calc(var(--ws-hover-card-anchor) * -1) calc(-100% - var(--space-xs)); transform-origin: var(--ws-hover-card-anchor) 100%; }
+.ws-hover-card--below { translate: calc(var(--ws-hover-card-anchor) * -1) var(--space-xs); transform-origin: var(--ws-hover-card-anchor) 0; }
+.ws-hover-card--above::after, .ws-hover-card--below::after { content: ""; position: absolute; left: var(--ws-hover-card-anchor); width: var(--space-xs); height: var(--space-xs); background: var(--ws-raised); }
+.ws-hover-card--above::after { top: 100%; border-right: var(--ws-hairline) solid var(--ws-edge-card); border-bottom: var(--ws-hairline) solid var(--ws-edge-card); clip-path: polygon(100% 0, 100% 100%, 0 100%); transform: translate(-50%, calc(var(--ws-nudge) * -1)) rotate(45deg); box-shadow: inset 0 0 0 var(--space-xs) transparent; transition: box-shadow var(--ws-duration-hover) var(--ws-ease-soft); }
+/* Under the ask foot the caret is the foot's own end, so it takes the foot's hover wash with it. */
+@media (hover: hover) { .ws-hover-card--above:has(> .ws-hover-card__foot:hover)::after { box-shadow: inset 0 0 0 var(--space-xs) var(--ws-hover); } }
+.ws-hover-card--below::after { bottom: 100%; border-top: var(--ws-hairline) solid var(--ws-edge-card); border-left: var(--ws-hairline) solid var(--ws-edge-card); clip-path: polygon(0 0, 100% 0, 0 100%); transform: translate(-50%, var(--ws-nudge)) rotate(45deg); }
+.ws-hover-card--start { --ws-hover-card-anchor: 20%; }
+.ws-hover-card--end { --ws-hover-card-anchor: 80%; }
+/* Motion (D7, North's chart tip, js@484880): it pops on the pop spring (.35 / .1, "Tooltip pop-in") from scale .9 and
+   6 px toward its mark, out of the caret's corner, its parts (the foot too) settling in after it 45 ms apart, each over
+   .32 s soft (js@483244) where the browser counts siblings (all at once elsewhere); it leaves over .12 s to scale .94
+   and 4 px, faster. --follow glides it after the pointer on the follow spring (.22 / 0, "Tooltip follows cursor",
+   never a bounce) as the app moves its left and top; leave it off when the app springs it itself. */
+.ws-hover-card { --ws-hover-card-from: var(--ws-rise); --ws-hover-card-to: var(--ws-nudge); }
+.ws-hover-card--below { --ws-hover-card-from: calc(var(--ws-rise) * -1); --ws-hover-card-to: calc(var(--ws-nudge) * -1); }
+@keyframes ws-hover-card-in { from { opacity: 0; transform: translateY(var(--ws-hover-card-from)) scale(0.9); } }
+@keyframes ws-hover-card-out { to { opacity: 0; transform: translateY(var(--ws-hover-card-to)) scale(var(--ws-pop-scale)); } }
+@media (prefers-reduced-motion: no-preference) {
+  .ws-hover-card { animation: ws-hover-card-in var(--ws-spring-pop-duration) var(--ws-spring-pop) backwards; }
+  .ws-hover-card > * { animation: ws-settle var(--ws-duration-settle) var(--ws-ease-soft) backwards; animation-delay: calc((sibling-index() - 1) * var(--ws-stagger-row)); }
+  .ws-hover-card[data-leaving] { animation: ws-hover-card-out var(--ws-duration-exit) var(--ws-ease-exit) forwards; pointer-events: none; }
+  .ws-hover-card--follow { transition: left var(--ws-spring-follow-duration) var(--ws-spring-follow), top var(--ws-spring-follow-duration) var(--ws-spring-follow); }
+}

package/design-system/components/IconButton/README.md

@@ -1,11 +1,13 @@
-A round button holding one icon and nothing else, for an act that needs no words to be understood.
+A square button holding one icon and nothing else, for an act that needs no words to be understood.
 
 ## Use it when
 
-- The act is a single, well-known icon beside other controls (close, mute, edit, remove) where words would crowd the row.
-- The composer's round Send or Talk button, or a header's Mute/End.
-- A card's corner needs a quiet remove or dismiss (`xs`, 24px).
-- A toggle needs to show as a disc (a mic that is listening, a mark that is set): `selected`.
+- The act is a single, well-known icon beside other controls (close, mute, edit, remove, previous, next) where words
+  would crowd the row.
+- A pane's or a card's close (`solid`, Seth's grey square), or a review's Previous and Next.
+- The composer's round Send or Talk (`round`).
+- A card's corner needs a quiet remove or dismiss (`xs`, 24 px).
+- A toggle needs to show it is on (a mic that is listening, a mark that is set): `selected`.
 
 ## Not for
 
@@ -15,50 +17,59 @@ A round button holding one icon and nothing else, for an act that needs no words
 
 ## Anatomy
 
-- A disc: `radius-full` corners, no edge by default.
-- Size: `xs` 24px, `small` 28px (`--ws-control-h-sm`), `medium` 32px (`--ws-control-h`, the default), `large` 36px
-  (`--ws-control-h-md`, the composer's round Send/Talk); every size grows to 40px (`--ws-touch`) on a touch screen.
-- Icon: 16px (`--ws-icon`) inside `small`/`medium`/`xs`, 20px (`--ws-icon-lg`) inside `large`.
+- A square: 6 px corners (`--ws-radius-row`; 4 at `xs`), no edge by default; `round` makes it a disc.
+- Size: `xs` 24, `small` 28 (`--ws-control-h-sm`), `medium` 32 (`--ws-control-h`, the default), `large` 36
+  (`--ws-control-h-md`). On a touch screen every size is a 40 px target: medium and large grow to 40, `xs` and `small`
+  keep their look and gain a 40 px hit area round them.
+- Icon: 16 px navy (`--ws-icon`), 20 px inside `large`.
 - `label` names the act for a screen reader and is its tooltip (never leave it out).
 
 ## Variants and sizes
 
 | Variant | Fill | Edge | Where |
 | --- | --- | --- | --- |
-| `ghost` | transparent, sunk cream on hover | none | the default: a row or header's quiet icon act |
-| `outline` | `--color-bg-page` (cream) | `--ws-shadow-hairline` | an icon act that needs to read as a control at rest |
-| `solid` | `--ws-surface-sunk` | none | an icon act that sits on a card without a hover-only hint |
-| `primary` | `--color-text-heading` (navy), solid | none | the one act of its place as an icon: Send, a shortlist pick |
+| `ghost` | none, the navy wash under the pointer | none | the default: a row's or a header's quiet icon act |
+| `outline` | none | 0.5 px `--ws-edge-card`, drawn inside | an icon act that must read as a control at rest |
+| `solid` | the tray grey (`--ws-tray`, #EDEDED) | none | Seth's close, Previous and Next |
+| `primary` | navy | none | the one act of its place as an icon: Send, a shortlist pick |
+| `round` (with any) | as its variant | as its variant | the composer's voice and send discs |
 
-Sizes: `xs` (24px), `small` (28px), `medium` (32px, default), `large` (36px).
+Sizes: `xs` (24), `small` (28), `medium` (32, default), `large` (36).
 
 ## States
 
 - **Default:** as the table above.
-- **Hover:** `ghost` and `outline` take the sunk cream; `solid` darkens to `--color-gray-2`; `primary` dims to 90%.
-- **Focus:** the kit's focus halo (`--shadow-focus-ring`).
-- **Pressed:** scales to 0.97 and springs back.
-- **Selected:** a toggle that is on (a mic that is listening, a mark that is set) wears `primary`'s navy regardless of its
-  own variant, and carries `aria-pressed="true"`.
-- **Pending:** its answer is on the way. The icon itself pulses on the working beat (`ws-working`, in full colour, never
-  greyed); the button stays focusable (`aria-disabled`) and refuses a second click (`aria-busy="true"`).
-- **Disabled:** 40% opacity, no pointer events.
+- **Hover (a mouse only):** `ghost` takes the navy wash (`--ws-hover-strong`, North's icon button); `outline` darkens its
+  edge (#AAA49D), no fill; `solid` darkens its grey (`--ws-well-hover`); `primary` goes a shade brighter with the light
+  under the pointer.
+- **Focus:** the kit's ring, 2 px navy, 2 px out.
+- **Pressed:** gives to 0.97 (a round one, the voice act, to 0.94, `--ws-press-scale-round`; a send act that wears
+  `ws-press--send` to 0.92, `--ws-press-scale-send`) and springs back, on North's press spring (`--ws-spring-press`, the
+  house's press rule); still under reduced motion.
+- **Selected:** a toggle that is on wears `primary`'s navy whatever its look, with `aria-pressed="true"`. Not for a
+  field's own toggle (a password's eye): that one changes its icon and its label instead.
+- **Pending:** its answer is on the way. The icon breathes on the working beat (`ws-working` on the svg) in full colour;
+  the button stays focusable (`aria-disabled`) and refuses a second press (`aria-busy="true"`); under the pointer it
+  keeps its resting look, so nothing invites the press it refuses.
+- **Pictured states (a preview or a mockup):** `is-hover`, `is-pressed` and `is-focus` draw them still.
+- **Disabled:** 40%, no pointer. A `primary` one sinks instead: the sunk cream with a muted icon, at full opacity.
 - **Empty / loading:** not a state of its own; the icon is always present.
-- **Long label:** not applicable (no visible words); the `label` prop may still be a full sentence for the screen reader.
-- **Narrow:** unaffected by width; it never truncates.
-- **Touch:** every size grows to 40px square.
+- **Long label:** not applicable (no visible words); `label` may still be a full sentence for the screen reader.
+- **Narrow:** unaffected by width; it never shrinks.
+- **Touch:** every size is a 40 px target.
+- **Dark:** the navy icons become the light ink; the tray grey and the hover grey take their dark values.
 
 ## Behaviour
 
 - Keyboard: a normal `<button>`; Enter or Space activates it.
-- Pointer / touch: hover and press as above; 40px touch floor on every size.
-- Motion: background and transform over `--ws-duration-instant` on `--ws-ease-soft`; the pending icon pulses on `--ws-loop`
-  (1.2s). Everything is still under `prefers-reduced-motion: reduce`.
+- Pointer / touch: hover and press as above.
+- Motion: colours over `--ws-duration-hover` on `--ws-ease-soft`, the press on the press spring; the pending icon
+  breathes on `--ws-loop` (1 s). Everything is still under reduced motion.
 
 ## Content
 
-- No visible words; `label` is a short, concrete verb phrase ("Mute", "Edit criteria", "Send"), read by assistive tech and
-  shown as the title.
+- No visible words; `label` is a short, concrete verb phrase ("Mute", "Close", "Previous review"), read by assistive
+  tech and shown as the title.
 - No em dashes in `label`.
 
 ## Props
@@ -68,21 +79,41 @@ Sizes: `xs` (24px), `small` (28px), `medium` (32px, default), `large` (36px).
 | `icon` | `IconName` | which icon it shows |
 | `label` | `string` | what it is called: `aria-label` and its tooltip |
 | `variant` | `'ghost' \| 'outline' \| 'solid' \| 'primary'` | the look, default `ghost` |
-| `size` | `'xs' \| 'small' \| 'medium' \| 'large'` | the disc's size, default `medium` |
+| `size` | `'xs' \| 'small' \| 'medium' \| 'large'` | the size, default `medium` |
+| `round` | `boolean` | a disc instead of a square (voice, send) |
 | `selected` | `boolean` | a toggle that is on: navy fill, `aria-pressed` |
-| `pending` | `boolean` | its answer is on the way: the icon pulses, `aria-busy`, refuses a click |
-| `weight` | `'regular' \| 'bold' \| 'fill'` | the icon's own weight (bold on a navy fill) |
+| `pending` | `boolean` | its answer is on the way: the icon breathes, `aria-busy`, refuses a press |
 | ...rest | native `<button>` props | passed through (`onClick`, `type`, `disabled`, `aria-*`) |
 
 ## Rules
 
-- `pending` keeps the icon in full colour and pulses it (`ws-working`), never greys it out, so waiting never looks broken
-  (the system's rule, 16 Oct 2026).
+- `pending` keeps the icon in full colour and breathes it (`ws-working`), never greys it, so waiting never looks broken
+  (16 Oct 2026).
 - `label` is required: an icon alone is never the only name for an act.
 - The one act of its place as an icon (Send, a shortlist pick) is `primary`, navy, matching `Button`'s one-navy rule.
+- A pane closes with a `solid` square holding an x (Seth's drawer, 301:2021).
+- Square by default (Seth's Fia frames and North both draw squares); `round` only for the voice and send discs.
 
 ## Source
 
-- **Derived from**: the system's control sizing and pending-state rules (`ws-working`, the shared pending pattern with
-  `Button`).
-- **Precedent**: the first product built on the system.
+**Derived from**: Seth's Fia frames: the drawer's close (301:2021) and the review's Previous and Next (313:2941, 313:2944),
+32 px squares with 6 px corners on #EDEDED with 16 px navy icons. Seth's North (style1.css:28-30): square icon buttons
+and their .06 navy hover wash; the round voice button's 0.94 press (app.js). The field's fix (Ignite controls.tsx): the
+disabled navy one sinks. **Precedent**: the first product built on the system.
+
+## Markup
+
+```html
+<button type="button" class="ws-icon-btn ws-icon-btn--solid" aria-label="Close" title="Close">
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8"/></svg>
+</button>
+<button type="button" class="ws-icon-btn ws-icon-btn--lg ws-icon-btn--round ws-icon-btn--primary" aria-label="Talk" title="Talk">
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><rect x="6" y="2" width="4" height="7" rx="2"/><path d="M4 7.5a4 4 0 0 0 8 0M8 13.5V15"/></svg>
+</button>
+```
+
+## Styles
+
+`design-system/components/IconButton/style.css`: `ws-icon-btn` with `--xs`, `--sm`, `--lg`, `--round`, `--outline`,
+`--solid`, `--primary`, and the pictured states `is-hover`, `is-pressed`, `is-focus`. The hover values (`--ws-edge-hover`, `--ws-act-hover`, `--ws-act-light`) are scoped in
+`Button/style.css`; the touch targets come from the house's touch block.