@felloinnovations/brand-kit 0.5.1 → 0.5.3

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

@@ -1,16 +1,23 @@
-Ordered steps on a line that fills: done is a tick, the one in hand is ringed, the rest wait their turn.
+Ordered steps on a line that fills: done is a tick, the one in hand is ringed, the rest wait their turn. Down the page
+by default; `--across` lays the stages left to right; `--milestones` makes them dated points on one row.
 
 ## Use it when
 
 - Something happens in a known sequence and the person benefits from seeing where it is (a setup's path, an onboarding
   checklist, an audit).
 - Several things run at once rather than in order (a scan's sources), and the page needs to say which are being read right now.
+- One thing's stages under its title (an onboarding's Scheduling to Graduated, a deal's stages): `--across`.
+- One thing's dated milestones, each reached or not, measured from the start (signed, first value, first agreement):
+  `--milestones`. A variant, not its own component: it is the same marks, line and done or waiting states on a row.
 
 ## Not for
 
 - A share of a goal or a percent: use `GoalTicks` or `Ring`.
 - A count out of a whole: use `TickRow`.
 - A plain loading wait with no named steps: a working chip or spinner, not a `Stepper`.
+- What happened, in order, grouped by day: use `Timeline`.
+- Many things across their stages at once: use `KanbanBoard`.
+- Phases and tasks as bars across dates (a plan): not in the kit yet (issue #24).
 
 ## Anatomy
 
@@ -20,6 +27,17 @@ Ordered steps on a line that fills: done is a tick, the one in hand is ringed, t
 - Waiting: the cream with the fine hairline ring (drawn inside), muted grey number.
 - Connecting line: a 1 px (`calc(--ws-hairline * 2)`) line between marks in `--ws-edge`, filled teal top to bottom when its step above is done.
 - Title: 14 / 20 medium navy, its first line level with the mark; a note under it in `ws-muted` (how far, or "Done").
+- A stall (`__late` on the note, with `ws-muted`): the note in needs-you words (`--ws-word-needs`), never a colour on
+  the mark: the in-hand ring stays navy.
+- Across (`--across`): equal columns, each at least 120 (`--space-7xl`), the mark centred over its words, 8 between
+  them; the line runs at the mark's middle from its right edge to the next mark's left edge and fills left to right
+  (`ws-grow`). Wider than its column, the track scrolls inside and fades at the edge that hides stages (the house
+  `ws-scroll-edges` cue), and the in-hand stage opens in view (`scroll-initial-target`).
+- Milestones (`--milestones`): an 8 px dot, 8 to the words, the name as the title and its measure beside it in
+  `ws-muted` (a date, or days since the start), on one line; the line takes the room left between the words and the
+  next dot, 8 from each. Reached is the teal dot; not reached a 1 px ring (`--ws-edge-card`) with "Not yet", and at
+  most one quiet act beside it (`ws-btn ws-btn--text`). The line after a milestone fills when the next is reached. 4 px
+  of room on every side, pulled back by a margin, so the act's focus ring is never cut.
 
 ## Variants and sizes
 
@@ -27,12 +45,18 @@ Ordered steps on a line that fills: done is a tick, the one in hand is ringed, t
 | --- | --- |
 | In order (default) | The first step not done is the one in hand, found automatically |
 | Side by side (`active` set on any step) | Only steps with `active: true` are in hand (several at once); none active means none are in hand, every undone step simply waits |
+| Across (`ws-stepper--across`) | The same steps left to right, a mark over its words; for a thing's stages under its title |
+| Milestones (`ws-stepper--milestones`) | Dated points on one row: dots, no numbers, no in-hand ring; each reached or not yet |
 
 ## States
 
 - Default: the first undone step is in hand, ringed in navy; everything after it waits.
 - In hand (parallel): rings navy and breathes on `ws-working`, because something is actually in progress right now.
 - Waiting (parallel, nothing active): every undone step sits quiet, no ring, no breathing; nothing has started reading yet.
+- Stalled: the in-hand step has sat past its expected time. Its note says so with the time, in needs-you words
+  ("Stalled 40 days"); the ring stays navy and nothing breathes.
+- Late (milestones): reached past its target; the measure says by how much, in needs-you words ("52 days, 7 late").
+- Not yet (milestones): the ring dot, "Not yet", and the one act if the person can log it ("Add date").
 - Done: a filled teal circle with a check, popping in (`ws-pop`) the moment it completes, and the line below it filling down (`ws-grow-up`) the same moment.
 - Disabled / error / hover / focus / pressed / selected: do not apply; a step is a status, not a control.
 - Reduced motion: ticks, rings and the filling line are all simply in their final state, no pop, breathe or growth.
@@ -46,26 +70,36 @@ Ordered steps on a line that fills: done is a tick, the one in hand is ringed, t
 
 ## Content
 
-- A step's title says what it does, not just its name ("Writing the three recommendations", not "Step 3").
+- A step's title says what it does, not just its name ("Writing the three recommendations", not "Step 3"). A stage's
+  title is the stage's own name, sentence case ("Review and handoff").
 - The note under an in-hand step says how far ("2 of 4") or what is happening now ("Reading now"); a waiting step carries no note.
+- A stall or a late milestone says the time in words, never a bare "40d" or a colour alone.
+- A milestone's name is plain words, not an acronym the reader must know ("First value", not "TTV1"); its measure is a
+  date ("Sep 11") or days since the start ("15 days").
 
 ## Props
 
 | Name | Type | Meaning |
 | --- | --- | --- |
 | `label` | `string` | Names the whole sequence for the `<ol>` |
-| `steps` | `{ key, title, note?, done, active? }[]` | Each step; `active` turns on the side-by-side mode across the whole list |
+| `steps` | `{ key, title, note?, done, active?, late? }[]` | Each step; `active` turns on the side-by-side mode across the whole list; `late` puts the note in needs-you words |
+| `layout` | `"down" \| "across" \| "milestones"` | Down the page (default), stages left to right, or dated milestones on a row |
 
 ## Rules
 
 - Sequences and waits are steps; do not reach for a progress bar or a percent where a named sequence says it plainer.
 - The in-hand ring is always navy; a step never borrows a chart's tone (teal, salmon, purple) for its own status beyond "done".
+  A stall or a late milestone is said in needs-you words, not painted on the mark.
+- Across needs room for every stage at 120; on a phone it scrolls with the in-hand stage in view. Where every stage
+  must show at once in a narrow column, use the default, down the page.
+- One act at most on a milestone row, on a milestone not yet reached; a step or a milestone itself never takes a click.
 - A step that cannot start yet (no data, blocked) still appears in its place, waiting; it is never removed from the list.
 
 ## Source
 
 **Derived from**: the brand kit's own guidance that sequences and waits are drawn as steps, not a progress bar
-(21 Oct 2026). **Precedent**: the first product built on the system.
+(21 Oct 2026). **Precedent**: the first product built on the system. `--across` and `--milestones`: the Customer
+Value onboarding detail (Hemanth, 10 Nov 2026), whose stage track and milestone row were built by hand for want of them.
 
 ## Markup
 
@@ -83,7 +117,49 @@ Ordered steps on a line that fills: done is a tick, the one in hand is ringed, t
 </ol>
 ```
 
+Across: a thing's stages under its title (the line under a done stage fills; the stalled note under the in-hand one).
+
+```html
+<ol class="ws-stepper ws-stepper--across" aria-label="Onboarding stages">
+  <li class="ws-stepper__item">
+    <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow"></span></span>
+    <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" fill="none"><path d="M3.5 8.5L6.5 11.5L12.5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">Optimizing</span></span>
+  </li>
+  <li class="ws-stepper__item" aria-current="step">
+    <span class="ws-stepper__line"></span>
+    <span class="ws-stepper__mark ws-stepper__mark--current" aria-hidden="true">5</span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">Review and handoff</span><span class="ws-muted ws-stepper__late">Stalled 40 days</span></span>
+  </li>
+  <li class="ws-stepper__item">
+    <span class="ws-stepper__mark ws-stepper__mark--wait" aria-hidden="true">6</span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">Graduated</span></span>
+  </li>
+</ol>
+```
+
+Milestones: reached, late and not yet, with the one act.
+
+```html
+<ol class="ws-stepper ws-stepper--milestones" aria-label="Milestones">
+  <li class="ws-stepper__item">
+    <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow"></span></span>
+    <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"></span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">Signed</span><span class="ws-muted">Sep 11</span></span>
+  </li>
+  <li class="ws-stepper__item">
+    <span class="ws-stepper__line"></span>
+    <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"></span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">First agreement</span><span class="ws-muted ws-stepper__late">52 days, 7 late</span></span>
+  </li>
+  <li class="ws-stepper__item">
+    <span class="ws-stepper__mark ws-stepper__mark--wait" aria-hidden="true"></span>
+    <span class="ws-stepper__body"><span class="ws-stepper__title">Graduated</span><span class="ws-muted">Not yet</span><button type="button" class="ws-btn ws-btn--text" aria-label="Add the graduation date">Add date</button></span>
+  </li>
+</ol>
+```
+
 ## Styles
 
 `design-system/components/Stepper/style.css`: `ws-stepper`, `__item`, `__line`, `__line-fill`, `__mark` with `--done`,
-`--current`, `--wait`; `__body`, `__title`.
+`--current`, `--wait`; `__body`, `__title`, `__late`; layouts `ws-stepper--across` and `ws-stepper--milestones`.

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

@@ -1,4 +1,4 @@
-<!-- @dsCard group="Progress" height=314 -->
+<!-- @dsCard group="Progress" height=520 -->
 <!doctype html>
 <html>
 <head>
@@ -104,6 +104,69 @@
     </ol>
   </div>
 
+  <div class="ws-stack" style="width: 100%;">
+    <span class="ws-muted">Across: four stages done, the fifth in hand and stalled, the last to come</span>
+    <ol class="ws-stepper ws-stepper--across" aria-label="Onboarding stages">
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" fill="none"><path d="M3.5 8.5L6.5 11.5L12.5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Scheduling</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow" style="animation-delay: 30ms;"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" fill="none"><path d="M3.5 8.5L6.5 11.5L12.5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Implementing</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow" style="animation-delay: 60ms;"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" fill="none"><path d="M3.5 8.5L6.5 11.5L12.5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Enabling</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow" style="animation-delay: 90ms;"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"><svg viewBox="0 0 16 16" width="12" height="12" fill="none"><path d="M3.5 8.5L6.5 11.5L12.5 5" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round"/></svg></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Optimizing</span></span>
+      </li>
+      <li class="ws-stepper__item" aria-current="step">
+        <span class="ws-stepper__line"></span>
+        <span class="ws-stepper__mark ws-stepper__mark--current" aria-hidden="true">5</span>
+        <span class="ws-stepper__body">
+          <span class="ws-stepper__title">Review and handoff</span>
+          <span class="ws-muted ws-stepper__late">Stalled 40 days</span>
+        </span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__mark ws-stepper__mark--wait" aria-hidden="true">6</span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Graduated</span></span>
+      </li>
+    </ol>
+  </div>
+
+  <div class="ws-stack" style="width: 100%;">
+    <span class="ws-muted">Milestones: three reached (one late), the last not yet</span>
+    <ol class="ws-stepper ws-stepper--milestones" aria-label="Milestones">
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Signed</span><span class="ws-muted">Sep 11</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"><span class="ws-stepper__line-fill ws-grow" style="animation-delay: 30ms;"></span></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">First value</span><span class="ws-muted">15 days</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__line"></span>
+        <span class="ws-stepper__mark ws-stepper__mark--done" aria-hidden="true"></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">First agreement</span><span class="ws-muted ws-stepper__late">52 days, 7 late</span></span>
+      </li>
+      <li class="ws-stepper__item">
+        <span class="ws-stepper__mark ws-stepper__mark--wait" aria-hidden="true"></span>
+        <span class="ws-stepper__body"><span class="ws-stepper__title">Graduated</span><span class="ws-muted">Not yet</span><button type="button" class="ws-btn ws-btn--text" aria-label="Add the graduation date">Add date</button></span>
+      </li>
+    </ol>
+  </div>
+
 </div>
 </body>
 </html>

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

@@ -11,3 +11,32 @@
 .ws-stepper__body { display: flex; flex: 1; min-width: 0; flex-direction: column; padding-top: var(--space-3xs); }
 .ws-stepper__title { font-size: var(--ws-text-body); line-height: calc(var(--space-md) + var(--space-xxs)); font-weight: 500; color: var(--color-text-heading); }
 
+/* A stall in words: the in-hand step's note when it has sat too long ("40 days in this stage"), and a milestone past its target. */
+.ws-stepper__late { color: var(--ws-word-needs); }
+/* Across: stages left to right, each mark over its words, the line running mark to mark. Equal columns (so the line
+   can reach the next mark's centre from its own item), each at least 120; past that the track scrolls inside and fades
+   at the edge that hides stages, like Segmented's stages. */
+.ws-stepper--across { display: grid; grid-auto-flow: column; grid-auto-columns: minmax(var(--space-7xl), 1fr); overflow-x: auto; scrollbar-width: none; }
+.ws-stepper--across::-webkit-scrollbar { display: none; }
+.ws-stepper--across > .ws-stepper__item { flex-direction: column; align-items: center; gap: var(--space-xs); padding: 0 var(--space-xxs); text-align: center; }
+.ws-stepper--across .ws-stepper__line { top: calc(var(--space-lg) / 2 - var(--ws-hairline)); bottom: auto; left: calc(50% + var(--space-lg) / 2); right: calc(var(--space-lg) / 2 - 50%); width: auto; height: calc(var(--ws-hairline) * 2); }
+.ws-stepper--across .ws-stepper__line-fill { transform-origin: left; }
+.ws-stepper--across .ws-stepper__body { align-items: center; padding-top: 0; }
+.ws-stepper--across .ws-stepper__title { text-wrap: balance; }
+/* The in-hand stage opens in view on a track that scrolls (a phone): the browser scrolls to it once, on load. */
+.ws-stepper--across > [aria-current="step"] { scroll-snap-align: center; scroll-initial-target: nearest; }
+/* Milestones: dated points on one row, an 8 px dot and its words, the line between them taking the room left. The
+   measure sits on the milestone (a date, or days since the start), so the line carries no words. 4 px of room on every
+   side, pulled back by a margin, so an act's focus ring and a text button's bleed are never cut by the scroll box. */
+.ws-stepper--milestones { flex-direction: row; gap: var(--space-xs); overflow-x: auto; scrollbar-width: none; padding: var(--space-xxs); margin: calc(var(--space-xxs) * -1); }
+.ws-stepper--milestones::-webkit-scrollbar { display: none; }
+.ws-stepper--milestones > .ws-stepper__item { flex: 1 0 auto; align-items: center; gap: var(--space-xs); padding: 0; }
+.ws-stepper--milestones > .ws-stepper__item:last-child { flex-grow: 0; }
+.ws-stepper--milestones .ws-stepper__line { position: relative; inset: auto; order: 1; flex: 1 0 var(--space-lg); width: auto; height: calc(var(--ws-hairline) * 2); }
+.ws-stepper--milestones .ws-stepper__line-fill { transform-origin: left; }
+.ws-stepper--milestones .ws-stepper__mark { width: var(--space-xs); height: var(--space-xs); }
+.ws-stepper--milestones .ws-stepper__mark--wait { box-shadow: inset 0 0 0 calc(var(--ws-hairline) * 2) var(--ws-edge-card); }
+.ws-stepper--milestones .ws-stepper__body { flex: 0 0 auto; flex-direction: row; align-items: baseline; gap: var(--space-xxs-plus); padding-top: 0; white-space: nowrap; }
+@supports (animation-timeline: scroll()) {
+  .ws-stepper--across, .ws-stepper--milestones { mask-image: linear-gradient(90deg, transparent, currentColor var(--ws-fade-start), currentColor calc(100% - var(--ws-fade-end)), transparent); animation: ws-scroll-edges linear; animation-timeline: scroll(self inline); }
+}

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

@@ -9,6 +9,7 @@ Eight weeks of activity as rows, Monday to Sunday across: a done day a pill, an
 **Not for**
 
 - Several people's attendance at once: use `ActivityGrid`.
+- Things that fall on a day (posts, tasks, sends) to open from their date: use `Calendar`.
 - A count out of a whole with no date axis: use `TickRow` or `GoalTicks`.
 - A trend line of a number changing day to day: this chart never plots a value, only whether a day happened.
 

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

@@ -25,7 +25,9 @@ a phone fold. This is the whole wide-table pattern; build every records table fr
   and takes the card's corners). A wide table scrolls inside its card, never the page.
 - Every cell: 8 px above and below (`--space-xs`), 12 at the sides (`--space-sm`), one line (`white-space: nowrap`, so
   a squeezed table scrolls instead of breaking every cell to a word a line). A cell that may wrap takes `ws-table__wrap`
-  (at least 200 wide).
+  (at least 200 wide: one long column of words); several short prose columns (a note, a reason, a description) take
+  `ws-table__prose`, which wraps at whatever width the column gets, with no floor, so five columns still fit the card.
+  Put either on the `th` and every `td` of the column.
 - The outer cells sit on the card's 20 px edge (`--ws-card-inset`): the first cell's left and the last cell's right, so
   the table lines up with the card's head, band and pagination.
 - Head: rows at least 40 (`--ws-row-h-dense`), 13 / 18 medium muted labels (`--ws-text-control`, `--color-text-muted`),
@@ -120,7 +122,7 @@ a phone fold. This is the whole wide-table pattern; build every records table fr
   "Rows vs table"), and it always shows that it scrolls: the shade and the fade.
 - **One content edge per card**: the first and last cells sit on the card's 20 px edge, like its head (K8).
 - **Numbers line up through fixed numeric columns** (North, A4), right-aligned, tabular, the `th` included.
-- **Every row is one line**: a squeezed table scrolls; only a cell marked `__wrap` breaks, and under 30rem the stuck
+- **Every row is one line**: a squeezed table scrolls; only a cell marked `__wrap` or `__prose` breaks, and under 30rem the stuck
   name, which would otherwise leave no room for the columns sliding under it.
 - **A selected row never changes colour alone**: the navy mark travels with the tint.
 - **Row acts are always in the DOM**: hover-to-reveal is cosmetic only.
@@ -173,5 +175,7 @@ columns with no cue, cells 12 in against the card's 20, no vertical padding, no
 
 `design-system/components/Table/style.css`, in `bundle.css` and `fello.css`. Light, dark and the navy ground come from
 the tokens (`--color-bg-page`, `--ws-surface-sunk`, `--ws-hover-faint`, `--ws-divider`); a table on another surface
-sets `--ws-table-ground`. The card is a size container named `ws-table`, so it needs the width of its column (a card in
+sets `--ws-table-ground` to that surface's token, on the `ws-table` element: a white card or panel
+`var(--color-surface)`, a raised panel or menu `var(--ws-raised)`, a plate `var(--ws-surface-sunk)`. A product card
+is the cream already, so it needs nothing. The card is a size container named `ws-table`, so it needs the width of its column (a card in
 a shrink-to-fit row collapses: give it a width). The edge cues use scroll-driven animations where the browser has them.

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

@@ -166,6 +166,21 @@
       </section>
     </div>
 
+    <div class="ws-stack" style="width: min(100%, 560px);">
+      <span class="ws-muted">Short prose columns (__prose): each wraps at the width its column gets, with no 200 px floor; on a phone the rest still scrolls</span>
+      <section class="ws-card ws-table" aria-label="Ads review">
+        <div class="ws-table__scroll">
+          <table>
+            <thead><tr><th scope="col" class="ws-table__name">Ad</th><th scope="col" class="ws-table__prose">Reason</th><th scope="col" class="ws-table__prose">Note</th><th scope="col" class="ws-table__num">Spend</th></tr></thead>
+            <tbody>
+              <tr><td class="ws-table__name">Spring open house</td><td class="ws-table__prose">The image is mostly words</td><td class="ws-table__prose">Swap in the porch photo</td><td class="ws-table__num">$420</td></tr>
+              <tr><td class="ws-table__name">First-time buyers</td><td class="ws-table__prose">Approved</td><td class="ws-table__prose">Runs through Friday</td><td class="ws-table__num">$1,180</td></tr>
+            </tbody>
+          </table>
+        </div>
+      </section>
+    </div>
+
     <div class="ws-stack" style="width: 300px;">
       <span class="ws-muted">Empty, no matches: the same card, the act that clears the filter</span>
       <section class="ws-card ws-table" aria-label="Leads, no matches">

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

@@ -19,6 +19,8 @@
 .ws-table tr > :first-child { padding-left: var(--ws-card-inset); }
 .ws-table tr > :last-child { padding-right: var(--ws-card-inset); }
 .ws-table .ws-table__wrap { white-space: normal; min-width: var(--space-9xl); }
+/* A short prose cell (a note, a reason) that wraps at whatever width its column gets, with no floor (#21). */
+.ws-table .ws-table__prose { white-space: normal; text-wrap: pretty; }
 /* Head: 13 / 18 medium muted labels, stuck to the top of the scroller. */
 .ws-table thead th { position: sticky; top: 0; z-index: 2; height: var(--ws-row-h-dense); font-size: var(--ws-text-control); line-height: var(--ws-leading-control); font-weight: 500; color: var(--color-text-muted); border-bottom: var(--ws-divider); }
 .ws-table thead th[aria-sort="ascending"], .ws-table thead th[aria-sort="descending"] { color: var(--color-text-heading); }

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

@@ -0,0 +1,96 @@
+Two versions of a text side by side in one place: what was removed and what was added, by line or inside the words,
+told apart by a sign, a strike or an underline as well as by colour.
+
+## Use it when
+
+- A person checks a change to text before accepting it, or looks back at what changed: a prompt before and after an
+  edit, a proposed rewrite of a blog body, a saved version against the current one.
+- The point is the change itself, not either version alone.
+
+## Not for
+
+- A number that went up or down: a `ChangeChip` or the chart's own moment.
+- A list of what someone did and when: `Timeline`.
+- Showing one version: plain text in the card, with "Version of Nov 9" in its meta.
+
+## Anatomy
+
+- **By line** (`ws-diff`): a framed block on the field's white ground (the fine edge drawn inside, 4 px corners), 14 /
+  20 body words, line breaks kept (`pre-wrap`). Each line (`__line`) is a 16 px sign column (`__sign`), 8 apart, then
+  the words; 2 / 12 inside.
+  - A removed line (`<del class="ws-diff__line ws-diff__line--removed">`): the needs tint (`--ws-tint-needs`), its words
+    and its minus sign in the needs word (`--ws-word-needs`). Not struck: the old words stay easy to read.
+  - An added line (`<ins class="ws-diff__line ws-diff__line--added">`): the live tint (`--ws-tint-live`), its words and
+    its plus sign in the positive word (`--ws-word-positive`).
+  - An unchanged line: no ground, no sign, the body's words.
+  - A folded run of unchanged lines (`__skip`): one row on the sunk ground, the whole row the act ("6 unchanged
+    lines"), its words in the text column, navy medium in the meta size, the wash under the pointer, 24 tall (40 on
+    touch). Pressed, the run opens in its place (`aria-expanded`).
+- **Inline** (`ws-diff__del`, `ws-diff__ins` inside a `ws-body` paragraph): removed words on the needs tint, in the
+  needs word, struck through; added words on the live tint, in the positive word, underlined. 2 px corners.
+- Every change says itself to a screen reader: a hidden word first inside each `del` and `ins`
+  (`<span class="ws-sr">Removed: </span>`), because most screen readers do not announce the elements themselves.
+- The card around it says what is compared ("Version of Nov 9 against the current one") and the count ("1 line
+  removed, 2 added") in its meta.
+
+## Variants and sizes
+
+| Variant | Use | Notes |
+| --- | --- | --- |
+| By line (`ws-diff`) | a prompt, a list, a template, any text whose lines matter | unchanged runs of more than 3 lines fold, keeping 1 line of context on each side |
+| Inline (`__del`, `__ins`) | a paragraph rewritten in places | when most words stay; a rewrite of most of it reads better by line |
+
+## States
+
+- **Folded**: unchanged runs behind their `__skip` row; the card's act "Show the whole prompt" opens them all.
+- **Open**: every line shown, the changes still marked.
+- **No changes**: no diff; one line in the card ("No changes since Nov 9").
+- **Long line**: wraps inside its column, under its own words, never under the sign; never a sideways scroll.
+- **Dark**: the tints and the words take their dark values (AA on each tint).
+
+## Behaviour
+
+- Keyboard: each `__skip` row is a button (Enter or Space opens its run); nothing else in a diff is a stop.
+- The diff is computed by the app (by line or by word); the component only draws it. Lines keep their order: a changed
+  line is its removed version, then its added one.
+- Copying a diff copies its words, not its signs (`user-select: none` on the sign).
+- Motion: an opened run rises in (`ws-arrive` on its lines); still under reduced motion.
+
+## Content
+
+- Say what is compared and when ("Version of Nov 9 against the current one"), never "Old" and "New".
+- The count in words: "1 line removed, 2 added", "3 changes".
+
+## Rules
+
+- Never colour alone: a removed line has its minus, an added one its plus; inline, removed is struck and added
+  underlined. An underline inside a diff means added, never a link: a diff holds no links.
+- Removed is the needs tone, added the live tone, both at their AA word steps. Never the alert red, never a raw green.
+- One diff per card, and the card says what it compares.
+
+## Source
+
+- **Derived from**: the kit's needs and live tints and their AA words (Colour), the field's ground and edge (`Input`),
+  `Plate`'s sunk ground for the folded run.
+- **Precedent**: Marketing OS (ContentOS): the prompt diff, the SEO refresh's body changes and the content version
+  history, each hand-built on app-local error and success tints (issue #28, Madan, 10 Nov 2026).
+
+## Markup
+
+```html
+<!-- By line -->
+<div class="ws-diff" role="group" aria-label="Changes to the prompt">
+  <div class="ws-diff__line"><span class="ws-diff__sign" aria-hidden="true"></span><span>You write follow-up emails for real estate agents.</span></div>
+  <button type="button" class="ws-diff__skip" aria-expanded="false"><span>6 unchanged lines</span></button>
+  <del class="ws-diff__line ws-diff__line--removed"><span class="ws-diff__sign" aria-hidden="true">&minus;</span><span><span class="ws-sr">Removed: </span>Keep every email under 200 words.</span></del>
+  <ins class="ws-diff__line ws-diff__line--added"><span class="ws-diff__sign" aria-hidden="true">+</span><span><span class="ws-sr">Added: </span>Keep every email under 120 words.</span></ins>
+</div>
+
+<!-- Inline -->
+<p class="ws-body">Spring is <del class="ws-diff__del"><span class="ws-sr">removed: </span>usually</del> <ins class="ws-diff__ins"><span class="ws-sr">added: </span>still</ins> the busiest season.</p>
+```
+
+## Styles
+
+`design-system/components/TextDiff/style.css`: `ws-diff`, `__line` (`--removed`, `--added`), `__sign`, `__skip`,
+`__del`, `__ins`.

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

@@ -0,0 +1,42 @@
+<!-- @dsCard group="Data" height=620 -->
+<!doctype html>
+<html>
+<head>
+<meta charset="utf-8">
+<title>TextDiff</title>
+<link rel="stylesheet" href="../../tokens.css">
+<link rel="stylesheet" href="../bundle.css">
+</head>
+<body>
+<div class="ws-stage">
+  <div class="ws-stack" style="width: 460px;">
+    <span class="ws-muted">By line: a prompt before and after an edit, the unchanged run folded</span>
+    <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
+      <div class="ws-stack ws-stack--tight">
+        <h3 class="ws-section">What changes in the prompt</h3>
+        <p class="ws-meta">1 line removed, 2 added</p>
+      </div>
+      <div class="ws-diff" role="group" aria-label="Changes to the prompt">
+        <div class="ws-diff__line"><span class="ws-diff__sign" aria-hidden="true"></span><span>You write follow-up emails for real estate agents.</span></div>
+        <button type="button" class="ws-diff__skip" aria-expanded="false"><span>6 unchanged lines</span></button>
+        <del class="ws-diff__line ws-diff__line--removed"><span class="ws-diff__sign" aria-hidden="true">&minus;</span><span><span class="ws-sr">Removed: </span>Keep every email under 200 words.</span></del>
+        <ins class="ws-diff__line ws-diff__line--added"><span class="ws-diff__sign" aria-hidden="true">+</span><span><span class="ws-sr">Added: </span>Keep every email under 120 words.</span></ins>
+        <ins class="ws-diff__line ws-diff__line--added"><span class="ws-diff__sign" aria-hidden="true">+</span><span><span class="ws-sr">Added: </span>Name the listing in the first line.</span></ins>
+        <div class="ws-diff__line"><span class="ws-diff__sign" aria-hidden="true"></span><span>Sign off with the agent's first name.</span></div>
+      </div>
+    </div>
+  </div>
+
+  <div class="ws-stack" style="width: 460px;">
+    <span class="ws-muted">Inline: a proposed rewrite of a blog paragraph, removed words struck, added words underlined</span>
+    <div class="ws-card ws-card--pad-md ws-stack ws-stack--loose">
+      <div class="ws-stack ws-stack--tight">
+        <h3 class="ws-section">Suggested rewrite</h3>
+        <p class="ws-meta">Version of Nov 9 against the current one</p>
+      </div>
+      <p class="ws-body">Spring is <del class="ws-diff__del"><span class="ws-sr">removed: </span>usually</del> <ins class="ws-diff__ins"><span class="ws-sr">added: </span>still</ins> the busiest season for listings in Ohio, and buyers who <del class="ws-diff__del"><span class="ws-sr">removed: </span>start looking in January</del> <ins class="ws-diff__ins"><span class="ws-sr">added: </span>get pre-approved by February</ins> close first.</p>
+    </div>
+  </div>
+</div>
+</body>
+</html>

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

@@ -0,0 +1,21 @@
+/* ---- TextDiff: two versions of a text, what was removed and what was added, told apart by more than colour. By line
+   (`ws-diff`): a framed block, each changed line on its tint with a sign in a 16 px gutter (minus removed, plus added),
+   unchanged runs folded behind a quiet act. Inline (`ws-diff__del`, `ws-diff__ins` in running words): removed words on
+   the needs tint and struck, added words on the live tint and underlined. Every change also says itself to a screen
+   reader (a ws-sr word inside the del or the ins). ---- */
+.ws-diff { display: grid; min-width: 0; overflow: clip; border-radius: var(--ws-radius-control); background: var(--ws-field); box-shadow: var(--ws-shadow-hairline-in); color: var(--color-text-body); font-size: var(--ws-text-body); line-height: calc(var(--space-md) + var(--space-xxs)); }
+.ws-diff__line { display: grid; grid-template-columns: var(--space-md) minmax(0, 1fr); column-gap: var(--space-xs); padding: var(--space-3xs) var(--space-sm); white-space: pre-wrap; overflow-wrap: anywhere; text-decoration: none; }
+.ws-diff__sign { font-weight: 600; text-align: center; user-select: none; }
+.ws-diff__line--removed { background: var(--ws-tint-needs); color: var(--ws-word-needs); }
+.ws-diff__line--added { background: var(--ws-tint-live); color: var(--ws-word-positive); }
+/* An unchanged run folded: the row itself is the act (it opens the run), on the sunk ground, its words in the text
+   column saying how many lines it holds, the wash under the pointer. */
+.ws-diff__skip { display: grid; grid-template-columns: var(--space-md) minmax(0, 1fr); column-gap: var(--space-xs); width: 100%; min-height: var(--space-lg); padding: var(--space-3xs) var(--space-sm); border: 0; background: var(--ws-surface-sunk); color: var(--color-text-heading); font: inherit; font-size: var(--ws-text-meta); font-weight: 500; text-align: start; cursor: pointer; transition: background-color var(--ws-duration-hover) var(--ws-ease-soft); }
+.ws-diff__skip > * { grid-column: 2; }
+@media (pointer: coarse) { .ws-diff__skip { min-height: var(--ws-touch); } }
+@media (hover: hover) { .ws-diff__skip:hover { background-image: linear-gradient(var(--ws-hover), var(--ws-hover)); } }
+.ws-diff__skip:focus-visible { outline-offset: calc(var(--ws-focus-width) * -1); }
+/* Inline: changed words inside a sentence. */
+.ws-diff__del, .ws-diff__ins { border-radius: calc(var(--ws-radius-control) / 2); text-decoration-thickness: var(--ws-line); }
+.ws-diff__del { background: var(--ws-tint-needs); color: var(--ws-word-needs); text-decoration-line: line-through; }
+.ws-diff__ins { background: var(--ws-tint-live); color: var(--ws-word-positive); text-decoration-line: underline; text-underline-offset: var(--space-3xs); }

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

@@ -7,7 +7,9 @@ A vertical feed of what happened, grouped by day, a coloured dot on a fine line
 
 ## Not for
 
-- A sequence of steps still in progress toward an end: use `Stepper`.
+- A sequence of steps still in progress toward an end: use `Stepper`; a thing's stages across its head: `Stepper --across`.
+- A few dated milestones on one row (signed, first value): use `Stepper --milestones`.
+- A plan's phases across their dates: use `PlanTimeline`. Things that fall on a day (posts, sends): use `Calendar`.
 - A list of records to compare or act on: use `Table` or rows in a `Card`.
 - A single moment worth calling out inside a chart: use `TrendBars`' own labelled moment.
 

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

@@ -1,4 +1,4 @@
-A value over periods against an axis, as a line with its dots and the hatched area under it, or as columns that collapse into the line's points and back.
+A value over periods against an axis, as a line with its dots and the hatched area under it, or as columns that collapse into the line's points and back; up to three series in one unit as lines with a key.
 
 **Use it when**
 
@@ -7,13 +7,17 @@ A value over periods against an axis, as a line with its dots and the hatched ar
 - The same run reads two ways: columns to compare periods, a line to see the trend. A Bars / Line switch over the card
   shows both, from the same data, with no reload: the columns collapse into the line's points.
 - A tile needs a small preview of that run (`--bare`, inside `MetricTile`'s `__preview`).
+- Two or three series in one unit move over the same periods and the reader compares them (onboardings started,
+  graduated and stalled, by month): one axis, a line each, a key naming them (`__series`).
 
 **Not for**
 
 - A day-by-day trend with one moment that explains it: use `TrendBars`.
 - A bill or a rate that steps against a reference, the gap hatched: use `StepLine`.
 - Parts of one whole: use `ShareBar`. A goal's share: `GoalTicks` or `PaceBar`.
-- Two series or more: one TrendLine draws one series (and one reference). Put the second in its own card.
+- Series in different units, or one more than four times another (accounts and tickets): never two value axes. Stack
+  two TrendLines in one card on the same periods (Rules).
+- More than three series: a `Table`, or the three that matter and the rest named in the sentence.
 
 **Anatomy**
 
@@ -42,8 +46,16 @@ A value over periods against an axis, as a line with its dots and the hatched ar
   each a `title`); the current one (`__now`) 600 navy.
 - Key (`__legend`, optional): centred, 16 apart, 16 above; a 12 px swatch in the mark's look (`__key--now`,
   `__key--ahead`, `__key--ref` for the dotted line), 8, 14/20 medium body grey.
-- The reading (`__table`): a real `<table>` of every period and its value, with a caption, hidden from the eye inside
-  the `__table` box. The plot is `aria-hidden`.
+- Several series (up to 3): the first is the figure's own `__draw` and points; each other is a `__series` box after
+  them (`display: contents`, so its points still sit on the plot) holding its own `__draw` (the SVG path only, no
+  hatch) and its points, the same `--i` and `--n`. Tones in order: navy, teal (`--ws-chart-finished`), purple
+  (`--ws-chart-past-half`); salmon stays the reference's. `--tone` on a series overrides its tone (a figure that sets
+  its own `--tone` sets one on each series too, since the figure's is inherited). The key names every series:
+  `__key--2` and `__key--3` take the second and third tones (an overridden series' `<li>` carries the same `--tone`).
+  With several series there is no hatch (one area claims a whole; two cover each other) and the period in progress
+  keeps its series' tone: its name (`__now`) and the dotted `__ahead` say it.
+- The reading (`__table`): a real `<table>` of every period and its value (a column a series), with a caption, hidden
+  from the eye inside the `__table` box. The plot is `aria-hidden`.
 
 **Parts and modifiers**
 
@@ -54,6 +66,7 @@ A value over periods against an axis, as a line with its dots and the hatched ar
 - `__point--now`, `__point--ahead`: the period in progress; a period to come.
 - `__point--on`: the point held open (a tap, or the keyboard's mark when the app moves one); it looks hovered.
 - `__band`: the hover band, last in the plot. `__now`: the current period's name.
+- `__series`: a second or third series, after the first series' points; `__key--2`, `__key--3`: its swatch in the key.
 
 **States**
 
@@ -77,7 +90,9 @@ A value over periods against an axis, as a line with its dots and the hatched ar
   tall, the other columns step back to `--ws-dim` over the hover. Line: the band is a dashed guide from the dot to the
   baseline, and the dot grows to 1.5 inside a faint halo over `--ws-duration-hover` (North's `r .2s`). The band rides
   CSS anchor positioning: without it the band is left out and the rest still happens. A `HoverCard`
-  (`--above --follow`) reads the point.
+  (`--above --follow`) reads the point. With several series it reads the period, not the dot: the eyebrow names the
+  period (no swatch), then a row a series in the key's order, each with its swatch and value (`__row`); it sits over
+  the period's highest dot. The guide runs from the hovered dot to the baseline, through the others.
 - Narrow (the figure under 30rem): the plot is 200 tall; with more than six names, every other one and the current
   one's neighbours give way and the rest take two slots.
 - Zero: every column a 2 px stub on the baseline, every dot on it. One period: a dot (or a column) and no line.
@@ -104,7 +119,12 @@ A value over periods against an axis, as a line with its dots and the hatched ar
 
 **Rules**
 
-- **One series, one optional reference.** Two lines are two cards.
+- **Up to three series in one unit, one optional reference.** One value axis, always: never two.
+- **Different units or scales far apart** (one series more than four times another): two TrendLines stacked in one
+  card on the same periods (`--n`) and the same gutter (`--ws-trend-line-y`), each with its own value labels and a key
+  of one; the period names only under the last (leave the first's `__x` out). One title and one sentence for the pair.
+- **Several series are lines only**: no hatch and no Bars / Line switch (two columns cannot share a slot and still
+  collapse into their dots). A chart that wants columns per period across series is a `Table` or two cards.
 - **Columns start at zero.** A chart with the switch, or any columns, has its baseline at 0; a line alone may start
   above zero only without the hatch (an area claims a whole).
 - **The same data in both modes**: the switch changes the drawing, never the numbers.
@@ -143,6 +163,17 @@ A value over periods against an axis, as a line with its dots and the hatched ar
 </figure>
 ```
 
+A second series, after the first series' points (a third is another `__series` after it):
+
+```html
+<span class="ws-trend-line__series">
+  <span class="ws-trend-line__draw"><svg class="ws-trend-line__lines" viewBox="0 0 100 100" preserveAspectRatio="none" aria-hidden="true"><path d="M12.5 70 L37.5 62.5 L62.5 52.5 L87.5 40"/></svg></span>
+  <span class="ws-trend-line__point" style="--i: 0; --y: 70%;"></span><!-- a point a period -->
+</span>
+<!-- the key, after the plot: <ul class="ws-trend-line__legend" aria-hidden="true"><li>Started</li><li class="ws-trend-line__key--2">Graduated</li></ul> -->
+<!-- the table: a column a series, <th scope="col"> named as the key -->
+```
+
 A reference goes after the rules: `<span class="ws-trend-line__ref" style="--y: 19.94%;"><span>Plan $40.03M</span></span>`.
 What is to come: `__point--ahead` on its points, and a second path `<path class="ws-trend-line__ahead" d="...">` from
 the last real point on. The switch, in the card's head:
@@ -160,5 +191,5 @@ on tokens, except North's own numbers: the dotted line's 0.1 dash (a round cap's
 the hatch at 45%, the hovered dot's 1.5 and its halo at 12%, and the build's 55 / 45 share. Tokens: `--ws-duration-draw`,
 `--ws-duration-settle`, `--ws-duration-hover`, `--ws-duration-exit`, `--ws-ease-settle`, `--ws-ease-steady`,
 `--ws-ease-pop`, `--ws-ease-soft`, `--ws-ease-exit`, `--ws-spring-morph-chart` and its duration, `--ws-dim`,
-`--ws-hover`, `--ws-chart-line`, `--ws-chart-navy-light`, `--ws-chart-under-half`, `--ws-word-needs`, `--ws-edge-slot`,
+`--ws-hover`, `--ws-chart-line`, `--ws-chart-navy-light`, `--ws-chart-finished`, `--ws-chart-past-half`, `--ws-chart-under-half`, `--ws-word-needs`, `--ws-edge-slot`,
 `--ws-edge-card`.