@felloinnovations/brand-kit 0.4.0 → 0.5.1

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

@@ -1,6 +1,7 @@
 The kit's marketing piece: for a public page, never a product screen.
 
-The sticky header of a marketing site: the wordmark, five links and a CTA, collapsing to a menu on a phone.
+The sticky header of a marketing site: the wordmark, five links and a CTA; under 60rem the links fold behind a menu
+button by themselves and the CTA stays in the bar.
 
 ## Use it when
 
@@ -9,56 +10,67 @@ The sticky header of a marketing site: the wordmark, five links and a CTA, colla
 ## Not for
 
 - Any product screen inside a product built on this system: a signed-in workspace has no top nav; it has a
-  sidebar (`NavItem`) and, on a page that is not chat-first, `AppShell`'s 56px top bar, both different components
-  for a signed-in product.
+  sidebar (`AppShell`) and, on a page that is not chat-first, a 56px top bar, both different components.
 - A page with no reason to stay reachable while scrolling: a one-screen dialog or a step in a flow does not need
   a sticky nav.
 
 ## Anatomy
 
-- Bar: 72px tall, `--color-white` background, a 1px `--color-border-default` bottom edge, `--layout-margin`
-  (48px) side padding, sticky at `top: 0` with `--z-header` (100) so it stays above page content while scrolling.
-- Wordmark: at the left, `--font-size-lg2` (20px) semibold, `--color-brand-navy`.
-- Links: five, centred, `--font-size-sm` (14px) medium, `--color-text-primary`, `--space-lg` (24px) apart, each
-  with `--color-nav-hover-bg` behind it on hover.
-- CTA: a `KitButton` `primary`, `medium`, at the right.
-- Phone: the five links and their centred row disappear; a 40px menu button (a hamburger icon) appears at the
-  right in their place, `aria-expanded="false"` until opened.
+- Bar: 72px tall, full width, `--color-surface`, a 1px `--color-border-default` bottom edge, `--layout-margin` (48px)
+  sides (16px under 40rem), its content capped at `--layout-content-max` (1344px) and centred like the bands under it,
+  sticky at `top: 0` on `--z-header` (100).
+- Wordmark (`__brand`): a link home, `--font-size-lg2` (20px) semibold, `--color-text-heading`, 44px tall target.
+- Links (`__links`): centred, `--space-lg` (24px) apart. Each link (`__link`) is 14/20 medium, `--color-text-primary`,
+  `--space-xs` by `--space-sm` padding (36px tall), 6px corners, `--color-nav-hover-bg` behind it on hover; 44px tall
+  on touch.
+- CTA (`__cta`): a `KitButton` `primary` `medium` at the right (an `<a>` when it goes to a page). On touch it takes
+  the 44px hit area `KitButton` gives medium.
+- Menu button (`__menu-btn`): 36 by 36, the CTA's height, so the two share a top and bottom edge; 6px corners, a 1px
+  `--color-border-hairline` edge, a 20px icon in `--color-text-heading`; a 44px hit area on touch. Shown only when
+  the bar is folded.
+- Sheet (folded and open): the links in a column under the bar, full width, `--color-surface`, a 1px rule above and
+  below, `--shadow-card-hover`; each link a 44px row at 16px, its words on the wordmark's edge.
 
 ## Variants and sizes
 
-One height (72px), two layouts: the full desktop row, and the phone row (wordmark plus menu button only). There
-is no tablet-specific state named in the brief; a page in between picks whichever the available width allows the
-links to fit without crowding.
+One height (72px), two layouts:
+
+- **Full** (60rem and wider): wordmark, links, CTA.
+- **Folded** (under 60rem, on its own; or forced at any width with `--phone`): wordmark, CTA, menu button.
+
+The breakpoint is the viewport's, because the bar spans the page. Five short links and the CTA fit down to about
+50rem; 60rem leaves room for longer labels.
 
 ## States
 
