@contraagent/elements 0.0.0-stage → 0.2.0

package/docs/examples/transcript.ts

@@ -0,0 +1,59 @@
+// A conversation with a support bot in two sessions: the first ended with a
+// failed lookup, the second answered. The host holds the sections and decides
+// what a reader's pick means: here the picked session is simply shown.
+import '@contraagent/elements/transcript/define';
+import { md } from '@contraagent/elements/markdown';
+import type { TranscriptSection } from '@contraagent/elements/transcript';
+
+const sections: TranscriptSection[] = [
+  {
+    id: 's1',
+    title: 'Session 1',
+    verdict: { tone: 'failed', text: 'failed', tip: 'The order service did not answer' },
+    tags: [
+      { label: 'bot', value: 'helpdesk' },
+      { label: 'model', value: 'small-2', look: 'mono' },
+    ],
+    items: [
+      { type: 'prompt', id: 'p1', text: 'Where is order 1042?' },
+      { type: 'reasoning', id: 'r1', text: 'Look the order up first, then answer with its **status**.' },
+      { type: 'tool', id: 't1', name: 'orders.get', icon: 'read', summary: 'order 1042', output: 'timeout after 30s', status: 'error' },
+    ],
+    footer: { tone: 'failed', title: 'The order service did not answer' },
+  },
+  {
+    id: 's2',
+    title: 'Session 2',
+    facts: ['small-2'],
+    verdict: { tone: 'done', text: 'answered' },
+    items: [
+      { type: 'event', id: 'e1', icon: '↻', title: 'Request sent again', text: 'after a timeout' },
+      {
+        type: 'tool',
+        id: 't2',
+        name: 'web_search',
+        icon: 'search',
+        summary: 'carrier tracking 1042',
+        query: 'carrier tracking 1042',
+        links: [
+          { title: 'Track a parcel', url: 'https://example.com/track' },
+          { title: 'Delivery times', url: 'https://example.org/delivery' },
+        ],
+        output: 'Track a parcel https://example.com/track\nDelivery times https://example.org/delivery',
+        status: 'ok',
+      },
+      { type: 'notice', id: 'n1', text: 'cache hit: orders/1042' },
+      { type: 'message', id: 'm1', text: 'Order **1042** left the warehouse on Monday and arrives on *Thursday*.' },
+    ],
+  },
+];
+
+export function mount(host: HTMLElement): void {
+  const t = document.createElement('cae-transcript');
+  t.sections = sections;
+  t.markdown = md;
+  t.strings = { sections: 'Sessions', sectionsTip: 'One session per conversation with the bot' };
+  t.style.height = '420px';
+  t.addEventListener('cae-section-change', (e) => (t.shown = e.detail.index));
+  host.replaceChildren(t);
+}

package/docs/examples/tree.ts

@@ -0,0 +1,44 @@
+// A tree of a CI pipeline's files, paired with a code element: selecting a file shows
+// its text. The host holds the selection and answers `cae-select`.
+import '@contraagent/elements/code/define';
+import '@contraagent/elements/tree/define';
+import type { TreeItem } from '@contraagent/elements/tree';
+
+const files: Record<string, string> = {
+  'ci/build.py': 'def build(target: str) -> bool:\n    return run(["make", target]).returncode == 0\n',
+  'ci/jobs.yaml': 'jobs:\n  unit: { needs: [build] }\n  lint: { needs: [] }\n',
+  'ci/tests/test_build.py': 'def test_build():\n    assert build("all")\n',
+  'README.md': 'The CI pipeline of the project.\n',
+};
+
+const items: TreeItem[] = [
+  {
+    id: 'ci',
+    name: 'ci',
+    children: [
+      { id: 'ci/build.py', name: 'build.py' },
+      { id: 'ci/jobs.yaml', name: 'jobs.yaml', badge: 'changed', tone: 'attention' },
+      { id: 'ci/tests', name: 'tests', open: false, children: [{ id: 'ci/tests/test_build.py', name: 'test_build.py', badge: 'failed', tone: 'failed' }] },
+    ],
+  },
+  { id: 'README.md', name: 'README.md' },
+];
+
+export function mount(host: HTMLElement): void {
+  const tree = document.createElement('cae-tree');
+  tree.items = items;
+  tree.label = 'Files';
+  const code = document.createElement('cae-code');
+  const show = (id: string) => {
+    tree.selected = id;
+    code.code = files[id] ?? '';
+    code.path = id;
+    code.language = id;
+  };
+  tree.addEventListener('cae-select', (e) => e.detail.id && show(e.detail.id));
+  show('ci/build.py');
+  const pair = document.createElement('div');
+  pair.style.cssText = 'display: grid; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); gap: 12px; align-items: start';
+  pair.append(tree, code);
+  host.replaceChildren(pair);
+}

