@karmo-co/drift-kit-reference 0.0.0-stage → 23.4.0

package/LICENSE

@@ -0,0 +1,7 @@
+Copyright (c) Karmo. All rights reserved.
+
+This package contains reference documentation of Karmo's private Drift design system. It is published so that Karmo's tools can read it.
+
+You may read these files to build or review software for Karmo with the Drift design system. Any other use, including copying, modifying, redistributing or using them to build a design system, is not permitted without Karmo's written permission.
+
+The documentation is provided as is, without warranty of any kind.

package/README.md

@@ -1,3 +1,25 @@
-# Temporary Holding Version
+# @karmo-co/drift-kit-reference
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The reference documentation of Drift, Karmo's private design system, published for Karmo's Claude skills. It holds the facts of one kit version: the components and their markup, attributes and React props, the tokens, how a project sets the kit up, the rules for building a new component, and the upgrade notes between majors.
+
+It does not contain the design system itself. The kit's code and stylesheets are private.
+
+## Use
+
+Its version always matches the kit version it describes. Ask it about the version a project uses:
+
+```
+drift-kit-ref info
+drift-kit-ref search "steps in a flow"
+drift-kit-ref component stepper
+drift-kit-ref tokens motion
+drift-kit-ref setup
+drift-kit-ref rules
+drift-kit-ref changes 21.0.0
+```
+
+Every answer starts with the kit version it describes. A name that version does not have is answered "not in", with the closest names.
+
+## Licence
+
+Documentation only. © Karmo. All rights reserved. See LICENSE.