-- **Default (desktop):** all five links, the CTA, visible.
-- **Hover:** a link's background tints to `--color-nav-hover-bg`; the CTA follows `KitButton`'s own hover.
-- **Focus:** a link or the menu button shows the kit's standard focus treatment; the CTA shows `--shadow-focus-ring`.
-- **Phone (collapsed):** the links are hidden behind the menu button, not removed; `aria-expanded` on the button
-  reflects whether they are shown.
-- **Selected:** not applicable; a marketing nav does not mark a "current" link the way the product's sidebar does.
+- **Default (full):** all five links and the CTA.
+- **Hover:** a link or the menu button tints to `--color-nav-hover-bg`; the CTA follows `KitButton`.
+  Only on a pointer that hovers (`@media (hover: hover)`), so a tap on a phone leaves nothing behind.
+- **Focus:** every link, the wordmark, the CTA and the menu button take the house ring, 2px navy, 2px out.
+- **Folded, closed:** the links are hidden behind the menu button, which says `aria-expanded="false"`.
+- **Folded, open:** `aria-expanded="true"` on the menu button opens the sheet, which rises in over 200ms, and the
+  button keeps the hover tint while it is open. The open state is read from the button itself (`:has()`), so the
+  page's script only toggles `aria-expanded`, the label and the glyph: three bars closed, a cross open, so what the
+  button shows matches what it says ("Close menu").
+- **Selected:** not applicable; a marketing nav does not mark a "current" link.
 - **Pending / disabled / error / empty:** not applicable.
-- **Long label:** a longer link label is accepted as-is; five short, fixed labels are expected, not variable data.
-- **Narrow:** below the point the five links and the CTA no longer fit, the layout switches to the phone state
-  rather than wrapping the links onto a second line.
+- **Long label:** links do not wrap (`white-space: nowrap`); a set too long for the full bar should fold earlier.
 
 ## Behaviour
 
-- Keyboard: the wordmark link, five nav links, and the CTA (or the menu button on a phone) are focusable in
-  document order; opening the phone menu would move focus into it (not shown here, since the brief asks for no
-  script beyond what a component cannot be shown without, and a static menu button demonstrates the collapsed
-  state without needing to open it).
-- Pointer / touch: hover applies only on desktop; the phone's menu button is a 40px target, clearing the touch floor.
-- Motion: none in this static state; a real implementation would slide the phone menu open, matching the
-  product's own panel-opening motion rather than a custom one.
+- Keyboard: wordmark, links, CTA, then the menu button, in document order. Opening the sheet should move focus to its
+  first link and Escape should close it and return focus to the button; that is the page's script, not CSS.
+- Pointer / touch: every act is a 44px target on touch: links and wordmark by their height, the menu button and the
+  CTA by their hit area.
+- Motion: the sheet fades in on a small rise (`ws-rise`, 200ms), only under `prefers-reduced-motion: no-preference`.
 
 ## Content
 
 - Links: one word each, sentence case ("Product", "Pricing", "Customers", "Resources", "About").
-- CTA: the same short, imperative phrase as the hero's primary action ("Book a demo"), so a visitor sees one
-  consistent next step everywhere on the page.
+- CTA: the same short, imperative phrase as the hero's primary act ("Book a demo"). It stays in the folded bar, so
+  booking is one tap away on a phone; do not add a second booking button beside it.
+- Menu button: `aria-label` "Open menu" over three bars, and "Close menu" over a cross while open; `aria-controls`
+  names the links' id. The open glyph: `<path d="M4 4l8 8M12 4l-8 8" .../>` on the same 16 by 16 box.
 
 ## Props
 
@@ -71,18 +83,40 @@ Not a kit export; composed from `KitButton` and tokens. A reusable version would
 
 ## Rules
 
