@felloinnovations/brand-kit 0.4.0 → 0.5.0

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

@@ -1,69 +1,127 @@
-A name on hover or keyboard focus, for a control that shows less than it is: an icon, a circle of initials.
+A name on hover or keyboard focus, for a control that shows less than it is; and Seth's navy note, the full words behind a short one.
 
 ## Use it when
 
-- An icon-only button's accessible name should also be visible to a sighted pointer or keyboard user ("Close", "Ask about this").
-- A circle of initials or a small mark needs its full name available without taking permanent space.
+- An icon-only button's name should also show to a sighted pointer or keyboard user ("Refresh the audit").
+- A short word stands for longer words that some people want to read (a question cut to "A buyer"): the note.
 
 ## Not for
 
-- A control's only label: the tip is for the eyes only; the same words must already be the control's `aria-label`, since a touch screen never shows a tip at all.
-- A brief confirmation that something happened: use a toast.
-- Extra detail someone opts into reading: use `Fold`.
-- A native `title` attribute alongside it: the component replaces that, it does not sit beside it.
+- The only way to know what a control does on touch: a touch screen never shows a plain tip, so the icon must read on
+  its own.
+- What a chart mark holds (a title, figures, rows): use `HoverCard`.
+- Content someone acts on (a field, a link): use `Popover`.
+- A receipt for something that happened: use `Toast`.
+- A native `title` beside it: this replaces that.
 
 ## Anatomy
 
-- A small card above the control: `--ws-radius-card` (8 px) corners, the cream (`--color-bg-page`) background, the fine hairline edge plus the lifted shadow (`--ws-shadow-hairline`, `--ws-shadow-lift`).
-- `--space-xs` (8 px) padding, `--space-xxs` (4 px) gap from the control below it.
-- Its words: 12 px semibold, navy (`--color-text-heading`), truncated to one line up to `--ws-thing-width`.
-- Positioned above the control (`bottom: 100%`), aligned to the control's centre by default, or flush to its start or end edge when centring would run off the side of its container.
+- The wrapper (`ws-tooltip`): an inline box around the control, which the tip is placed against.
+- The tip (`ws-tooltip__tip`): North's compact tip. `--ws-raised` ground, 6 / 10 inside, 6 px corners
+  (`--ws-radius-row`), the 0.5 px hairline and the tip drop (`--ws-shadow-hairline`, `--ws-shadow-tip`), 12 / 16
+  semibold navy words on one line; a longer name wraps at 440 (or the window less 32) and is never cut. 8 above its control (`--ws-tooltip-gap`), centred on it.
+- The note (`ws-tooltip--note`, Seth 305:2272): the act's navy (`--ws-inverse`, words `--ws-on-inverse`), the brand navy in dark, 4 px corners, 10 / 12
+  inside, 14 / 20 regular white words that wrap at 300 (12.71:1), no shadow (in dark, a faint light rim). Its words start where the word
+  it explains starts (its 12 px padding hangs to the left). A 12 x 6 caret points down at that word's middle, 4 above
+  it; the note sits 10 above.
+- The term (`ws-tooltip__term`): the word the note explains, a button with a 1 px dotted underline 4 under the words,
+  the cue that more shows. On touch its hit area is 24 tall while its words keep the line, so a term inside a sentence
+  stays on the sentence's baseline.
 
 ## Variants and sizes
 
-| `align` | Behaviour |
+| Class | Where |
 | --- | --- |
-| `center` (default) | Centred over the control |
-| `start` | Grows to the right of the control's left edge |
-| `end` | Grows to the left of the control's right edge |
+| `ws-tooltip` | Centred, above |
+| `ws-tooltip--below` | Under the control |
+| `ws-tooltip--start` | Flush to the control's left edge, for a control near the left of its container |
+| `ws-tooltip--end` | Flush to its right edge (with the note, its words end where the word ends) |
+| `ws-tooltip--note` | Seth's navy note with its caret, left-anchored |
+| `ws-tooltip--note ws-tooltip--below` | The note under its term, the caret turned up, for a term near the top of its card |
+| `ws-tooltip--open` | Shown, whatever the pointer does (a tap toggle, or a preview) |
+| `ws-tooltip--dismissed` | Hidden after Escape, even while hovered or focused |
 
 ## States
 
