@felloinnovations/brand-kit 0.4.0 → 0.5.1

package/design-system/05-space-and-layout.md

@@ -1,73 +1,196 @@
 # Space and layout
 
-A 4 px grid, a few named gaps, and alignment rules that make a screen read as one hand.
+A 4 px grid with four half steps, a rhythm set by relationship, rimmed containers, one content edge per surface,
+numbers in fixed columns, and layouts that re-lay out by the room they have. Seth's frames (the Fia report, Fixes,
+Inbox and Tally frames, and his North app) are the reference for every value here; where they disagree with each
+other, this chapter says which one the kit takes (Decisions, 4 Nov 2026).
+
+## The scale
+
+The 4 px steps (`space-xxs` 4, `space-xs` 8, `space-sm` 12, `space-md` 16, `space-lg` 24, `space-xl` 32, `space-2xl`
+40, `space-3xl` 48, `space-4xl` 64 and up) plus the half steps Seth uses in two or more places: 2 (`space-3xs`), 6
+(`space-xxs-plus`), 10 (`space-xs-plus`) and 14 (`space-sm-plus`).
+
+- **Every other value snaps to the nearest step.** A one-off 5, 7, 9, 19 or 22 in a frame is a near miss, not a new step.
+- **Build from Seth's base values, not Figma's scaled ones.** A component scaled into its slot reads 17.5, 13.12 or
+  43.74 in the file; its base values are 16, 12 and 40, and those are what the kit uses.
+- **Never a one-off in your own code.** If no step fits, say so and leave it (How Claude decides, step 5).
+- **The scale spaces layout, not a drawing's marks.** The gaps inside a chart (ticks 3 apart in Seth's row strips, the
+  1 px cuts in a share bar) are the chart's own geometry, named in Charts and in its README.
 
 ## Spacing, by relationship
 
 | Relationship | Space | Token |
 | --- | --- | --- |