-- **Intentional addition, decided from the system (26 Oct 2026):** the kit ships no nav component; every public
-  page needs one, built here from the kit's own header height, z-index and hover tokens rather than a new set.
-- Sticky at `--z-header`, the token `tokens/tokens.md` itself names for exactly this job ("Z-index," `z-header:
-  100`), ahead of ordinary content but below a dropdown, modal or toast, so a marketing nav slots into the same
-  stacking order the rest of the system already defines.
-- The hover tint is `--color-nav-hover-bg`, the one token in `tokens/tokens.md` named for a nav link's hover
-  (`color-mix(in srgb, var(--color-brand-mid-blue) 5%, transparent)`), not an invented tint.
-- The CTA is `KitButton primary`, matching "a `KitButton` primary at the right," rather than the product's own
-  navy button, since this bar belongs to the public site.
+- **On the page's edge** (4 Nov 2026): the bar's content ran to the window's 48px margin at any width, so on a screen
+  wider than 1440px its wordmark and act sat outside the edge the hero, the cards and the footer share (240px out at
+  1920). The sides are the larger of the 48px margin and what centres a 1344px content column.
+- **Folds by itself** (4 Nov 2026): it used to fold only with the `--phone` class, so at 390px the full bar ran 316px
+  past the screen. A media query now folds it under 60rem; `--phone` stays as a way to force the folded bar.
+- **The CTA stays when folded**: public pages keep "always one way to book within reach on a phone"
+  (`19-public-pages.md`), and the bar is where it is.
+- **44px for every act on a public page** (`14-accessibility.md`): the menu button was 40 and the links 36 on touch.
+  The menu button keeps the CTA's 36px look and takes the rest as a hit area, so the folded bar's two controls line up.
+- Sticky at `--z-header`, ahead of ordinary content but below a dropdown, modal or toast.
+- The hover tint is `--color-nav-hover-bg`, the token named for a nav link's hover.
 
 ## Source
 
 - **Derived from**: the system's header height, z-index and hover tokens (`z-header`, `color-nav-hover-bg`,
-  `layout-margin`, `font-size-lg2`, `font-size-sm`) and `KitButton` for the CTA.
+  `layout-margin`, `font-size-lg2`, `font-size-sm`), `KitButton` for the CTA, the geometry check at 320 and 390, and
+  the public page rules (`19-public-pages.md`).
 - **Precedent**: an intentional addition decided from the system, 26 Oct 2026.
+
+## Markup
+
+```html
+<nav class="ws-marketing-nav" aria-label="Main">
+  <a class="ws-marketing-nav__brand" href="/">Fello</a>
+  <div class="ws-marketing-nav__links" id="site-menu">
+    <a class="ws-marketing-nav__link" href="/product">Product</a>
+    <a class="ws-marketing-nav__link" href="/pricing">Pricing</a>
+    <a class="ws-marketing-nav__link" href="/customers">Customers</a>
+  </div>
+  <div class="ws-marketing-nav__cta"><a class="ws-kit-button ws-kit-button--medium ws-kit-button--primary" href="/demo">Book a demo</a></div>
+  <button class="ws-marketing-nav__menu-btn" type="button" aria-label="Open menu" aria-expanded="false" aria-controls="site-menu">
+    <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
+  </button>
+</nav>
+```
+
+Styles: the `MarketingNav` block (`components/MarketingNav/style.css`), plus `KitButton` for the CTA.

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

@@ -1,6 +1,6 @@
-<!-- @dsCard group="Marketing" height=248 -->
+<!-- @dsCard group="Marketing" height=632 -->
 <!doctype html>
-<html>
+<html lang="en">
 <head>
 <meta charset="utf-8">
 <title>MarketingNav</title>
@@ -11,9 +11,9 @@
 <div class="ws-stage ws-stage--column" style="padding: 0 0 var(--ws-gap-component) 0;">
 
   <div class="ws-stack">
-    <span class="ws-muted" style="padding: 0 var(--ws-gap-component);">Desktop, 72px, sticky at --z-header</span>
+    <span class="ws-muted" style="padding: 0 var(--ws-gap-component);">Desktop, 72px, sticky at --z-header; under 60rem it folds by itself</span>
     <nav class="ws-marketing-nav" aria-label="Main">
-      <div class="ws-marketing-nav__brand">Fello</div>
+      <a class="ws-marketing-nav__brand" href="#" onclick="return false;">Fello</a>
       <div class="ws-marketing-nav__links">
         <a class="ws-marketing-nav__link" href="#" onclick="return false;">Product</a>
         <a class="ws-marketing-nav__link" href="#" onclick="return false;">Pricing</a>
@@ -21,20 +21,49 @@
         <a class="ws-marketing-nav__link" href="#" onclick="return false;">Resources</a>
         <a class="ws-marketing-nav__link" href="#" onclick="return false;">About</a>
       </div>
-      <div class="ws-marketing-nav__cta"><button class="ws-kit-button ws-kit-button--medium ws-kit-button--primary">Book a demo</button></div>
+      <div class="ws-marketing-nav__cta"><a class="ws-kit-button ws-kit-button--medium ws-kit-button--primary" href="#" onclick="return false;">Book a demo</a></div>
+      <button class="ws-marketing-nav__menu-btn" type="button" aria-label="Open menu" aria-expanded="false">
+        <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
+      </button>
     </nav>
   </div>
 
   <div class="ws-stack">