-- **Hidden** (default): opacity 0, not interactive, present for layout timing only.
-- **Shown on hover**: after a short pause under the pointer (the hover delay is `--ws-duration-instant` once the pointer has settled), opacity 1.
-- **Shown on focus**: appears at once when the control inside gets keyboard focus (`:focus-visible`), never on a click's own focus.
-- **Never on touch**: there is no hover on a touch screen, so the tip never appears there; the control's own accessible name must carry the meaning on its own.
+- **Hidden** (default): not shown, takes no presses; still read: a plain tip names its control (`aria-labelledby`), a
+  note describes its term (`aria-describedby`).
+- **Hover**: shown once the pointer has rested 40 ms (`--ws-hover-intent`); only for pointers that hover. A bridge
+  over the 8 px gap keeps it while the pointer moves onto it.
+- **Keyboard focus**: shown at once when the control has `:focus-visible`, never on a click's own focus.
+- **Tap**: the note toggles on a tap (`ws-tooltip--open`); a plain tip never shows on touch.
+- **Opening** (North's "Tooltip pop-in", js@484880): it pops out of .9 and 4 px toward its control, growing from the
+  edge it hangs from, on the pop spring (`--ws-spring-pop`, .35 / .1, 500 ms to rest); the note's caret pops with it.
+- **Leaving**: it fades off over 180 ms (North's tip fade, css:388; `--ws-tooltip-out`) on `--ws-ease-exit`, faster
+  than it came.
 
 ## Behaviour
 
-- Keyboard: shows immediately when the control inside receives visible keyboard focus; disappears when focus moves on.
-- Pointer: shows after a brief hover delay, disappears when the pointer leaves.
-- Touch: never shown; nothing to tap to reveal it.
-- Motion: opacity fades in over `--ws-duration-instant` (120 ms) on `--ws-ease-soft`; the hover case adds the same duration as a delay before it starts.
-- Reduced motion: the fade itself is a plain opacity change already quick enough to keep as is; no separate reduced-motion branch is needed.
+- Keyboard: shows on visible focus, goes when focus moves on. Escape hides it where it is (WCAG 1.4.13): a few lines
+  of script add `ws-tooltip--dismissed` on Escape and take it off when the pointer or focus leaves.
+- Pointer: shows after the hover intent, stays while the pointer is on the control, the gap or the tip.
+- Touch: the plain tip never shows; the note opens on a tap of its term and closes on a second tap or a tap outside.
+- The note hangs from its term's start (or its end, `--end`) and never moves itself onto the screen: a term away from
+  both edges of a phone gets its place from the app (Floating UI `shift`), or the note runs past the edge.
+- Where the browser places by anchor (CSS anchor positioning), the tip is fixed to its wrapper as its anchor, so no
+  scroller, card or stage that clips can cut it (K9): a tip on AppShell's bar or its body's first row shows whole. A
+  plain tip with no room on its side turns to the other one (above to below) or slides along its control to stay on the
+  screen; the note keeps its side. Without anchor placement, inside a scroller or a card that clips, render the tip in a
+  portal (Radix `Tooltip` with its container on a `class="fello"` root in a scoped app), or it is cut.
+- Reduced motion: it simply appears and goes; so does a browser without `linear()`.
+- The preview's last stack is live: point at or tab to each.
 
 ## Content
 
-- The same short name as the control's own `aria-label`, never different words: the tip is a visible echo of the accessible name, not a second source of truth.
-- One line, no em dash, sentence case for a phrase ("Ask about this"), title case only for a proper name.
+- A plain tip is the control's name: the control points at it with `aria-labelledby` and has no `aria-label` of its
+  own, so the words live in one place and are read once.
+- One line, sentence case ("Ask about this").
+- A note holds the full words the term stands for, as they were written, up to three lines.
 
 ## Props
 
 | Name | Type | Meaning |
 | --- | --- | --- |
-| `label` | `ReactNode` | The name shown in the tip. |
-| `align` | `"center"` \| `"start"` \| `"end"` | Where it sits relative to the control. Default `center`. |
+| `label` | `ReactNode` | The words shown in the tip. |
+| `align` | `"center"` \| `"start"` \| `"end"` | Where it sits along the control. Default `center`. |
+| `side` | `"above"` \| `"below"` | Which side it opens on. Default `above`. |
+| `note` | boolean | Seth's navy note with a caret. |
 | `className` | string | Layout only. |
-| `children` | `ReactNode` | The control the tip names. |
+| `children` | `ReactNode` | The control (or the term) the tip names. |
 
 ## Rules
 
-- The tip is for the eyes: the same words always sit in the control's own `aria-label` too, so a screen reader and a touch user get the name regardless.
-- No native `title` beside it: `Tip` is the one way to show a name on hover in this system.
-- Shows at once on keyboard focus, never only after a delay the way hover does: a keyboard user should not have to wait to learn what a button is.
-- **Contradiction found, not resolved**: a brief for this preview once asked for "a small navy tip above a control, 12 px white words, 4 px corners." The actual, and only, tooltip in the reference implementation is the opposite: a small cream card with navy 12 px semibold words and 8 px corners, lifted with the hairline and lift shadows. This README and preview follow the source, since code is truth; the navy-with-white-words version does not exist anywhere in the product.
+- The plain tip names its control (`aria-labelledby`); never an `aria-label` and an `aria-describedby` to the same
+  words, which a screen reader reads twice.
+- Shows at once on keyboard focus: a keyboard user never waits to learn what a button is.
+- No hover-only content: the note also opens on focus and on a tap (14-accessibility.md).
+- The note is navy (Seth, 305:2272). It resolves the old open question about a navy tip: the label tip stays the light
+  card, the note is navy.
 
 ## Source
 
-**Derived from**: the system's cream-card, hairline-plus-lift surface treatment, with navy 12 px semibold words.
-**Precedent**: the first product built on the system.
+**Derived from**: North's compact tip and its placement (style1.css:386-398, :484-486: 6 px corners, 8 to 10 from its
+mark, edge-flush near a side, the tip drop; js@484880: pop from .94 and 4 px, 120 ms exit), Seth's note (Figma
+305:2272: navy, 4 px corners, 10 / 12, 14 / 20, 300 wide, 12 x 6 caret over the word, left-anchored) and the field
+fix (hidden until hover or focus, start and end placement; Ignite Tip.tsx). **Precedent**: the first product built on
+the system.
+
+## Markup
+
+```html
+<span class="ws-tooltip">
+  <span class="ws-tooltip__tip" role="tooltip" id="tip-refresh">Refresh the audit</span>
+  <button type="button" class="ws-icon-btn" aria-labelledby="tip-refresh">
+    <svg viewBox="0 0 16 16" fill="none"><path d="M13 8a5 5 0 1 1-1.5-3.5M13 3v2.5h-2.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+  </button>
+</span>
+
+<span class="ws-tooltip ws-tooltip--note">
+  <span class="ws-tooltip__tip" role="tooltip" id="note-buyer">I'm thinking of buying a home in Chagrin Falls, OH. Which real estate agent or team should I talk to?</span>
+  <button type="button" class="ws-tooltip__term" aria-describedby="note-buyer" onclick="this.parentElement.classList.toggle('ws-tooltip--open')">A buyer</button>
+</span>
+```
+
+## Styles
+
+`Tooltip/style.css`, built into `bundle.css` and `fello.css`. Tokens only, so it turns dark with the page (the note
+keeps the brand navy and white words, with a faint light rim, D12).

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

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Overlays" height=128 -->
+<!-- @dsCard group="Overlays" height=340 -->
 <!doctype html>
 <html>
 <head>
