@felloinnovations/brand-kit 0.0.0-stage → 0.5.0

package/AGENTS.md

@@ -0,0 +1,286 @@
+# brand-kit for coding agents (0.5.0)
+
+Read this before writing UI in any Fello project that uses `@felloinnovations/brand-kit`. It ships inside the
+package at `node_modules/@felloinnovations/brand-kit/AGENTS.md`. The HubSpot website (felix-theme) is out of scope:
+it follows its own repo's rules.
+
+---
+
+## Where things are
+
+All paths are under `node_modules/@felloinnovations/brand-kit/`.
+
+| Path | What it is |
+| --- | --- |
+| `design-system/README.md` | The guide's front page. Read it first. |
+| `design-system/01-how-claude-decides.md` | The decision workflow: situation, recipe, components, foundations, states, verify. Follow it in order. |
+| `design-system/<NN>-*.md` | The other numbered chapters, one per topic: colour, type, space, sizing, scrolling, choosing components, charts, patterns, page recipes, content, motion, accessibility, AI experiences, creativity, public pages, palettes (`20-palettes.md`), decisions, and `18-checklist.md`. |
+| `design-system/components/README.md` | The catalog's index: every component by group, one line each. |
+| `design-system/components/<Name>/` | The catalog: `README.md` (use, anatomy, states, rules) and `preview.html` (markup to copy). |
+| `tokens/tokens.md` | Every token and its value, light and dark, and every word's contrast on every ground. Grep it before writing any value. |
+| `dist/fello.css` | The whole kit in one file, in cascade layers. |
+| `dist/fello.scoped.css` | The whole kit under a `.fello` root, for an app inside a host it does not own. |
+| `tokens/tokens.css` | Tokens only, as a Tailwind v4 `@theme`. |
+| `scripts/check-palette.mjs` | Checks an app's own palette file against the contract (Palettes, below). |
+
+The same guide is hosted, always current, at `https://brand-kit-site-production.up.railway.app/latest/llms.txt`
+(pinned copies under `/v/0.5.0/`).
+
+---
+
+## Which stylesheet
+
+| Your app | Import |
+| --- | --- |
+| Owns its page, Tailwind v4 | `tokens.css` and `fello.css` (below) |
+| Owns its page, no Tailwind | `fello.css`, or `tokens.root.css` for the tokens alone |
+| Owns its page, Tailwind v3 | the scoped build (below): v3's preflight is unlayered and beats every layered `fello.css` rule |
+| Lives inside a host it does not own: a platform's guest app, a shared bundle, a Tailwind v3 host, a host with its own shadcn tokens | the scoped build (below) |
+
+- **`fello.css`** (`@felloinnovations/brand-kit/fello.css`): Instrument Sans, every token (kit and product layer, light
+  and dark), and the `ws-*` component classes the catalog markup uses. Every rule sits in a `fello` layer nested in
+  Tailwind v4's own (`theme.fello`, `base.fello`, `components.fello`), so the app's utilities still win and its theme
+  stays its own. Its resets touch only elements that wear a `ws-*` class or sit inside one; only `html` and `body` are
+  styled bare. Unlayered CSS beats every layered rule, so an app's own bare `button`, `body` or `*:focus` rules now win
+  over the kit: keep them in a layer or off `ws-*` elements, or take the scoped build.
+- **`tokens.css`** (`@felloinnovations/brand-kit/tokens.css`): the tokens only, as a Tailwind v4 `@theme`, so utilities
+  such as `bg-brand-salmon` exist. It leaves Tailwind's `--radius-*` names to the host; the kit's corners are the
+  `--ws-radius-*` lengths.
+
+A Tailwind v4 app usually takes both, with the font first:
+
+```css
+@import url("https://fonts.googleapis.com/css2?family=Instrument+Sans:wght@400..700&display=swap");
+@import "tailwindcss";
+@import "@felloinnovations/brand-kit/tokens.css";
+@import "@felloinnovations/brand-kit/fello.css";
+@source "../node_modules/@felloinnovations/brand-kit/dist";
+```
+
+The font line comes first: compiled into one stylesheet, `fello.css`'s own font `@import` lands after Tailwind's rules,
+where a browser drops it and the face never loads. A `<link>` to the same URL in the document head (or `next/font`)
+does the same job. The `@source` line is what makes Tailwind generate the classes the kit's React components use.
+
+**The scoped build** puts every rule under `.fello`, renames the keyframes `fello-ws-*`, and changes nothing outside a
+`.fello` element:
+
+```tsx
+import { felloScopedCss } from '@felloinnovations/brand-kit/scoped';
+
+<div className="fello">
+  <style>{felloScopedCss}</style>
+  {/* the app */}
+</div>
+```
+
+Or link `dist/fello.scoped.css`. Put `class="fello"` on the app's root and on the root of every portal (a menu, a tooltip,
+a dialog rendered outside it), or those lose the kit. It has no font `@import`: link Instrument Sans yourself. The string
+is plain TypeScript, so a Node test run that cannot load CSS still loads it. The `brand-adopt` skill has the whole path
+for a guest app, without touching the host's lockfile or Dockerfile.
+
+**shadcn**: `shadcn-compat.css` points shadcn's variables at the kit as `var()` refs (follows dark);
+`shadcn-compat.hsl.css` writes bare HSL channels for a `hsl(var(--x))` config, with light, dark and `.dark` values.
+`--primary` is the navy act and `--ring` the navy focus.
+
+---
+
+## Dark theme
+
+Opt-in. A page that sets nothing stays light.
+
+```html
+<html data-theme="dark">            <!-- night, always -->
+<html data-theme="system">          <!-- follow the person's system -->
+<html data-theme="dark" data-ground="navy">   <!-- the navy ground, for brand and event pages -->
+```
+
+Any element takes the same attributes (a container, an app's `.fello` root), and the nearest one wins: dark inside a
+light page, light inside a dark one.
+
+Brand colours stay literal in every theme; semantic tokens carry the swap. So in your own CSS use the semantic names:
+`--color-surface` (never `--color-white`) for a white surface, `--ws-raised` for anything that floats, `--ws-track` for an
+empty track, `--ws-field` and `--ws-field-ink` for a field, `--ws-on-act` for words on the navy act, and
+`--color-text-heading` for a navy mark. A wash or a shadow of your own is
+`color-mix(in srgb, var(--ws-ink) 5%, transparent)` or the same with `--ws-shade`; the 0.4 channels `--ws-ink-rgb` and
+`--ws-shade-rgb` still work but do not follow a palette. Prefer a token over a theme selector; if you must write one, use
+`[data-theme="dark"] .x` (any element, not only `:root`) and repeat it for `system` inside
+`@media (prefers-color-scheme: dark)`. A person's choice is the `ThemeSwitch` component.
+
+---
+
+## Palettes
+
+An app whose colours differ a little from the kit's sets a palette. It never writes its own values for kit tokens on
+`:root` or in `@theme`: such an override goes unchecked, can set a token that should derive, and, being unlayered,
+beats the kit's dark values too. A palette sets only the 33 contract tokens, everything derived recomputes from them,
+and the check proves it AA in light, night and navy.
+
+```html
+<html data-palette="cool">                                   <!-- a built-in: default (none), cool, warm -->
+<div class="fello" data-palette="warm" data-theme="dark">    <!-- on a container, with its own theme -->
+```
+
+- Pick by how it should look, and name your own the same way: never after the app.
+- Your own: write the checked form, one file of `[data-palette="name"] { ... }` and the same with
+  `[data-theme="dark"]`, setting only contract tokens (in dark, only what the kit's dark does not give you). Check it,
+  fix every error, then ship what `--emit` writes, never the file you wrote:
+
+  ```sh
+  node node_modules/@felloinnovations/brand-kit/scripts/check-palette.mjs src/app.css
+  node node_modules/@felloinnovations/brand-kit/scripts/check-palette.mjs --emit src/app.css > src/app.shipped.css
+  ```
+
+  The shipped file nests anywhere (on `<html>` or any container, either way round with the theme, light or dark, both
+  builds) and load order no longer matters. A dark value left out is the kit's derived dark, never the light value.
+  The check reports a hand-written file as "not in the shipped form": as written, its light values also paint in dark
+  wherever the theme sits on another element.
+- A contract token the kit derives (the focus ring from the heading, the raised ground, the alert and positive words,
+  the rating and agent tones) recomputes on a container unless the palette sets it.
+- A `:root` override does not reach the chart fades, tints and empty cell: they are literal on `:root` and derive only
+  on a palette or theme element. Use `data-palette`.
+- Many apps in one bundle: each on its own `.fello` root with its own `data-palette`; its portals carry the same.
+- In JS: `import { palettes, contract } from '@felloinnovations/brand-kit/palettes'` (every built-in resolved per theme).
+
+The contract, nesting and the check are in `design-system/20-palettes.md`.
+
+---
+
+## Face and layer
+
+Name the face before choosing anything (guide chapter 01, step 0: product workspace, dashboard or report, entry,
+public web page, email, deck, mockup). The face sets one of two layers, never mixed on one surface:
+
+- **Product layer**: a cream page and rimmed cream cards (the 1 px tray rim, 8 px corners), flat; one solid navy button
+  per card and per page; 14 px body; compact controls. Built from the catalog markup and `ws-*` classes, wrapped in the
+  app's own thin components.
+- **Marketing layer** (public pages, chapter 19): white cards at 4 px, the salmon gradient button, the kit's big type
+  steps, 16 px body. The package's React `Button`, `Card`, `Input`, `Badge`, `Checkbox`, `Radio` and `Stat` are this
+  layer (`KitButton`, `KitCard` and friends in the catalog).
+
+`Tabs`, `Skeleton`, `Label` and `Toaster` (from `@felloinnovations/brand-kit/toast`) serve both.
+
+---
+
+## The rules
+
+- **Never invent a value.** No raw hex, px font-size, one-off shadow, ad-hoc radius or duration. Every value is a token in
+  `tokens/tokens.md`. If none fits, say so and leave it; do not make one up. A one-off spacing snaps to the nearest step.
+- **Tailwind v4:** write `text-[color:var(--x)]` and `text-[length:var(--x)]`, never bare `text-[var(--x)]`. Tailwind
+  cannot tell a colour from a size behind a bare `var()`, guesses font-size, and drops the colour silently. This has
+  already shipped a bug. Never `--radius-xl` or `--radius-2xl` for a product corner: those are Tailwind's.
+- **Semantic tokens over primitives**: `var(--color-text-heading)`, not `var(--color-brand-navy)`, for the same job.
+  The semantic layer is what lets a colour be retuned, and what turns in dark.
+- **Check the catalog before building a component.** Never redraw one. If the kit has nothing for it, build it in
+  the consuming app from tokens and say what was missing, as an issue
+  (`https://github.com/FelloInnovations/brand-kit/issues/new?template=feedback.yml`). Do not add it to brand-kit and do not open a PR against it
+  from a consuming app; the kit's owners take it from there.
+- **Close but not exact**: pass `className` to a React export (merged through `tailwind-merge`, so your utility wins).
+  Do not fork it.
+- **Layout**: one content edge per surface; numbers in fixed right-aligned columns; rows in a list share one
+  min-height; a selected row never changes size. A scroll region's children never shrink: a child that scrolls says so
+  (`flex: 1; min-height: 0; overflow: auto`). Never `overflow: hidden` on a card or a table. Inline icons are `ws-icon`.
+- **Accessibility**: native elements first; the 2 px navy focus ring on every control (never `outline: none` without a
+  replacement); an error is a message wired with `aria-describedby`; targets 40 px boxed on touch and 24 px for words
+  that act; every word passes AA on its ground (use the word tokens).
+- **Motion comes from the kit** (Motion, below): build with the catalog's classes and the motion comes with them.
+  Never hand-roll a transition, a duration, a curve or a `@keyframes`.
+- **Every page scrolls**: no content trapped by a nested `overflow: hidden` or a fixed-height parent. A field on the
+  cream page has a white ground (`ws-field`).
+- **Words**: sentence case, no em dashes, nothing developer-facing on a screen, never a faked card or number.
+
+Before calling UI done, run `design-system/18-checklist.md`.
+
+---
+
+## Motion
+
+Seth's motion is in `fello.css`, on his springs: build with the catalog's markup and classes and every press, slide,
+fold, enter and exit is already there. The situations, with markup, are in `design-system/13-motion.md`.
+
+- **Never hand-roll it.** No raw duration, `cubic-bezier()`, `ease-in-out`, `transition-all` or `@keyframes` of your
+  own, and no restyling a kit element's transition.
+- **Hover is a tint, never a lift**: `ws-hover-tint` (`--faint`, `--strong`), inside `@media (hover: hover)`. No rise,
+  grow or shadow on hover.
+- **Press**: `ws-btn`, `ws-icon-btn`, `ws-suggestion-chip` and chips that act spring to `--ws-press-scale` on their
+  own; a pressable of your own adds `ws-press`. Rows never scale; they take `--ws-surface-press`.
+- **A choice slides**: `Segmented`, `Tabs`, `AppShell`'s current row, `SideList` and `ListDetail` move their
+  indicator when you move `aria-pressed`, `aria-selected` or `aria-current`. No extra markup or script.
+- **Opening in place**: a kit `<details>`, or `ws-unfold` on a body shown and hidden with `hidden`.
+- **Over the page**: `Menu` and `Popover` as a native `popover`, `Dialog` as a native `<dialog>`; a `Toast`,
+  `HoverCard`, `Panel` or mounted menu gets `data-leaving` and stays until its exit has played
+  (`Promise.allSettled(el.getAnimations().map((a) => a.finished)).then(() => el.remove())`). Opens grow from their
+  source; every exit is quicker than its entrance.
+- **The two moves CSS cannot start**, both from the package root (under reduced motion, or without view transitions,
+  each just runs the update):
+
+  ```ts
+  import { morph, reorder } from '@felloinnovations/brand-kit';
+
+  // as: 'full' a card to full screen and back, 'grow' / 'shrink' a tile opening and closing, 'shift' the chat's modes
+  morph(() => flushSync(() => setFull(true)), { as: 'full', el: cardRef.current, close: () => flushSync(() => setFull(false)) });
+  // rows re-sorting or filtering, a card moving column
+  reorder(() => flushSync(() => setRows(sorted)), listRef.current);
+  ```
+
+- **A dashboard** wears `ws-build`, each card `ws-build__card` with `--ws-i`; **loading** is `Skeleton` (the shimmer),
+  never a spinner; **charts** take their `--draw` variant.
+- **Your own part** (nothing in the catalog has it): a spring for what the person drives,
+  `transition: <prop> var(--ws-spring-<name>-duration) var(--ws-spring-<name>)` (the table in `13-motion.md`, "Which
+  spring, when"); `--ws-duration-*` with `--ws-ease-*` for what the system plays. In React the same springs:
+  `import { springs, eases } from '@felloinnovations/brand-kit/tokens'`, every motion tree in
+  `<MotionConfig reducedMotion="user">`.
+- **Reduced motion is still**: write your own motion inside `@media (prefers-reduced-motion: no-preference)`; the
+  kit's net does the rest. Every change lands in its final state at once.
+- **Check it** against the Motion card (`design-system/components/Motion/preview.html`: the playground and the
+  206-row reference), side by side.
+
+---
+
+## Checking it
+
+The kit's own checks run in the kit's repo, for anyone changing a catalog component (only `check-palette.mjs` ships in
+the package; the rest show what "done" means for your own screens too):
+
+```sh
+node scripts/check-geometry.mjs --only Name1,Name2 --widths 320,390,1440   # alignment, spacing, centring, clipping, targets
+node scripts/check-geometry.mjs --only Name1,Name2 --theme dark
+node scripts/check-geometry.mjs --only Name1,Name2 --palette cool          # any built-in palette, with or without --theme
+node scripts/check-geometry.mjs --only Name1,Name2 --hover                 # rest, hover and focus; no lift, still under reduced motion
+node scripts/check-geometry.mjs --only Name1,Name2 --hover --motion        # the same with motion on: a lift that only plays then
+node scripts/check-scope.mjs                                               # the scoped build leaks nothing; fello.css resets miss the host
+node scripts/check-palette.mjs [file.css]                                  # the built-ins, or a palette file, against the contract
+```
+
+Open every screenshot the geometry check writes. In an app, run the same eye over the screen at 320, 390 and 1440,
+light and dark, with the keyboard, with motion on and with reduced motion (Checklist, "Senior QA, by eye").
+
+---
+
+## Provisional values
+
+Not signed off and **will change**. Do not build anything load-bearing on them, and flag it when you use one:
+
+- `--color-feedback-*`, `--color-alert`, `--color-stat-positive`: inherited from the HubSpot boilerplate.
+- The kit `Button`'s `tertiary` and `clean` themes, and all kit `Badge` tones.
+- The dark values of the glass stage and the frame gradient: derived, not drawn.
+
+---
+
+## Paste this into your project
+
+Add to the consuming repo's `CLAUDE.md` or `AGENTS.md`:
+
+```markdown
+## Design system
+
+This project uses `@felloinnovations/brand-kit` (the Fello brand kit). Before writing any UI, read
+`node_modules/@felloinnovations/brand-kit/AGENTS.md`, then the guide's front page
+`node_modules/@felloinnovations/brand-kit/design-system/README.md` and its workflow `01-how-claude-decides.md`.
+
+Every value is a token in `node_modules/@felloinnovations/brand-kit/tokens/tokens.md`: never invent a colour,
+size, radius, shadow or duration. Motion comes with the catalog's classes (`design-system/13-motion.md`): never
+hand-roll a transition. Check the catalog (`design-system/components/`) before building a component. Write
+`text-[color:var(--x)]`, never `text-[var(--x)]`. Dark is opt-in (`data-theme`). This app's own colours are a palette
+(`data-palette`, `design-system/20-palettes.md`), checked with `scripts/check-palette.mjs` and shipped as its
+`--emit` writes it, never tokens retuned on `:root`. Run `design-system/18-checklist.md` before calling UI done.
+```

package/CHANGELOG.md

@@ -0,0 +1,328 @@
+# Changelog
+
+## 0.5.0 (4 Nov 2026)
+
+The kit the whole team can trust: teams kept hitting alignment, spacing and placement bugs, and Seth (the designer) has
+new, detailed work to learn from. 0.5.0 rebuilds the product layer on his six Fia frames and his North app, fixes every
+fault the field found, stops `fello.css` restyling other apps, adds an opt-in dark theme and lets every app keep its own
+palette. Fifteen decisions set the defaults (D1 to D15 in Decisions, 4 Nov 2026), D1 to D14 open to Amit's veto; every
+kit rule they overturn is logged with Seth's source.
+
+- **Seth's layout, measured.** One content edge per surface; numbers in fixed right-aligned columns; rows in a list share
+  one min-height and a selected row never changes size; dividers 0.5 px and full width; four half steps on the 4 px
+  grid (2, 6, 10, 14), every other value snapped; a 32 px app gutter, the stage 13 from the top and 12 from the right
+  and bottom; layouts re-lay out by the room they have, never just shrink.
+- **The rimmed card.** Every product card is Seth's tray: a 1 px #EDEDED rim, concentric corners (8 and 7; a drawer 12
+  and 11), the cream surface, an optional foot on the rim, no outline and no shadow at rest. Same class names, so markup
+  upgrades in place except the items in "Upgrading from 0.4" below.
+- **Type gains Seth's steps**: a 96 px report score, 44, 32 and 28 px figures, 13/18 control words, 15/22 sections, 15/20
+  row names.
+- **Words AA on every ground.** Every word token is computed on eight grounds in light, night and navy, and the build
+  stops on a fail. Muted words are #666666. New word and mark tokens for needs work (pink), alert and past halfway; a
+  rating is teal, mid blue or pink.
+- **Motion from North**: role-named durations, curves and staggers, and Seth's springs in `tokens.ts` (`springs`,
+  `eases`); hover is a colour, never a lift; opens grow from their slot and their details settle after; loading is a
+  shimmer in the chart colours. Everything is still under reduced motion, by a net on every kit element.
+- **Motion comes with the components, and the guide says how.** Seth's springs are CSS too (`--ws-spring-<name>` over
+  `--ws-spring-<name>-duration`, a `linear()` curve with its overshoot kept), so buttons and chips press on a spring,
+  `Segmented`, `Tabs`, `AppShell`, `SideList` and `ListDetail` slide their indicator (CSS anchor positioning), every
+  kit `<details>` and `.ws-unfold` folds, and menus, popovers, dialogs, toasts, tooltips, hover cards and panels grow
+  in from their source and leave quicker; `morph()` and `reorder()` do the two moves CSS cannot start. Motion is
+  rewritten by situation (hover, press, a choice, a fold, an overlay, full screen, a reorder, a dashboard, loading,
+  charts), with which spring to use when, the reduced-motion and older-browser fallbacks, and the Motion card as the
+  reference; the skill, AGENTS.md, the Checklist, `brand-new` and `brand-audit` carry the same rules, and
+  `check-geometry --hover --motion` catches a hover lift that only plays with motion on.
+- **Dashboards build in, in every app** (Amit, 5 Nov). `.ws-build` on a page or section: its cards rise in 70 ms apart
+  and each card's charts draw as it lands, once, as it scrolls into view (a scroll trigger where the browser has one,
+  first paint elsewhere). `MetricTile` gains North's mini charts (a column strip, a line with dots) that grow and draw
+  in and wake to their tone on hover; `SideList` goal rows fill in order, navy, teal past the goal, red behind.
+- **`TrendLine`, a value over periods as a line or as columns.** Bars / Line morphs between them: the columns melt into
+  the line on `--ws-spring-morph-chart` while it draws, and grow back down from the dots. A band slides to the hovered
+  period and a dot grows; a real table reads it out. It builds in on arrival, or as it scrolls into view. Motion's
+  playground now opens on a dashboard that builds in (four tiles, the goals, the chart card) with Replay the arrival.
+- **Full screen covers the window from anywhere.** `morph(update, { as: 'full', el })` lifts a chat card into the top
+  layer while it is full (a manual popover), with Escape (`close`) and focus in and back, so the chat's glass, AppShell's
+  stage or any ancestor with a transform, filter, `contain` or `will-change` no longer squashes it into a strip. The
+  stage draws its blur on a layer, so a toaster or a phone's full-screen panel inside it reaches the window, and a
+  tooltip anchors to the window, so the bar and the body's scroll no longer cut it. The Motion card opens on a
+  playground: a product screen with every North move live and a numbered hint at each.
+- **Focus you can see**: a 2 px navy ring 2 px outside everything that takes focus, drawn inside dense rows. The old
+  salmon halo was 1.21:1.
+- **Dark, opt-in**: `data-theme="dark"` or `"system"` on `<html>` or any container, `data-ground="navy"` for the navy
+  ground; the nearest wins, so light inside dark works and the reverse. A page that sets nothing stays light. Brand
+  colours stay literal; semantic tokens carry the swap.
+- **Palettes: one kit, many apps** (D15). A palette sets only the contract, 33 existing semantic tokens listed with
+  their meaning in `design-tokens.json` and the new Palettes chapter; everything derived recomputes inside the element
+  that sets it, and so does a contract token the kit derives (the focus ring from the heading, the raised ground, the
+  alert and positive words, the rating and agent tones) unless the palette sets it. Built-ins named for how they look:
+  `default` (no attribute), `cool`, `warm`. The first product's tally navy gets no palette: Seth's #2C4870 wins (D1)
+  and the product adopts it. On `<html>` or any container, light or dark, nested either way, in `fello.css` and the
+  scoped build, so many apps in one bundle each keep their own. `scripts/check-palette.mjs` ships in the package and
+  checks any app's palette file (contract only, every word AA on every ground, the focus ring and the act 3:1, chart
+  tones apart) in light, night and navy; `--emit` then writes the file to ship, in the built-ins' own form, so an app's
+  palette nests anywhere too and load order no longer matters. A dark value a palette leaves out is the kit's derived
+  dark, never its light value. `palettes` and `contract` come from the package and
+  `@felloinnovations/brand-kit/palettes`. The gallery's Components page gains a theme and palette switch.
+- **Every colour follows the palette** (D15), in light, night and the navy ground. Component styles carry no colour
+  literal (`build-bundle --check` fails on one), and every colour a component paints derives from the contract. The
+  dark tints and fades are now their tone over the dark page (within CIEDE2000 3.5 of the old literals), so an app's
+  dark page moves them; the dark alert tone #FF5A5A became #FF5470, which a chart can tell from salmon. New tokens
+  (none renamed): `--ws-frame-top`, `--ws-stage-foot`, `--ws-agent-coach`, `--ws-agent-growth`, `--ws-agent-recruit`;
+  `--ws-ink` and `--ws-shade` (the ink of washes and rings, the tint of a drop); `--ws-inverse` and `--ws-on-inverse`
+  (the toast, note and footer pair); `--ws-control-off` (a switch's off track); `--ws-shimmer-ground`; `--ws-glow-rose`,
+  `--ws-glow-pink`, `--ws-glow-blue` and `--ws-orb`; `--ws-mask` for mask stops. `--ws-ink-rgb` and `--ws-shade-rgb`
+  stay as legacy and do not follow a palette. Kit aliases now: `--color-border-default` is `--ws-edge`, the hairline
+  `--ws-edge-card`, `--color-stat-positive` `--ws-chart-finished`, `--color-text-brand-strong` `--ws-word-needs`.
+  Still the brand's under any palette, by ruling: the toast, the note tip and the footer keep the brand navy with white
+  words in dark; `KitButton`'s salmon and navy acts and the `Cover` logo; the navy ground's fields. Proof:
+  `check-palette` finds a leftover statically (a colour a component reads that no contract token moves), and the
+  poison test (`scripts/palette-poison.mjs`, run in CI from `check-scope`) sets each contract token to a wild colour
+  on `<html>` and on a container around every preview, light and dark, and finds nothing stale, leaked or constant.
+- **`fello.css` stops leaking** into the apps around it: every rule sits in a `fello` layer nested in Tailwind's own, so
+  utilities win; resets touch only kit elements; Tailwind's radius names stay the host's. New `fello.scoped.css` and
+  `@felloinnovations/brand-kit/scoped` (the CSS as a string) put everything under a `.fello` root for a guest app in a
+  shared host. `shadcn-compat.hsl.css` for `hsl(var(--x))` configs; `--primary` is now the navy act.
+- **The shell owns its scroll** (the Revenue OS audit, K1 to K17): nothing squashed by its scroller, screen-reader words
+  no longer stretch the window, dialogs scroll and fit the window, drawers are the whole screen on a phone, menus open
+  in the top layer, one touch block (40 px boxes, 24 px words), inline icons sized (`ws-icon`).
+- **New components**: Split, HoverCard, ListDetail, SideList, Matrix, CheckRow, Slider, FilterBar, ThemeSwitch,
+  TickStrip, ScoreHero, SegmentedProgress, ShareBar, StepLine, Heatmap, MetricTile, PaceBar, StatusLine, LoadBar,
+  SuggestionChip, TopicRail and ChatShell. Issues #5 to #12 are done (GoalBars, the v7 ring, TickRow sizes, the Example
+  tag, the tile row, the snug card, the first-open recipe).
+- **The guide**: Space and layout, Motion, Scrolling, Colour and Type rewritten; interaction states (hover, press, focus,
+  selected, pending, loading) in Patterns; every new component in Choosing components and Charts; three new recipes
+  (the first open of an AI app's thread, a report with its drawer, an inbox list and detail) and a dashboard home;
+  Accessibility on focus and reduced motion; Checklist gains the geometry check and a senior QA list.
+- **Checks**: `yarn check:geometry` measures every preview at 320, 390 and 1440 (`--theme dark`, `--palette cool`,
+  `--hover` for focus);
+  `yarn check:scope` proves the scoped build changes nothing outside `.fello` and `fello.css`'s resets never touch
+  the host's markup. The skills and AGENTS.md cover the scoped build,
+  dark and the checks; `brand-adopt` gains the guest-app path (no root lockfile or Dockerfile change).
+
+### Upgrading from 0.4
+
+Most markup keeps working: the class names stay, and a card, a button or a row takes the new look by itself. These are
+the exceptions. After the bump, run `yarn check:geometry` on your own previews (or look at each screen at 320, 390 and
+1440) before you ship.
+
+**Classes removed** (7, the only ones 0.4 had that 0.5 does not)
+
+| 0.4 | 0.5 |
+| --- | --- |
+| `ws-stat-tiles__stripe` with `--navy`, `--purple`, `--salmon` or `--teal` | Gone: Seth's tile has no stripe, so delete the element. Where the tone meant a category, put it on the tile's mark: a `ws-tick-row ws-tick-row--tall` with `style="--tone: var(--ws-chart-...)"` in `__value-row` |
+| `ws-stat-tiles__ticks` | A `ws-tick-row` (`--tall` for Seth's size) inside `ws-stat-tiles__value-row`, beside the figure |
+| `ws-funnel-bars__fill--first` | Delete it: every bar takes the same 4 px corners now |
+
+**Markup to change**
+
+| Piece | 0.4 | 0.5 |
+| --- | --- | --- |
+| StatTiles | `<ul class="ws-stat-tiles">` of `<li class="ws-card ws-stat-tiles__tile">` | `<div class="ws-stat-tiles"><ul class="ws-stat-tiles__grid">` of `<li class="ws-stat-tiles__tile"><div class="ws-stat-tiles__surface">...</div><div class="ws-stat-tiles__foot">...</div></li>`. The 0.4 form still lays out (as many tiles of at least 14 rem as its own width holds) but gets no count rule and no foot |
+| A card with a foot | the 80 px band (`ws-band`) for every act | On a page: `<div class="ws-card"><div class="ws-card__surface">...</div><a class="ws-card__foot">...</a></div>`, the foot on the tray. The band stays for a chart card's one act |
+| AppShell, to pin the person | `__wordmark`, `__rows` and `__foot` straight inside `__nav` | `__head` (holding `__wordmark`), then `__groups` (holding each `__group` and its `__rows`), then `__foot`. Without the wrappers the person scrolls away with the rows |
+| A page in AppShell | a `.ws-page` inside `__body` | No `.ws-page` there: the body is the page (its gutter, gap and size container) |
+| PageBar | `__words` held the `h1` and a `<p class="ws-body">` sentence under it | `__words` is one line: `__face`, the `h1` `__title`, a short `__context` word. An old sentence now sits inline beside the title; move it into the page under the bar |
+| Ring, the split | `.ws-ring__split` with `.ws-ring__hole` inside `.ws-ring__ticks` | Inside `.ws-ring__split`, a `.ws-ring__plate` holding `.ws-ring__ticks` and then `.ws-ring__hole` (with `__total` and `__caption`). An old hole inside the ticks shows the dots through it |
+| GoalBars | `__fillbox` held `__not-yet` and `__fill` | Add `<span class="ws-goal-bars__leader"></span>` between them, so each bar's leader runs to its dot |
+| EntryShell, StatusScreen | filled only their parent | A bare page (the shell or the screen straight in `body`) adds `--page` (`ws-entry-shell--page`, `ws-status-screen--page`) to fill and centre in the window. Without it StatusScreen stays in the top third of its parent by design, since it can also sit inside a page as a block |
+| Tooltip | the tip was always drawn; the app mounted it only while it showed | The tip is hidden until its `.ws-tooltip` is hovered or holds keyboard focus; to show it from code, add `ws-tooltip--open` |
+
+**Looks and behaviour that change on their own**
+
+- **Focus**: a 2 px navy outline 2 px outside, on `:focus-visible`, replaces the salmon halo (it was 1.21:1). A host rule
+  such as `*:focus { outline: none }` now hides the kit's focus: remove it.
+- **Corners**: buttons and square icon buttons 6 (were 4); `IconButton` is a square, `ws-icon-btn--round` for voice and
+  send; chips 4 (were 2); checkboxes and radios 18 px with 4 px corners and a navy edge (were 16 and grey); cards 8
+  outside, 7 inside; dialogs and drawers 12; menus 10; the toast an 18 px pill.
+- **Cards**: the rim is a 1 px `border` in the tray colour, so a card's inside is 2 px narrower and a `border` of your own
+  replaces the rim. A child that rounds with the card takes `--ws-radius-card-inner`. Hover on a pressable card darkens
+  the rim; nothing lifts.
+- **Buttons**: words 13/18 (were 14/16), `--lg` 40 tall (was 36), `--secondary` has no fill (the cream is gone; the new
+  `--well` sits on the tray), primary hover brightens instead of dimming. A button still stays on one line and never
+  shrinks beside its row's words, as in 0.4; a label that can be wider than its column opts in with `ws-btn--wrap`
+  (balanced lines). The halves of a `ws-btn-split` stack, full width, instead of breaking a label.
+- **Card heads wrap**: in a `.ws-head` the aside drops under the title, as one piece, when it would squeeze the title
+  below 200 px, where 0.4 kept one line. Put controls that may drop together in one element (a `ws-cluster`). Icon acts
+  (a close, an expand) never drop: they stay top right on the title's first line and the title wraps.
+- **Stacks**: `ws-stack` and `ws-cluster` are 8 apart and no longer read a `--ws-gap` set on a parent; take a modifier
+  for another gap (`--tight`, `--loose`, `--component`, `--group`, and on a stack `--block` 32 or `--section` 56).
+- **Titles** (`ws-title`, `ws-section`) lose their -0.5% tracking and balance their lines.
+- **Hover only where a pointer hovers**: every kit hover sits in `@media (hover: hover)`, so a tap on a phone never
+  leaves it stuck. A hover of your own on a kit piece needs the same query.
+- **Sizes**: the page gutter is 32 (was 24, still 16 on a phone); the folded rail 64 (was 72); a PageBar title 16/22
+  (was 26/32) and one line, with an ellipsis; muted words #666666 (were #6E6E6E). Breadcrumb links are body grey with a
+  "/" (were mid blue with chevrons). Section rows lost their 8 px sides and 6 px corners. Toasts are navy pills.
+- **Tailwind's radius names are the host's again**: `tokens.css` no longer sets `--radius-xs` to `--radius-2xl`, so
+  `rounded-xl` and `rounded-2xl` go back to Tailwind's own sizes. Use the `--ws-radius-*` lengths for kit corners; every
+  kit piece, the marketing ones and the React exports included, rounds with them, so a shadcn `--radius` no longer
+  moves a kit corner.
+- **The font in a Tailwind v4 app**: put the Instrument Sans `@import` before `@import "tailwindcss"` (AGENTS.md), or a
+  `<link>` in the head. Compiled into one stylesheet, `fello.css`'s own font `@import` lands after Tailwind's rules,
+  where a browser drops it, so the face never loaded.
+- **shadcn**: `--primary` in `shadcn-compat.css` is now the navy act with `ws-on-act` words (was salmon with white).
+- **A `:root` override of a chart tone**: the chart fades, tints and empty cell are literal on `:root` and derive on
+  every palette or theme element, so a bare `:root { --ws-chart-under-half: X }` without `data-palette` no longer moves
+  them. Put the change in a palette.
+- **Washes of your own**: `rgba(var(--ws-ink-rgb), a)` still paints, in the default's colours only (it follows the
+  theme, not a palette). Write `color-mix(in srgb, var(--ws-ink) 5%, transparent)` (and `--ws-shade` for a drop) so it
+  follows a palette.
+- **Layers**: `fello.css` sits in cascade layers (`theme.fello`, `base.fello`, `components.fello`, inside Tailwind's own),
+  so your utilities win, and so does any unlayered CSS of yours. In 0.4 a bare `button { ... }` or `body { ... }` rule of
+  the host lost to the kit; now it wins. Put such rules in a layer, scope them away from `ws-*` elements, or take the
+  scoped build. Tailwind v3 (its preflight is unlayered) always takes the scoped build.
+- **An artifact** inlines `fello-core.css` (unlayered) and the blocks of the components it uses, as `Starter` and the
+  skill do, not the whole `fello.css`, which is now over 400 kB and layered.
+
+**Opting in**
+
+- **Dark**: `<html data-theme="dark">` for the night ground, `data-theme="system"` to follow the person's setting, and
+  `data-ground="navy"` beside it for the navy ground (brand and event pages). A page that sets nothing stays light.
+  In the scoped build the same attributes work on the `.fello` element or any ancestor; a host's `.dark` class does not
+  turn the kit.
+- **A palette**: an app whose colours differ a little from the kit's sets `data-palette` instead of retuning kit
+  tokens on `:root`: a built-in, or its own file of contract tokens, checked with
+  `node node_modules/@felloinnovations/brand-kit/scripts/check-palette.mjs <file>` and shipped as
+  `check-palette.mjs --emit <file> > <file>.shipped.css` writes it. The `brand-adopt` skill has the step. A theme
+  selector of your own can now be `[data-theme="dark"] .x` on any element.
+- **The scoped build**, for an app inside a host it does not own (a platform's guest app, a shared bundle) or any
+  Tailwind v3 app: `import { felloScopedCss } from '@felloinnovations/brand-kit/scoped'` and render
+  `<div className="fello"><style>{felloScopedCss}</style>...</div>`, or link `fello.scoped.css`. Put `class="fello"` on
+  every portal's root too (menus, tooltips, dialogs rendered outside the app). It has no font `@import`: link Instrument
+  Sans yourself. `yarn check:scope` proves it changes nothing outside `.fello`.
+
+## Feedback loop (30 Oct 2026)
+
+What the kit misses now reaches its owners. A new `brand-feedback` skill turns a job's gaps (a component built from
+tokens, a missing token, an unclear rule, something broken) into one GitHub issue per gap on this repo, after checking
+for an open one to add to. The other skills and the guide offer it when they finish. Without `gh` (claude.ai, Cowork)
+it gives a link that opens the issue already filled in, through the new feedback issue form. No package change.
+
+## 0.4.0 on npm (30 Oct 2026)
+
+The kit moves from GitHub Packages to the public npm registry, so anyone, any app and any deploy installs it with
+`npm install @felloinnovations/brand-kit`: no token, no `.npmrc`. Same 0.4.0 tokens, CSS and components; the install
+steps in the README, the skills and llms.txt drop every token line. Releases publish from GitHub through npm's
+trusted publishing, with no stored token.
+
+## 0.4.0
+
+The kit gains its guide. Lokesh's design system (his Claude Design System
+export of 26 Oct 2026, built from the first product on the kit) is now part
+of the kit, in `design-system/`: a front page and chapters on how to decide a
+screen, the foundations, patterns, page recipes, content, motion and
+accessibility, plus a catalog of 74 components, each with a README and a
+static preview. It ships in the package and is published as Claude's design
+system, so Claude's Design and Slides use it.
+
+- **Any Fello build, not only workspace screens.** "How Claude decides" covers
+  seven faces (product workspace, dashboard or console, entry, public web page,
+  email or one-pager, deck, mockup or artifact) and two layers (product,
+  marketing), with a quick path at the top for artifacts and mockups. New
+  chapter: Public pages. Built from our products and the website.
+- **The kit's CSS styles every component.** All catalog styles live in
+  `bundle.css` under `ws-<component>` names; previews are markup only. New:
+  `ActionList` (a card's list of next acts), `Page` (`.ws-page`, `.ws-board`),
+  `PageBar`, `Kbd`, and `Starter` (a paste-ready page).
+- **`fello-core.css`** (tokens and house styles, minified, ~29 kB) plus each
+  component's own styles: an artifact inlines only what it uses instead of the
+  whole 140 kB `fello.css`. Each component's card in the skill lists its styles.
+
+- **One token source, now with the product layer.** The `--ws-*` tokens
+  (surfaces, edges, AA words, chart tones, gaps, corners, control heights,
+  layout widths, motion) live in `tokens/_product.css`, written the way the
+  first product writes them (as kit steps, so they move with the kit), and
+  `yarn tokens` emits them with the kit's 106 into every output: 225 tokens
+  in `tokens.css`, `tokens.root.css`, `tokens.ts` and `tokens.md`. Includes
+  the hero washes (`--ws-team-glow`, `--ws-cool-glow`) and
+  `--ws-ease-spring` (no overshoot, so it is the soft curve).
+- **`design-system/tokens.json` is generated** by the same run, in the
+  Claude Design System list format: values resolved to literals (a formula
+  kept at the end of its usage note), colour aliases kept, Lokesh's notes,
+  order and type groups preserved, and the format's rules checked so a bad
+  value fails the run instead of vanishing from the page.
+- Kit names keep the kit's values: `--color-text-muted` is #6E6E6E (4.95:1 on
+  the cream) and the 0.3.0 text tokens (`--color-text-placeholder`,
+  `--color-text-brand-strong`, `-error-strong`, `-success-strong`) are in the
+  design system too. `--ws-word-needs` is now `--color-text-brand-strong`
+  (same hex). Field placeholders in `bundle.css` use
+  `--color-text-placeholder` instead of Gray 5 (2.3:1).
+- **`fello.css`**: one stylesheet with the whole kit, Instrument Sans plus
+  every token as `:root` plus the house component styles (`ws-*` classes).
+  `import '@felloinnovations/brand-kit/fello.css'`, built into `dist/` by
+  every tsup run.
+- **Hosted on the gallery**, with open CORS: `/latest/` and `/v/0.4.0/` each
+  serve `fello.css`, `tokens.css`, `tokens.json`, `llms.txt`,
+  `llms-full.txt`, `guide/<chapter>.md` and
+  `components/<Name>/README.md` + `preview.html`; `/llms.txt` at the root.
+  `/v/` is cached as immutable, `/latest/` is not cached.
+- **`llms.txt`**: a short index of the kit for any model (what it is, how to
+  use it in Claude, in an artifact, a plain page and a React app, and a link
+  with one line for every chapter and component). `llms-full.txt` is the
+  whole guide in one file.
+- The package now ships `design-system/` (export `./design-system/*`), so a
+  coding agent reads the guide from `node_modules`.
+- New component: **Kbd**, a key as printed on the keyboard (`.ws-kbd`).
+- The gallery has a **Guide** page (the design system, chapter by chapter)
+  and a **Components** page (every preview, live, on `fello.css`).
+
+## 0.3.0
+
+Accessibility. Six colour pairs were failing WCAG AA and are fixed:
+
+- `--color-text-muted` un-aliased from Gray 6. #7F7F7F was 4.00:1 on white
+  and 3.89:1 on the cream page, so every muted label in the estate failed. Now
+  #6E6E6E, 5.10:1 and 4.95:1. The grey ramp is unchanged for fills and rules.
+- New `--color-text-brand-strong`, `--color-text-error-strong` and
+  `--color-text-success-strong`: the brand and feedback hues darkened until
+  they clear 4.5:1 on their own tint. Badge labels now use these, which is why
+  a salmon badge's text is not salmon.
+- `--color-text-placeholder`. Input placeholders were Gray 5 at 2.35:1.
+- `Stat` used a raw 28px; now on the scale.
+
+**Still failing, and not changed:** white on the primary button, 2.44 to
+2.65:1. That is the live brand CTA, so it is a brand decision rather than a
+kit one.
+
+Logos and brand assets ship with the kit, and the gallery serves them
+individually and as a zip.
+
+## 0.2.1
+
+- `AGENTS.md` and generated `tokens/tokens.md` ship inside the package, so a
+  coding agent in a consuming repo can read the rules and every token value.
+- CI regenerates `tokens/` and `dist/` and fails on any diff, since both are
+  generated but committed.
+- Releases publish from GitHub Actions on a tag, using the runner's own
+  token. Nobody needs a personal token with `write:packages`.
+
+## 0.2.0
+
+- **Checkbox** and **Radio** / **RadioGroup**, native inputs under a custom
+  skin so form participation, autofill and keyboard behaviour stay the
+  browser's.
+- **Tabs**, on Radix, with `underline` and `pill` variants.
+- **Card**: radius drops to 4px, surface is white by default, shadow only when
+  `interactive`. New `surface` prop (`white` / `tinted` / `transparent`).
+- **Toast** gets a gallery page, and its action button is brand salmon rather
+  than sonner's default black.
+- Gallery is one page per section with hash routing, rather than one long
+  scroll.
+- `AGENTS.md` and generated `tokens/tokens.md` for coding agents.
+- New runtime dependency: `@radix-ui/react-tabs`.
+
+## 0.1.1
+
+- **Fixed:** every `text-[var(--color-*)]` was parsed by Tailwind v4 as a
+  font-size, so primary and navy buttons rendered their labels in inherited
+  body ink instead of white.
+- **Fixed:** `buttonVariants()` used directly on an `<a>` lost its border.
+  Each variant now owns its border rather than relying on `tailwind-merge` to
+  resolve a base/variant conflict.
+- `Toaster` moved to the `/toast` subpath so `sonner` is genuinely optional.
+
+## 0.1.0
+
+- 102 tokens generated from the Figma capture of
+  `Marketing - Design System 3.0`: `tokens.css` (Tailwind v4),
+  `tokens.root.css` (plain CSS), `tokens.ts` (typed), `shadcn-compat.css`.
+- Button, Badge, Card, Input, Label, Skeleton, Stat, Toaster.