-    <span class="ws-muted" style="padding: 0 var(--ws-gap-component);">Phone: the links collapse behind a menu</span>
+    <span class="ws-muted" style="padding: 0 var(--ws-gap-component);">Folded (forced here with --phone): the links behind the menu, the act stays in the bar</span>
     <nav class="ws-marketing-nav ws-marketing-nav--phone" aria-label="Main">
-      <div class="ws-marketing-nav__brand">Fello</div>
-      <button class="ws-marketing-nav__menu-btn" aria-label="Open menu" aria-expanded="false">
+      <a class="ws-marketing-nav__brand" href="#" onclick="return false;">Fello</a>
+      <div class="ws-marketing-nav__links">
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Product</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Pricing</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Customers</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Resources</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">About</a>
+      </div>
+      <div class="ws-marketing-nav__cta"><a class="ws-kit-button ws-kit-button--medium ws-kit-button--primary" href="#" onclick="return false;">Book a demo</a></div>
+      <button class="ws-marketing-nav__menu-btn" type="button" aria-label="Open menu" aria-expanded="false">
         <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M2.5 4.5h11M2.5 8h11M2.5 11.5h11" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
       </button>
     </nav>
   </div>
 
+  <div class="ws-stack" style="min-height: 360px;">
+    <span class="ws-muted" style="padding: 0 var(--ws-gap-component);">Folded and open: aria-expanded="true" drops the links in a sheet under the bar, 44px rows; the glyph is a cross</span>
+    <nav class="ws-marketing-nav ws-marketing-nav--phone" aria-label="Main">
+      <a class="ws-marketing-nav__brand" href="#" onclick="return false;">Fello</a>
+      <div class="ws-marketing-nav__links" id="mn-menu">
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Product</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Pricing</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Customers</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">Resources</a>
+        <a class="ws-marketing-nav__link" href="#" onclick="return false;">About</a>
+      </div>
+      <div class="ws-marketing-nav__cta"><a class="ws-kit-button ws-kit-button--medium ws-kit-button--primary" href="#" onclick="return false;">Book a demo</a></div>
+      <button class="ws-marketing-nav__menu-btn" type="button" aria-label="Close menu" aria-expanded="true" aria-controls="mn-menu">
+        <svg viewBox="0 0 16 16" fill="none" aria-hidden="true"><path d="M4 4l8 8M12 4l-8 8" stroke="currentColor" stroke-width="1.5" stroke-linecap="round"/></svg>
+      </button>
+    </nav>
+  </div>
+
 </div>
 </body>
 </html>

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