@@ -8,24 +8,78 @@
 <link rel="stylesheet" href="../bundle.css">
 </head>
 <body>
-<div class="ws-stage ws-stage--grey" style="justify-content: center;">
+<div class="ws-stage ws-stage--grey">
 
-  <div class="ws-cluster ws-cluster--start" style="gap: var(--space-xl);">
-    <div class="ws-stack" style="gap: var(--space-xl); align-items: center;">
-      <span class="ws-muted">Shown above an icon button</span>
-      <span class="ws-tooltip">
-        <span class="ws-tooltip__tip" role="tooltip" id="tip-1">Ask about this</span>
-        <button type="button" class="ws-icon-btn" aria-label="Ask about this" aria-describedby="tip-1">
-          <svg viewBox="0 0 16 16" fill="none"><path d="M6 6a2 2 0 1 1 3 1.7c-.6.4-1 .9-1 1.6v.4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="8" cy="12" r="0.75" fill="currentColor"/></svg>
-        </button>
-      </span>
-    </div>
+  <div class="ws-stack" style="width: 160px; gap: var(--space-3xl); align-items: center;">
+    <span class="ws-muted">Centred, 8 above its control</span>
+    <span class="ws-tooltip ws-tooltip--open">
+      <span class="ws-tooltip__tip" role="tooltip" id="tip-centre">Ask about this</span>
+      <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-centre">
+        <svg viewBox="0 0 16 16" fill="none"><path d="M6 6a2 2 0 1 1 3 1.7c-.6.4-1 .9-1 1.6v.4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="8" cy="12" r="0.75" fill="currentColor"/></svg>
+      </button>
+    </span>
+  </div>
 
-    <div class="ws-stack" style="gap: var(--space-xl); align-items: center;">
-      <span class="ws-muted">At rest, no tip</span>
-      <button type="button" class="ws-icon-btn" aria-label="Search">
+  <div class="ws-stack" style="width: 160px; gap: var(--space-3xl); align-items: center;">
+    <span class="ws-muted">At rest, nothing shows</span>
+    <span class="ws-tooltip">
+      <span class="ws-tooltip__tip" role="tooltip" id="tip-rest">Search</span>
+      <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-rest">
         <svg viewBox="0 0 16 16" fill="none"><circle cx="7" cy="7" r="4.5" stroke="currentColor" stroke-width="1.5"/><path d="M13 13l-2.5-2.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
       </button>
+    </span>
+  </div>
+
+  <div class="ws-stack" style="width: 160px; gap: var(--space-3xl); align-items: flex-start;">
+    <span class="ws-muted">Near the left edge: flush to the start</span>
+    <span class="ws-tooltip ws-tooltip--start ws-tooltip--open">
+      <span class="ws-tooltip__tip" role="tooltip" id="tip-start">Refresh the audit</span>
+      <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-start">
+        <svg viewBox="0 0 16 16" fill="none"><path d="M13 8a5 5 0 1 1-1.5-3.5M13 3v2.5h-2.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+      </button>
+    </span>
+  </div>
+
+  <div class="ws-stack" style="width: 160px; padding-bottom: var(--space-2xl); align-items: flex-end;">
+    <span class="ws-muted">Near the right edge: below, flush to the end</span>
+    <span class="ws-tooltip ws-tooltip--end ws-tooltip--below ws-tooltip--open">
+      <span class="ws-tooltip__tip" role="tooltip" id="tip-end">Settings</span>
+      <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-end">
+        <svg viewBox="0 0 16 16" fill="none"><path d="M8 2v2M8 12v2M3 8H1M15 8h-2M4 4l1.4 1.4M10.6 10.6L12 12M4 12l1.4-1.4M10.6 5.4L12 4" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/><circle cx="8" cy="8" r="2.5" stroke="currentColor" stroke-width="1.5"/></svg>
+      </button>
+    </span>
+  </div>
+
+  <div class="ws-stack" style="width: 360px; gap: var(--space-6xl);">
+    <span class="ws-muted">The note: the full words behind a short one, a caret on its middle</span>
+    <div class="ws-row__title" style="padding: 0 0 var(--space-md) var(--space-md);">
+      <span class="ws-tooltip ws-tooltip--note ws-tooltip--open">
+        <span class="ws-tooltip__tip" role="tooltip" id="note-buyer">I'm thinking of buying a home in Chagrin Falls, OH. Which real estate agent or team should I talk to?</span>
+        <button type="button" class="ws-tooltip__term" aria-describedby="note-buyer">A buyer</button>
+      </span>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 360px; padding-bottom: var(--space-5xl);">
+    <span class="ws-muted">Near the top of its card the note opens below, its caret turned up; in a sentence the term keeps the line</span>
+    <p class="ws-body" style="padding-left: var(--space-md);"><span class="ws-tooltip ws-tooltip--note ws-tooltip--below ws-tooltip--open"><span class="ws-tooltip__tip" role="tooltip" id="note-seller">I'm thinking of selling my home in Chagrin Falls, OH. Who should I list it with?</span><button type="button" class="ws-tooltip__term" aria-describedby="note-seller">A seller</button></span> asked it on Nov 2, and twice more after.</p>
+  </div>
+
+  <div class="ws-stack" style="width: 360px; gap: var(--space-3xl);" data-live>
+    <span class="ws-muted">Live: point at or tab to each. The tip pops out of .9 on the pop spring after the 40 ms hover intent and fades off over 180 ms; the note pops with its caret</span>
+    <div class="ws-cluster" style="gap: var(--space-xl);">
+      <span class="ws-tooltip">
+        <span class="ws-tooltip__tip" role="tooltip" id="tip-live-1">Search</span>
+        <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-live-1"><svg viewBox="0 0 16 16" fill="none"><circle cx="7" cy="7" r="4.5" stroke="currentColor" stroke-width="1.5"/><path d="M13 13l-2.5-2.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg></button>
+      </span>
+      <span class="ws-tooltip">
+        <span class="ws-tooltip__tip" role="tooltip" id="tip-live-2">Refresh the audit</span>
+        <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-labelledby="tip-live-2"><svg viewBox="0 0 16 16" fill="none"><path d="M13 8a5 5 0 1 1-1.5-3.5M13 3v2.5h-2.5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></button>
+      </span>
+      <span class="ws-tooltip ws-tooltip--note">
+        <span class="ws-tooltip__tip" role="tooltip" id="note-live">Asked by people who want to buy a home here.</span>
+        <button type="button" class="ws-tooltip__term" aria-describedby="note-live">A buyer</button>
+      </span>
     </div>
   </div>
 

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