package/docs/graph.md

@@ -0,0 +1,112 @@
+# Layered graph
+
+`<cae-layered-graph>` draws nodes in layers, joined by edges, inside clusters: a
+pipeline, a build, any flow of steps. Each node holds a group of marks, one per
+series id, at the same place in every node, so one series can be followed across
+the graph. Register it with `@contraagent/elements/graph/define` (it registers
+`<cae-mark-matrix>` and `<cae-segmented>` too); the types, `arrange` and
+`layoutGraph` are in `@contraagent/elements/graph`.
+
+![A layered graph: commit, then build, then a retry loop of test and deploy, a mark per series in each node, and the legend](images/graph.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/graph.ts"}
+
+## The model
+
+A `GraphInput` names the series, the nodes, the clusters, the edges and the stubs
+(edges from outside the graph). A state is any id: `states` (`StateStyles`) gives
+each its word, its tone and its shape, and its key order is the legend's.
+
+A mark is in a series when the same item has a mark in several nodes: a service
+built, tested and deployed is a series, and its marks line up across the steps.
+A mark of one node only (a job of one CI step) is in that node's `loose`.
+
+A node's `counts` (the bar of a node with many marks) and `progress` (the count
+in its header, "2/3") default to what its marks say: its marks by state, and its
+marks whose state has the tone `done` of all its marks, in the words of
+`strings.progress`. Give them when a node stands for more items than it has marks.
+
+::code{file="../src/graph/types.ts" from="export interface GraphNodeInput {" to="/** A node as the graph draws it"}
+
+A cluster is a box of nodes (and of other clusters). A cluster that `cycle`s draws
+a return from its last layer to its first; an edge with `ranks: false` closes that
+cycle: it never sets the layers and is not drawn. An edge may join items in
+different clusters, at any depth: it leaves and enters each box on its way.
+
+An item the host can draw open or closed carries `toggle`: a node with `toggle:
+'closed'` draws a control in its header (`strings.open`, "Show inside") and a
+cluster with `toggle: 'open'` one in its corner (`strings.close`); either sends
+`cae-toggle` with the item's id and whether it is to be open, and the host draws
+the graph again. A cluster named by a `path` of parts shows them as "a › b › c":
+the first part is its name, and each later part sends `cae-drill` with that part's
+id. `focusToggle(id)` puts the focus on an item's control once it is drawn again.
+
+`key` is the graph's identity. A new `key` is a new graph: the frame shows all of
+it again, and the focused mark of each node is forgotten. Keep the `key` while the
+same graph changes (a run in progress), so the reader's zoom and pan stay.
+
+## Order and drawing
+
+`arrange` gives each item its layer by the longest path to it, orders each layer to
+reduce crossings, and gives each edge its edge path: a point on every layer it crosses.
+The order depends on the structure only. Give the element the `order` of an earlier
+drawing of the same graph to keep its items in place: an item that appears later is
+added at the end of its layer. `layoutGraph` places everything from the measured
+sizes; the element measures its nodes itself. Below 640 px of width, `direction:
+'auto'` draws top to bottom. `extentOf(arrangement)` gives a drawing's shape before
+it is measured: the layers it spans along the flow and the items it stacks across
+it at most, a cluster counted as what it holds; a host can choose the direction,
+or how much to draw, from it.
+
+## Size
+
+The element is as wide as its container. Without a height, the frame is as tall
+as the whole drawing at that width (never scaled up), up to 70% of the window's
+height or 360 px, whichever is more; top to bottom, as tall as the drawing. With a
+height set on the element (or given by a flex or grid container), the `crumbs`
+slot and the row under the frame keep their height, and the frame takes the rest,
+with the whole drawing fitted and centred in it.
+
+## Selection and events
+
+A click selects a mark, a node or a cluster and sends `cae-select`; the element
+does not select by itself: the host sets `selected`. Enter or a double click sends
+`cae-activate`, or `cae-drill` for an item with `drill` (an inner view). "Graph |
+Table" sends `cae-view-change`: the table is a row per node with the nodes it is
+joined to. With `matrix`, the frame shows a [mark matrix](matrix.md) as the table.
+
+The card of the selected item is the host's content in the `inspector` slot,
+beside the item in the frame; its first heading and its `[data-status]` element
+name the item to a screen reader. With nothing in the slot when the element
+draws (a new `selected` draws it), there is no card: a page that shows the
+selection elsewhere leaves the slot empty.
+
+Hovering, focusing or selecting a mark highlights its series; `related` names more
+marks to light (a mark's id, or a series id, to the ids of the marks it lights).
+
+The line under the legend holds the key hints. It keeps its height at all times,
+and shows its words while the graph has the focus. On a screen with touch alone
+(no fine pointer) there is no line; `::part(keys) { display: none; }` removes it
+everywhere.
+
+## Look
+
+The words are `strings` ([Strings](strings.md)). `renderIcon` draws the icons a
+node names (`icons`), and `iconStyles` adds styles for them. A mark has the state's
+look as `data-tone` and `data-shape`. The parts, for `::part()`:
+
+| Part | What it is |
+|---|---|
+| `frame` | the frame every view is drawn in |
+| `stage` | what pans and zooms |
+| `node`, `node-header`, `node-name` | each node, its first line, its name |
+| `mark` | each mark |
+| `cluster`, `cluster-label` | each cluster, its header |
+| `edge`, `stub` | each edge, each stub |
+| `legend` | the legend |
+| `keys` | the line of key hints |
+| `inspector` | the selected item's card |
+| `table`, `row` | the node table, each of its rows |

package/docs/lanes.md

@@ -0,0 +1,48 @@
+# Lanes
+
+`<cae-lanes>` shows bars on a time axis, a lane per group: each bar as long as
+the thing it stands for took. Register it with
+`@contraagent/elements/lanes/define`; the types and the placement functions are
+in `@contraagent/elements/lanes`.
+
+![Lanes on a time axis: a build that failed then passed, a test still running, and a line at now](images/lanes.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/lanes.ts"}
+
+## Lanes and bars
+
+A lane is a `Lane`, a bar a `LaneBar`: a start and an end in epoch
+milliseconds, the key of its look and its tooltip. A bar with no end is
+running: it grows until now, and a line marks now. Set `live` while a bar runs,
+so the element draws again every second.
+
+::code{file="../src/lanes/types.ts" from="/** Something that took time" to="/** A row of bars"}
+
+The overlapping bars of a lane are stacked, each on the first row whose last
+bar has ended (`stack`), so no bar hides another. The bars grow in when they
+are first drawn.
+
+## Looks and the legend
+
+`barStyles` maps each key to a `LaneStyle`: a label, a colour, and a pattern
+(`solid`, `hatched`, `striped`, which moves on a bar, or `outline`). Give a
+status a pattern besides its colour, so it does not depend on colour alone. The
+labels are the legend, a row per `group`, in key order; `omitted` adds a note
+of the bars the host left out (`strings.omitted`).
+
+## The axis
+
+By default the axis fits the bars (`fitRange`): from the first start to the
+last end; with a running bar, to now plus 20 seconds, rounded up to the minute.
+Set `range` to fix it. The axis shows five times, with seconds when it spans
+less than 10 minutes, in `locale` (by default the page's `lang`).
+
+## Look
+
+`--cae-lanes-label-width` sets the width of the lanes' labels (112px, 78px when
+the element is narrower than 760 px). The parts are `axis`, `lane`, `lane-label`, `track`, `bar`,
+`now`, `legend` and `empty`; with no bars the element shows `strings.empty`, or
+the `empty` slot.

package/docs/matrix.md

@@ -0,0 +1,34 @@
+# Mark matrix
+
+`<cae-mark-matrix>` shows marks in a table: a row per series (its label, then a
+value), a column per item, the columns under nested groups. Register it with
+`@contraagent/elements/matrix/define`; the types are in
+`@contraagent/elements/matrix`.
+
+![A mark matrix of nightly checks: a row per service with its failures, a column per check under each night](images/matrix.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/matrix.ts"}
+
+## The model
+
+A `MarkMatrixInput` holds the header rows (outermost first), the columns, the rows
+and the line above the table. A column names the groups it is under: a border marks
+where a group starts. A mark is drawn in its state's look (`states`, as in the
+[layered graph](graph.md)).
+
+::code{file="../src/matrix/types.ts" from="export interface MatrixRowInput {" to="export interface MarkMatrixStrings {"}
+
+## Keyboard and events
+
+The marks are one tab stop. The arrow keys, Home, End, Page Up and Page Down move
+between them (Ctrl with Home and End: the first and the last row). A click or the
+focus sends `cae-select`; Enter or a double click sends `cae-activate`, or
+`cae-drill` for a mark with `drill`. The sort control sends `cae-sort`: the host
+sorts the rows and sets `sort`. Above `windowAt` rows (150), only the rows in view
+are drawn.
+
+The words are `strings` ([Strings](strings.md)): the sort control's label and the
+header of the rows' labels.

package/docs/page.md

@@ -0,0 +1,87 @@
+# Building a page
+
+A page made of several elements: one run of a made-up CI pipeline, with a theme
+switch, stat tiles, a sortable table of jobs, and a layered graph of the steps
+beside a detail panel of the page's own. The whole example is
+`docs/examples/ci-pipeline.ts`; it uses only the package's public entry points,
+and `mount(host)` builds the page in any element.
+
+![A CI pipeline's page in the light theme: a theme switch, stat tiles, the layered graph of its steps beside a detail panel, and a table of its jobs](images/page.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+## What the page holds
+
+The elements keep no state of their own that the page needs: each one draws
+what its properties give it and sends a `cae-*` event for what the reader did.
+The page holds the data, the theme, the selection and the order of the table,
+and sets them back on the elements.
+
+| The reader | The element sends | The page sets |
+|---|---|---|
+| picks a theme | `cae-change` from `<cae-segmented>` | `data-ca-theme` on the page's box, and the control's `value` |
+| sorts a column | `cae-sort` from `<cae-data-table>` | the table's `sort`, and its `rows` in that order (`sortRows`) |
+| opens a row | `cae-activate` from `<cae-data-table>` | the graph's `selected`, and the panel |
+| selects a mark, a node or the loop | `cae-select` from `<cae-layered-graph>` | the graph's `selected`, and the panel |
+
+## Registering and theming
+
+Each `define` entry registers its elements; `adoptThemes(document)` adds the
+themes' rules once, and `data-ca-theme` on any ancestor then picks a theme
+([Theming](theming.md)).
+
+::code{file="examples/ci-pipeline.ts" from="import '@contraagent/elements/segmented/define'" to="// ---- The data"}
+
+## Widths
+
+Each element is as wide as its container and lays itself out by its own width,
+not the window's: its host is a CSS container (`container-type: inline-size`),
+so the same element fits a sidebar, a column or a whole page. Its width does
+not come from its content: in a flex row, give it a width or `flex: 1`. A table
+wider than its element scrolls inside its own box. This page's two columns
+become one below 760 px of the page's own width (`@container` in its stylesheet).
+
+## The data
+
+A step is a node of the graph and a job is one run of it, or of one of its
+shards. The steps `e2e` and `triage` repeat in a retry loop.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The data" to="// ---- What each state"}
+
+## States
+
+A state is the page's own word: `StateStyles` gives each one a tone, a shape
+and a rank, and the legend follows its key order.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- What each state" to="// ---- The graph"}
+
+## The graph
+
+The shards are the graph's `series`, so shard 2 is at the same place in every
+node that has shards; a step that runs once has one mark in `loose`. Each mark
+shows the last pass of its job, and the number of passes as its `badge`. The
+loop is a cluster that `cycle`s, closed by an edge with `ranks: false`. A
+node's `counts` and `progress` follow from its marks. The page puts nothing in
+the graph's `inspector` slot, so the graph draws no card beside the selection:
+the panel beside the graph describes it.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The graph" to="// ---- The table"}
+
+## The table and the tiles
+
+A column with `compare` sorts by it; a column with `sortable` and no `compare`
+sorts by its cell, a string or a number.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The table" to="// ---- The page's own styles"}
+
+## The page's styles
+
+The page's own text and boxes take the theme's colours (`--ca-*`), so they
+change with the switch.
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The page's own styles" to="// ---- The page: build it"}
+
+## The page
+
+::code{file="examples/ci-pipeline.ts" from="// ---- The page: build it"}

package/docs/primitives.md

@@ -0,0 +1,57 @@
+# Primitives
+
+The parts every element is built from, in `@contraagent/elements/primitives`.
+Most are template functions that a Lit element calls in its `render()`; their
+look comes from the element's styles, which start from `base`
+(`@contraagent/elements/styles`: the tokens, the status rules, chips, layout
+and motion).
+
+![Status pills (passed, failed, running, queued), a row of facts, and a legend](images/primitives.webp)
+
+## Tones
+
+A tone is the status colour a value takes: `failed`, `attention`, `done`,
+`running`, `muted`, or `neutral` (the text colour). The names are the token
+names (`--ca-status-<tone>`, [Theming](theming.md)). An element shows a tone as
+`data-tone`, and `neutral` as no attribute (`toneAttr`).
+
+::code{file="../src/core/tone.ts" from="/** A status colour" to="export const TONES"}
+
+## Statuses, legends and facts
+
+`pill` draws a status as a pill, `statusWord` as a word in a row, and
+`statusChip` in a class the element styles. Each sets `data-tone` and, where a
+mark belongs, `data-mark` (✓ done, ✕ failed, ◌ pending): the mark is drawn by
+CSS and hidden from screen readers, which read the word. A pill also has the
+parts `pill` and `tone-<tone>`.
+
+`legend` draws a list of entries, each a swatch (a colour, a tone and a shape,
+a class, or an icon of its own) and its word; add `legendStyles` to the
+element's styles. `factLine` draws a row of facts separated by ` | ` that
+breaks between facts, never inside one; a fact with a tone is in its status
+colour.
+
+::code{file="examples/status.ts"}
+
+## Icons
+
+`icon(name, label)` draws a glyph, or a template registered under `name` with
+`registerIcon`. Without a label it is hidden from screen readers; with one, the
+label is its tooltip and what a screen reader reads.
+
+## The segmented control
+
+`<cae-segmented>` is one choice among a few: a radio group, one tab stop, the
+arrow keys, Home and End to choose. It sends `cae-change` with the chosen
+value; the host keeps `value`.
+
+::code{file="examples/segmented.ts"}
+
+## Keyboard and long lists
+
+`RovingFocusController` gives a group of items one tab stop and moves the
+focus with the arrow keys, in a row, a column or a grid (`rovingStep` is the
+rule). `windowRows` is the arithmetic for drawing only the rows of a long list
+that are on screen.
+
+::code{file="../src/primitives/window.ts" from="/**" to="export function windowRows"}

package/docs/strings.md

@@ -0,0 +1,16 @@
+# Strings
+
+An element shows words: a button's name, an empty state, a count. It takes
+them from its `strings` property, a partial set of its `XStrings` interface,
+and uses its English default (`DEFAULT_X_STRINGS`) for each word it is not
+given. A word with a number is a function of the number, so the host decides
+plural forms and word order. Nothing here depends on a localization library:
+the host translates.
+
+::code{file="../src/markdown/cae-markdown.ts" from="export interface MarkdownStrings" to="export const DEFAULT_MARKDOWN_STRINGS"}
+
+```ts
+markdown.strings = { showRendered: 'プレビューを表示', showSource: 'ソースを表示' };
+```
+
+`withDefaults(defaults, given)` merges the two, as each element does.

package/docs/theming.md

@@ -0,0 +1,147 @@
+# Theming
+
+Each element keeps its styles in its own shadow root, so your page's CSS cannot
+break it and its CSS cannot leak into your page. What reaches it are the
+`--ca-*` custom properties:
+
+1. **A built-in theme**, picked by `data-ca-theme="<name>"` on any ancestor
+   (or on the element), sets every colour property on that element. The
+   elements inside it read them, and so does your page's own CSS.
+2. **A `--ca-*` property of your own** wins over the theme when it is set on
+   the element that carries `data-ca-theme` or on an element inside it. A theme
+   of your own is a set of them.
+
+With neither, an element shows contraagent Dark.
+
+![The CI pipeline's page in the contraagent Dark theme](images/theming-dark.webp)
+
+## The built-in themes
+
+| `data-ca-theme` | Name | Source |
+|---|---|---|
+| `contraagent-dark` | contraagent Dark (the default) | this package |
+| `contraagent-light` | contraagent Light | this package: the hues of contraagent Dark, set for a light page |
+| `github-dark` | GitHub Dark | [GitHub Primer primitives](https://github.com/primer/primitives), dark (MIT, GitHub Inc.) |
+| `github-light` | GitHub Light | Primer primitives, light (MIT, GitHub Inc.) |
+| `one-dark` | One Dark | [Atom One Dark](https://github.com/atom/atom/tree/master/packages/one-dark-syntax) (MIT, GitHub Inc.) |
+| `nord` | Nord | [Nord](https://www.nordtheme.com) (MIT, Arctic Ice Studio and Sven Greb) |
+| `high-contrast` | High contrast | Primer primitives, dark high contrast (MIT, GitHub Inc.) |
+
+An editor theme takes its surfaces, borders and text from the editor's own
+colours, its accent from the palette's accent, the statuses from its red,
+yellow, green and cyan, and the code colours from its syntax colours. Where a
+palette colour reads under 4.5:1 on the theme's surfaces and tints, its lightness
+is raised (or lowered, on a light theme) as little as needed and its hue kept;
+`src/themes/data.ts` lists every value. High contrast keeps text at 7:1 or
+more on every surface, has stronger borders and a wider focus ring, and its
+status colours stay apart under protanopia, deuteranopia and tritanopia.
+
+## Choosing a theme
+
+Set `data-ca-theme` on any ancestor. The rules that apply it are a stylesheet
+that a document (or a shadow root) adopts once: add it to the page's document,
+and to a shadow root of your own that holds the elements and sets
+`data-ca-theme` inside it. No import adopts it; `<ca-monitor>` of
+`@contraagent/ui` adopts it for its document when it connects.
+
+```ts
+import { adoptThemes } from '@contraagent/elements/themes';
+
+adoptThemes(document);
+adoptThemes(myShadowRoot);
+```
+
+The themes are also plain data: `THEMES`, `resolveTheme` and `themeRules` in
+`@contraagent/elements/themes`. `themeRules` writes the rules for a selector of
+your own, and `themeBootScript` is a script for a page's `<head>` that sets the
+reader's theme before the first paint, as the monitor's page does.
+`preferredTheme` and `rememberTheme` keep the reader's choice in this browser;
+`system` follows the system's colour scheme (contraagent Dark or contraagent
+Light).
+
+## Use the theme in your own page
+
+The theme's properties have the same names in your page as in the elements, so
+your page and the elements show one theme. Here `<html data-ca-theme="nord">`
+picks it, and the page's CSS reads it:
+
+::code{file="examples/page.css"}
+
+A theme sets each property that has a value per theme: the colours,
+`--ca-tint`, `--ca-focus-width` and `--ca-color-scheme`. Its selector has no specificity,
+so any rule of your page that sets a `--ca-*` property wins over it:
+
+::code{file="../src/themes/data.ts" from="/** A theme's selector on a page" to="/**"}
+
+The tints (`--ca-accent-bg`, `--ca-status-*-bg`, `--ca-agent-bg`), the type
+scale and the corners have one default for every theme; that default exists only
+inside the elements, unless your page sets the property.
+
+## What a colour means
+
+A colour means one thing, on every screen and in every theme:
+
+- **Neutral by default.** Text, totals, cost, tokens, time and every count that
+  is not a count of a problem are in the text colours. A number is emphasised by
+  its size and weight, not by a colour of its own.
+- **A status colour marks a status, and only where it applies.** A count of a
+  problem (failed attempts, tasks not started) takes its status colour above 0;
+  at 0 it is neutral, with its words ("All attempts done"). A total is never
+  coloured by its worst part.
+- **A status also has a shape and a word**, so it reads without colour: ✓ done,
+  ✕ failed, ◌ not started, a round mark for done and a square one for failed.
+- **One rule set draws every status.** An element that shows a status carries
+  `data-tone`, its tone (`failed`, `attention`, `done`, `running`, `muted`; none
+  for `neutral`), which picks its `--ca-status-*` colour and tint, and
+  `data-mark` for its mark. The primitives set both
+  ([Primitives](primitives.md)).
+- **One accent** for links and the selected tab or item; the focus ring has
+  its own colour and width.
+- **Identity colours are small cues** (an agent task's icon and edge, the token
+  bars, the timeline's bars): none of them is a status hue.
+
+| Properties | Meaning |
+|---|---|
+| `--ca-backdrop`, `--ca-bg`, `--ca-card`, `--ca-panel`, `--ca-panel2`, `--ca-raise`, `--ca-well`, `--ca-track`, `--ca-line`, `--ca-line2`, `--ca-shadow` | the page, surfaces, borders and shadows |
+| `--ca-text`, `--ca-text-secondary`, `--ca-text-muted` | text, from the main text to labels and units |
+| `--ca-accent`, `--ca-accent-bg` | what can be clicked or is selected |
+| `--ca-focus`, `--ca-focus-width` | the focus ring |
+| `--ca-selection` | selected text |
+| `--ca-status-failed` | failed: a task, an attempt, a check |
+| `--ca-status-attention` | not failed, needs a look: not started, a usage limit near |
+| `--ca-status-done` | done or passed: in marks and small chips only |
+| `--ca-status-running` | running, live |
+| `--ca-status-muted` | skipped, waiting, not run |
+| `--ca-status-*-bg`, `--ca-tint` | the tint behind a status pill or chip: by default the status colour at `--ca-tint` |
+| `--ca-agent`, `--ca-agent-bg` | identity: an agent task |
+| `--ca-meter` | a bar that measures, not judges: time, usage, progress |
+| `--ca-tok-input`, `--ca-tok-cache-read`, `--ca-tok-cache-write`, `--ca-tok-output` | the kinds of tokens in a bar |
+| `--ca-series-1` to `--ca-series-6` | the series of a chart, in a fixed order; never a status, and each series also named in words |
+| `--ca-code-*` | syntax colours in code, prompts and JSON |
+| `--ca-color-scheme` | `light` or `dark`: native controls and scrollbars |
+| `--ca-sans`, `--ca-mono` | the fonts |
+| `--ca-font-size-xs` to `--ca-font-size-2xl` | the type scale |
+| `--ca-radius-sm`, `--ca-radius-md`, `--ca-radius-lg`, `--ca-radius-pill` | the corners |
+
+Every property, its meaning and its value in each built-in theme are in the
+site's theme reference, generated from `src/themes/tokens-list.ts` (`TOKENS`),
+`src/themes/token-meanings.ts` (`TOKEN_MEANINGS`)
+and `src/themes/data.ts` (`THEMES`).
+
+## Type and corners
+
+The type and radius scale is the same in every theme: no theme sets it, and
+each step has a default. A `--ca-*` property on an ancestor changes a step for
+every element under it.
+
+::code{file="../src/themes/tokens-list.ts" from="{ name: 'font-size-xs'" to="];"}
+
+## A theme of your own
+
+Set the `--ca-*` properties on an element, here with a class: on the element
+that carries `data-ca-theme`, or on one inside it (on `<body>` under
+`<html data-ca-theme>`). Build it
+the way the built-in themes are built: each text colour keeps a contrast of at
+least 4.5:1 (WCAG AA) on every surface and on every status tint.
+
+::code{file="examples/theme.css"}

package/docs/tiles.md

@@ -0,0 +1,40 @@
+# Stat tiles
+
+`<cae-stat-tiles>` shows figures as a grid of tiles: each a label, a value and
+lines of facts under it, and a link. Register it with
+`@contraagent/elements/tiles/define`, which also registers the `<cae-count>` a
+tile's number counts up in; the types are in `@contraagent/elements/tiles`.
+
+![Four stat tiles: jobs, failed jobs with a link, build time, and queued](images/tiles.webp)
+
+<!-- not on the site -->
+Live on this topic's page of the documentation site (`pnpm run docs` in `web/`).
+
+::code{file="examples/tiles.ts"}
+
+## Tiles
+
+A tile is a `StatTile`. Its value is a number or a text: a number counts up to a
+new value, and the tile bumps when it changes (unless `bump` is off or the
+reader asks for reduced motion). Each line under the value is a row of facts
+(`factLine`, [Primitives](primitives.md)); a fact with a tone is in its status
+colour, and an empty line keeps its place.
+
+::code{file="../src/tiles/types.ts" from="/** A figure as a tile"}
+
+A tile is neutral by default. A tile with a tone takes it on its value, on the
+mark before its label (✓ done, ✕ failed, ◌ attention) and on a thin edge, and
+has `data-tone`. Give a tone only to a figure that is a status, such as a count
+of failures above 0; a total or a measure stays neutral.
+
+## Events
+
+A tile's link sends `cae-action` with the tile's `id` and the action's `id`;
+the host decides what it opens.
+
+## Look
+
+`columns` sets the tiles per row in a wide element (5); a narrower one has 4
+below 1100px of its width, 2 below 660px and 1 below 240px. `--cae-stat-tiles-gap` sets the space between
+the tiles. The parts are `tiles`, `tile` (with `data-id` and `data-tone`),
+`label`, `value`, `sub` and `action`.