-| An icon and its word, inside a row, between a bar's segments | 4 | `space-xxs`, `ws-gap-tight` |
-| Related controls, rows in a tight list, a label and its field | 8 | `space-xs`, `ws-gap` |
-| Rows that breathe, a dialog's buttons, inside a plate | 12 | `space-sm`, `ws-gap-loose` |
-| Between components (cards on a board, a toolbar and its board), inside a stat tile | 16 | `space-md`, `ws-gap-component` |
-| Inside a card, a pane, a dialog (its sides and head) | 20 | `ws-card-inset` |
-| Between groups, between a card's sections, the page gutter on a large screen, the chat's line | 24 | `space-lg`, `ws-gap-group`, `ws-gutter` |
-| A footer band's sides | 28 | `ws-band-inset` |
-| Between a chat's turns | 22 | `ws-gap-turn` |
-| The page edge on a phone | 16 | `space-md` |
-
-A page never adds its own padding inside the canvas: the gutter is the canvas's. A card never adds a margin: the board's gap
-separates cards.
-
-## Layout widths (defaults)
-
-| Piece | Width | Token |
+| Items in a segmented track, a stat's label and its value | 2 | `space-3xs` |
+| An icon and its word inside a row, segments of one group | 4 | `space-xxs`, `ws-gap-tight` |
+| A button's icon and its words, a big figure and the line under it, a label and its title | 6 | `space-xxs-plus` |
+| Related controls, a label and its field, a pair of buttons, tiles in a tight grid | 8 | `space-xs`, `ws-gap`, `ws-stack`, `ws-cluster` |
+| A title and its tag, an area heading and its card, a box and short words beside it | 10 | `space-xs-plus` |
+| Rows that breathe, a section head and its cards or list, a dialog's buttons, groups of segments | 12 | `space-sm`, `ws-gap-loose` |
+| A face and the title beside it, the parts of a row with a box | 14 | `space-sm-plus` |
+| Cards in a grid, the parts inside one block (figure, strip, sentence), a tile's inside, the header to the content | 16 | `space-md`, `ws-gap-component` |
+| Inside a card: its head, its rows' start edge | 20 | `ws-card-inset` |
+| A chart and its side column, a report and its drawer, the drawer's foot and the stage edge, between groups | 24 | `space-lg`, `ws-gap-group` |
+| A drawer section's sides | 28 | `ws-band-inset` |
+| Between the blocks of a report column (tabs, score, list); the app page's gutter | 32 | `ws-gap-block` (`ws-stack--block`), `ws-gutter` |
+| Between page sections (a hero, a chart row, a board) | 56 | `ws-gap-section` (`ws-stack--section`) |
+| The page edge on a phone | 16 | `space-md`, plus the safe area |
+
+A stack (`ws-stack`, top to bottom) and a cluster (`ws-cluster`, side by side, wrapping) are 8 apart; `--tight`,
+`--loose`, `--component` and `--group` take the named gaps above, and a stack also takes `--block` (32) and `--section`
+(56). Their gap is the step itself, never an inherited `--ws-gap`, so a parent's own layout gap does not leak into them.
+
+A page never adds its own padding inside the stage: the gutter is the stage's. A card never adds a margin: the board's
+gap separates cards. A chat's turns follow `ChatTurn` and `ChatShell`.
+
+## One content edge
+
+The one alignment rule teams break most. Seth's Tally report alone has its words at 14, 15, 16, 16.6, 17, 19, 20 and 22
+from the edge: each a near miss, together a page that looks hand-placed.
+
+- **One inset per surface.** In a card the title, the sentence, the rows, the plate and the foot's words share one
+  start edge. A rimmed card's inset is measured from its outer edge: the 1 px rim, then the surface's padding.
+- **A heading outside a card** aligns to the card's outer edge, never somewhere between it and the card's content.
+- **A detail opened under a row** starts on the row's words column, not on its box or a few pixels past it.
+- **Shared edges across regions**: anything docked into a bar (a search, a filter, the crumbs) sits on the same x as its
+  page counterpart below.
+- **A quiet act's hover box bleeds out by its own padding** (a negative margin equal to the padding), so its words line
+  up with the text above; a close button pulls into its corner the same way.
+- **Labels sit above fields** in a product screen; help or an error sits under, 4 px below.
+- **Buttons in a band or a dialog foot sit right**, the one primary last. In a drawer or a pane two acts may fill the
+  width as equal halves (8 apart, the primary last); where a half would be under 160 or break its label, they stack
+  full width, the primary at the bottom (`ws-btn-split`). In an item's act row (the inbox's open review) the acts start on
+  the content edge, 8 apart, the primary first.
+- **A card's aside** (a switch, a select, a group of controls in one element) sits top right of the head; when it would
+  squeeze the title under 200 px it drops under the title as one piece rather than shrinking it. **Icon acts** (a
+  close, an expand) never drop: they stay top right on the title's first line and the title wraps instead.
+- **Rows align their first column** (a box, a face, a dot) on one vertical line through the list.
+
+## Optical alignment
+
+Align to the ink, not the box. The geometry check measures glyphs, so it sees what a designer sees.
+
+- **A big figure's ink meets the column.** At 72 px and up a numeral's side bearing shows: pull it left until the
+  glyph's visible edge sits on the edge (GoalTicks pulls its 72 by 4); lines under a large score indent to its visible
+  edge, not its box. Measure each size: Seth's 96 in the Grow report needs no pull.
+- **An icon centres on the first line of its neighbour**, not on the neighbour's box. A 32 px close beside a 22 / 28
+  title moves up by half the difference (`margin-block: calc((var(--ws-leading-title) - var(--ws-control-h)) / 2)`).
+- **A chip beside a big numeral** sits with its bottom on the numeral's baseline, everywhere it appears.
+- **One line of text centres in its box.** Draw a control's edge inside (an inset shadow), so a 32 px button stays 32
+  and its words do not land on half pixels.
+- **Inline icons** sit on the words' line (`ws-icon`), never on the baseline below it.
+
+## Numbers in fixed columns
+
+- **Every number in a list sits in a fixed-width, right-aligned column**, so the figures line up down the list:
+  Seth's check rows give the score 56 and the status 112, both right-aligned; North's rows end in a 64 px figure
+  column. Tabular numerals as well (`ws-tnum`, Type); fixed columns do not replace them.
+- **A row's right column** (a value over its sub-value) is right-aligned as one block.
+- **Rows that compare counts share one grid**, so counts and labels line up across rows; a count is never centred in a
+  wide box (GoalBars).
+- **A number never truncates**: the words beside it give way first.
+
+## Rimmed containers
+
+The product card is Seth's rimmed construction (D5): the tray (`ws-tray`, #EDEDED) shows as a 1 px rim (`ws-rim`)
+through the card's padding, and the cream surface sits inside it. It replaces the 0.5 px outline; the class names stay,
+so existing markup upgrades in place.
+
+| Part | Rule | Token |
 | --- | --- | --- |