@@ -0,0 +1,78 @@
+/* ---- Tooltip: a control's name on hover or keyboard focus, North's compact tip; --note is Seth's navy note with a caret
+   over the word it explains (305:2272) ---- */
+/* The tip: 6 / 10 inside, 6 px corners, the hairline and the tip drop, 12 px semibold navy on one line (a longer name
+   wraps at 440, or the window less 32, and is never cut), 8 above its control and centred on it. Hidden until the control is hovered (after the 40 ms hover intent) or takes keyboard
+   focus (at once); never on a tap, so the control's own name must carry the meaning. --open shows it (a tap toggle,
+   or a preview). The bridge (::before) keeps it while the pointer crosses the gap, so it can be hovered. */
+.ws-tooltip { --ws-tooltip-gap: var(--space-xs); --ws-tooltip-from: var(--ws-nudge); position: relative; display: inline-flex; vertical-align: top; }
+.ws-tooltip::before { content: ""; position: absolute; right: 0; bottom: 100%; left: 0; height: var(--ws-tooltip-gap); pointer-events: none; }
+.ws-tooltip__tip { position: absolute; bottom: calc(100% + var(--ws-tooltip-gap)); left: 50%; z-index: var(--z-dropdown); width: max-content; max-width: min(var(--ws-thing-width), calc(100vw - var(--space-xl))); padding: var(--space-xxs-plus) var(--space-xs-plus); border-radius: var(--ws-radius-row); background: var(--ws-raised); box-shadow: var(--ws-shadow-hairline), var(--ws-shadow-tip); font-size: var(--ws-text-dense); line-height: var(--space-md); font-weight: 600; color: var(--color-text-heading); white-space: normal; text-wrap: balance; translate: -50% 0; transform-origin: bottom center; opacity: 0; visibility: hidden; pointer-events: none; }
+@media (hover: hover) {
+  .ws-tooltip:hover::before { pointer-events: auto; }
+  .ws-tooltip:hover > .ws-tooltip__tip { opacity: 1; visibility: visible; pointer-events: auto; }
+}
+.ws-tooltip--open > .ws-tooltip__tip, .ws-tooltip:has(:focus-visible) > .ws-tooltip__tip { opacity: 1; visibility: visible; pointer-events: auto; }
+/* Placement: --below under the control; --start and --end flush to its left or right edge, for a control near the
+   side of its container. */
+.ws-tooltip--below { --ws-tooltip-from: calc(var(--ws-nudge) * -1); }
+.ws-tooltip--below::before { top: 100%; bottom: auto; }
+.ws-tooltip--below > .ws-tooltip__tip { top: calc(100% + var(--ws-tooltip-gap)); bottom: auto; transform-origin: top center; }
+.ws-tooltip--start > .ws-tooltip__tip { left: 0; translate: none; transform-origin: bottom left; }
+.ws-tooltip--end > .ws-tooltip__tip { right: 0; left: auto; translate: none; transform-origin: bottom right; }
+/* The note (Seth, 305:2272): the brand navy with white words in both themes (D12; in dark the float rim, a faint light
+   line, is its only shadow), 4 px corners, 10 / 12 inside, 14 / 20 words that wrap at 300.
+   Its words start where the word it explains starts (the 12 px padding hangs left of it); a 12 x 6 caret points at
+   that word's middle, 4 above it. It shows on hover, focus and tap (--open). __term is that word: dotted underline,
+   the cue that more shows. */
+.ws-tooltip--note { --ws-tooltip-gap: calc(var(--space-xxs-plus) + var(--ws-nudge)); }
+.ws-tooltip--note > .ws-tooltip__tip { left: calc(var(--space-sm) * -1); max-width: min(calc(var(--ws-float-width) + var(--space-sm) * 2), calc(100vw - var(--space-xl))); padding: var(--space-xs-plus) var(--space-sm); border-radius: var(--ws-radius-control); background: var(--ws-inverse); box-shadow: var(--ws-float-rim); font-size: var(--ws-text-body); line-height: calc(var(--space-md) + var(--space-xxs)); font-weight: 400; color: var(--ws-on-inverse); text-wrap: wrap; translate: none; transform-origin: bottom left; }
+.ws-tooltip--note.ws-tooltip--end > .ws-tooltip__tip { right: calc(var(--space-sm) * -1); left: auto; transform-origin: bottom right; }
+.ws-tooltip--note::after { content: ""; position: absolute; bottom: calc(100% + var(--ws-nudge)); left: 50%; width: var(--space-sm); height: var(--space-xxs-plus); background: var(--ws-inverse); clip-path: polygon(0 0, 100% 0, 50% 100%); translate: -50% 0; opacity: 0; visibility: hidden; pointer-events: none; }
+@media (hover: hover) { .ws-tooltip--note:hover::after { opacity: 1; visibility: visible; } }
+.ws-tooltip--note.ws-tooltip--open::after, .ws-tooltip--note:has(:focus-visible)::after { opacity: 1; visibility: visible; }
+/* --dismissed: Escape hides it while the pointer or focus stays (WCAG 1.4.13); the app removes it when they leave. */
+.ws-tooltip.ws-tooltip--dismissed > .ws-tooltip__tip, .ws-tooltip.ws-tooltip--dismissed::after { opacity: 0; visibility: hidden; pointer-events: none; }
+/* --note --below: the note under its term, the caret turned up to it. */
+.ws-tooltip--note.ws-tooltip--below > .ws-tooltip__tip { transform-origin: top left; }
+.ws-tooltip--note.ws-tooltip--below::after { top: calc(100% + var(--ws-nudge)); bottom: auto; clip-path: polygon(50% 0, 100% 100%, 0 100%); }
+/* Where the browser places by anchor, the tip and the note's caret are fixed to the wrapper as their anchor, so no
+   scroller, card or stage that clips can cut them (K9: AppShell's body scrolls and its stage clips, so a tip on the bar
+   or on the body's first row was cut). They take the same places from the anchor's edges; a plain tip with no room
+   turns to the other side or slides along its control to stay on the screen (the note keeps its side, so its caret
+   stays on it). Without anchor placement they hang in the wrapper, and inside a box that clips the app portals them. */
+@supports (anchor-scope: all) {
+  .ws-tooltip { --ws-tooltip-block: top; --ws-tooltip-inline: span-all; --ws-tooltip-justify: anchor-center; anchor-name: --ws-tooltip; anchor-scope: --ws-tooltip; }
+  .ws-tooltip--below { --ws-tooltip-block: bottom; }
+  .ws-tooltip--start, .ws-tooltip--note { --ws-tooltip-inline: span-right; --ws-tooltip-justify: normal; }
+  .ws-tooltip--end { --ws-tooltip-inline: span-left; --ws-tooltip-justify: normal; }
+  .ws-tooltip__tip, .ws-tooltip--note::after { position: fixed; position-anchor: --ws-tooltip; inset: auto; translate: none; }
+  .ws-tooltip__tip { position-area: var(--ws-tooltip-block) var(--ws-tooltip-inline); justify-self: var(--ws-tooltip-justify); margin: var(--ws-tooltip-gap) 0; }
+  .ws-tooltip:not(.ws-tooltip--note) > .ws-tooltip__tip { position-try-fallbacks: flip-block, --ws-tooltip-right, --ws-tooltip-left, --ws-tooltip-right flip-block, --ws-tooltip-left flip-block; }
+  .ws-tooltip--note > .ws-tooltip__tip { margin-inline: calc(var(--space-sm) * -1) 0; }
+  .ws-tooltip--note.ws-tooltip--end > .ws-tooltip__tip { margin-inline: 0 calc(var(--space-sm) * -1); }
+  .ws-tooltip--note::after { position-area: var(--ws-tooltip-block) span-all; justify-self: anchor-center; margin: var(--ws-nudge) 0; }
+}
+@position-try --ws-tooltip-right { position-area: top span-right; justify-self: normal; }
+@position-try --ws-tooltip-left { position-area: top span-left; justify-self: normal; }
+.ws-tooltip__term { padding: 0; border: 0; background: none; font-weight: inherit; text-decoration: underline dotted var(--ws-line); text-underline-offset: var(--space-xxs); cursor: help; }
+/* On touch the term is 24 tall to a finger, but only its hit area grows, so a term inside a sentence keeps the
+   sentence's baseline (a taller box pushed its words 2 px down). */
+@media (pointer: coarse) {
+  .ws-tooltip__term { position: relative; }
+  .ws-tooltip__term::after { content: ""; position: absolute; inset: calc((100% - var(--space-lg)) / 2) 0; }
+}
+/* Motion (D7, North's "Tooltip pop-in", the pop spring .35 / .1, js@484880): it pops from scale .9 and 4 px toward its
+   control (--ws-tooltip-from), growing out of the edge it hangs from; it fades off over 180 ms (North's tip fade,
+   css:388), faster than it came. A pointer waits the 40 ms hover intent; keyboard focus shows it at once. With reduced
+   motion it simply appears and goes. */
+.ws-tooltip { --ws-tooltip-scale: 0.9; --ws-tooltip-out: 180ms; /* raw: North's .18 s tip fade; a global --ws-duration-fade wanted */ }
+@media (prefers-reduced-motion: no-preference) {
+  .ws-tooltip__tip { transform: translateY(var(--ws-tooltip-from)) scale(var(--ws-tooltip-scale)); transition: opacity var(--ws-tooltip-out) var(--ws-ease-exit), transform var(--ws-tooltip-out) var(--ws-ease-exit), visibility 0s linear var(--ws-tooltip-out); }
+  .ws-tooltip--note::after { transition: opacity var(--ws-tooltip-out) var(--ws-ease-exit), visibility 0s linear var(--ws-tooltip-out); }
+  @media (hover: hover) {
+    .ws-tooltip:hover > .ws-tooltip__tip { transform: none; transition: opacity var(--ws-spring-pop-duration) var(--ws-spring-pop) var(--ws-hover-intent), transform var(--ws-spring-pop-duration) var(--ws-spring-pop) var(--ws-hover-intent), visibility 0s linear var(--ws-hover-intent); }
+    .ws-tooltip--note:hover::after { transition: opacity var(--ws-spring-pop-duration) var(--ws-spring-pop) var(--ws-hover-intent), visibility 0s linear var(--ws-hover-intent); }
+  }
+  .ws-tooltip--open > .ws-tooltip__tip, .ws-tooltip:has(:focus-visible) > .ws-tooltip__tip { transform: none; transition: opacity var(--ws-spring-pop-duration) var(--ws-spring-pop), transform var(--ws-spring-pop-duration) var(--ws-spring-pop), visibility 0s; }
+  .ws-tooltip--note.ws-tooltip--open::after, .ws-tooltip--note:has(:focus-visible)::after { transition: opacity var(--ws-spring-pop-duration) var(--ws-spring-pop), visibility 0s; }
+}

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

