@felloinnovations/brand-kit 0.4.0 → 0.5.0

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

@@ -15,30 +15,45 @@ A quiet block set apart inside a card: the cream a shade darker, for a card's fa
 
 ## Anatomy
 
-- Background: `--ws-surface-sunk` (the cream 95% mixed with gray-8, `#f3f1ef`), a shade darker than the card's own `--color-bg-page`.
-- Corners: `--ws-radius-card` (8 px), the same ladder step as the card that holds it.
-- Inside: `--ws-card-padding` (12 px) on every side.
-- No edge, no shadow: a plate is a ground, not a bordered box.
+- Ground: `--ws-surface-sunk` (#F3F1EF), a shade darker than the card's cream. Corners `--ws-radius-card` (8 px).
+- Inside: Seth's 14 px top and bottom, 16 px at the sides (`--space-sm-plus`, `--space-md`). No edge, no shadow.
+- Facts (`ws-plate__fact`): label and value on one line, 16 px apart, the label on the value's first line (baseline),
+  the value at the end in navy semibold with tabular figures. A long value wraps under its own first line; the label
+  never wraps. Rows 4 px apart.
+- Stats (`ws-plate__stats`): label over value, 2 px apart: the label 13 / 18 medium in `--color-text-muted`
+  (`ws-plate__label`), the value 15 / 22 semibold navy (`ws-plate__value`); pairs 32 px apart, wrapping 8 px under.
+- A title (`ws-plate__title`): 14 / 20 semibold navy, for the thing the stats are about (a search, a place). Stats
+  right under it sit 16 px down (Seth 301:2084), in a body that is an 8 px `ws-stack`.
+- A foot (`ws-plate__foot`, Seth's search result plate): the plate shows 1 px of its sunk cream round a body
+  (`ws-plate__body`, 14 / 16 inside) and a cream foot under a 0.5 px divider, 12 / 16 inside, 7 px bottom corners;
+  13 / 18 medium navy words and a 16 px chevron at the end. A foot that opens something is an `a.ws-plate__foot`.
+- A track (`ws-plate__track`): 12 px tall, 2 px corners, the empty part in navy at 8 % (the load bar's track; the tray grey all but vanished on the sunk plate), the fill (`ws-plate__fill`, its width the share done) in teal.
+- The draft (`ws-plate--draft`, Seth's inbox reply 313): the sunk cream inside a 1 px tray rim, 20 px inside, its parts
+  12 px apart. Its head (`ws-plate__head`, 8 apart): the agent's 20 px face (an `svg`), a 15 / 22 semibold title
+  (`ws-section`) that takes the room, and a 13 / 18 word act (`ws-btn ws-btn--text`, "Edit"); then the words (`ws-body`).
 
 ## Variants and sizes
 
 | Use | What sits inside |
 | --- | --- |
-| Facts plate | Label and value rows, each row's label muted (`ws-muted`), its value navy and medium |
-| Track plate | A progress bar or strip, with a caption line under it |
-
-Both variants share the same 8 px corners and 12 px padding; only the content differs.
+| Facts plate | Label and value rows |
+| Stats plate | A title, then label-over-value pairs, optionally a foot |
+| Track plate | A progress track with a caption under it |
+| Draft (`--draft`) | Something the agent wrote for the person to use: a head (face, title, Edit), then the draft |
 
 ## States
 
-- **Default**: the sunk ground, static.
-- **Hover** (when a plate doubles as a row's ground, such as a menu item or a well's row): the surface can step further to `--ws-surface-press` under a press, so a tap answers on touch.
-- **Empty**: a plate with nothing to show is not drawn; the card either omits the plate or, if the whole card has no data, the card itself is left out.
-- **Narrow**: the plate has no width of its own; it fills whatever room its card gives it and its rows wrap or truncate as the card does.
+- **Default**: the sunk ground, still.
+- **Foot hover** (a pointer that hovers): a faint navy wash on the foot and its words underline; **pressed**: a
+  stronger wash at once; **focus**: the 2 px navy ring drawn inside the foot.
+- **Long words**: a value wraps under its own first line, the label stays put; a stat pair wraps to a new line.
+- **Empty**: a plate with nothing to show is not drawn.
+- **Narrow**: the plate fills its card; stats wrap.
+- **Dark**: the ground, the foot and the divider follow the theme.
 
 ## Behaviour
 
-- Keyboard and pointer: a plate is a passive ground, not an interactive element; anything pressable inside it (a row, a link) carries its own focus and hover states.
+- Keyboard and pointer: a plate is a passive ground; only its foot, when it is a link, takes focus.
 - Touch: no special handling; it is not itself a 40 px control.
 - Motion: a track plate's fill can grow in with `ws-grow` (`--ws-duration-calm`, scales from the left); the plate's own ground never animates.
 - Reduced motion: a growing track shows at its final width immediately.
@@ -65,7 +80,50 @@ Plate has no dedicated component in the first product built on the system: it is
 
 ## Source
 
-- **Derived from**: the system's sunk-surface and plate rules ("its facts are on a plate," never grey holding
-  white rows) and the `--ws-surface-sunk` token.
-- **Precedent**: the first product built on the system, where the pattern lives inline wherever a card needs it
-  rather than as a single `Plate.tsx`.
+- **Derived from**: Seth's search result plate (Grow 301:2080 to 301:2093: the 1 px sunk rim, the 14 / 16 body, the cream
+  foot, label-over-value stats) and the system's plate rule ("its facts are on a plate"). K17 (Revenue OS): facts on
+  the baseline.
+- **Precedent**: the first product built on the system.
+
+## Markup
+
+```html
+<div class="ws-plate">
+  <div class="ws-plate__body ws-stack">
+    <p class="ws-plate__title">Chagrin Falls, OH</p>
+    <div class="ws-plate__stats">
+      <div class="ws-plate__stat"><span class="ws-plate__label">Found</span><span class="ws-plate__value">5 of 9</span></div>
+      <div class="ws-plate__stat"><span class="ws-plate__label">Top three</span><span class="ws-plate__value">0 of 9</span></div>
+    </div>
+  </div>
+  <a class="ws-plate__foot" href="/map">
+    <span>See it on the map</span>
+    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M6.6 5.2L9.4 8l-2.8 2.8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+  </a>
+</div>
+
+<div class="ws-plate">
+  <div class="ws-plate__fact"><span class="ws-muted">Source</span><span class="ws-body ws-plate__value">Referral</span></div>
+</div>
+
+<div class="ws-plate ws-plate--draft">
+  <div class="ws-plate__head">
+    <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3.5 16.5V9l6.5-5.5L16.5 9v7.5Z"/><path d="M8 16.5v-4h4v4"/></svg>
+    <p class="ws-section">Grow drafted a reply in your voice</p>
+    <button type="button" class="ws-btn ws-btn--text">Edit</button>
+  </div>
+  <p class="ws-body">Thank you both! It was a pleasure helping you price it right.</p>
+</div>
+
+<div class="ws-plate ws-stack">
+  <div class="ws-plate__track"><div class="ws-plate__fill" style="width: 65%;"></div></div>
+  <p class="ws-muted">26 of 40 calls, nine days early</p>
+</div>
+```
+
+## Styles
+
+The ground and corners are the house's `.ws-plate`; `Plate/style.css` sets Seth's insets and adds the facts, stats,
+title, foot, track and the draft. Tokens: `--ws-surface-sunk`, `--space-sm-plus`, `--ws-rim`, `--ws-divider`,
+`--ws-radius-card-inner`, `--ws-text-control`, `--ws-text-section`, `--ws-hover-faint`, `--ws-ink`, `--ws-tray`,
+`--ws-card-inset`, `--ws-icon-lg`.

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

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Cards" height=228 -->
+<!-- @dsCard group="Cards" height=555 -->
 <!doctype html>
 <html>
 <head>
@@ -8,10 +8,9 @@
 <link rel="stylesheet" href="../bundle.css">
 </head>
 <body>
-<div class="ws-stage ws-stage--grey">
-
-  <div class="ws-stack" style="width: 300px; max-width: 100%;">
-    <span class="ws-muted">A plate of facts inside a card</span>
+<div class="ws-stage">
+  <div class="ws-stack" style="width: 300px;">
+    <span class="ws-muted">Facts: label and value rows; a long value wraps under its own line</span>
     <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
       <h3 class="ws-section">This lead</h3>
       <div class="ws-plate">
@@ -25,13 +24,33 @@
         </div>
         <div class="ws-plate__fact">
           <span class="ws-muted">Next step</span>
-          <span class="ws-body ws-plate__value">Call Priya Nair</span>
+          <span class="ws-body ws-plate__value">Call Priya Nair about the Oak Street offer</span>
         </div>
       </div>
     </div>
   </div>
 
-  <div class="ws-stack" style="width: 300px; max-width: 100%;">
+  <div class="ws-stack" style="width: 380px;">
+    <span class="ws-muted">Stats with a foot (Seth's search result plate)</span>
+    <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
+      <h3 class="ws-section">Buyers near you see you in 5 of 9 spots</h3>
+      <div class="ws-plate">
+        <div class="ws-plate__body ws-stack">
+          <p class="ws-plate__title">Chagrin Falls, OH: &ldquo;real estate agent in chagrin falls, oh&rdquo;</p>
+          <div class="ws-plate__stats">
+            <div class="ws-plate__stat"><span class="ws-plate__label">Found</span><span class="ws-plate__value">5 of 9</span></div>
+            <div class="ws-plate__stat"><span class="ws-plate__label">Top three</span><span class="ws-plate__value">0 of 9</span></div>
+          </div>
+        </div>
+        <a class="ws-plate__foot" href="#" onclick="return false;">
+          <span>See it on the map</span>
+          <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M6.6 5.2L9.4 8l-2.8 2.8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg>
+        </a>
+      </div>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 300px;">
     <span class="ws-muted">A plate as a track (a goal's progress)</span>
     <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
       <h3 class="ws-section">October goal</h3>
@@ -42,6 +61,20 @@
     </div>
   </div>
 
+  <div class="ws-stack" style="width: 440px; max-width: 100%;">
+    <span class="ws-muted">A draft (Seth's inbox reply): the tray rim round the sunk cream, the agent's face, Edit</span>
+    <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
+      <h3 class="ws-section">&ldquo;Knew the market inside out and got us a great price.&rdquo;</h3>
+      <div class="ws-plate ws-plate--draft">
+        <div class="ws-plate__head">
+          <svg viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M3.5 16.5V9l6.5-5.5L16.5 9v7.5Z"/><path d="M8 16.5v-4h4v4"/></svg>
+          <p class="ws-section">Grow drafted a reply in your voice</p>
+          <button type="button" class="ws-btn ws-btn--text">Edit</button>
+        </div>
+        <p class="ws-body">Thank you both! It was a pleasure helping you price it right, and I&rsquo;m so glad it came together the way you hoped. Enjoy the next chapter.</p>
+      </div>
+    </div>
+  </div>
 </div>
 </body>
 </html>

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

@@ -0,0 +1,37 @@
+/* ---- Plate: a card's facts set apart on the sunk cream (Seth's facts plate): label and value rows, stats, a track, a foot ---- */
+/* Seth's plate is 14 / 16 inside (the house had 12 all round). */
+.ws-plate { padding: var(--space-sm-plus) var(--space-md); }
+/* A plate with a foot: the sunk cream shows 1 px round a body and a cream foot (Seth's search result plate, 301:2080). */
+.ws-plate:has(> .ws-plate__foot) { padding: var(--ws-rim); }
+.ws-plate__body { padding: var(--space-sm-plus) var(--space-md); }
+.ws-plate__foot { display: flex; align-items: center; justify-content: space-between; gap: var(--space-xs); padding: var(--space-sm) var(--space-md); border-top: var(--ws-divider); border-radius: 0 0 var(--ws-radius-card-inner) var(--ws-radius-card-inner); background: var(--color-bg-page); font-size: var(--ws-text-control); line-height: var(--ws-leading-control); font-weight: 500; color: var(--color-text-heading); }
+a.ws-plate__foot { text-decoration: none; transition: background-color var(--ws-duration-hover) var(--ws-ease-soft); }
+@media (hover: hover) { a.ws-plate__foot:hover { background-image: linear-gradient(var(--ws-hover-faint), var(--ws-hover-faint)); } a.ws-plate__foot:hover > :first-child { text-decoration: underline; } }
+a.ws-plate__foot:active { background-image: linear-gradient(var(--ws-hover), var(--ws-hover)); }
+a.ws-plate__foot:focus-visible { outline-offset: calc(var(--ws-focus-width) * -1); }
+.ws-plate__foot > svg { flex-shrink: 0; width: var(--ws-icon); height: var(--ws-icon); }
+/* Label and value rows: the label on the value's first line (a wrapped value never strands its label mid-way, K17),
+   16 apart, the value at the end. */
+.ws-plate__fact { display: flex; align-items: baseline; justify-content: space-between; gap: var(--space-md); }
+.ws-plate__fact > :first-child { flex-shrink: 0; }
+.ws-plate__fact + .ws-plate__fact { margin-top: var(--space-xxs); }
+.ws-plate__value { font-weight: 600; color: var(--color-text-heading); text-align: right; font-variant-numeric: tabular-nums; }
+/* Stats: label over value (13 / 18 medium muted over 15 / 22 semibold navy, 2 apart), pairs 32 apart, wrapping. */
+.ws-plate__stats { display: flex; flex-wrap: wrap; gap: var(--space-xs) var(--space-xl); }
+/* Under a plate's title the stats sit 16 down (Seth 301:2084): 8 more than the body's 8 px stack. */
+.ws-plate__title + .ws-plate__stats { padding-top: var(--space-xs); }
+.ws-plate__stat { display: flex; flex-direction: column; gap: var(--space-3xs); }
+.ws-plate__label { font-size: var(--ws-text-control); line-height: var(--ws-leading-control); font-weight: 500; color: var(--color-text-muted); }
+.ws-plate__stat > .ws-plate__value { font-size: var(--ws-text-section); line-height: var(--ws-leading-section); text-align: left; }
+/* A goal's track on the plate: the empty track in navy at 8 % (the load bar's track), 2 px corners (Seth's 12 px
+   segments). The tray grey was 1.04:1 on the sunk plate, so the track's end, the goal, did not show. */
+.ws-plate__track { height: var(--space-sm); border-radius: var(--ws-radius-chip); background: color-mix(in srgb, var(--ws-ink) 8%, transparent); overflow: hidden; }
+.ws-plate__fill { height: 100%; border-radius: var(--ws-radius-chip); background: var(--color-stat-positive); transform-origin: left; }
+/* A plate's own title (a search query, a named fact): 14 / 20 semibold navy. */
+.ws-plate__title { font-size: var(--ws-text-body); line-height: calc(var(--space-md) + var(--space-xxs)); font-weight: 600; color: var(--color-text-heading); }
+/* The draft (Seth's inbox reply, 313): the sunk cream inside the 1 px tray rim, 20 inside, its parts 12 apart. Its
+   head: the agent's 20 px face, a 15 / 22 title that takes the room (ws-section) and a 13 / 18 word act (Edit). */
+.ws-plate--draft { display: flex; flex-direction: column; gap: var(--space-sm); padding: var(--ws-card-inset); border: var(--ws-rim) solid var(--ws-tray); }
+.ws-plate__head { display: flex; align-items: center; gap: var(--space-xs); font-size: var(--ws-text-control); line-height: var(--ws-leading-control); font-weight: 500; }
+.ws-plate__head > svg { flex-shrink: 0; width: var(--ws-icon-lg); height: var(--ws-icon-lg); color: var(--color-text-heading); }
+.ws-plate__head > .ws-section { flex: 1; min-width: 0; }

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

@@ -1,85 +1,106 @@
-A small lifted card of content, anchored to a control, for the one time a tooltip is too thin and a dialog is too much.
+A small lifted card beside its control, for the time a tooltip is too thin and a dialog is too much.
 
 ## Use it when
 
 - A control needs to show a short piece of content (a note, a small field) without leaving the page or blocking it.
-- An icon button's result belongs right where it was pressed, not in a panel or a dialog.
-- A quick, optional one-field form (renaming something, adding a quick note) fits in a few lines.
+- An icon button's answer belongs right where it was pressed ("Why this call is flagged").
+- A quick, optional one-field form fits in a few lines (renaming a list, a short note).
 
 ## Not for
 
-- A one-word label on hover or focus: use `Tooltip`; a popover is never the only place a label lives.
-- A short blocking task the person must resolve before continuing: use `Dialog`.
+- A control's name on hover: use `Tooltip`.
+- What a chart mark holds: use `HoverCard`.
 - A list of actions: use `Menu`.
-- A thing's full detail opened from the chat: use `Panel`.
+- A task the person must finish before going on: use `Dialog`.
+- A thing's full detail: use `Panel`.
 
 ## Anatomy
 
-- Panel: `ws-menu`'s shell (cream `--color-bg-page`, `--ws-radius-card` corners, `--ws-shadow-lift`), with `--space-sm`
-  (12 px) padding instead of `Menu`'s own 4 px row padding, since a popover holds a block of content, not a tight list
-  of 32 px action rows.
-- Title: 14 px navy medium (weight 500, `--color-text-heading`). This is not `row-title` (14/20, weight 600): the brief
-  calls for "medium," and `row-title`'s role is a row's name, not a popover's heading, so this is its own 14 px/500
-  treatment.
-- Body: `.ws-body` (14 px regular, `--color-text-body`).
-- Optional field and one small primary button, styled exactly as `Input` and `Button`.
-- No arrow pointing at the anchor: a plain floating card, offset a small gap from the control that opened it.
+- The card (`ws-popover`): `--ws-raised` ground, 8 px corners (`--ws-radius-card`), the 0.5 px hairline and the pop drop
+  (`--ws-shadow-hairline`, `--ws-shadow-pop`), 12 px inside, its parts 8 apart. As wide as its words, from 200 up to
+  300 (North's pop), never wider than the window less 32; never taller than the window less 32, its own scroll past
+  that.
+- Title (`ws-popover__title`): 14 / 20 medium navy.
+- Body: `.ws-body`, 14 / 20.
+- Form (`ws-popover__form`): one field and one small primary act on the right, 8 apart, as `Input` and `Button`.
+- No arrow: a plain card, 8 from its control.
 
 ## Variants and sizes
 
-| Variant | What it holds |
+| Class | Where |
 | --- | --- |
-| Note | a title and a line or two of body words |
-| Small form | a title, one field, one small primary button |
-
-There is one size; the panel's width fits its content, roughly 220 to 280 px.
+| `ws-popover` | Under its control, right edges flush, growing from the top right |
+| `ws-popover ws-popover--above` | Over its control, growing from the bottom right |
 
 ## States
 
-- **Closed:** not rendered.
-- **Open:** lifted on `--ws-shadow-lift`, anchored under or beside its control.
-- **Focus:** focus moves into the panel when it opens (to its first focusable element) and returns to the anchor
-  control when it closes, as `Dialog`'s own focus-trap-and-return behaviour, though a popover is lighter than a dialog
-  and uses no scrim.
-- **Disabled:** not applicable to the panel itself; a disabled field or button inside it follows its own component's
-  rule.
+- **Closed**: not shown.
+- **Opening** (North js@620042 and js@556550): it grows out of the corner it hangs from, 4 px toward its control and
+  .97 (`--ws-open-scale`), on the settle spring (`--ws-spring-settle`, .32 / .1); `--above` (or `data-side="top"` from
+  an app that places it) turns the nudge and the corner round. As `Menu`: a native popover by `@starting-style`, where
+  the browser places it by anchor the nudge rides on the margin so a flip turns it too, one the app mounts plays
+  `ws-popover-in`.
+- **Open**: anchored 8 from its control.
+- **Focus**: focus moves to its first field when it opens (give that field `autofocus`: a native popover does not move
+  focus by itself, it only puts its content next in the Tab order) and back to the control when it closes.
+- **Leaving** (`data-leaving`, or a native popover closing): it goes back into its corner, fading, over
+  `--ws-duration-exit` (120 ms) on `--ws-ease-exit`, faster than it came; a close mid-entrance turns back from where
+  it is.
+- **Long words**: they wrap at 300.
 
 ## Behaviour
 
-- Keyboard: Escape closes it and returns focus to the anchor, exactly as `Menu`'s and `Dialog`'s own dismiss rule; Tab
-  cycles through the panel's own focusable content while open.
-- Pointer: an outside click closes it, the same `useDismiss` pattern `Menu` uses and the same scrim-click logic `Dialog`
-  uses, without a scrim.
-- Motion: the panel rises in on `--ws-duration-gentle` on `--ws-ease-soft`, exactly as `Menu`'s own entrance.
-- Reduced motion: it appears without the rise.
+- Placement (K9): as `Menu`. Open it in the top layer with the native `popover` attribute and its control's
+  `popovertarget`; where the browser places by anchor it hangs 8 under (or over, with `--above`), right edges flush,
+  capped to that side and scrolling inside (never over its control), flips when less than 200 px fits, and centres in
+  the window when it is wider than either side of its control (a phone). In a React app, portal it with `flip` and
+  `shift`; a scoped app's portal root carries `class="fello"`.
+- Keyboard: `popover="auto"` closes on Escape and on a press outside, and focus goes back to the control; Tab moves
+  through its own content.
+- Touch: it opens on a tap of its control; its field and act are 40 tall.
+- Reduced motion: it appears and goes at once; so does a browser without `@starting-style` or `linear()`.
+- The preview's last stack is live: press either button.
 
 ## Content
 
 - The title is a short phrase, sentence case, no colon.
-- Body words are brief; a popover is not the place for a paragraph.
-- No em dashes.
+- Body words are brief: a popover is not the place for a paragraph.
 
 ## Props
 
 | Name | Type | Meaning |
 | --- | --- | --- |
-| `open` | `boolean` | whether it is shown |
-| `onClose` | `() => void` | fires on Escape or an outside click |
-| `anchorRef` | `RefObject` | the control it is positioned against |
-| `title` | `string` | the 14 px heading |
-| `children` | `ReactNode` | the body content |
+| `open` | `boolean` | Whether it is shown. |
+| `onClose` | `() => void` | Fires on Escape or a press outside. |
+| `anchorRef` | `RefObject` | The control it is placed against. |
+| `side` | `"below"` \| `"above"` | Which side it opens on; it flips when there is no room. Default `below`. |
+| `title` | `string` | The 14 px title. |
+| `children` | `ReactNode` | The body. |
 
 ## Rules
 
-- Built on `ws-menu`'s exact shell, with one difference: 12 px panel padding instead of `Menu`'s 4 px, since `Menu` is a
-  list of tight action rows and `Popover` is a block of content.
-- No arrow, per spec; the panel is a plain floating card.
-- Dismissal and focus-return follow `Menu`'s `useDismiss` and `Dialog`'s focus-trap precedent, without a scrim, since a
-  popover is not a blocking task.
+- It floats, so it has the pop drop; never a lift on a card.
+- No scrim: it does not block the page.
+- Dismissal and focus return follow `Menu`.
 
 ## Source
 
-Intentional addition, decided from the system (26 Oct 2026): 08-choosing-components.md draws `Tooltip` ("a short tip on
-hover or focus... never the only place a label lives") below this weight and `Dialog` ("a short blocking task") above
-it, leaving the middle case, lifted content that is not blocking and not label-only, undocumented. Built on `Menu`'s
-`ws-menu` shell and dismiss behaviour, and `Dialog`'s focus-trap-and-return rule.
+**Derived from**: Seth's North pop (style1.css:87: 300 wide, 8 px corners, the 0.5 px edge, `0 12px 32px -16px` drop,
+8 under its trigger, right-aligned, origin at that corner; pickers open from y 4 or -4, js@556550) and Revenue OS K9.
+**Precedent**: an intentional addition, decided from the system (26 Oct 2026), between `Tooltip` and `Dialog`.
+
+## Markup
+
+```html
+<button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-label="Why this call is flagged" popovertarget="flag-note">
+  <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"><circle cx="8" cy="8" r="6"/><path d="M8 7.3v3.4M8 5.3v.01"/></svg>
+</button>
+<div id="flag-note" class="ws-popover" role="dialog" aria-labelledby="flag-note-title" popover>
+  <p class="ws-popover__title" id="flag-note-title">Why this call is flagged</p>
+  <p class="ws-body">Priya has not had a cold call logged in nine days.</p>
+</div>
+```
+
+## Styles
+
+`Popover/style.css`, built into `bundle.css` and `fello.css`. Tokens only, so it turns dark with the page.

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

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Feedback" height=212 -->
+<!-- @dsCard group="Feedback" height=240 -->
 <!doctype html>
 <html>
 <head>
@@ -9,36 +9,58 @@
 </head>
 <body>
 <div class="ws-stage ws-stage--grey">
-  <div class="ws-cluster ws-cluster--start" style="gap: calc(var(--ws-gap-component) * 3);">
 
-    <div class="ws-stack">
-      <span class="ws-muted">Open above an icon button: a short note, no arrow</span>
-      <div class="ws-stack ws-stack--tight" style="width: 240px;">
-        <div class="ws-popover" role="dialog" aria-labelledby="pop-note-title">
-          <p class="ws-popover__title" id="pop-note-title">Why this call is flagged</p>
-          <p class="ws-body">Priya has not had a cold call logged in nine days.</p>
-        </div>
-        <div><button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-label="Why this call is flagged">
-          <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="8" cy="8" r="6"/><path d="M8 7.3v3.4M8 5.3v.01"/></svg>
-        </button></div>
+  <div class="ws-stack" style="width: 300px;">
+    <span class="ws-muted">A note, above its icon button: 8 apart, right edges flush</span>
+    <div class="ws-stack" style="align-items: flex-end; gap: var(--space-xs);">
+      <div class="ws-popover ws-popover--above" role="dialog" aria-labelledby="pop-note-title">
+        <p class="ws-popover__title" id="pop-note-title">Why this call is flagged</p>
+        <p class="ws-body">Priya has not had a cold call logged in nine days.</p>
       </div>
+      <button type="button" class="ws-icon-btn ws-icon-btn--outline" aria-label="Why this call is flagged" aria-expanded="true">
+        <svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"><circle cx="8" cy="8" r="6"/><path d="M8 7.3v3.4M8 5.3v.01"/></svg>
+      </button>
     </div>
+  </div>
 
-    <div class="ws-stack">
-      <span class="ws-muted">Open with a small form: 12 px inside, one field, one small primary act</span>
-      <div class="ws-stack ws-stack--tight" style="width: 240px;">
-        <div class="ws-popover" role="dialog" aria-labelledby="pop-form-title">
-          <p class="ws-popover__title" id="pop-form-title">Rename this list</p>
-          <div class="ws-popover__form">
-            <input class="ws-input" value="This week's follow-ups" aria-label="List name">
-            <button type="button" class="ws-btn ws-btn--primary">Save</button>
-          </div>
+  <div class="ws-stack" style="width: 300px;">
+    <span class="ws-muted">A small form, under its button: one field, one small primary act</span>
+    <div class="ws-stack" style="align-items: flex-end; gap: var(--space-xs);">
+      <button type="button" class="ws-btn ws-btn--secondary" aria-expanded="true">This week's follow-ups</button>
+      <div class="ws-popover" role="dialog" aria-labelledby="pop-form-title">
+        <p class="ws-popover__title" id="pop-form-title">Rename this list</p>
+        <div class="ws-popover__form">
+          <input class="ws-input" value="This week's follow-ups" aria-label="List name">
+          <button type="button" class="ws-btn ws-btn--primary">Save</button>
         </div>
-        <div><button type="button" class="ws-btn ws-btn--secondary">This week's follow-ups</button></div>
       </div>
     </div>
+  </div>
+
+  <div class="ws-stack" style="width: 300px;">
+    <span class="ws-muted">Longer words wrap at 300; the popover never runs past the window</span>
+    <div class="ws-popover" role="dialog" aria-labelledby="pop-long-title">
+      <p class="ws-popover__title" id="pop-long-title">How the score is worked out</p>
+      <p class="ws-body">Each of the six checks counts the same. A check we could not run is left out, so it never pulls the score down.</p>
+    </div>
+  </div>
 
+  <div class="ws-stack" style="width: 300px;" data-live>
+    <span class="ws-muted">Live: press either. Each grows out of the corner it hangs from, toward its control, on the settle spring, and goes back faster (Escape or a press outside)</span>
+    <div class="ws-cluster">
+      <button type="button" class="ws-btn ws-btn--secondary" popovertarget="pop-live" aria-haspopup="dialog">How it is scored</button>
+      <button type="button" class="ws-btn ws-btn--secondary" popovertarget="pop-live-up" aria-haspopup="dialog">Above</button>
+    </div>
+    <div id="pop-live" class="ws-popover" popover role="dialog" aria-labelledby="pop-live-title">
+      <p class="ws-popover__title" id="pop-live-title">How the score is worked out</p>
+      <p class="ws-body">Each of the six checks counts the same.</p>
+    </div>
+    <div id="pop-live-up" class="ws-popover ws-popover--above" popover role="dialog" aria-labelledby="pop-live-up-title">
+      <p class="ws-popover__title" id="pop-live-up-title">Opened above its control</p>
+      <p class="ws-body">It grows up out of its bottom corner.</p>
+    </div>
   </div>
+
 </div>
 </body>
 </html>

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

@@ -0,0 +1,41 @@
+/* ---- Popover: a short note or a small form lifted beside its control, Seth's North pop: 8 px corners on the hairline and
+   the pop drop, 12 px inside, opened in the top layer and kept on screen ---- */
+/* As wide as its words up to 300 (North's pop) and never past the window (K9), its own scroll past its height. It grows
+   from the corner it hangs from: the top right, 8 under its control (North P1). */
+.ws-popover { display: flex; flex-direction: column; gap: var(--space-xs); width: max-content; min-width: var(--space-9xl); max-width: min(var(--ws-float-width), calc(100vw - var(--space-xl))); max-height: calc(100dvh - var(--space-xl)); overflow-y: auto; overscroll-behavior: contain; z-index: var(--z-dropdown); padding: var(--space-sm); border: 0; border-radius: var(--ws-radius-card); background: var(--ws-raised); color: var(--color-text-body); box-shadow: var(--ws-shadow-hairline), var(--ws-shadow-pop); transform-origin: top right; }
+.ws-popover__title { font-size: var(--ws-text-body); line-height: calc(var(--space-md) + var(--space-xxs)); font-weight: 500; color: var(--color-text-heading); }
+.ws-popover__form { display: flex; flex-direction: column; gap: var(--space-xs); }
+.ws-popover__form > .ws-btn { align-self: flex-end; }
+/* The top layer (K9): see Menu. It hangs 8 under its control (over it, with --above), right edges flush; a tall one is
+   capped to that side and scrolls inside, never over its control; it flips only when less than 200 px fits, and
+   centres in the window when it is wider than either side of its control. */
+.ws-popover[popover]:not(:popover-open) { display: none; }
+@supports (position-area: block-end) {
+  .ws-popover[popover] { inset: auto; margin: var(--space-xs) 0; position-area: block-end span-inline-start; justify-self: end; position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline, --ws-popover-wide, --ws-popover-wide flip-block; max-height: calc(100% - var(--space-xs) * 2); min-height: calc-size(max-content, min(size, var(--space-9xl))); }
+  .ws-popover--above[popover] { position-area: block-start span-inline-start; transform-origin: bottom right; }
+}
+@position-try --ws-popover-wide { position-area: block-end span-all; justify-self: center; }
+/* Motion (D7, North js@620042 and js@556550: from 4 px toward its control and scale .97 on the settle spring .32 / .1,
+   out the same way over .12 s): as Menu. It grows out of the corner it hangs from and goes back into it, faster;
+   --above (or data-side="top" from an app that places it) turns the nudge and the corner round. Where the browser
+   places it by anchor the nudge rides on the margin, which the flip fallbacks turn with it. */
+.ws-popover { --ws-popover-from: calc(var(--ws-nudge) * -1); }
+.ws-popover--above, .ws-popover[data-side="top"] { --ws-popover-from: var(--ws-nudge); transform-origin: bottom right; }
+@keyframes ws-popover-in { from { opacity: 0; transform: translateY(var(--ws-popover-from)) scale(var(--ws-open-scale)); } }
+@keyframes ws-popover-out { to { opacity: 0; transform: translateY(var(--ws-popover-from)) scale(var(--ws-open-scale)); } }
+@media (prefers-reduced-motion: no-preference) {
+  .ws-popover:not([popover]) { animation: ws-popover-in var(--ws-spring-settle-duration) var(--ws-spring-settle) backwards; }
+  .ws-popover[data-leaving] { animation: ws-popover-out var(--ws-duration-exit) var(--ws-ease-exit) forwards; pointer-events: none; }
+  .ws-popover[popover] { transition: opacity var(--ws-spring-settle-duration) var(--ws-spring-settle), transform var(--ws-spring-settle-duration) var(--ws-spring-settle), margin-block var(--ws-spring-settle-duration) var(--ws-spring-settle), overlay var(--ws-duration-exit) allow-discrete, display var(--ws-duration-exit) allow-discrete; }
+  .ws-popover[popover]:not(:popover-open) { opacity: 0; transform: translateY(var(--ws-popover-from)) scale(var(--ws-open-scale)); transition-duration: var(--ws-duration-exit); transition-timing-function: var(--ws-ease-exit); }
+  @starting-style { .ws-popover[popover]:popover-open { opacity: 0; transform: translateY(var(--ws-popover-from)) scale(var(--ws-open-scale)); } }
+  @supports (position-area: block-end) {
+    .ws-popover[popover]:not([data-side]) { --ws-popover-from: 0px; }
+    .ws-popover[popover]:not([data-side]):not(:popover-open) { margin-block-start: calc(var(--space-xs) - var(--ws-nudge)); }
+    .ws-popover--above[popover]:not([data-side]):not(:popover-open) { margin-block: var(--space-xs) calc(var(--space-xs) - var(--ws-nudge)); }
+    @starting-style {
+      .ws-popover[popover]:not([data-side]):popover-open { margin-block-start: calc(var(--space-xs) - var(--ws-nudge)); }
+      .ws-popover--above[popover]:not([data-side]):popover-open { margin-block: var(--space-xs) calc(var(--space-xs) - var(--ws-nudge)); }
+    }
+  }
+}