@@ -0,0 +1,45 @@
+/* ---- MarketingNav: the public site's 72 px top bar, sticky; under 60rem its links fold behind a menu button and the act stays ---- */
+/* The bar is full width, its content inside the same 1344 px cap as the bands under it, so on a wide screen the wordmark
+   and the act stay on the hero's, the cards' and the footer's edges instead of riding out to the window's. */
+.ws-marketing-nav { position: sticky; top: 0; z-index: var(--z-header); width: 100%; height: calc(var(--space-4xl) + var(--space-xs)); display: flex; align-items: center; gap: var(--space-xs); padding: 0 max(var(--layout-margin), calc((100% - var(--layout-content-max)) / 2)); background: var(--color-surface); border-bottom: var(--ws-line) solid var(--color-border-default); }
+.ws-marketing-nav__brand { flex: 0 0 auto; display: inline-flex; align-items: center; min-height: var(--ws-touch-public); font-size: var(--font-size-lg2); line-height: var(--ws-leading-title); font-weight: 600; color: var(--color-text-heading); text-decoration: none; }
+.ws-marketing-nav__links { display: flex; align-items: center; gap: var(--space-lg); margin: 0 auto; }
+.ws-marketing-nav__link { display: inline-flex; align-items: center; padding: var(--space-xs) var(--space-sm); border-radius: var(--ws-radius-row); font-size: var(--font-size-sm); line-height: calc(var(--space-md) + var(--space-xxs)); font-weight: 500; color: var(--color-text-primary); text-decoration: none; white-space: nowrap; }
+.ws-marketing-nav__menu-btn[aria-expanded="true"] { background: var(--color-nav-hover-bg); }
+@media (hover: hover) { .ws-marketing-nav__link:hover, .ws-marketing-nav__menu-btn:hover { background: var(--color-nav-hover-bg); } }
+.ws-marketing-nav__cta { flex: 0 0 auto; }
+/* The menu button is the CTA's height (KitButton medium, 36), so the two sit on one top and bottom edge; on touch it
+   takes a 44 px hit area the way the CTA does. Open, it keeps the hover tint. */
+.ws-marketing-nav__menu-btn { position: relative; display: none; flex: 0 0 auto; align-items: center; justify-content: center; width: calc(var(--space-xl) + var(--space-xxs)); height: calc(var(--space-xl) + var(--space-xxs)); padding: 0; border-radius: var(--ws-radius-row); border: var(--ws-line) solid var(--color-border-hairline); background: var(--color-surface); color: var(--color-text-heading); cursor: pointer; }
+.ws-marketing-nav__menu-btn svg { width: var(--ws-icon-lg); height: var(--ws-icon-lg); }
+@media (pointer: coarse) {
+  .ws-marketing-nav__link { min-height: var(--ws-touch-public); }
+  .ws-marketing-nav__menu-btn::after { content: ""; position: absolute; inset: min(0px, calc((100% - var(--ws-touch-public)) / 2)); }
+}
+
+/* Folded (under 60rem on its own, or forced with --phone): the links go behind the menu button; the act stays in the bar,
+   so booking is always one tap away. The button's aria-expanded="true" opens the links as a sheet under the bar. */
+@media (max-width: 60rem) {
+  .ws-marketing-nav > .ws-marketing-nav__links { display: none; }
+  .ws-marketing-nav > .ws-marketing-nav__brand { margin-right: auto; }
+  .ws-marketing-nav > .ws-marketing-nav__menu-btn { display: inline-flex; }
+  .ws-marketing-nav:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) > .ws-marketing-nav__links { position: absolute; top: 100%; left: 0; right: 0; display: flex; flex-direction: column; align-items: stretch; gap: 0; margin: 0; padding-block: var(--space-xs) var(--space-md); padding-inline: inherit; background: var(--color-surface); border-block: var(--ws-line) solid var(--color-border-default); box-shadow: var(--shadow-card-hover); }
+  .ws-marketing-nav:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) .ws-marketing-nav__link { min-height: var(--ws-touch-public); margin-inline: calc(var(--space-sm) * -1); padding-block: 0; font-size: var(--font-size-md); }
+}
+.ws-marketing-nav--phone > .ws-marketing-nav__links { display: none; }
+.ws-marketing-nav--phone > .ws-marketing-nav__brand { margin-right: auto; }
+.ws-marketing-nav--phone > .ws-marketing-nav__menu-btn { display: inline-flex; }
+.ws-marketing-nav--phone:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) > .ws-marketing-nav__links { position: absolute; top: 100%; left: 0; right: 0; display: flex; flex-direction: column; align-items: stretch; gap: 0; margin: 0; padding-block: var(--space-xs) var(--space-md); padding-inline: inherit; background: var(--color-surface); border-block: var(--ws-line) solid var(--color-border-default); box-shadow: var(--shadow-card-hover); }
+.ws-marketing-nav--phone:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) .ws-marketing-nav__link { min-height: var(--ws-touch-public); margin-inline: calc(var(--space-sm) * -1); padding-block: 0; font-size: var(--font-size-md); }
+/* The sheet fades in on a small rise. */
+@media (prefers-reduced-motion: no-preference) and (max-width: 60rem) {
+  .ws-marketing-nav:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) > .ws-marketing-nav__links { animation: ws-rise var(--transition-default) backwards; }
+}
+@media (prefers-reduced-motion: no-preference) {
+  .ws-marketing-nav--phone:has(> .ws-marketing-nav__menu-btn[aria-expanded="true"]) > .ws-marketing-nav__links { animation: ws-rise var(--transition-default) backwards; }
+}
+/* A phone's 16 px page margin. */
+@media (max-width: 40rem) {
+  .ws-marketing-nav { padding: 0 var(--space-md); }
+}
+.ws-marketing-nav--phone { padding: 0 var(--space-md); }

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