package/bin/drift-kit-ref.js

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+'use strict';
+/* drift-kit-ref: the facts of one Drift kit version, from the manifest beside
+   this script. It ships in @karmo-co/drift-kit (reading dist/manifest) and in
+   @karmo-co/drift-kit-reference (reading manifest/), so a project reads its
+   own installed version offline and everything else reads the public one.
+   No dependencies, Node 18 or later. Every answer opens with the version it
+   describes; a name the version does not have is answered "not in", never
+   with the nearest entry as if it matched. */
+const fs = require('fs');
+const path = require('path');
+
+const HELP = `drift-kit-ref <command> [argument]
+
+  info                 the kit version these facts describe, and when they were built
+  search "<need>"      components and token groups for a need ("steps in a flow")
+  component <id>       one component: anatomy, attributes, React props, tokens
+  tokens <group>       one token group, light and dark
+  setup                how a project installs and imports the kit
+  rules                the rules for building a new component the kit's way
+  changes <version>    upgrade notes from that version up to this one
+`;
+
+function findManifest(fromDir = __dirname) {
+  for (const rel of ['../dist/manifest', '../manifest']) {
+    const dir = path.resolve(fromDir, rel);
+    if (fs.existsSync(path.join(dir, 'index.json'))) return dir;
+  }
+  throw new Error('No Drift manifest found beside drift-kit-ref (looked for ../dist/manifest and ../manifest).');
+}
+
+// ---------- matching and search ----------
+const normaliseName = (s) => String(s).toLowerCase().replace(/[\s_-]+/g, '');
+
+function editDistance(a, b) {
+  const row = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = row[0];
+    row[0] = i;
+    for (let j = 1; j <= b.length; j++) {
+      const tmp = row[j];
+      row[j] = Math.min(row[j] + 1, row[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1));
+      prev = tmp;
+    }
+  }
+  return row[b.length];
+}
+
+// Closest ids: substring or shared prefix first, then edit distance.
+function closest(ids, name, limit = 3) {
+  const want = normaliseName(name);
+  const scored = ids.map((raw) => {
+    const id = normaliseName(raw);
+    let prefix = 0;
+    while (prefix < id.length && prefix < want.length && id[prefix] === want[prefix]) prefix++;
+    const related = want && (id.includes(want) || want.includes(id) || prefix >= 3);
+    return { id: raw, rank: related ? 0 : 1, score: related ? -prefix : editDistance(id, want) };
+  });
+  scored.sort((a, b) => a.rank - b.rank || a.score - b.score || a.id.localeCompare(b.id));
+  return scored.slice(0, limit).map((s) => s.id);
+}
+
+const STOP = new Set(['a', 'an', 'the', 'in', 'of', 'to', 'for', 'and', 'or', 'on', 'with', 'is', 'it', 'how', 'do', 'i']);
+const words = (s) => String(s).toLowerCase().split(/[^a-z0-9]+/).filter((w) => w && !STOP.has(w));
+const stem = (w) => (w.length > 4 ? w.replace(/(ing|es|s)$/, '') : w.replace(/s$/, ''));
+
+// A whole-phrase hit, then one point per matching term.
+function scoreText(text, phrase, terms) {
+  const t = text.toLowerCase();
+  let s = phrase && t.includes(phrase) ? terms.length + 1 : 0;
+  const tw = words(text).map(stem);
+  for (const term of terms) if (tw.some((w) => w === term || w.startsWith(term))) s += 1;
+  return s;
+}
+
+// Matches on id, name and purpose (weight 10) rank above matches in the body (weight 1).
+function search(m, query, limit = 10) {
+  const phrase = query.trim().toLowerCase();
+  const terms = words(query).map(stem);
+  if (!terms.length) return null;
+  const hits = [];
+  const consider = (kind, id, name, purpose, body) => {
+    let score = 10 * (scoreText(`${id} ${name}`, phrase, terms) * 2 + scoreText(purpose || '', phrase, terms));
+    if (score === 0) score = scoreText(m.read(body) || '', phrase, terms);
+    if (score > 0) hits.push({ kind, id, name, purpose: purpose || '', score });
+  };
+  for (const c of m.index.components) consider('component', c.id, c.name, c.purpose, `components/${c.id}.md`);
+  for (const g of m.index.tokenGroups || []) consider('token group', g.id, g.title, '', `tokens/${g.id}.md`);
+  hits.sort((a, b) => b.score - a.score || a.id.localeCompare(b.id));
+  return hits.slice(0, limit);
+}
+
+// ---------- versions ----------
+const SEMVER = /^(\d+)\.(\d+)\.(\d+)(?:-[0-9A-Za-z.-]+)?$/;
+function compare(a, b) {
+  const x = SEMVER.exec(a), y = SEMVER.exec(b);
+  for (let i = 1; i <= 3; i++) if (+x[i] !== +y[i]) return +x[i] - +y[i];
+  return 0;
+}
+
+// ---------- the commands ----------
+function load(dir) {
+  const index = JSON.parse(fs.readFileSync(path.join(dir, 'index.json'), 'utf8'));
+  const read = (rel) => {
+    try { return fs.readFileSync(path.join(dir, rel), 'utf8'); } catch { return null; }
+  };
+  return { index, read };
+}
+
+function run(argv, manifestDir) {
+  const [cmd, ...rest] = argv;
+  const arg = rest.join(' ').trim();
+  if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') return { code: cmd ? 0 : 1, out: HELP };
+  let m;
+  try {
+    m = load(manifestDir || findManifest());
+  } catch (e) {
+    return { code: 2, out: `The Drift manifest could not be read (${e.code || e.message}), so these facts can't be checked here.\n` };
+  }
+  const v = m.index.version;
+  const head = `Drift kit ${v}.\n\n`;
+  const usage = (what) => ({ code: 1, out: `${what}\n\n${HELP}` });
+
+  switch (cmd) {
+    case 'info':
+      return { code: 0, out: `${head}Built ${m.index.built || 'on an unknown date'}. ${m.index.components.length} components, ${(m.index.tokenGroups || []).length} token groups, upgrade notes for ${(m.index.migrations || []).length} majors.\n` };
+    case 'search': {
+      if (!arg) return usage('search needs a phrase, for example: search "steps in a flow"');
+      const hits = search(m, arg);
+      if (hits === null) return { code: 0, out: `${head}Nothing to search for in "${arg}": try the words for what the screen needs.\n` };
+      if (!hits.length) return { code: 0, out: `${head}Nothing in ${v} matches "${arg}". The kit may not have it: build it on the kit's foundations (rules).\n` };
+      return { code: 0, out: head + hits.map((h) => `- ${h.kind} \`${h.id}\`: ${h.name}${h.purpose ? '. ' + h.purpose : ''}`).join('\n') + '\n' };
+    }
+    case 'component': {
+      if (!arg) return usage('component needs an id, for example: component button');
+      const want = normaliseName(arg);
+      const c = m.index.components.find((x) => normaliseName(x.id) === want || normaliseName(x.name) === want);
+      if (!c) return { code: 0, out: `${head}"${arg}" is not in ${v}. Closest: ${closest(m.index.components.map((x) => x.id), arg).map((id) => '`' + id + '`').join(', ')}.\n` };
+      return { code: 0, out: head + m.read(`components/${c.id}.md`) };
+    }
+    case 'tokens': {
+      if (!arg) return usage('tokens needs a group, for example: tokens motion');
+      const groups = m.index.tokenGroups || [];
+      const g = groups.find((x) => normaliseName(x.id) === normaliseName(arg) || normaliseName(x.title) === normaliseName(arg));
+      if (!g) return { code: 0, out: `${head}Token group "${arg}" is not in ${v}. The groups are: ${groups.map((x) => '`' + x.id + '`').join(', ')}.\n` };
+      return { code: 0, out: head + m.read(`tokens/${g.id}.md`) };
+    }
+    case 'setup':
+    case 'rules':
+      return { code: 0, out: head + (m.read(`${cmd}.md`) || `No ${cmd} notes in ${v}.\n`) };
+    case 'changes': {
+      if (!SEMVER.test(arg)) return usage('changes needs the version you are upgrading from, for example: changes 21.0.0');
+      if (compare(arg, v) >= 0) return { code: 0, out: `${head}${arg} is already at or past ${v}: there are no upgrade notes to apply.\n` };
+      const majors = (m.index.migrations || []).filter((x) => compare(x.major, arg) > 0 && compare(x.major, v) <= 0).sort((a, b) => compare(a.major, b.major));
+      if (!majors.length) return { code: 0, out: `${head}No breaking changes between ${arg} and ${v}: pin ${v} and rebuild.\n` };
+      return { code: 0, out: `${head}Upgrade notes from ${arg} to ${v}, oldest first. Apply one major at a time.\n\n` + majors.map((x) => m.read(`migrations/${x.major}.md`) || '').join('\n') };
+    }
+    default:
+      return usage(`Unknown command "${cmd}".`);
+  }
+}
+
+module.exports = { run, findManifest };
+
+if (require.main === module) {
+  const r = run(process.argv.slice(2));
+  process.stdout.write(r.out);
+  process.exitCode = r.code;
+}