-| Sidebar open / folded | 232 / 72 | `ws-sidebar-width`, `ws-rail-width` |
-| The one column (home, chat) | 656, centred | `ws-column-width` |
-| The panel beside the chat | 440, at most half the stage | `ws-thing-width` |
-| A card on a board | 556, giving to 480 before the column wraps | `ws-chart-card-w`, `ws-chart-card-min` |
-| The stage | the window less the sidebar, a 16 px cornered surface on the grey | `ws-radius-panel`, `ws-page` |
+| Rim | 1 px of the tray around the surface, all sides | `ws-tray`, `ws-rim` |
+| Corners | concentric: 8 outside, 7 inside; a drawer 12 and 11 | `ws-radius-card`, `ws-radius-card-inner`, `ws-radius-drawer`, `ws-radius-drawer-inner` |
+| Surface | the cream; a draft or a plate inside sits on the sunk cream the same way | `color-bg-page`, `ws-surface-sunk` |
+| Rows | cream, joined by 0.5 px full-width dividers; the first rounds its top corners, the last its bottom ones | `ws-divider` |
+| Foot | optional, on the tray itself: short (one line of words), no fill and no shade of its own | words on the tray take the word tokens, all AA there |
+| Hover | when the whole card is one target, the rim darkens; nothing moves | `ws-well-hover` |
+| At rest | no outline, no shadow | |
+
+- **The rows round their own corners**; the card never takes `overflow: hidden` to do it (Scrolling).
+- **Two trays can join into one** (a detail and its list, `ListDetail`): each keeps its outer corners and a single
+  1 px line of the tray splits them.
+
+## Dividers and grouping
+
+- **A divider is 0.5 px and runs the container's full width**, past its padding (`border-top: var(--ws-divider)`). In a
+  list of inset rows (rows as pills on a 4 px padded surface) the divider runs the surface's width, and the dividers on
+  both sides of the selected row drop out: a filled pill needs no line.
+- **Proximity first**: related things 4 to 8 apart, different tasks 16 to 24. The line between groups is usually the gap
+  itself; a rule between groups only where it orients (the sidebar's groups, a chat's topics, a report's lanes).
+- **Rows in one list share one min-height**: the tallest single-line form (56 when any row carries a 32 px act). A row
+  with a second line grows; a row without an act does not shrink.
+- **A selected or open row never changes size**: only its ground and its weight change, never its type size or line
+  height, so nothing under it moves.
+- **Cells that touch** (a heatmap) are split by a 1 px inset ring in the paper colour, not by a gap.
+- A plate (`ws-surface-sunk`) holds a card's facts; a well (`ws-well`) holds a list of things to ask.
 
-Size from the space a region actually has (container queries at 40, 48, 60 and 76 rem: `area-sm` to `area-xl`), never from
-the window: a card beside the chat has less room than the same card on a page.
-
-## Alignment
+## Corners and elevation
 
-- **One content edge per card**: the title, the sentence, the body and the band's words share the 20 px inset; the band's
-  words sit at 28 so they read as a different surface.
-- **Text aligns to the start edge**; numbers in a column align right and use tabular numerals; a figure and its chip align
-  on the baseline.
-- **Labels sit above fields** (never beside them in a product screen); help or an error sits under, 4 px below.
-- **Buttons in a band or a dialog foot sit right**, the one primary last; a form's submit inside a card sits full width.
-- **A card's aside** (a switch, a close) sits top right of the head; when it would squeeze the title it drops under the
-  title rather than shrinking it.
-- **Rows align their first column** (a face, a dot, a check) on one vertical line through the list.
-- **Icons centre on the words' x-height.**
+Corners climb with size, each a literal length: a bar or a tick 1 (`ws-radius-bar`), a field, a chip, a tag or a
+checkbox 4 (`ws-radius-control`), a button, a square icon button or a row 6 (`ws-radius-row`), a card 8 (its inner
+surface 7), a menu 10 (North's), a dialog or a drawer 12 (inner 11), the chat bubble 14 (a 4 px tail corner), the stage
+16 (`ws-radius-panel`), a toast's pill 18. A component's README says which step
+each part takes. Never `--radius-xl` or `--radius-2xl` in product CSS: Tailwind owns those names.
+A public page's `KitCard` is 4.
 
-## Grouping
+Everything is flat at rest. What floats lifts on one family of shadows, a single soft drop each: a popover
+(`ws-shadow-pop`), a menu (`ws-shadow-menu`), a tooltip or hover card (`ws-shadow-tip`), a floating chat or a tile opened
+out of its slot (`ws-shadow-float`). In dark each carries a 0.5 px light rim. Buttons never lift. Layers: `z-dropdown`
+for menus and tips, `z-modal` for a dialog or drawer, `z-toast` for a toast.
 
-Group related information closely (4 to 8 px), separate different tasks with more (16 to 24). Proximity before lines: a
-hairline between rows is `ws-edge-slot`; a line between groups is the gap itself, not a rule. A plate (`ws-surface-sunk`)
-holds a card's facts; a well (`ws-well`) holds a list of things to ask.
+## The frame
 
-## Corners and elevation
+| Piece | Rule | Token |
+| --- | --- | --- |
+| Page behind the stage | the soft frame gradient | `ws-frame` (as `background:`) |
+| Stage | a 16 px cornered surface with a 1 px edge; glass in an app shell | `ws-radius-panel`, `ws-edge-stage`, `ws-glass`, `ws-glass-blur` |
+| Stage insets | 13 from the top, 12 from the right and the bottom | `ws-stage-inset-top`, `ws-stage-inset` |
+| App page in the stage | a 56 px header with 32 px sides; the content 16 under it, 32 from both sides, filling the stage | `ws-header-h`, `ws-gutter`, `space-md` |
+| A single page | `Page` takes the same 32 px gutter (16 on a phone) | `ws-gutter` |
 
-Corners climb with size: a bar 1 px, a chip 2, a control 4, a row 6, a card 8, a bubble 12, a dialog or the stage 16 (a
-public page's `KitCard` is 4). Everything is flat; only a menu, a popover or a tooltip (`z-dropdown`), a dialog or drawer
-(`z-modal`) and a toast (`z-toast`) lift.
+The content inside the stage is left-anchored: a board never centres itself in a wide stage, so every block shares one
+start edge (K12).
 
-## Boards
+## Layout widths (defaults)
 
-A page of cards is a board (`CardBoard`, or `Page`'s board on a single page): columns side by side at 556, each card its
-own height, one column on a phone in the same DOM order (Accessibility, reading order). A
-list or a board of things is one card. Four stat tiles go across from the `lg` width, two below. A `Tile` spans by
-content, never to fill a gap.
+| Piece | Width | Token |
+| --- | --- | --- |
+| Sidebar open, folded to its rail | 232, 64 folded | `ws-sidebar-width`, `ws-rail-width` |
+| The one column (home, chat) | 656, centred; `ChatShell`'s docked and full-screen modes hold their own widths | `ws-column-width` |
+| The panel beside the chat, a drawer beside a report | 440, at most half the stage; a report and its drawer 24 apart | `ws-thing-width` |
+| A side column beside a chart | a fixed width, the chart takes the rest, 24 apart | `ws-thing-width` or the design's |
+| A card on a board | 556, giving to 480 before the column wraps | `ws-chart-card-w`, `ws-chart-card-min` |
 
-## Responsive
+## Boards and grids
+
+- **A board of cards** (`CardBoard`, or `Page`'s board): columns side by side at 556, each card its own height, one
+  column on a phone in the same DOM order. A list or a board of things is one card.
+- **Grids above and below share one column grid.** Seth's inbox puts three tiles 8 apart over a list exactly one column
+  wide and a detail spanning the other two, so the list's right edge meets the first tile's.
+- **A main column with an aside** is `Split`: the aside a fixed width, tops aligned, stacking under by container width.
+- **Stat tiles**: four across where they fit, then two, then one; five or six go three across in two rows, never four
+  and an orphan. `StatTiles` measures its own width.
+- **A `Tile` spans by content**, never to fill a gap.
+
+## Responsive: by container, re-lay out, never just shrink
+
+- **Size from the region, not the window.** A component that adapts is its own size container (`StatTiles`, a board,
+  `PageHero`), so it reads the column it sits in. A card beside the chat has less room than the same card on a page.
+- **Switch where the content stops fitting**, measured. Seth's North switches its page at 1120, 940 and 820 px and a
+  chat card at 470; the kit's named areas are 40, 48, 60 and 76 rem (`area-sm` to `area-xl`).
+- **Re-lay out, never just shrink** (Seth's own heading): columns drop, side columns move under, header parts become
+  flow, a band's second line goes before a title shrinks. Type never shrinks to fit and a figure keeps its size.
+- **Write the DOM in the phone's order**: when a list belongs above its detail on a phone, it comes first in the markup
+  (Accessibility, reading order).
+- **Nothing fixed-width pushes past its column**: a panel, a sidebar or a strip caps at `max-width: 100%`. An
+  inline-level piece (a segmented switch) never stretches in a column unless asked (`--stretch`).
+- **A card moving between two sizes is not a size container** while it moves, so its layout cannot flip halfway.
+- **Phone**: the edge is 16 plus the safe area; the stage loses its corners and edge; below 40 rem a drawer is the whole
+  screen; bars with links collapse on their own below 40 rem; the panel is the screen; a board is one column.
+- **320 px works**: every face reflows at 320 wide (Accessibility, zoom and reflow).
 
 Every face renders at 100%. A dense desk app may choose a UI zoom (Decisions); it then divides viewport units back by
-the zoom. Below 1280 px the panel beside the chat is a slide-over; on a
-phone the chat is full bleed, the panel is the screen and a board is one column.
+the zoom. Below 1280 px the panel beside the chat is a slide-over.
 
 The marketing face sizes from the kit's layout tokens, not the workspace's (Public pages, Layout).

package/design-system/06-sizing-profiles.md

@@ -9,9 +9,9 @@ deliberately, in the rationale.
 | Body | 14 / 20 | 16 / 24 (`kit-md`) | 16 / 24 | 16 / 24; a lead 18 / 28 (`kit-lg`) |
 | Meta, labels | 12 to 13 | 13 to 14 | 13 to 14 | 12 to 14 |
 | Title | 22 / 28 | 22 / 28 | 22 / 28 | `kit-4xl` sections, `kit-5xl` to `kit-6xl` hero; smaller on a phone |
-| Controls | 28 small, 32 default, 36 large | 36 | 40 boxed, 48 submit, 24 words that act | 45 (`KitButton` large), 40 fields |
-| Row height | 32 to 40; 48 with a face | 48 | 48 | 48 |
-| Card inset | 20 | 24 | 20 | 24 |
+| Controls | 28 small, 32 default, 36 large; 40 for a pane's acts | 36 | 40 boxed (`ws-touch`), 48 submit, 24 words that act | 44 every act (`ws-touch-public`; `KitButton` large is 45), 40 fields |
+| Row height | by content, one min-height per list: 28 a sidebar row, 40 a dense row, 48 with a face or in a matrix, 56 a check row | 48 | 48 | 48 |
+| Card inset | 20 (a tile 16, a drawer's sections 28 at the sides) | 24 | 20 | 24 |
 | Gap between components | 16 | 24 | 16 | 24 |
 | Line length | up to 656 px | 60 to 70 characters | the screen less 32 | 60 to 75 characters |
 
@@ -24,4 +24,4 @@ deliberately, in the rationale.
 - **Touch is a floor, not a profile switch**: on a coarse pointer (`pointer: coarse`) the touch floors in Accessibility
   apply whatever the profile.
 - **Enlarged text (200%)** must reflow in every profile: columns stack, the panel becomes the screen, nothing clips sideways.
-- **A number card keeps its 72 px number** in every profile; what gives is the room around it.
+- **A hero figure keeps its size** (the 72 px number, the 96 px score) in every profile; what gives is the room around it.

package/design-system/07-scrolling.md

@@ -1,37 +1,83 @@
 # Scrolling
 
-Who scrolls, what stays, and what "fits" means. Compactness comes from prioritising and grouping, never from shrinking words
-or clipping content to avoid a scroll.
+Who scrolls, what stays, and what "fits" means. Compactness comes from prioritising and grouping, never from shrinking
+words or clipping content to avoid a scroll.
 
 ## By surface
 
 | Surface | Default | Who owns the scroll |
 | --- | --- | --- |
 | Home | fits: the greeting, the composer, Needs you, a few starters; the list grows down if it must | the stage |
-| Chat | the conversation scrolls; the composer stays reachable at the foot (24 px above the edge) | the thread, with a new turn gliding to the bottom (`scrollBehavior`) |
-| Panel beside the chat (440) | the thing's own view scrolls inside the panel; its 56 px header stays | the panel |
-| App page (a board) | the key cards first; the page grows; nothing sideways | the page |
-| A dialog | content scrolls inside; head and foot stay | the dialog's content |
-| A drawer | as a dialog, from the right | the drawer's content |
-| A list with a detail pane | the list and the pane scroll independently when both need it; the chosen row stays visible | each region |
-| A wide table | contained horizontal scroll inside its card, the first column sticky, never the page | the card |
+| Chat | the conversation scrolls; the composer stays reachable at the foot; room under the last turn so it never sits on the composer | the thread, with a new turn gliding to the bottom (`scrollBehavior`) |
+| Panel beside the chat (440) | the thing's own view scrolls inside the panel; its 56 px header stays | the panel's body |
+| App page (a board) | the key cards first; the page grows; nothing sideways | the shell's body |
+| A dialog | content scrolls inside; the head and the foot stay; the dialog is never taller than the window less 32. Under 40 rem of window height or width the whole pane scrolls under its head and the foot comes at the end | the dialog's content (the pane, when short or on a phone) |
+| A drawer | as a dialog, from the right; below 40 rem wide it is the whole screen | the drawer's content |
+| A list with a detail | the list and the detail scroll independently when both need it; the chosen row stays visible | each region |
+| A wide table | contained sideways scroll inside its card, the first column and its header sticky, never the page | the table's scroller |
+| A board of stages (kanban) on its own page | the board fills the room left; each column scrolls down; the sideways bar sits at the window's foot | the board, and each column |
 | A form or settings | normal vertical page scroll; the submit at the end of the card, not sticky unless the form is long on a phone | the page |
 | A guide, a long read | normal vertical page scroll, a slim sticky header only if it holds the one act | the page |
 
+## The shell owns its scroll
+
+An app shell is the window's height; its body is the one scroll region. The kit builds the rules below in (K1, K2), so
+the shell's markup never needs patching.
+
+- **A scroll region's children never shrink.** In a height-bound column (the shell's body and nav, a dialog, a panel's
+  body, a stack, a compound card, a page, a board's column) every child keeps its height and the column scrolls. A child
+  that should scroll inside says so: `flex: 1; min-height: 0; overflow: auto`. A card squashed to 0 px, a table sliced
+  mid-row or a tab row reduced to its hairline is this rule broken.
+- **Every kit scroller is positioned**, so what sits absolutely inside it (screen-reader words, a sticky cell's shade)
+  stays inside and never stretches the window. A shell whose window scrolls past its own end is this rule broken.
+- **The nav's foot never scrolls**: the wordmark at the top, the groups scrolling between, the person pinned at the foot.
+- **No `overflow: hidden` on a card or a table**: it clips menus, focus rings and edges. Round the first and last child
+  instead.
+- **A long page never chains into the window**: the body's scroll stops at its end (`overscroll-behavior: contain`).
+
+## Sticky
+
+- **Sticky is for the one act and the orientation**: a dialog's head and foot, a panel's header, a table's first column
+  and its header cell. A sticky element never covers content: pad the scrolling region by its height.
+- **A sticky head shows its bottom hairline only once content scrolls under it.** At rest it has no line; the line (a
+  0.5 px `ws-edge-slot`) appears when something passes beneath, and goes when the region is back at the top.
+- **Cap what sticks.** A drawer's or dialog's sticky head is its one title line (`ws-header-h`, 56): the name, its tag,
+  the labelled x and at most one more icon act. The kit pins the whole head (a full-screen phone drawer must keep its
+  close), so what you put in the head is what sticks: facts, figures, chips, editors and acts go in the scrolling
+  content (the drawer's first section), never in the head. The foot holds one row, at most two buttons. Under 40 rem of
+  window height or width the foot scrolls with the content. A phone keeps most of its height for the content, never a
+  third of it.
+- **The sticky column of a wide table** carries its header cell with it, on the card's ground, with a soft edge while
+  the table is scrolled sideways.
+
+## Overflow that must be seen
+
+- **A tab row that overflows** shows it: an edge fade while it can scroll, the chosen tab scrolled into view, the
+  scroll padded by 24 at the ends. On a phone, more than four tabs become a `Select`; a shared tab row stays one line and
+  scrolls sideways with its focus ring drawn inside.
+- **A wide table** shows that columns exist past the edge: the same edge fade, a thin visible scrollbar. It shows the
+  columns the question needs and folds the rest into each row under 480 px.
+- **A menu or a popover** opens in the top layer (the native `popover` attribute or a portal), flips and shifts to stay
+  on screen, and scrolls inside past the window's height. No card, dialog or stage clips it.
+- **A full screen** (a chat card's) goes through `morph()`, which lifts it into the top layer while it is full: a bare
+  `position: fixed` fills only the nearest ancestor with a transform, a filter or backdrop-filter, `contain` or
+  `will-change` (a glass surface is one), and is cut to it. A tooltip anchors to the window the same way.
+- **A wide heatmap** (Seth's lanes by metrics) may scroll sideways inside its own card when its columns cannot narrow
+  further; the page around it never does.
+
 ## Rules
 
-- **Every screen works at both the panel width and the page width and fits without clipping**: nothing cut off, no sideways
-  scroll. Where it does not fit, reduce what is shown (the panel shows the essentials, the page shows everything), not the
-  size of what is shown.
-- **One scroll region per view where possible**; a second only when two things must be compared or kept in place (list +
-  detail, chat + panel).
-- **Sticky is for the one act and the orientation**: a dialog's head and foot, a panel's header, a table's first column. A
-  sticky element never covers content: pad the scrolling region by its height.
-- **Focus follows the opening**: a panel that opens takes focus to its header; Escape or Close returns it to what opened it;
-  a page returned to restores its scroll position and the chosen row.
+- **Every screen works at both the panel width and the page width and fits without clipping**: nothing cut off, no
+  sideways page scroll. Where it does not fit, reduce what is shown (the panel shows the essentials, the page shows
+  everything), not the size of what is shown.
+- **One scroll region per view where possible**; a second only when two things must be compared or kept in place
+  (list and detail, chat and panel).
+- **Focus follows the opening**: a panel that opens takes focus to its header; Escape or the x returns it to what
+  opened it; a page returned to restores its scroll position and the chosen row.
 - **Keyboard open on a phone**: the composer and a sticky submit sit above it; the thread scrolls to keep the last turn
   visible.
 - **Long collections**: a list over about 50 rows paginates or virtualises; a board of cards never exceeds what one page
   can show without a second column of columns; a table shows the columns the question needs and folds the rest.
-- **Charts never scroll**: a chart that does not fit at 480 px wraps its labels, drops to one column, or becomes a different
-  chart (a wide bar chart becomes rows of ticks).
+- **Charts do not scroll**: a chart that does not fit at 480 px wraps its labels, drops to one column, or becomes a
+  different chart (a wide bar chart becomes rows of ticks). The one exception is a wide heatmap, above.
+- **No scrollbar while a card is moving** between two sizes, and a scrolled card returns to its top before it closes.

package/design-system/08-choosing-components.md

@@ -1,28 +1,34 @@
 # Choosing components
 
 Each user need, the component that answers it, and the rule that decides. Start here, not in the component list.
+Components new in 0.5.0 are marked (new).
 
 ## Acting and navigating
 
 | Need | Component | Rule |
 | --- | --- | --- |
-| Do the one thing this card or page is for | `Button` primary, large (36) | one navy button per card and per page, last on the band |
-| Do a second thing beside it | `Button` secondary, large | never a second navy |
-| A page header's acts ("Build a call", "New criteria") | `Button` secondary, small (28) beside a title, medium (32) in a toolbar of 32 px fields | |
-| A row's acts ("Done", "Approve", "Move") | `Button` secondary or ghost, small | |
+| Do the one thing this card or page is for | `Button` primary, large | one navy button per card and per page, last on the band |
+| Do a second thing beside it | `Button` secondary, large; in a drawer or a row, Seth's grey `ws-btn--well` | never a second navy; in a drawer the two may fill the width as equal halves (the well, then the primary), stacking full width when a half would break a label |
+| A page header's acts ("Refresh", "Settings") | `Button` secondary at the default 32, in the 56 px header or a toolbar of 32 px fields | |
+| A row's acts ("Done", "Approve", "Review") | `Button` secondary or ghost at the default 32 (Seth's fix rows); small in a dense table row | the act may turn primary while its row is open |
+| A label that may be wider than its column (a long link act, a translation) | `Button` with `ws-btn--wrap` | a button is one line and never shrinks beside its row's words; only an opted-in label wraps, in balanced lines (a link, text or ghost reads from its start) |
 | Words that act inside a sentence | `Button` link (mid blue: goes somewhere or shows more) or text (navy: a quiet act) | never a boxed button in running words |
 | Go somewhere | `Button` as a link (`ButtonLink`), or `ws-link` | a link is a link in the markup, whatever it looks like |
-| An act with no words (send, close, more, mic) | `IconButton` with a label | |
+| An act with no words (send, close, more, previous, next) | `IconButton` with a label | |
 | Turn something on or off, stays on | `Button selected` or `IconButton selected` (navy) | a toggle's state is `aria-pressed` |
 | Switch between a few views of one thing | `Segmented` (a switch) | inside the card it filters |
-| Move between 2 to 4 views of one thing | `Segmented tabs` (a real tablist) | no tab row of its own styles; no inner tabs on a board page |
-| Move between 5 or more sections of a settings or detail page | `Tabs` (underline) | scrolls sideways on a phone |
-| Know where you are in a deep hierarchy | `Breadcrumb` | collapse the middle over four levels |
+| Move between 2 to 4 views of one thing | `Segmented tabs` (a real tablist) | the well look carries a figure per tab; no tab row of its own styles |
+| Move between 5 or more sections of a settings or detail page | `Tabs` (underline) | overflow shows an edge fade; more than four on a phone become a `Select` |
+| Filter a whole page by period and scope | `FilterBar` (new) | one per page, under its head, docking into the bar as the page scrolls; a filter for one chart stays in that card |
+| Know where you are in a deep hierarchy | `Breadcrumb` | the root crumb never shrinks; collapse the middle over four levels |
 | Move through a long collection | `Pagination` in the card's foot | |
-| A product of several pages that is not chat-first | `AppShell` and `TopBar` | the same rows, gutters and one navy button as the chat shell |
+| A product of several pages that is not chat-first | `AppShell` (with its sidebar) and `TopBar` | the same rows, gutters and one navy button as the chat shell |
 | A single page: an artifact, a report, an internal page | `Page` with a `PageBar` | no shell; its board holds the cards; start from `Starter` |
-| Open the one thing's details | a link `Card`, a `Well` row, a table row | it opens in the panel beside the chat, or the page's side pane |
+| A thread or app page in place of the chat | `PageBar`'s 56 px thread header | the page's name, the app's name, its acts, the way back |
+| Open the one thing's details | a link `Card`, a `Well` row, a `CheckRow`, a table row | it opens in the panel beside the chat, a drawer, or the page's side pane |
 | A list of things to ask or start | `Well` (its rows are `WellRow`s) | every "what to ask" list |
+| A few starters under an ask field or in the chat | `SuggestionChip` (new) | short, sentence case, at most a row of them |
+| Choose light, dark or the system's | `ThemeSwitch` (new) | at the foot of the nav; dark is opt-in (Colour) |
 | Find a page or a command | a command palette on ⌘K (a pattern; no catalog piece yet) | |
 | Show a keyboard shortcut | `Kbd` | beside the command it runs, never alone |
 
@@ -36,11 +42,12 @@ Each user need, the component that answers it, and the rule that decides. Start
 | Choose one of many | `Select` | over 5 options, or a choice that changes the data rather than the view |
 | Choose one of many with search, or several as tags | `Combobox` | over about 20 options, or when the list is open-ended ("Create 'Pine Street'") |
 | A number with a unit or steps | `NumberInput` | |
+| A value on a range (a team size, a share) | `Slider` (new) | the value said in words beside it |
 | A password | `PasswordInput` | |
 | A file | `FileUpload` | |
 | Choose several | `Checkbox` | independent choices; the label is part of the target |
 | A setting that applies at once | `Switch`, with "Saved" shown for a moment | the whole row is the target |
-| Talk or type to an agent | `Composer` | the one chat box |
+| Talk or type to an agent | `Composer` | the one chat box; a drawer's small ask field is its compact look |
 | Pick a date or a range | `DateInput` (native first, with its popover month grid) | |
 | Search a list | `Input` with the search icon, in the card it searches | (Patterns) |
 
@@ -48,32 +55,45 @@ Each user need, the component that answers it, and the rule that decides. Start
 
 | Need | Component | Rule |
 | --- | --- | --- |
-| A question with an answer and an act | `Card` (title, one line, body, band) | the whole site's unit |
+| A question with an answer and an act | `Card` (title, one line, body, foot or band) | the whole site's unit; rimmed (Space and layout) |
 | Several questions on one page | `CardBoard` of cards | one card per question; the key cards first |
+| A main column with a side column | `Split` (new) | the aside a fixed width, tops aligned, stacking by container width |
 | A list or a pipeline | one `Card` holding rows or a board | a list is one card, never loose rows on the page |
+| A list beside the one item it opens (an inbox) | `ListDetail` (new) | the list one column, the item the rest; the chosen row stays lit; on a phone the item is its own screen |
+| A short grouped list in a side column, no card | `SideList` (new) | small heads, 0.5 px dividers, rows that open |
+| Several ratings or checks, each opening its detail | `CheckRow` (new) in a rimmed `Card` | name, a tick strip, the figure and the status in fixed right-aligned columns |
+| A checklist of fixes with one act each | `CheckRow` (new), the fix form | the box, the title and its effort, one act, a chevron that opens the detail in place |
+| Yes or no across a few sources (a question by platform) | `Matrix` (new) | one column template for head and rows; hovering a row dims the others |
 | Repeated attributes to compare (columns) | `Table` inside a card | only when the question is about columns; when each item is read as a thing (a person), rows |
 | Who leads, by a score | `Leaderboard` | the person's own row lit |
 | What to do next, one row a person or thing ("who needs a nudge") | `ActionList` in a `Card` | the reason in words with its figures; one secondary act per row; a bulk act in the band |
 | What happened, in order | `Timeline` | |
 | Things moving through stages | `KanbanBoard` | a card glides between stages |
 | A few facts about one thing | a `Plate` of label and value rows | inside the card |
-| A number that matters | `GoalTicks` (the 72 px number with its change chip) or `StatTiles` (several 40 px figures) | one 72 px number per card; tiles only where the answer is numbers |
+| A score that answers a report | `ScoreHero` (new) | the 96 px score, its strip, the rating word and one sentence; one per report |
+| A number that matters | `GoalTicks` (the 72 px number with its change chip) or `StatTiles` (several figures) | one hero figure per card; tiles only where the answer is numbers |
+| A key metric that opens across its row | `MetricTile` (new) | closed: label, figure, pace bar, foot; open: its chart and side column |
+| Progress against a pace or a target | `PaceBar` (new) | the fill, the pace mark, the figure in words beside |
 | A change since when | `ChangeChip` (in `Chip`) | an arrow and words, never colour alone |
-| A count, a kind, a state | `Chip` | |
+| A count, a kind, a state | `Chip` | a rating's tag takes the rating's tint and word |
 | A disclosure ("Why", "All details", a chapter) | `Fold` (card, quiet or row) | the one disclosure; never a custom accordion |
 | A small group inside a card | `Section` | |
-| A tile in a bento | `Tile` | |
+| A tile in a bento, or the row of what an app can do | `Tile` | the tile row sits on the well, each tile a door or the step it waits on |
 | People | `Avatar` (and its stack) | |
 | An agent | the assistant's own mark, drawn by the designer (no catalog piece) | still outside the chat (AI experiences) |
-| A short tip on hover or focus | `Tooltip` | never the only place a label lives |
+| A short tip on hover or focus | `Tooltip` | never the only place a label lives; its navy note holds a cell's full words |
+| A reading of a chart's mark under the pointer | `HoverCard` (new) | a caret to its mark; the value is still written beside the mark |
 | Content anchored to a control (a small form, an explanation) | `Popover` | Escape closes, focus returns |
 | A count on a face, an icon or a row | `Badge` | a dot alone where a number would crowd |
+| Charts of every kind | Charts | `TickStrip`, `ShareBar`, `StepLine`, `Heatmap`, `SegmentedProgress` and the rest |
 
 ## Containing and interrupting
 
 | Need | Component | Rule |
 | --- | --- | --- |
-| Inspect one thing while keeping the list or chat | `Panel` (440 beside the chat) or a page's side pane | the same view component in both; Close is a word |
+| Inspect one thing while keeping the list or chat | `Panel` (440 beside the chat, or a rimmed drawer beside a report) or a page's side pane | the same view component in each |
+| The chat as a bar, docked beside a page, floating or full screen | `ChatShell` (new) | one chat; it moves between its modes as itself |
+| One long conversation, marked by topic | `TopicRail` (new) with `ChatShell` | the topics as a rail; the conversation stays one thread |
 | A short blocking task (confirm, name, one field) | `Dialog` | sparingly; head, content, foot with the one primary last |
 | A list of acts | `Menu` | the three dots open it |
 | A quiet confirmation of a background act | `Toast` | essential information lives elsewhere |
@@ -86,16 +106,24 @@ Each user need, the component that answers it, and the rule that decides. Start
 
 | Need | Component | Rule |
 | --- | --- | --- |
-| Content on its way | `Skeleton` | never a spinner for content |
-| A press waiting on its answer | `Button pending` | a second press waits; the button stays focusable |
+| Content on its way | `Skeleton` (the shimmer, one quiet grey, over ghost shapes) | never a spinner for content |
+| An answer at work | `StatusLine` (new) | the agent, what it is doing, the step |
+| A long load with no figure | `LoadBar` (new) | it never claims to finish before it has |
+| A press waiting on its answer | `Button pending` | keeps its width; a second press waits; the button stays focusable |
 | A long job | `Stepper`, or a `Meter` for a share done | |
-| Nothing here yet | `EmptyState` | first use, no matches and unavailable differ (Patterns) |
+| Nothing here yet | `EmptyState` | a plain cream card; first use, no matches and unavailable differ (Patterns) |
 | Data that does not exist | nothing: leave the card out | never a placeholder card |
 
 ## Deciding between near neighbours
 
-- **Dialog vs panel vs page**: one field or a yes/no is a dialog; a thing with its own content is a panel; anything with
-  steps, several sections or its own navigation is a page (or an entry step), never a dialog.
+- **Dialog vs panel vs page**: one field or a yes/no is a dialog; a thing with its own content is a panel or a drawer;
+  anything with steps, several sections or its own navigation is a page (or an entry step), never a dialog.
 - **Chip vs ChangeChip vs word**: a chip names a kind or a count; a change chip says how a number moved; a plain word in a
   tone says a state inside a sentence.
+- **TickStrip vs TickRow vs GoalTicks**: a share across the full width in one tone is a `TickStrip`; a small count of a
+  few ticks is a `TickRow`; a goal's one number with its gradient strip is `GoalTicks`.
+- **CheckRow vs Table vs ActionList**: things read as ratings or fixes, each opening its detail, are `CheckRow`s; columns
+  to compare are a `Table`; who to act on next, each with a reason, is an `ActionList`.
+- **ListDetail vs Panel**: when choosing a row is the whole page's job (an inbox), the detail shares the page's grid
+  (`ListDetail`); when the list is the page and the detail is a visit, it opens in a `Panel`.
 - **Editing**: inline, panel or page, as Patterns' editing table says.