@@ -1,65 +1,57 @@
-The 56 px bar alone: a wordmark, up to five page links, a search box, an icon act and the person, for a product that
-puts its navigation across the top rather than down the side.
+The 56 px bar alone: a wordmark, up to five page links, a search box, one quiet act and the person, for a product
+that puts its navigation across the top rather than down the side.
 
 ## Use it when
 
-- A product reads better as a row of top-level sections than as a side nav: a handful of destinations, no groups, no
-  nesting worth an eyebrow.
-- A page needs its navigation and its identity in one fixed strip, with the content free to use the full width below it.
-- A phone needs the same bar collapsed to the wordmark and a menu.
+- A product reads better as a row of top-level sections than as a side nav: a handful of destinations, no groups.
+- A page needs its navigation and identity in one strip, with the content free to use the width below it.
 
 ## Not for
 
-- Five or more sections that fall into groups, or a product with any depth to its hierarchy: use `AppShell`'s side nav
-  instead; a top bar with eight crowded links is the wrong shape for that.
-- Moving between views of the same thing (list and board, this month and last): that is `Segmented` or `Tabs`, not a
-  second row under this bar (no inner tabs on a page, per the desk's own rule).
-- The chat-first desk: the system's own `Sidebar` is the nav there; this bar is for a conventional product shape instead.
+- More than five sections, or sections that fall into groups: `AppShell`.
+- Moving between views of the same thing (list and board, this month and last): `Segmented` or `Tabs`.
+- The chat-first workspace: the chat's own frame.
 
 ## Anatomy
 
-- Bar: `--ws-header-h` (56 px) tall, the width of the page, flat (shown here on a hairline card so its edge reads in the
-  preview; in product it usually sits directly on the page with a hairline beneath it).
-- Wordmark: 16 px semibold (`--ws-text-value`), navy, at the left. The reference implementation has no logo file to
-  draw here; a real product supplies its mark.
-- Links: up to five, 14 px medium, `--color-text-body` at rest; the current one `--color-text-heading` with a 2 px navy
-  underline (`--ws-ring`) sitting on the bar's own baseline.
-- Search: a 36 px box? No: in the top bar it sits at the default control height (`--ws-control-h`, 32 px) like any inline
-  field, 4 px corners, the field's hairline, placed to the right of the links.
-- Icon act: one 32 px `IconButton` (notifications, help, or whatever the one quiet global act is).
-- The person: a `--ws-avatar` neutral disc with navy initials, at the far right.
+- Bar (`.ws-top-bar`): 56 tall (`--ws-header-h`), 24 at the sides, its parts 24 apart. Flat; in the preview it sits on
+  a card so its edge reads.
+- Wordmark (`__wordmark`): 16 / 24 semibold navy.
+- Links (`__links`, `__link`): up to five, 14 px medium in the body grey, 24 apart, each the bar's full height, its
+  box bleeding 8 past its words (so the focus ring clears them); the current one (`aria-current="page"`, or `--current`) navy with a 2 px navy underline (`--ws-ring`) on the bar's foot.
+- Search (`__search`): a `<label>` round an `<input type="search">`, 200 wide (it gives way first, down to 96, so
+  five links of two words still fit at 60rem), 32 tall (40 on touch), 4 px corners, the field's inset hairline, a 12 px
+  icon, the focus ring on the box. The links never shrink under their words.
+- End (`__end`): one 32 px `IconButton` and the person's 32 px avatar, 8 apart.
+- Menu button (`__menu`): an `IconButton`, shown only in the phone form.
 
 ## Variants and sizes
 
 | Variant | Shows |
 | --- | --- |
-| Default (desktop) | Wordmark, links, search, an icon button, the avatar |
-| Phone (375 px and under) | Wordmark and one menu `IconButton` only; links, search and the icon act move into the menu it opens |
+| Default | Wordmark, links, search, an icon button, the avatar |
+| Phone form (under 60rem of window, or `--phone` at any width) | The wordmark at the left, the menu button at the right, 16 px sides; the links, search and quiet act move into the menu it opens |
 
 ## States
 
-- **Default**: as above.
-- **Current link**: navy words, the 2 px underline; set by `aria-current="page"`, never colour alone.
-- **Hover**: a link darkens toward `--color-text-heading`; underline only on the current link, never on hover.
-- **Focus**: the kit's `--shadow-focus-ring` on the link, the search box and the icon button.
-- **Long link label**: the bar does not wrap or stack; a label this long belongs in `AppShell`'s side nav instead, where
-  rows can grow.
-- **Empty search**: shows the placeholder "Search" only; it is never the only way to reach a page.
-- **Narrow desktop**: below the five links' combined width, drop the least-used link into an overflow `Menu` rather than
-  shrinking words or wrapping the bar.
+- **Current link**: navy words and the underline, set by `aria-current="page"`, never colour alone.
+- **Hover** (pointers that hover): a link's words darken to navy over 200 ms; the underline stays the current link's.
+- **Focus**: the house's 2 px navy ring on each link (drawn inside it on 4 px corners, since a link is the bar's full
+  height), on the search's box and on the icon button.
+- **Long link label**: the bar never wraps; a label this long belongs in `AppShell`'s nav.
+- **Empty search**: "Search" only; it is never the only way to reach a page.
 
 ## Behaviour
 