package/manifest/components/accordion.md

@@ -0,0 +1,47 @@
+# Accordion (`accordion`)
+
+A list of things you can open: FAQs, settings, details on demand. Built on <details>, so it works before the script does, with motion that turns round mid-way.
+
+
+## Anatomy (HTML)
+
+```text
+  div.dk-component-accordion[data-variant="separated|joined|flush"][data-size][data-icon="plus"]
+    details.dk-component-accordion__item[name][open]
+      summary.dk-component-accordion__summary[aria-disabled]
+        span.__leading?  span.__heading? > span.__title + span.__description?
+        span.__meta?  svg.__icon (injected when missing)
+      div.dk-component-accordion__panel
+        div.dk-component-accordion__content
+── 
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-flush` | (present or absent) |
+| `data-glyph` | `chevron` |
+| `data-icon` | `plus` |
+| `data-size` | `large`, `small` |
+| `data-state` | `closing`, `opening` |
+| `data-variant` | `flush`, `joined` |
+
+## React
+
+```tsx
+import { Accordion } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'separated' \| 'joined' \| 'flush'` | separated (default): a stack of cards. joined: one card with rules between items. flush: rules only, for an accordion already in a card. |
+| `size` | `'small' \| 'medium' \| 'large'` |  |
+| `icon` | `'chevron' \| 'plus'` |  |
+| `exclusive` | `boolean \| string` | One open at a time. true makes a group name; a string names it, which is the <details name> the platform makes exclusive before any script runs. |
+| `className` | `string` |  |
+| `children` | `ReactNode` |  |
+
+## Component tokens
+
+`--dk-component-accordion-inset`, `--dk-component-accordion-padding-block`, `--dk-component-accordion-small-padding-block`, `--dk-component-accordion-large-padding-block`, `--dk-component-accordion-padding-inline`, `--dk-component-accordion-flush-padding-inline`, `--dk-component-accordion-row-radius`, `--dk-component-accordion-row-surface-hover`, `--dk-component-accordion-row-surface-active`, `--dk-component-accordion-press-scale`, `--dk-component-accordion-focus-ring-width`, `--dk-component-accordion-focus-ring`, `--dk-component-accordion-gap`, `--dk-component-accordion-font-family`, `--dk-component-accordion-font-size`, `--dk-component-accordion-line-height`, `--dk-component-accordion-small-font-size`, `--dk-component-accordion-small-line-height`, `--dk-component-accordion-large-font-size`, `--dk-component-accordion-large-line-height`, `--dk-component-accordion-summary-font-weight`, `--dk-component-accordion-summary-color`, `--dk-component-accordion-heading-gap`, `--dk-component-accordion-description-font-size`, `--dk-component-accordion-description-line-height`, `--dk-component-accordion-description-color`, `--dk-component-accordion-content-color`, `--dk-component-accordion-surface`, `--dk-component-accordion-border`, `--dk-component-accordion-border-width`, `--dk-component-accordion-radius`, `--dk-component-accordion-rule`, `--dk-component-accordion-joined-rule`, `--dk-component-accordion-icon-size`, `--dk-component-accordion-icon-color`, `--dk-component-accordion-icon-color-hover`, `--dk-component-accordion-icon-gap`, `--dk-component-accordion-leading-size`, `--dk-component-accordion-leading-color`, `--dk-component-accordion-meta-gap`, `--dk-component-accordion-title-color-disabled`, `--dk-component-accordion-description-color-disabled`, `--dk-component-accordion-icon-color-disabled`, `--dk-component-accordion-open-duration`, `--dk-component-accordion-close-duration`, `--dk-component-accordion-easing`, `--dk-component-accordion-content-rise`, `--dk-component-accordion-duration`

package/manifest/components/action-bar.md