@@ -0,0 +1,129 @@
+A grid of yes-or-no answers: one row per question, one column per source, each cell lit when the answer is yes. Seth's
+answers grid (305:2341): which AI assistants named you, for each of the questions a buyer might ask.
+
+## Use it when
+
+- The same few questions are put to the same few sources, and the pattern of yes and no is the finding ("Gemini names
+  you for every question; ChatGPT only by name").
+- There are up to about six columns and eight rows: a grid read at a glance.
+
+## Not for
+
+- Records with real values in their columns: use `Table`.
+- One score per check: use `CheckRow`.
+- A dense field of values in tones (a week by hour): use `Heatmap`.
+
+## Anatomy
+
+- A rim (`.ws-matrix`): the tray grey (`--ws-tray`), 1 px of it round the rows (`--ws-rim`), 8 px corners outside and 7
+  inside (`--ws-radius-card-inner`) on the first and last row. No outline, no shadow.
+- One column template for the head and every row: 20 in, 16 out, a 200 px question column, then equal columns 2 apart
+  (`--ws-matrix-first`, `--ws-matrix-cols`, default 4). The heads centre over their cells because both use it.
+- Rows: cream, joined by 0.5 px lines (`--ws-edge`), full width, drawn inside the top of the row (an inset line), so a
+  row's 48 includes its line as in Seth's frame.
+- Head (`__head`): 16 above and below (54 tall); "Question" in 13 / 18 medium muted (`__corner`); each source a 20 px mark
+  (`__mark`, paste the source's official mark) and its name, 15 / 22 semibold navy, 8 apart, centred (`__col`, which
+  also carries the name as its `aria-label`).
+- Body rows: at least 48, 1 px above and below, so each cell is 46 tall.
+- The question (`__q`, a button in `__q-wrap`): 14 / 20 medium navy with a 1 px dotted underline, the cue that the whole
+  question shows; it wraps rather than hiding words.
+- A cell (`__cell`): 2 px corners; named (`--yes`) the strong tone (`--ws-rating-strong`, teal), not named the empty
+  track (`--ws-track`); the source's mark centred in it, dimmed to 0.3 (`--ws-dim`) on the empty track. Its words
+  ("Named you", "Not named") are for a screen reader (`ws-sr`).
+- The note (`__tip`, Seth's navy tip 305:2272): the act fill (`--color-text-heading`), 4 px corners, 10 / 12 inside,
+  14 / 20 words in `--ws-on-act` that wrap at 300, left-anchored so its words start on the question's, a 12 x 6 caret over
+  the word, 3 above it. No shadow.
+- Foot (`__foot`, a `details`): Seth's "Behind the answers", a folded row in the rim, 16 above and below, 20 in and 16 out;
+  the title 15 / 22 semibold, a 13 / 18 medium muted line, a 16 px chevron that turns when open.
+
+## Variants and sizes
+
+| Part | Value |
+| --- | --- |
+| Question column | 200 (`--ws-matrix-first`) |
+| Source columns | equal (`--ws-matrix-cols`), 2 apart |
+| Head | 54 |
+| Row | 48, cells 46 |
+| Dim | 0.2 (`--ws-matrix-dim`) |
+| Note | wraps at 300, caret 12 x 6 |
+| Narrow (under 40rem) | the question column takes the room, each source 32 wide, its mark only; the foot's line under its title |
+
+## States
+
+- **Default**: as above.
+- **Hover a row** (Seth 305:2143): every other body row's question and cells drop to 0.2; row grounds, lines, the head
+  and the foot stay; the hovered row does not change. The whole question shows in the note.
+- **Focus** (keyboard, or a tap that focuses the question): the same dim and the same note. A page script may set
+  `aria-expanded="true"` on the question to keep the note open after a tap where the browser does not focus buttons.
+- **Loading**: every cell a ghost under the shimmer (`__cell ws-shimmer`), the questions and sources shown at
+  once; still under reduced motion.
+- **Narrow**: source names drop to their marks in 32 px columns (a screen reader still hears each source through the
+  head's label), and the foot's line drops under its title.
+- **Long question**: it wraps and its row grows; keep questions to a few words ("A buyer") and put the full question
+  in the note.
+
+## Behaviour
+
+- Keyboard: each question is a button, in row order; focusing it dims the other rows and shows the note
+  (`aria-describedby` points at the note, so a screen reader hears the full question). Under keyboard focus the note sits
+  4 px higher, so its caret clears the focus ring. The note covers the row above, so Escape must hide it (WCAG 1.4.13):
+  a page script sets `data-tip="hidden"` on the row (the note hides while the pointer stays) and clears it when the
+  pointer or focus leaves.
+- Pointer: hovering anywhere on a row does the same.
+- Motion: the dim and the note fade on hover's 200 ms after North's 40 ms hover intent; the note leaves on the 120 ms
+  exit. Under reduced motion both change at once.
+
+## Content
+
+- A question is a short label for a longer question ("A buyer" for "I'm thinking of buying a home in Chagrin Falls, OH.
+  Which real estate agent or team should I talk to?"); the note holds the long one.
+- A source is its own name, with its official mark.
+- No em dashes.
+
+## Rules
+
+- **One template for head and body**: never size a head cell on its own.
+- **The full question is never hover-only** (`14-accessibility.md`): focus and tap show it too.
+- **A cell's state is never colour alone**: its screen-reader words say it, and the lit and empty grounds differ in
+  lightness, not only hue.
+- **No clip**: the note may cover the head and the row above; the rim never cuts it.
+
+## Source
+
+**Derived from**: Seth's Grow audit report, "Which AI platforms mention you" (305:2280, the grid 305:2341, the hover
+305:2143, the tip 305:2272), on the kit's rim (D5), rating tones (D10) and hover timing (D7). **Precedent**: new in
+0.5.0 (4 Nov 2026).
+
+## Markup
+
+```html
+<div class="ws-matrix">
+  <div class="ws-matrix__table" role="table" aria-label="Which AI assistants named you, by question">
+    <div class="ws-matrix__head" role="rowgroup">
+      <div class="ws-matrix__row" role="row">
+        <span class="ws-matrix__corner" role="columnheader">Question</span>
+        <span class="ws-matrix__col" role="columnheader" aria-label="Gemini"><svg class="ws-matrix__mark" viewBox="0 0 20 20" aria-hidden="true"><!-- the official mark --></svg><span class="ws-matrix__name" aria-hidden="true">Gemini</span></span>
+      </div>
+    </div>
+    <div class="ws-matrix__body" role="rowgroup">
+      <div class="ws-matrix__row" role="row">
+        <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q" aria-describedby="mx-buyer">A buyer</button><span class="ws-matrix__tip" role="tooltip" id="mx-buyer">I'm thinking of buying a home in Chagrin Falls, OH. Which real estate agent or team should I talk to?</span></span></span>
+        <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" aria-hidden="true"><!-- the official mark --></svg><span class="ws-sr">Named you</span></span>
+      </div>
+    </div>
+  </div>
+  <details class="ws-matrix__foot">
+    <summary><span class="ws-matrix__foot-title">Behind the answers</span><span class="ws-matrix__foot-line">What to fix first, where they looked</span><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg></summary>
+    <div class="ws-matrix__foot-body"><p class="ws-body">What they read, and what to fix first.</p></div>
+  </details>
+</div>
+```
+
+Set `style="--ws-matrix-cols: 3"` on `.ws-matrix` for three sources.
+
+## Styles
+
+`design-system/components/Matrix/style.css`, in `bundle.css` and `fello.css`. Dark and the navy ground come from the
+tokens (`--ws-tray`, `--ws-edge`, `--ws-track`, `--ws-rating-strong`; the note is `--color-text-heading` with
+`--ws-on-act` words, so it turns light with dark words in dark). In dark a mark on a named cell takes the ground's dark
+(`--color-bg-page`), since the strong teal turns light there. The rim is a size container named `ws-matrix`.

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

@@ -0,0 +1,99 @@
+<!-- @dsCard group="Data" height=720 -->
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>Matrix</title>
+<link rel="stylesheet" href="../../tokens.css">
+<link rel="stylesheet" href="../bundle.css">
+</head>
+<body>
+<div class="ws-stage ws-stage--column">
+
+  <div class="ws-stack">
+    <span class="ws-muted">Seth's answers grid: one column template for the head and every row, so each source's name centres over its cells; hover or focus a question to dim the other rows and read it whole (the marks here are stand-ins: paste each source's official mark in __mark)</span>
+    <div class="ws-matrix">
+      <div class="ws-matrix__table" role="table" aria-label="Which AI assistants named you, by question">
+        <div class="ws-matrix__head" role="rowgroup">
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__corner" role="columnheader">Question</span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="ChatGPT"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-matrix__name" aria-hidden="true">ChatGPT</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Gemini"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-matrix__name" aria-hidden="true">Gemini</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Claude"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-matrix__name" aria-hidden="true">Claude</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Perplexity"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-matrix__name" aria-hidden="true">Perplexity</span></span>
+          </div>
+        </div>
+        <div class="ws-matrix__body" role="rowgroup">
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q" aria-describedby="mx-q1">Finding an agent</button><span class="ws-matrix__tip" role="tooltip" id="mx-q1">Who are the best real estate agents in Chagrin Falls, OH?</span></span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-sr">Not named</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-sr">Not named</span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-sr">Not named</span></span>
+          </div>
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q" aria-describedby="mx-q2">A buyer</button><span class="ws-matrix__tip" role="tooltip" id="mx-q2">I'm thinking of buying a home in Chagrin Falls, OH. Which real estate agent or team should I talk to?</span></span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-sr">Not named</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-sr">Named you</span></span>
+          </div>
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q" aria-describedby="mx-q3">A seller</button><span class="ws-matrix__tip" role="tooltip" id="mx-q3">I want to sell my house in Chagrin Falls, OH this spring. Who should list it?</span></span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-sr">Not named</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-sr">Not named</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-sr">Named you</span></span>
+          </div>
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q" aria-describedby="mx-q4">You by name, with your team's name and the brokerage</button><span class="ws-matrix__tip" role="tooltip" id="mx-q4">What do people say about Priya Nair and the Nair Group at Howard Hanna?</span></span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-sr">Named you</span></span>
+            <span class="ws-matrix__cell ws-matrix__cell--yes" role="cell"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-sr">Named you</span></span>
+          </div>
+        </div>
+      </div>
+      <details class="ws-matrix__foot">
+        <summary><span class="ws-matrix__foot-title">Behind the answers</span><span class="ws-matrix__foot-line">What to fix first, where they looked</span><svg viewBox="0 0 16 16" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M4 6l4 4 4-4"/></svg></summary>
+        <div class="ws-matrix__foot-body"><p class="ws-body">ChatGPT looked at Zillow and two brokerage pages; none of them name your service area. Start with your Google Business Profile.</p></div>
+      </details>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 420px;">
+    <span class="ws-muted">Loading: every cell a ghost under the shimmer, the questions and sources shown at once</span>
+    <div class="ws-matrix" aria-busy="true">
+      <div class="ws-matrix__table" role="table" aria-label="Which AI assistants named you, checking">
+        <div class="ws-matrix__head" role="rowgroup">
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__corner" role="columnheader">Question</span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="ChatGPT"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><circle cx="10" cy="10" r="6"/></svg><span class="ws-matrix__name" aria-hidden="true">ChatGPT</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Gemini"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="currentColor" aria-hidden="true"><path d="M10 3l1.8 5.2L17 10l-5.2 1.8L10 17l-1.8-5.2L3 10l5.2-1.8z"/></svg><span class="ws-matrix__name" aria-hidden="true">Gemini</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Claude"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round" aria-hidden="true"><path d="M10 4l6 12H4z"/></svg><span class="ws-matrix__name" aria-hidden="true">Claude</span></span>
+            <span class="ws-matrix__col" role="columnheader" aria-label="Perplexity"><svg class="ws-matrix__mark" viewBox="0 0 20 20" fill="none" stroke="currentColor" stroke-width="1.5" aria-hidden="true"><rect x="4.5" y="4.5" width="11" height="11" rx="1"/></svg><span class="ws-matrix__name" aria-hidden="true">Perplexity</span></span>
+          </div>
+        </div>
+        <div class="ws-matrix__body" role="rowgroup">
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q">A buyer</button></span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+          </div>
+          <div class="ws-matrix__row" role="row">
+            <span class="ws-matrix__q-cell" role="rowheader"><span class="ws-matrix__q-wrap"><button type="button" class="ws-matrix__q">A seller</button></span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+            <span class="ws-matrix__cell ws-shimmer" role="cell"><span class="ws-sr">Checking</span></span>
+          </div>
+        </div>
+      </div>
+    </div>
+  </div>
+
+</div>
+</body>
+</html>