-- Keyboard: links are real `<a>`/`Link`s in document order; Tab reaches search and the icon button after them.
-- Pointer: hover darkens a link's words; the search box and icon button take the standard control hover.
-- Touch: the bar's controls grow to the 40 px floor; on a phone the bar collapses to wordmark and menu, per the house
-  responsive rule that a phone stays at 100% and boxed controls grow to 40 px.
-- Motion: none of its own; the underline can be a sliding highlight (`layoutId`) between links as the sidebar's wash does,
-  or simply present under the current link.
+- Keyboard: links are real `<a>`s in document order, then the search and the icon button.
+- Touch: the bar's controls grow to the 40 px floor.
+- The phone form is set by the window (60rem, where five links and the search stop fitting), since the bar is the
+  window's own strip.
+- Motion: only the link colour. The underline can slide between links in React; in plain HTML it is simply present.
 
 ## Content
 
-- The wordmark is the product's name only, never a slogan.
+- The wordmark is the product's name only.
 - Link words are the page's own name, sentence case, one or two words.
 - No em dashes.
 
@@ -71,23 +63,45 @@ puts its navigation across the top rather than down the side.
 | `search` | `{ placeholder, onSearch }` | The inline search box |
 | `actions` | `IconButtonProps[]` | Quiet global acts, icon only |
 | `person` | `{ name, initials }` | The avatar at the right |