@@ -0,0 +1,51 @@
+# Action bar (`action-bar`)
+
+A flow's controls along the bottom: Back, Next, what the step costs and how far along it is.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-action-bar[data-variant="float"]?[data-align="split"]?[data-sticky]?
+  div.__inner
+    div.__start                 (Back: a plain Button)
+    button.__summary?           (__summary-label, __summary-value, __summary-chevron; opens __detail)
+    div.__end                   (Next: a Button, default + primary)
+  div.__detail?
+  div.__progress?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `split` |
+| `data-closing` | (present or absent) |
+| `data-open` | (present or absent) |
+| `data-phone` | (present or absent) |
+| `data-sticky` | (present or absent) |
+| `data-stuck` | (present or absent) |
+| `data-variant` | `float` |
+
+## React
+
+```tsx
+import { ActionBar } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `start` | `ReactNode` | Back, usually a plain Button. |
+| `end` | `ReactNode` | Next, usually a default primary Button. |
+| `summary` | `{ label: ReactNode; value: ReactNode; detail?: ReactNode; detailLabel?: string }` | What the step costs: "Due today", "$224.50". With a detail the summary is a button: press it and the detail opens above the bar (the price breakdown, a photo of the car). detailLabel names it. |
+| `progress` | `{ value: number; max: number; label?: string; text?: string }` | Where the flow is, drawn along the bar's top edge. |
+| `variant` | `'fixed' \| 'float'` |  |
+| `sticky` | `boolean` |  |
+| `align` | `'end' \| 'split'` | 'end' (the design's) keeps Back beside Next; 'split' puts it at the start. |
+| `device` | `'auto' \| 'phone' \| 'desktop'` |  |
+| `theme` | `'light' \| 'dark'` | Dark chrome: 'dark' makes it dark on a light page and one step deeper than a dark one. Everything inside resolves dark, menus included. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-action-bar-padding-block`, `--dk-component-action-bar-padding-inline`, `--dk-component-action-bar-phone-padding-inline`, `--dk-component-action-bar-gap`, `--dk-component-action-bar-button-gap`, `--dk-component-action-bar-max-width`, `--dk-component-action-bar-surface`, `--dk-component-action-bar-border`, `--dk-component-action-bar-border-width`, `--dk-component-action-bar-float-radius`, `--dk-component-action-bar-float-surface`, `--dk-component-action-bar-blur`, `--dk-component-action-bar-float-inset`, `--dk-component-action-bar-float-shadow`, `--dk-component-action-bar-stuck-shadow`, `--dk-component-action-bar-z-index`, `--dk-component-action-bar-summary-label-font-size`, `--dk-component-action-bar-summary-label-line-height`, `--dk-component-action-bar-summary-label-font-weight`, `--dk-component-action-bar-summary-label-letter-spacing`, `--dk-component-action-bar-summary-label-color`, `--dk-component-action-bar-summary-value-font-size`, `--dk-component-action-bar-summary-value-line-height`, `--dk-component-action-bar-summary-value-font-weight`, `--dk-component-action-bar-summary-value-color`, `--dk-component-action-bar-progress-thickness`, `--dk-component-action-bar-progress-track`, `--dk-component-action-bar-progress-fill`, `--dk-component-action-bar-progress-gradient`, `--dk-component-action-bar-progress-gradient-rtl`, `--dk-component-action-bar-duration`, `--dk-component-action-bar-progress-duration`, `--dk-component-action-bar-easing`, `--dk-component-action-bar-summary-padding`, `--dk-component-action-bar-summary-radius`, `--dk-component-action-bar-summary-surface-hover`, `--dk-component-action-bar-summary-surface-active`, `--dk-component-action-bar-summary-press-scale`, `--dk-component-action-bar-summary-ring`, `--dk-component-action-bar-summary-ring-width`, `--dk-component-action-bar-chevron-size`, `--dk-component-action-bar-chevron-color`, `--dk-component-action-bar-chevron-color-hover`, `--dk-component-action-bar-chevron-color-active`, `--dk-component-action-bar-detail-surface`, `--dk-component-action-bar-detail-border`, `--dk-component-action-bar-detail-radius`, `--dk-component-action-bar-detail-shadow`, `--dk-component-action-bar-detail-padding`, `--dk-component-action-bar-detail-width`, `--dk-component-action-bar-detail-gap`, `--dk-component-action-bar-detail-rise`, `--dk-component-action-bar-detail-enter-duration`, `--dk-component-action-bar-detail-enter-easing`, `--dk-component-action-bar-detail-exit-duration`, `--dk-component-action-bar-detail-exit-easing`

package/manifest/components/alert.md

@@ -0,0 +1,53 @@
+# Alert (`alert`)
+
+An inline, persistent message in the page: a status colour, an optional icon, title, body, actions and a dismiss button.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-alert[data-status="primary|success|warning|error|information"][data-variant="solid|outline|plain"]?[data-size="small"]?[data-pointer]?[data-dismissible]?[role="status"]
+  span.__icon?
+  div.__content
+    p.__title?
+    p.__body
+    div.__actions?
+  button.__dismiss?
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-full-width` | `true` |
+| `data-pointer` | `bottom`, `left`, `right`, `top` |
+| `data-size` | `small` |
+| `data-status` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-text` | `tinted` |
+| `data-variant` | `outline`, `plain`, `solid` |
+
+## React
+
+```tsx
+import { Alert } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `status` | `'neutral' \| 'information' \| 'success' \| 'warning' \| 'error' \| 'primary'` | 'neutral' and omitting the prop render identically: neutral is what the base rule already is, and naming it is for the caller who wants to say so. |
+| `variant` | `'subtle' \| 'solid' \| 'outline' \| 'plain'` |  |
+| `size` | `'small' \| 'medium'` | Medium is the default and needs no attribute, as on Input and Select. |
+| `pointer` | `'left' \| 'top' \| 'right' \| 'bottom'` | The balloon: a triangle on that side, centred, in the alert's own fill and border. Not on plain. |
+| `text` | `'tinted'` | Omitted, the title is default-coloured and the body grey. 'tinted' paints both in the status colour. The icon is status-coloured either way. |
+| `fullWidth` | `boolean` | Content width by default, like Button. |
+| `title` | `ReactNode` | A string in nearly every case, so it is a prop rather than a slot. |
+| `children` | `ReactNode` | The body. Always rendered inside a <p> (__body), so children must be phrasing content, i.e. text and inline elements only: a block child such as <ul> or <div> inside a <p> is invalid HTML, which the browser repairs by closing the <p> early. renderToString does not warn about this, so the first sign is a silent hydration mismatch on the client. |
+| `icon` | `ReactNode` | No icon by default; omitting the prop and passing icon={null} render identically. The per-status glyph convention (which icon for which status) is documentation for callers, in the docs, not something this component injects: picking one here would make an icon set a dependency of Alert, and the kit ships icons as markup, not as component logic. |
+| `actions` | `ReactNode` |  |
+| `dismissible` | `boolean` |  |
+| `onDismiss` | `() => void` | Called instead of the element removing itself. React owns its own DOM, so this component must never delete nodes out from under it: a React consumer holds visibility in state and does not load components.js for Alert. |
+| `dismissLabel` | `string` |  |
+
+## Component tokens
+
+`--dk-component-alert-gap`, `--dk-component-alert-padding`, `--dk-component-alert-radius`, `--dk-component-alert-border-width`, `--dk-component-alert-icon-size`, `--dk-component-alert-dismiss-padding`, `--dk-component-alert-dismiss-offset`, `--dk-component-alert-trailing-extra`, `--dk-component-alert-small-gap`, `--dk-component-alert-small-padding`, `--dk-component-alert-small-icon-size`, `--dk-component-alert-small-dismiss-padding`, `--dk-component-alert-small-dismiss-offset`, `--dk-component-alert-small-trailing-extra`, `--dk-component-alert-title-font-size`, `--dk-component-alert-title-line-height`, `--dk-component-alert-title-font-weight`, `--dk-component-alert-body-font-size`, `--dk-component-alert-body-line-height`, `--dk-component-alert-body-font-weight`, `--dk-component-alert-small-title-font-size`, `--dk-component-alert-small-title-line-height`, `--dk-component-alert-small-body-font-size`, `--dk-component-alert-small-body-line-height`, `--dk-component-alert-pointer-depth`, `--dk-component-alert-pointer-base`, `--dk-component-alert-neutral-color`, `--dk-component-alert-primary-color`, `--dk-component-alert-warning-color`, `--dk-component-alert-error-color`, `--dk-component-alert-information-color`, `--dk-component-alert-success-color`, `--dk-component-alert-scrim-active-opacity`, `--dk-component-alert-scrim-hover-opacity`

package/manifest/components/app-shell.md

@@ -0,0 +1,43 @@
+# App shell (`app-shell`)
+
+The layout that places a Sidebar, a Top bar, the page and an Action bar, in the viewport or in a box.
+
+
+## Anatomy (HTML)
+
+```text
+div.dk-component-app-shell[data-contained]?[data-presentation="bar|drawer"]?
+  nav.dk-component-sidebar      (its own component)
+  div.__main
+    header.dk-component-top-bar? (its own component)
+    main.__content
+    div.dk-component-action-bar? (its own component)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-contained` | (present or absent) |
+| `data-presentation` | `bar`, `drawer` |
+| `data-sticky` | (present or absent) |
+| `data-variant` | `float`, `floating` |
+
+## React
+
+```tsx
+import { AppShell } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `sidebar` | `ReactNode` | A Sidebar. |
+| `topBar` | `ReactNode` | A Top bar, usually sticky. |
+| `actionBar` | `ReactNode` | An Action bar, usually sticky. |
+| `children` | `ReactNode` | The page. |
+| `contained` | `boolean` | Fill the parent's box instead of the viewport: the main column scrolls and the phone bar stays in the frame. |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-app-shell-surface`, `--dk-component-app-shell-height`, `--dk-component-app-shell-floating-inset`

package/manifest/components/avatar.md