-| `phone` | `boolean` | Collapses to wordmark and menu |
+| `phone` | `boolean` | The phone form at any width |
 
 ## Rules
 
-- **Five links, not more**: past five, the hierarchy has outgrown a top bar; move to `AppShell`.
-- **One underline, the current page's**: never two links styled as current, never a filled pill (navy fills are for the
-  one act and a selected toggle only, not for navigation links).
-- **No inner tabs on a page** carries over here too: a page below this bar still never draws its own second tab row for
-  the same navigation job.
-- **Source**: Intentional addition, decided from the system (26 Oct 2026): a flat-hierarchy product reads better with its
-  navigation across the top than down a 232 px side nav it would barely fill. Derived from `--ws-header-h` (the desk's
-  and a page's own header line), the link colour and underline rule already used for the current item elsewhere (the
-  navy thumb pattern in `Segmented`'s tabs), and the avatar and icon-button sizes used everywhere else in the system.
+- **Five links, not more**: past five, move to `AppShell`.
+- **One underline, the current page's**: never two, never a filled pill.
+- **No inner tabs on a page** for the same navigation job.
 
 ## Source
 
-**Derived from**: `--ws-header-h` (the same header line used elsewhere), the current-link treatment adapted from
-`Segmented`'s navy-thumb rule into an underline, and the avatar and icon-button sizes used throughout the system.
-**Precedent**: an intentional addition decided from the system, 26 Oct 2026; no card in the first product builds a
-top bar, since its chat-first desk uses a side `Sidebar` instead.
+**Derived from**: `--ws-header-h`, the current-link underline, the avatar and icon-button sizes used across the
+system, and the geometry check (4 Nov 2026: at 390 the end ran to 428 and the fifth link to 445, the page scrolled
+55 px sideways, because only `--phone` collapsed it). **Precedent**: an intentional addition decided from the system,
+26 Oct 2026.
+
+## Markup
+
+```html
+<nav class="ws-top-bar" aria-label="Main">
+  <span class="ws-top-bar__wordmark">Fello</span>
+  <div class="ws-top-bar__links">
+    <a href="/pipeline" class="ws-top-bar__link" aria-current="page">Pipeline</a>
+    <a href="/leads" class="ws-top-bar__link">Leads</a>
+  </div>
+  <label class="ws-top-bar__search">
+    <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" aria-hidden="true"><circle cx="6.8" cy="6.8" r="3.8"/><path d="M9.7 9.7l3.6 3.6"/></svg>
+    <input type="search" placeholder="Search" aria-label="Search">
+  </label>
+  <div class="ws-top-bar__end">
+    <button type="button" class="ws-icon-btn" aria-label="Notifications"><!-- 16 px icon --></button>
+    <span class="ws-avatar">PN</span>
+  </div>
+  <button type="button" class="ws-icon-btn ws-top-bar__menu" aria-label="Open the menu"><!-- 16 px icon --></button>
+</nav>
+```
+
+## Styles
+
+`TopBar/style.css`, with `IconButton` and `Avatar` for the menu button, the quiet act and the person. Tokens: `--ws-header-h`, `--ws-text-value`,
+`--ws-text-body`, `--ws-text-meta`, `--ws-control-h`, `--ws-ring`, `--ws-radius-control`, `--ws-radius-bar`,
+`--ws-field`, `--ws-field-ink`, `--ws-edge-card`, `--ws-hairline`, `--ws-touch`, `--ws-focus-width`, `--ws-focus-color`,
+`--ws-focus-offset`, `--space-6xl`, `--color-text-heading`, `--color-text-body`, `--color-text-muted`.

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

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Navigation" height=320 -->
+<!-- @dsCard group="Navigation" height=232 -->
 <!doctype html>
 <html>
 <head>
@@ -8,53 +8,40 @@
 <link rel="stylesheet" href="../bundle.css">
 </head>
 <body>
-<div class="ws-stage ws-stage--grey ws-stage--column" style="gap: var(--ws-gap-component);">
+<div class="ws-stage ws-stage--grey ws-stage--column">
 
   <div class="ws-stack">
-    <span class="ws-muted">Default: wordmark, up to five links, the current one navy and underlined, search, an icon button, the avatar</span>
+    <span class="ws-muted">Default: wordmark, up to five links, the current one navy and underlined, search, an icon button, the avatar; under 60rem of window it is the phone form</span>
     <nav class="ws-card ws-top-bar" aria-label="Main">
       <span class="ws-top-bar__wordmark">Fello</span>
       <div class="ws-top-bar__links">
-        <a href="#" class="ws-top-bar__link ws-top-bar__link--current" aria-current="page" onclick="return false;">Pipeline</a>
+        <a href="#" class="ws-top-bar__link" aria-current="page" onclick="return false;">Pipeline</a>
         <a href="#" class="ws-top-bar__link" onclick="return false;">Leads</a>
         <a href="#" class="ws-top-bar__link" onclick="return false;">Listings</a>
         <a href="#" class="ws-top-bar__link" onclick="return false;">Reports</a>
+        <a href="#" class="ws-top-bar__link" onclick="return false;">Settings</a>
       </div>
-      <span class="ws-top-bar__search" role="searchbox" aria-label="Search">
-        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="6.8" cy="6.8" r="3.8"/><path d="M9.7 9.7l3.6 3.6"/></svg>
-        Search
-      </span>
+      <label class="ws-top-bar__search">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="6.8" cy="6.8" r="3.8"/><path d="M9.7 9.7l3.6 3.6"/></svg>
+        <input type="search" placeholder="Search" aria-label="Search">
+      </label>
       <div class="ws-top-bar__end">
         <button type="button" class="ws-icon-btn" aria-label="Notifications">
           <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M4 11.5V7a4 4 0 0 1 8 0v4.5l1 1.5H3l1-1.5Z"/><path d="M6.5 14.5h3"/></svg>
         </button>
         <span class="ws-avatar">PN</span>
       </div>
-    </nav>
-  </div>
-
-  <div class="ws-stack" style="max-width: 760px;">
-    <span class="ws-muted">Five links, a long one truncating never: it wraps the bar before it clips</span>
-    <nav class="ws-card ws-top-bar" aria-label="Main">
-      <span class="ws-top-bar__wordmark">Fello</span>
-      <div class="ws-top-bar__links">
-        <a href="#" class="ws-top-bar__link" onclick="return false;">Pipeline</a>
-        <a href="#" class="ws-top-bar__link ws-top-bar__link--current" aria-current="page" onclick="return false;">Leads</a>
-        <a href="#" class="ws-top-bar__link" onclick="return false;">Listings</a>
-        <a href="#" class="ws-top-bar__link" onclick="return false;">Reports</a>
-        <a href="#" class="ws-top-bar__link" onclick="return false;">Settings</a>
-      </div>
-      <div class="ws-top-bar__end">
-        <span class="ws-avatar">PN</span>
-      </div>
+      <button type="button" class="ws-icon-btn ws-top-bar__menu" aria-label="Open the menu">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"/></svg>
+      </button>
     </nav>
   </div>
 
   <div class="ws-stack" style="width: 375px; max-width: 100%;">
-    <span class="ws-muted">Phone, 375 px: the wordmark and a menu icon button only</span>
+    <span class="ws-muted">--phone at any width: the wordmark and the menu button only; the links, search and quiet act are in the menu it opens</span>
     <nav class="ws-card ws-top-bar ws-top-bar--phone" aria-label="Main">
       <span class="ws-top-bar__wordmark">Fello</span>
-      <button type="button" class="ws-icon-btn" aria-label="Open the menu">
+      <button type="button" class="ws-icon-btn ws-top-bar__menu" aria-label="Open the menu">
         <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11"/></svg>
       </button>
     </nav>