@@ -0,0 +1,42 @@
+# Avatar (`avatar`)
+
+A person, as their photo or their initials: the photo fades in once it has loaded, and the initials stay if it never does.
+
+
+## Anatomy (HTML)
+
+```text
+span.dk-component-avatar[data-name][data-size="24|40|48"]?[data-variant="solid"]?[data-hue]?
+  img?                          (the photo; the runtime sets data-loaded)
+  span.__initials             (written by the runtime from data-name)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-hue` | `next1`, `next2`, `next3`, `next4`, `prev1`, `prev2`, `prev3`, `prev4`, `primary` |
+| `data-loaded` | `error`, `false`, `true` |
+| `data-size` | `24`, `40`, `48` |
+| `data-variant` | `solid` |
+
+## React
+
+```tsx
+import { Avatar } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `name` (required) | `string` | Whose it is: the initials come from it ("Ada Lovelace" is AL). |
+| `src` | `string` | A photo. Until it decodes, and if it fails, the initials show. |
+| `size` | `24 \| 32 \| 40 \| 48` | 32 when absent. |
+| `hue` | `AvatarHue` | A category colour instead of primary, to tell people apart without photos. |
+| `variant` | `'subtle' \| 'solid'` | Subtle when absent. |
+| `label` | `string` | A name for a screen reader, for an avatar that stands on its own. Without one it is decorative: the name is usually written beside it. |
+| `href` | `string` | A link to the person: the avatar becomes an <a>, named by label or name, and steps through hover and press. |
+| `onClick` | `(event: ReactMouseEvent<HTMLElement>) => void` | An action, an account menu say: the avatar becomes a <button>, named by label or name, and steps through hover and press. |
+
+## Component tokens
+
+`--dk-component-avatar-radius`, `--dk-component-avatar-24-size`, `--dk-component-avatar-24-font-size`, `--dk-component-avatar-32-size`, `--dk-component-avatar-32-font-size`, `--dk-component-avatar-40-size`, `--dk-component-avatar-40-font-size`, `--dk-component-avatar-48-size`, `--dk-component-avatar-48-font-size`, `--dk-component-avatar-font-family`, `--dk-component-avatar-font-weight`, `--dk-component-avatar-letter-spacing`, `--dk-component-avatar-subtle-surface`, `--dk-component-avatar-subtle-text`, `--dk-component-avatar-solid-surface`, `--dk-component-avatar-solid-text`, `--dk-component-avatar-ring`, `--dk-component-avatar-edge-mix`, `--dk-component-avatar-solid-mix-to`, `--dk-component-avatar-hover-mix`, `--dk-component-avatar-active-mix`, `--dk-component-avatar-photo-hover`, `--dk-component-avatar-photo-active`, `--dk-component-avatar-focus-ring`, `--dk-component-avatar-focus-ring-width`, `--dk-component-avatar-transition-duration`, `--dk-component-avatar-fade-duration`, `--dk-component-avatar-fade-easing`

package/manifest/components/body.md

@@ -0,0 +1,48 @@
+# Body (`body`)
+
+The body-copy primitive: one element, eleven colours, two emphasis rungs, four sizes, eight weights, and, unlike the component- library original, aware of the surface it sits on.
+
+
+## Anatomy (HTML)
+
+```text
+p|span.dk-component-body[data-size="xlarge|large|medium|small|xsmall"]?[data-weight]?[data-color]?[data-emphasis="subtle"]?[data-align]?[data-style]?[data-trim]?
+  span.__value?               (a figure inside running text)
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `left`, `right` |
+| `data-color` | `black`, `default`, `error`, `information`, `inverse`, `neutral`, `primary`, `success`, `warning`, `white` |
+| `data-disabled` | (present or absent) |
+| `data-emphasis` | `subtle` |
+| `data-size` | `large`, `medium`, `small`, `xlarge`, `xsmall` |
+| `data-style` | `italic`, `normal`, `underline` |
+| `data-trim` | `both`, `end`, `start` |
+| `data-weight` | `bold`, `extra-bold`, `extra-light`, `light`, `medium`, `regular`, `semi-bold`, `thin` |
+
+## React
+
+```tsx
+import { Body } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `size` | `'xlarge' \| 'large' \| 'medium' \| 'small' \| 'xsmall'` |  |
+| `weight` | `\| 'thin' \| 'extra-light' \| 'light' \| 'regular' \| 'medium' \| 'semi-bold' \| 'bold' \| 'extra-bold'` |  |
+| `textStyle` | `'normal' \| 'underline' \| 'italic'` | React owns `style`, so the data-style axis is `textStyle`. This is the one place the mirror-the-HTML rule cannot hold. |
+| `as` | `ElementType` |  |
+| `color` | `Color` |  |
+| `emphasis` | `Emphasis` |  |
+| `align` | `Align` |  |
+| `trim` | `Trim` |  |
+| `disabled` | `boolean` | A span cannot carry :disabled, so the kit uses [data-disabled]. |
+| `children` | `ReactNode` |  |
+| `className` | `string` |  |
+
+## Component tokens
+
+`--dk-component-body-font-family`, `--dk-component-body-transition-duration`, `--dk-component-body-xlarge-font-size`, `--dk-component-body-xlarge-line-height`, `--dk-component-body-large-font-size`, `--dk-component-body-large-line-height`, `--dk-component-body-medium-font-size`, `--dk-component-body-medium-line-height`, `--dk-component-body-small-font-size`, `--dk-component-body-small-line-height`, `--dk-component-body-xsmall-font-size`, `--dk-component-body-xsmall-line-height`, `--dk-component-body-thin-font-weight`, `--dk-component-body-extra-light-font-weight`, `--dk-component-body-light-font-weight`, `--dk-component-body-regular-font-weight`, `--dk-component-body-medium-font-weight`, `--dk-component-body-semi-bold-font-weight`, `--dk-component-body-bold-font-weight`, `--dk-component-body-extra-bold-font-weight`, `--dk-component-body-default-color`, `--dk-component-body-inverse-color`, `--dk-component-body-white-color`, `--dk-component-body-black-color`, `--dk-component-body-primary-color`, `--dk-component-body-success-color`, `--dk-component-body-error-color`, `--dk-component-body-warning-color`, `--dk-component-body-information-color`, `--dk-component-body-neutral-default-color`, `--dk-component-body-neutral-subtle-color`, `--dk-component-body-disabled-color`, `--dk-component-body-value-surface`, `--dk-component-body-value-color`, `--dk-component-body-value-font-weight`, `--dk-component-body-value-font-size`, `--dk-component-body-value-line-height`, `--dk-component-body-value-padding-block`, `--dk-component-body-value-padding-inline`, `--dk-component-body-value-radius`

package/manifest/components/box.md

@@ -0,0 +1,58 @@
+# Box (`box`)
+
+A grouped surface: a panel that separates what is in it from what is around it, optionally laid out as a responsive grid of facts.
+
+
+## Anatomy (HTML)
+
+```text
+section.dk-component-box[data-variant][data-size][data-tone][data-tone-fill][data-surface]
+  header.__header
+    div.__heading > .__title + .__description?
+    div.__actions?
+  dl|div.__grid[data-columns="1..6"][data-dividers][data-align]
+    div.__cell[data-span="full"]?
+      dt.__label + dd.__value        (a fact)
+      … or anything
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-align` | `center`, `end`, `start` |
+| `data-columns` | `1`, `2`, `3`, `4`, `5`, `6` |
+| `data-dividers` | `both`, `columns`, `rows` |
+| `data-size` | `large`, `small`, `xlarge`, `xsmall` |
+| `data-span` | `full` |
+| `data-surface` | (present or absent) |
+| `data-tone` | `none` |
+| `data-tone-fill` | `solid` |
+| `data-variant` | `flat`, `inset`, `raised` |
+
+## React
+
+```tsx
+import { Box } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | `'outline' \| 'raised' \| 'inset' \| 'flat'` | How the box separates from what is around it. outline (the default) is a hairline, raised lifts it with a shadow, inset presses it in, flat is its fill alone and needs a tone or a surface to be seen. |
+| `size` | `'xsmall' \| 'small' \| 'medium' \| 'large' \| 'xlarge'` | Padding and gaps together: 12, 18, 24 (medium, the default), 32 or 40. Past medium the corner and the header grow with it. |
+| `tone` | `'primary' \| 'success' \| 'warning' \| 'error' \| 'information' \| 'inverse'` | The kit's tone: tints the box and remaps the colours of everything in it. |
+| `toneFill` | `'solid'` | With a tone: the solid fill instead of the tint. |
+| `surface` | `0 \| 1 \| 2` | A step down the neutral ladder (1 or 2), so a flat box reads as a panel. |
+| `title` | `ReactNode` | A header: the title wires aria-labelledby, so the box is a named region. |
+| `titleAs` | `'h2' \| 'h3' \| 'h4' \| 'h5' \| 'h6'` |  |
+| `description` | `ReactNode` |  |
+| `actions` | `ReactNode` | Beside the title: a Link, a Button, an icon button. |
+| `headerBand` | `boolean` | The header as a band: edge to edge, one level up from the box's surface (a level-2 box steps back to 1), with a hairline under it. On a toned box it carries the tone too. |
+| `columns` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | Lays the children out as a grid of at most this many columns, wrapping to fewer on its own once a column would be narrower than 10rem. Without it the children sit straight in the box, as a plain panel. |
+| `dividers` | `'rows' \| 'columns' \| 'both'` | Hairlines between the cells, correct at any wrap. |
+| `align` | `'start' \| 'center' \| 'end'` | Cells stretch to the row when absent. |
+| `as` | `'section' \| 'div' \| 'aside' \| 'article'` | section when the box has a name (a title or an aria-label), div when it does not; pass one to choose. |
+
+## Component tokens
+
+`--dk-component-box-xsmall-padding`, `--dk-component-box-small-padding`, `--dk-component-box-padding`, `--dk-component-box-large-padding`, `--dk-component-box-xlarge-padding`, `--dk-component-box-radius`, `--dk-component-box-large-radius`, `--dk-component-box-xlarge-radius`, `--dk-component-box-border-width`, `--dk-component-box-border-color`, `--dk-component-box-raised-border-color`, `--dk-component-box-inset-border-color`, `--dk-component-box-raised-shadow`, `--dk-component-box-inset-shadow`, `--dk-component-box-column-min`, `--dk-component-box-line-color`, `--dk-component-box-line-width`, `--dk-component-box-focus-room`, `--dk-component-box-label-color`, `--dk-component-box-label-font-size`, `--dk-component-box-label-line-height`, `--dk-component-box-label-letter-spacing`, `--dk-component-box-label-font-weight`, `--dk-component-box-fact-gap`, `--dk-component-box-value-color`, `--dk-component-box-value-font-size`, `--dk-component-box-value-line-height`, `--dk-component-box-value-font-weight`, `--dk-component-box-title-font-size`, `--dk-component-box-title-line-height`, `--dk-component-box-title-font-weight`, `--dk-component-box-description-font-size`, `--dk-component-box-description-line-height`, `--dk-component-box-large-title-font-size`, `--dk-component-box-large-title-line-height`, `--dk-component-box-large-description-font-size`, `--dk-component-box-large-description-line-height`, `--dk-component-box-xlarge-title-font-size`, `--dk-component-box-xlarge-title-line-height`, `--dk-component-box-xlarge-description-font-size`, `--dk-component-box-xlarge-description-line-height`, `--dk-component-box-header-gap`, `--dk-component-box-xsmall-band-padding`, `--dk-component-box-small-band-padding`, `--dk-component-box-band-padding`, `--dk-component-box-large-band-padding`, `--dk-component-box-xlarge-band-padding`, `--dk-component-box-font-family`, `--dk-component-box-title-color`, `--dk-component-box-description-color`

package/manifest/components/breadcrumb.md

@@ -0,0 +1,59 @@
+# Breadcrumb (`breadcrumb`)
+
+Where this page sits, and the way back up: the pages above it as quiet pills, its own name last.
+
+
+## Anatomy (HTML)
+
+```text
+nav.dk-component-breadcrumb[data-size]                (aria-label="Breadcrumb")
+  div.dk-component-breadcrumb__arrows                 (optional, role="group")
+    button.dk-component-breadcrumb__arrow             (aria-label="Back", then "Forward")
+  ol.dk-component-breadcrumb__list
+    li.dk-component-breadcrumb__item
+      a.dk-component-breadcrumb__link                 (a page above this one: a pill)
+        span.dk-component-breadcrumb__icon            (optional, aria-hidden)
+        span.dk-component-breadcrumb__label
+    li.dk-component-breadcrumb__item                  (a page with related pages)
+      span.dk-component-breadcrumb__pill              (the link and its chevron, one pill)
+        a.dk-component-breadcrumb__link | span.dk-component-breadcrumb__current
+        div.dk-component-dropdown.dk-component-breadcrumb__more
+          button.dk-component-breadcrumb__trigger.dk-component-dropdown__trigger
+          div.dk-component-menu.dk-component-dropdown__menu
+    li.dk-component-breadcrumb__item                  (the pages folded away)
+      div.dk-component-dropdown.dk-component-breadcrumb__more
+        button.dk-component-breadcrumb__ellipsis.dk-component-dropdown__trigger  ("3 more pages")
+        div.dk-component-menu.dk-component-dropdown__menu
+    li.dk-component-breadcrumb__item                  (the last)
+      span.dk-component-breadcrumb__current[aria-current="page"][title]
+```
+
+## Attributes
+
+| Attribute | Values the stylesheet styles |
+|---|---|
+| `data-size` | `small` |
+| `data-tone` | `error`, `information`, `primary`, `success`, `warning` |
+| `data-variant` | `inset`, `plain`, `raised` |
+
+## React
+
+```tsx
+import { Breadcrumb } from '@karmo-co/drift-kit/react';
+```
+
+| Prop | Type | Notes |
+|---|---|---|
+| `items` (required) | `BreadcrumbItem[]` | From the top down. The last is the current page. |
+| `size` | `'small' \| 'medium'` | medium when absent. |
+| `variant` | `'ghost' \| 'raised' \| 'plain' \| 'inset'` |  |
+| `linkAs` | `ElementType` | The element the ancestors render as: react-router's Link most often, so navigation stays client-side. Each item's own props go to it. |
+| `maxItems` | `number` | Past this many items the middle folds into a "..." pill that opens a Dropdown of them: the first, the "...", the last two. 4 when absent; 0 never folds. |
+| `onBack` | `() => void` | Back and forward arrows in their own pill to the left, shown when either handler is given. |
+| `onForward` | `() => void` |  |
+| `backDisabled` | `boolean` |  |
+| `forwardDisabled` | `boolean` |  |
+
+## Component tokens
+
+`--dk-component-breadcrumb-small-font-size`, `--dk-component-breadcrumb-small-line-height`, `--dk-component-breadcrumb-font-size`, `--dk-component-breadcrumb-line-height`, `--dk-component-breadcrumb-font-family`, `--dk-component-breadcrumb-gap`, `--dk-component-breadcrumb-separator-size`, `--dk-component-breadcrumb-separator-color`, `--dk-component-breadcrumb-container-separator-color`, `--dk-component-breadcrumb-back-icon`, `--dk-component-breadcrumb-link-color`, `--dk-component-breadcrumb-link-color-hover`, `--dk-component-breadcrumb-link-color-active`, `--dk-component-breadcrumb-link-surface-hover`, `--dk-component-breadcrumb-link-surface-active`, `--dk-component-breadcrumb-link-ring`, `--dk-component-breadcrumb-link-ring-width`, `--dk-component-breadcrumb-link-font-weight`, `--dk-component-breadcrumb-press-scale`, `--dk-component-breadcrumb-padding-block`, `--dk-component-breadcrumb-padding-inline`, `--dk-component-breadcrumb-small-padding-block`, `--dk-component-breadcrumb-small-padding-inline`, `--dk-component-breadcrumb-radius`, `--dk-component-breadcrumb-icon-size`, `--dk-component-breadcrumb-small-icon-size`, `--dk-component-breadcrumb-icon-gap`, `--dk-component-breadcrumb-icon-stroke`, `--dk-component-breadcrumb-small-icon-stroke`, `--dk-component-breadcrumb-chevron-size`, `--dk-component-breadcrumb-current-color`, `--dk-component-breadcrumb-current-icon-color`, `--dk-component-breadcrumb-current-font-weight`, `--dk-component-breadcrumb-current-max-width`, `--dk-component-breadcrumb-container-padding`, `--dk-component-breadcrumb-edged-padding-block`, `--dk-component-breadcrumb-edged-padding-inline`, `--dk-component-breadcrumb-container-radius`, `--dk-component-breadcrumb-container-border-width`, `--dk-component-breadcrumb-raised-surface`, `--dk-component-breadcrumb-raised-border`, `--dk-component-breadcrumb-raised-shadow`, `--dk-component-breadcrumb-plain-border`, `--dk-component-breadcrumb-inset-surface`, `--dk-component-breadcrumb-divider`, `--dk-component-breadcrumb-divider-space`, `--dk-component-breadcrumb-inset-divider`, `--dk-component-breadcrumb-inset-toned-color`, `--dk-component-breadcrumb-arrows-surface`, `--dk-component-breadcrumb-arrows-radius`, `--dk-component-breadcrumb-arrow-radius`, `--dk-component-breadcrumb-arrows-padding`, `--dk-component-breadcrumb-arrows-gap`, `--dk-component-breadcrumb-arrows-margin`, `--dk-component-breadcrumb-arrow-size`, `--dk-component-breadcrumb-arrow-icon-size`, `--dk-component-breadcrumb-small-arrow-size`, `--dk-component-breadcrumb-small-arrow-icon-size`, `--dk-component-breadcrumb-arrow-color`, `--dk-component-breadcrumb-arrow-color-hover`, `--dk-component-breadcrumb-arrow-surface-hover`, `--dk-component-breadcrumb-arrow-surface-active`, `--dk-component-breadcrumb-arrow-color-disabled`