@slotted/react 0.1.0-beta.1 → 0.1.0-beta.11

package/dist/docs/skills/build-own-element/SKILL.md

@@ -0,0 +1,90 @@
+---
+name: build-own-element
+description: Use when writing a component, widget or visual element that no family of @slotted/react draws — a timeline strip, a seat map, a heat grid, a bespoke control. Proves first that no family answers, then builds the element from the theme's tokens with the states, focus, target size, forced colours and motion the families keep.
+---
+
+# Build an element of the application's own
+
+An element of the application's own is a node the application writes and
+styles itself, outside any family (CP-04). It is the last resort, and it is
+built from the same theme as the families beside it.
+
+## 1. Prove that no family answers
+
+1. Read `../../index.md` and list the families whose line is near the
+   element.
+2. Read `../../<family>.md` for each: its anatomy, its slots, its axes.
+   When a family draws the element, or names a slot that holds it, the family
+   is used (CP-01).
+3. When a family draws a part of the element — a toggle, a popup, a list, a
+   tooltip — that part is the family, and only the rest is written.
+4. Write, in a comment above the element, the families read and what each
+   lacks.
+
+## 2. What is free and what is fixed
+
+Free, decided by the problem:
+
+- the element's shape, its arrangement and how it encodes the data — a strip,
+  a grid, a ring, a map;
+- which states it has, and what each state shows;
+- its layout inside the box it is given.
+
+Fixed, read from the theme:
+
+- every value it paints comes from a token of the group
+  `../../tokens.md` lists for that decision (OE-01, CP-05);
+- a tone carries the meaning the `tone` group gives it, and a data series takes
+  the `data` slots in order;
+- how its states yield, how focus is drawn, how large a target is, what forced
+  colours keep and how it moves (OE-02 to OE-07).
+
+A new appearance is a new combination of tokens, never a new value.
+
+## 3. Map each decision to a group
+
+| Decision                                       | Group in `../../tokens.md`                    |
+| ---------------------------------------------- | --------------------------------------------------- |
+| Distance between parts, inner padding          | `space`                                             |
+| Corners                                        | `radius`                                            |
+| Ground of the element and its parts            | `surface`; `tone` when the ground carries an intent |
+| Text                                           | `text`, `font-size`, `font-weight`, `line-height`   |
+| Edges                                          | `border`, `border-width`                            |
+| Series and categories of data                  | `data`                                              |
+| The place the reader is on, a matched span     | `current`, `highlight`                              |
+| Focus                                          | `focus-ring`                                        |
+| Hit area                                       | `target`                                            |
+| A part that stands beside controls             | `control`, `control-size`                           |
+| Movement                                       | `duration`, `easing`                                |
+| A surface above another, a layer over the page | `shadow`, `z-index`                                 |
+| A disabled part                                | `disabled`                                          |
+
+A decision no group names is written as a literal beside a comment that says
+why no token covers it (CP-05).
+
+## 4. Write it
+
+1. Give each interactive part the native element that carries its role: a
+   button for an action, a link for a destination, an input for a value. Add
+   ARIA only where no element carries the role.
+2. List the element's states, and paint each pair that can hold at once in the
+   order of OE-02.
+3. Draw focus on `:focus-visible` as an outline of `--slotted-focus-ring-width`
+   in `--slotted-focus-ring-color`, offset by `--slotted-focus-ring-offset`
+   (OE-03). Size every target to `--slotted-target-min` (OE-04), and take the
+   control step of the controls beside it (OE-05).
+4. Under `forced-colors: active`, tell each state from rest by a border,
+   an outline or text (OE-06). Move with the motion tokens, and stop a
+   repeating animation under `prefers-reduced-motion: reduce` (OE-07).
+5. Write the CSS in a layer of the application after the library's, on class
+   names of the element's own (OE-08). Reflow by a container query on a
+   container of its own (OE-09). Float with a raised surface and one shadow
+   step (OE-10).
+6. Text that stands alone takes its size from the `typography` family (CP-02).
+
+## 5. Done
+
+1. Each `Check` of `../../guidelines/own-elements.md` passes.
+2. The element's CSS holds no colour or length literal without its comment.
+3. Every custom property the element reads is listed in
+   `../../tokens.md` above "Read by their family only".

package/dist/docs/skills/compose-screen/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: compose-screen
+description: Use when writing or changing a screen of an application built with @slotted/react — a list of records, the page of one record, a form that writes one, an overview, a report, a tree beside a list, a rule builder, a conversation or a ledger. Applies the Slotted guidelines in order and ends with each Check of the rules read.
+---
+
+# Compose a screen
+
+A screen is composed from the families' own parts first. An element of the
+screen's own exists only where no family names a place for it.
+
+## 1. Name the domain values
+
+Name the values the product is about on this screen — money, a period, a day,
+an account, a person — and the task the reader performs with each: enter it in
+one motion, step it, compare it. For each, write which family accepts the
+value and whether that family performs the task in one step with the value's
+own words. When it does not, CP-04 applies before any family is chosen: a
+family that technically accepts a value does not answer the reader's task by
+that fact.
+
+## 2. Classify the screen
+
+| The screen                                            | Topic              |
+| ----------------------------------------------------- | ------------------ |
+| Lists records, searches, filters, pages               | `list-pages.md`    |
+| Shows one record, its figures and its related records | `record-pages.md`  |
+| Creates or edits a record                             | `forms.md`         |
+| Summarises a domain in figures and charts             | `overviews.md`     |
+| Places a list beside a tree of its places             | `browsing.md`      |
+| Reads records over a chosen period                    | `reports.md`       |
+| Writes or reads a rule the system runs later          | `builders.md`      |
+| Holds a conversation the reader answers               | `conversations.md` |
+| Works a queue against candidates in three regions     | `workspaces.md`    |
+| Lists immutable changes with their cause and balance  | `ledgers.md`       |
+
+A screen can be two of these: a record with an edit form in place reads both
+topics.
+
+## 3. Read
+
+1. `../../guidelines/index.md`.
+2. `../../guidelines/composition.md`, always.
+3. The topic of step 2. Add `layout-alignment.md` and `shell-composition.md`
+   when the screen places controls in a row or in the application frame.
+4. Add `errors-and-conflicts.md` and `reading-permissions.md` when the screen
+   writes data or reads under a role.
+5. When the screen writes an element of its own, follow
+   `../../skills/build-own-element/SKILL.md`.
+
+## 4. Read each family before writing beside it
+
+For each family the screen uses, read `../../<family>.md` — its anatomy,
+its slots, its axes (CP-01). When the family names a slot for an element, the
+element stands in that slot.
+
+## 5. Compose
+
+- Every destination of the navigation is `full`, and a list adds `fill`; a
+  create or edit form is `wide`; preferences read as prose are `measure`
+  (CP-10).
+- Siblings of the screen's own stand in `inline` (one row) or `stack` (one
+  column) with a gap from the space scale; text of the screen's own takes its
+  size from the `typography` family's `text` member (CP-02).
+- A track that holds a family which scrolls states a zero minimum, so the
+  family's scroller is what scrolls (CP-03).
+- An element of the screen's own paints only with theme tokens; a literal is
+  written only beside a comment that says why no token covers it (CP-05).
+- A state a family already draws is set on the family and stated once, with
+  nothing louder beside it (CP-06).
+- A control that switches what a region holds changes words and values, never
+  the size or the position of a box (CP-08).
+- A control that switches a region — tabs, a route, a filter — updates its
+  own state at once and renders the region from a deferred value (in React,
+  useDeferredValue or startTransition) (CP-09). A list longer than a hundred
+  rows is a `data-grid`, which windows its rows where it has a height of its
+  own and is served in pages below 600 pixels (LP-12, LP-14). Its columns, its disabled keys and a function row key are module constants or memoised: a new one on a render of the screen renders every mounted row again. Its renderers, its messages and its tree may be written inline.
+- Where no anatomy answers the problem, the screen writes an element of its
+  own instead of bending a family into a shape it does not have (CP-04). That
+  element is built with `../../skills/build-own-element/SKILL.md`.
+
+## 6. Waits
+
+Every region filled by a request and every control that starts one follow
+`../../skills/waiting-states/SKILL.md`.
+
+## 7. Done
+
+1. Each `MUST` rule of the topics read: its `Check` passes.
+2. Each `SHOULD` rule not followed is listed with its reason.
+3. No CSS of the screen's own targets a family's parts; a family's appearance
+   changes through its axes.
+4. On the production build, at 375 pixels with a coarse pointer and the CPU
+   throttled 4×, with the list holding at least 200 rows: each control that
+   switches a region, a row's selection, select-all, a sort, a row menu and a
+   scroll of one screen each paint within 200 ms of the input (the Event Timing
+   duration), and no list mounts more rows than its window or than the pages
+   it has requested (LP-12). A development build is not a measurement: a
+   hundred rows of twenty columns measured 93 ms on the production build and
+   160 ms on the development one (LP-14).
+5. For each value named in step 1, the control that edits it was chosen
+   against the task, and the reason is written beside it.
+6. At 360 pixels with a coarse pointer, the header's actions and the footer's
+   actions each occupy one row (LA-03, LA-07).

package/dist/docs/skills/index.md

@@ -0,0 +1,9 @@
+# Skills index
+
+Each skill, with when it applies. Read a skill before its task.
+
+- build-own-element: `./build-own-element/SKILL.md` — Use when writing a component, widget or visual element that no family of @slotted/react draws — a timeline strip, a seat map, a heat grid, a bespoke control. Proves first that no family answers, then builds the element from the theme's tokens with the states, focus, target size, forced colours and motion the families keep.
+- compose-screen: `./compose-screen/SKILL.md` — Use when writing or changing a screen of an application built with @slotted/react — a list of records, the page of one record, a form that writes one, an overview, a report, a tree beside a list, a rule builder, a conversation or a ledger. Applies the Slotted guidelines in order and ends with each Check of the rules read.
+- review-screen: `./review-screen/SKILL.md` — Use when reviewing, auditing or fixing an existing screen of an application built with @slotted/react, or when asked whether a screen follows the Slotted guidelines. Reads the rules that apply, sweeps the screen's code for the defects found without running it, and reports each finding with its rule, level and place.
+- theme-app: `./theme-app/SKILL.md` — Use when changing how an application built with @slotted/react looks, as a whole or in one region — its brand colour, a light, dark or high-contrast scheme, density, fonts, corners, or the shape of a control. Chooses the narrowest level that reaches the change — a seed, a token, a family token or a theme rule — and where it is declared.
+- waiting-states: `./waiting-states/SKILL.md` — Use when building or reviewing anything a person waits in front of in an application built with @slotted/react — placeholders, a control's own loading state, a loading overlay, a progress indicator, or the empty and error states beside them. Decides which indicator answers which wait and how placeholders are built from the anatomy they stand in for.

package/dist/docs/skills/review-screen/SKILL.md

@@ -0,0 +1,79 @@
+---
+name: review-screen
+description: Use when reviewing, auditing or fixing an existing screen of an application built with @slotted/react, or when asked whether a screen follows the Slotted guidelines. Reads the rules that apply, sweeps the screen's code for the defects found without running it, and reports each finding with its rule, level and place.
+---
+
+# Review a screen
+
+A review answers one question per rule read: does the screen pass the rule's
+`Check`. A finding names a rule; a remark that names no rule is not a finding.
+
+## 1. Inventory
+
+1. List the screen's files: its component, its template, its stylesheet and
+   the requests it starts.
+2. List the families it imports, and read `../../<family>.md` for each.
+3. List the elements of the screen's own: every element that is not a family,
+   with the CSS that paints it.
+4. Classify the screen with the table in step 1 of
+   `../../skills/compose-screen/SKILL.md`.
+
+## 2. Read
+
+1. `../../guidelines/index.md` and
+   `../../guidelines/composition.md`.
+2. The topics of the classification, and each topic whose `triggers` the
+   screen matches.
+3. `own-elements.md` when step 1 listed an element of the screen's own.
+4. `../../skills/waiting-states/SKILL.md` when the screen starts a
+   request.
+
+## 3. Sweep the code
+
+Each search below finds a defect without running the screen.
+
+| Search the screen's files for                                                                                                                                | Defect                                                    | Rule         |
+| ------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------- | ------------ |
+| A colour literal (hex, rgb, hsl, oklch), a length in pixels or rem other than zero, or a font size, in the screen's CSS                                      | a value the theme has a token for                         | CP-05, OE-01 |
+| A rule of the application's CSS that sets colour, border, radius, padding or type on a family's `data-ui` or `data-part`                                     | the screen restyles a family instead of setting its axes  | OE-08        |
+| A control that starts a request and is not in its `loading` state until the answer, except a Refresh of the whole page                                       | a control that fires twice                                | AF-03        |
+| A Refresh of the whole page drawing a spinner on its button, or a refetch of data on screen with no `page-header` progress bar                               | a wait in the wrong place, and no wait shown for the page | AF-07        |
+| An empty state drawn from the initial value of the data, before the first answer                                                                             | a wait shown as nothing                                   | AF-01        |
+| A spinner standing in a region that has no items yet                                                                                                         | placeholders missing                                      | AF-02        |
+| Siblings of the page's own spaced by margins, or text with a font size of its own                                                                            | layout outside the primitives                             | CP-02        |
+| A grid or flex track around a family that scrolls, with no zero minimum                                                                                      | the page scrolls, not the family                          | CP-03        |
+| A badge, a tag or a colour beside a family that already draws the same state                                                                                 | a state stated twice                                      | CP-06        |
+| An element of the screen's own that takes focus with no ring in its `focus-visible` state                                                                    | focus not drawn                                           | OE-03        |
+| A `data-grid` or `table` with no `variant` on a page whose `width` is not `bleed`                                                                            | a grid with no frame on the page's surface                | LP-15        |
+| A list page's `page-header` with a heading and no subheading, no figures and no solid primary action                                                         | a header that does not say what the list covers           | LP-16        |
+| A grid whose column state unpins its `actions` column                                                                                                        | the row's actions leave the frame                         | LP-17        |
+| A row of `stat-card`s where a label has more than three words, or one card has a comparison the others lack                                                  | a row of cards with no shared structure                   | OV-06        |
+| Two destinations of the navigation whose `page`s state different `width`s                                                                                    | the column's edges move between destinations              | CP-10        |
+| A write whose success handler refreshes only the region of the control that wrote                                                                            | figures elsewhere stay stale after the write              | AF-08        |
+| Two or more actions in a `page-header`'s `actions` outside a `toolbar` that folds into its menu, or toolbar items with no counterpart beside the primary one | a header whose actions wrap on a phone                    | LA-03        |
+| A footer `action-bar` of three or more actions with no overflow control, or a secondary action with no counterpart                                           | a footer that stacks into a column on a phone             | LA-07        |
+
+A rule whose `Check` needs the screen running — a size class, a throttled
+network, the accessibility tree — is run when the environment can run it, and
+otherwise reported as not checked, with the step that checks it.
+
+## 4. Report
+
+One finding per entry, every `MUST` before every `SHOULD`:
+
+- the rule's id and level;
+- the file and the line;
+- what the screen does, in one sentence;
+- the change after which the rule's `Check` passes.
+
+A `SHOULD` the screen breaks on purpose is listed with its reason, as a
+deviation. The screen passes when no `MUST` finding remains.
+
+## 5. Fix, when asked
+
+1. Fix every `MUST` finding, then each `SHOULD` finding the request covers.
+2. A fix uses what the family offers — its state, its slot, its axis — and
+   never CSS on its parts.
+3. A literal becomes a token of the group `../../tokens.md` lists for
+   that decision.
+4. Run the searches of step 3 again on the changed files: none finds anything.

package/dist/docs/skills/theme-app/SKILL.md

@@ -0,0 +1,98 @@
+---
+name: theme-app
+description: Use when changing how an application built with @slotted/react looks, as a whole or in one region — its brand colour, a light, dark or high-contrast scheme, density, fonts, corners, or the shape of a control. Chooses the narrowest level that reaches the change — a seed, a token, a family token or a theme rule — and where it is declared.
+---
+
+# Theme an application
+
+The theme decides every value a family paints. A change of look is made in a
+theme or on a scope, never by CSS of the application on a family's parts.
+
+## 1. Choose the level
+
+Take the first row that reaches the change.
+
+| The change                                                                      | Level                                                           | Declared in                                                                                                  |
+| ------------------------------------------------------------------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ |
+| The brand colour, or the colour of one intent                                   | a seed: `--slotted-seed-accent` or another name of `SEED_NAMES` | the theme's `seeds`, or a scope                                                                              |
+| Light, dark, high contrast, or the system's preference                          | the scheme: `light`, `dark`, `high-contrast`, `system`          | `data-slotted-scheme`, or the scheme of the `ThemeScope` component from `@slotted/react/theme`                                                       |
+| How tight controls and rows are                                                 | the density: `comfortable`, `compact`, `dense`                  | `data-slotted-density`, or the density of the `ThemeScope` component from `@slotted/react/theme`                                                     |
+| How deep a scheme's grounds sit, or how far each layer steps from the one below | the recipe: one derivation per token per scheme                 | the theme's `recipe`, spread from the base theme's, as below; `themeConformance` still checks every contrast |
+| Spacing, corners, type, lines, shadows or motion                                | a token of a group in `../../tokens.md`                   | the theme's `base`; `schemes` for a value per scheme; `densities` per density                                |
+| One family's look                                                               | a token the family's page lists under Tokens                    | the theme's `components`                                                                                     |
+| What no token reaches                                                           | a theme rule                                                    | the theme's `rules`                                                                                          |
+
+Every colour token derives from the six seeds within contrast bounds, so a
+new seed keeps the ratios of every scheme. A colour of the `tone`, `surface`,
+`text` or `border` groups is changed through its seed, or through its
+derivation in the recipe, never declared by hand.
+
+A recipe change keeps every other derivation of the base theme: the theme's
+`recipe` spreads the base theme's recipe, spreads from it the scheme it
+changes, and replaces one token's derivation — its seed, its lightness and its
+chroma's scale and ceiling, the shape every derivation of the standard recipe
+has.
+
+## 2. One theme for the product
+
+1. Build it with `extendTheme` on the theme of `@slotted/themes/default`: a
+   name of its own, and only what changes — `seeds`, then `base`, `schemes`
+   and `densities`, then `components`, then `rules`. A face the product brings
+   goes in `fonts`, and the `font-family` group names it; headings read
+   `--slotted-font-family-heading`.
+2. Compile it with `slotted-build-theme`, load the stylesheet it writes in
+   place of `@slotted/themes/default.css`, and set the theme's name in
+   `data-slotted-theme` and the scheme in `data-slotted-scheme` on the root
+   element.
+3. A theme chosen at runtime is applied with `applyTheme`, in a module the
+   application loads on demand: `@slotted/theme` carries the whole token
+   contract and its validator.
+4. In a test of the theme, `themeConformance` from `@slotted/theme/conformance`
+   checks the structure, the contrast of every scheme and the glyphs, under
+   Node's test runner. It takes the `contract`, the theme passed through
+   `flattenTheme`, and the compiled stylesheet.
+
+## 3. One region
+
+1. A scheme or a density for a subtree: the `ThemeScope` component from `@slotted/react/theme`, which carries both to
+   an overlay opened inside it, or the `data-slotted-scheme` and
+   `data-slotted-density` attributes on the subtree's root.
+2. A seed for a subtree: the seed property on an element that also carries
+   `data-slotted-seeds`, or the seeds of the `ThemeScope` component from `@slotted/react/theme`. Every colour under it
+   derives again from that seed.
+3. A colour the reader picks at runtime: write the seed property on the element
+   that carries `data-slotted-theme`, with `seedStyle` from
+   `@slotted/theme/seeds`, which leaves the token contract out of the bundle.
+4. A bar of the application's own that floats over scrolling content — a phone
+   tab bar, a sticky banner — is a material: its background reads
+   `--slotted-surface-material` and its backdrop filter reads
+   `--slotted-material-backdrop`. The theme makes both opaque under reduced
+   transparency and forced colours. A page header becomes that material once
+   content passes under it with its `material` input, set on the header or on
+   its defaults. A theme draws the command palette as one by setting
+   `--slotted-command-palette-surface` to the material surface and
+   `--slotted-command-palette-backdrop-filter` to the material backdrop, and a
+   raised toast with `--slotted-toast-surface` and
+   `--slotted-toast-backdrop-filter`. The bars at the bottom edge take
+   `--slotted-page-footer-background` with
+   `--slotted-page-footer-backdrop-filter`, and
+   `--slotted-detail-panel-footer-background` with
+   `--slotted-detail-panel-footer-backdrop-filter`, and a dialog's panel
+   `--slotted-dialog-surface` with `--slotted-dialog-backdrop-filter`.
+
+## 4. Restyle a control
+
+1. A token every control reads, in `base`, `schemes` or `densities`.
+2. Else a token of the family, in `components`; it falls back to the control
+   token.
+3. Else a theme rule. It lives in `slotted.theme-rules`, selects only
+   `data-ui`, `data-part`, the attributes a family writes and the theme's
+   attributes, and reads only tokens; the compiler names the file, the line
+   and the selector of a rule it refuses.
+
+## 5. Done
+
+1. The application's own CSS declares no token of the `tone`, `surface`,
+   `text` or `border` groups, and sets no colour, border, radius, padding or
+   type on a family's `data-ui` or `data-part`.
+2. `themeConformance` passes for the theme.

package/dist/docs/skills/waiting-states/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: waiting-states
+description: Use when building or reviewing anything a person waits in front of in an application built with @slotted/react — placeholders, a control's own loading state, a loading overlay, a progress indicator, or the empty and error states beside them. Decides which indicator answers which wait and how placeholders are built from the anatomy they stand in for.
+---
+
+# Waiting states
+
+A waiting state is a screen the reader sees, not a gap in one. It is built from
+the anatomy it stands in for, and it is finished when the loaded screen and the
+pending screen occupy the same boxes.
+
+The failure this skill prevents: three grey bars of equal length where a table,
+a card and a list should have been.
+
+Rules cited here are in `../../guidelines/async-feedback.md`. Each family
+named here has its page: `../../<family>.md`.
+
+## 1. Which indicator answers which wait
+
+Answer in order and stop at the first row that decides.
+
+| The wait                                                                                                         | The indicator                                                                                                         |
+| ---------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Structure is known before the data arrives — a list, a table, a card, a form                                     | `skeleton` placeholders                                                                                               |
+| Data already on screen is read again for the whole page — a Refresh, a refetch after a write, a refetch on focus | the `page-header` progress part in the page header; the region keeps its items and no control draws its own indicator |
+| A control started the request and stays on screen — a button, a field, a menu item                               | that family's own `loading` state                                                                                     |
+| A region already painted is being replaced and must not be touched meanwhile                                     | `loading-overlay`                                                                                                     |
+| The work reports how much is done                                                                                | `progress-indicator` with a value                                                                                     |
+| Nothing above: duration unknown, structure unknown, area small                                                   | `progress-indicator` in its `indeterminate` state                                                                     |
+
+Two indicators never answer the same wait in the same region. Placeholders
+under an overlay, an indeterminate indicator inside placeholders, and a
+progress indicator over a control that already waits are each one indicator
+too many.
+
+A region that already shows items is busy, not pending: it keeps its items,
+carries `aria-busy`, and swaps them when the newer answer arrives (AF-02,
+AF-07). Replacing read content with placeholders on every refresh is how a
+screen flickers. A change of view or page is different: the rows on screen are
+removed and placeholders stand in their place (AF-04).
+
+A control that starts a request waits on it: it is in its `loading` state from
+activation until the answer, refuses a second activation and shows the
+family's indicator (AF-03).
+
+## 2. Placeholders are the anatomy, not rectangles
+
+Placeholders are the same layout as the content, drawn in one colour. Build
+them from the loaded markup:
+
+1. Keep the container, the parts, the grid, the inset and the gap tokens the
+   loaded content uses. Copy the structure; replace only what carries data.
+2. Text becomes `skeleton` text lines at the same type size, so the reserved
+   height is the height the text will take.
+3. Media — avatar, thumbnail, chart — becomes a shape of its own measured box.
+4. Repetition takes the real count: a list reserves the rows its first page
+   returns, a table reserves its columns at their real widths, a card reserves
+   the avatar and the two lines that card holds.
+5. Stop where the reader stops. A row's badge, a trailing icon and a caption
+   belong to the loaded row, not to its placeholder.
+
+Line lengths vary the way text varies: the last line of a paragraph is short,
+a name is shorter than a description. A stack of bars of equal length is the
+defect this section names.
+
+### What never gets placeholders
+
+Chrome that is already painted renders with its real content: the application
+bar, the navigation column, the page header's title, a toolbar, a tab strip, a
+section heading. Only what is being fetched is reserved. An action nobody can
+press yet is absent, not drawn as a placeholder.
+
+## 3. The test: nothing moves
+
+The pending state and the loaded state occupy the same boxes. Capture both at
+the same width, in the same scheme, and compare their bounding boxes: any box
+that moves between them is a defect.
+
+Where the two cannot match exactly — an unknown number of rows, a description
+of unknown length — reserve the smaller of the two and let the content grow
+downward, never a box that shrinks.
+
+## 4. Timing
+
+- A region's placeholders appear at once; they are never delayed (AF-05).
+- A control's indicator may wait for the family's `loadingDelay`, so a request
+  that answers first shows no indicator; the control still refuses a second
+  activation (AF-05).
+- Once painted, placeholders stay for one minimum duration the application
+  states once for the whole product — the `minDuration` of `skeleton` and
+  `loading-overlay` — even when the answer has already arrived (AF-06).
+
+## 5. Announcement and focus
+
+- Placeholders are out of the accessibility tree. They describe nothing; the
+  region says what is happening.
+- One announcement per region, `polite`, once — not one per placeholder.
+  `skeleton` and `loading-overlay` announce through their `live` axis, `polite`
+  by default: keep it on the one that stands for the region and set it to `off`
+  on every other placeholder in that region.
+- The region carries `aria-busy` while it waits and drops it when the answer
+  arrives.
+- Focus does not move, on entry or on arrival. Content that lands under the
+  reader's focus does not take it, and a placeholder never holds a tab stop.
+
+## 6. Motion
+
+One shimmer per region, from the family's own animation, not one per bar.
+Under `prefers-reduced-motion: reduce` the animation stops and the reserved
+shape stays.
+
+## 7. Pending, empty and error are three states
+
+| State      | What it says                              | What it offers                            |
+| ---------- | ----------------------------------------- | ----------------------------------------- |
+| Pending    | the answer is coming                      | nothing to press                          |
+| Empty      | an answer arrived and it holds zero items | the action that creates the first one     |
+| No results | the filter excluded everything            | clearing the filter                       |
+| Error      | the answer did not arrive                 | retry; the data that is still valid stays |
+
+The empty state appears only after an answer holding zero items, never while
+the first answer is pending (AF-01). Empty, no results and error are drawn by
+`result-state`. An error replaces the indicator; it never leaves placeholders
+animating behind a message.
+
+## 8. Before calling a wait done
+
+- [ ] The indicator matches the wait, by the table in section 1, and there is
+      only one.
+- [ ] Placeholders mirror the anatomy: same parts, same grid, same tokens, real
+      counts.
+- [ ] Loaded and pending captured at the same width: no box moves.
+- [ ] Line lengths vary; no stack of equal bars.
+- [ ] Chrome that already exists is painted with its real content.
+- [ ] Placeholders are not delayed; the minimum duration is stated once.
+- [ ] One polite announcement per region, `aria-busy` on the region, focus
+      untouched.
+- [ ] Reduced motion stops the animation and keeps the shape.
+- [ ] Empty, no results and error are distinct states, each with its next step.
+- [ ] For each control that writes, the regions on any screen whose figures
+      the write changes are listed, and each is shown read again after the
+      write (AF-08).
+- [ ] Each `Check` of AF-01 to AF-08 passes.

package/dist/docs/sparkline.json

@@ -24,6 +24,7 @@
       "neutral",
       "accent",
       "secondary",
+      "info",
       "success",
       "warning",
       "danger"
@@ -191,7 +192,7 @@
         },
         {
           "name": "tone",
-          "type": "'neutral' | 'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'neutral' | 'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "—",
           "appliesTo": "Sparkline",
           "description": "How the series is doing. Wins over series; unset, a container may decide"
@@ -320,6 +321,7 @@
     "--slotted-sparkline-marker-size",
     "--slotted-sparkline-marker-size-lg",
     "--slotted-sparkline-marker-size-sm",
+    "--slotted-sparkline-min-inline-size",
     "--slotted-sparkline-reference-color",
     "--slotted-sparkline-ring-color",
     "--slotted-sparkline-ring-width",
@@ -328,6 +330,7 @@
     "--slotted-text-muted",
     "--slotted-tone-accent-text",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-text",
     "--slotted-tone-secondary-text",
     "--slotted-tone-success-text",
     "--slotted-tone-warning-text"
@@ -360,7 +363,7 @@
     {
       "id": "tone",
       "title": "How the series is doing",
-      "note": "A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the theme’s own blue.",
+      "note": "A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the accent’s own hue.",
       "language": "tsx",
       "source": "<Sparkline data={errorRate} label=\"Error rate\" tone=\"success\" />;\n<Sparkline data={leadTime} label=\"Lead time\" tone=\"danger\" />;\n<Sparkline data={lastQuarter} label=\"Last quarter\" tone=\"neutral\" />;\n",
       "verdict": "excerpt"

package/dist/docs/sparkline.md

@@ -43,7 +43,7 @@ Excerpt — not a complete module
 | `reference` | `number` | — | Sparkline | A dashed hairline at this value. Widens the extent to hold it |
 | `min` | `number` | — | Sparkline | The lowest value the extent must hold. The data widens the extent, never narrows it |
 | `max` | `number` | — | Sparkline | The highest value the extent must hold |
-| `tone` | `'neutral' \| 'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | — | Sparkline | How the series is doing. Wins over series; unset, a container may decide |
+| `tone` | `'neutral' \| 'accent' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | — | Sparkline | How the series is doing. Wins over series; unset, a container may decide |
 | `series` | `1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8` | — | Sparkline | Which series this is, as a slot of the data scale. Unset, a container decides, then slot 1 |
 | `label` | `string` | — | Sparkline | What the series is, said first in the description |
 | `description` | `string` | — | Sparkline | The whole accessible name, in place of the generated one |
@@ -63,7 +63,7 @@ Excerpt — not a complete module
 | `type` | `line`, `bar` | `line` |
 | `size` | `sm`, `md`, `lg` | `md` |
 | `curve` | `linear`, `monotone` | `linear` |
-| `tone` | `neutral`, `accent`, `secondary`, `success`, `warning`, `danger` | — |
+| `tone` | `neutral`, `accent`, `secondary`, `info`, `success`, `warning`, `danger` | — |
 | `series` | `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8` | — |
 
 ## Rules
@@ -77,7 +77,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-data-1`, `--slotted-data-2`, `--slotted-data-3`, `--slotted-data-4`, `--slotted-data-5`, `--slotted-data-6`, `--slotted-data-7`, `--slotted-data-8`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-space-11`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-7`, `--slotted-space-9`, `--slotted-sparkline-area-opacity`, `--slotted-sparkline-bar-share`, `--slotted-sparkline-block-size`, `--slotted-sparkline-block-size-lg`, `--slotted-sparkline-block-size-sm`, `--slotted-sparkline-color`, `--slotted-sparkline-line-width`, `--slotted-sparkline-line-width-sm`, `--slotted-sparkline-marker-size`, `--slotted-sparkline-marker-size-lg`, `--slotted-sparkline-marker-size-sm`, `--slotted-sparkline-reference-color`, `--slotted-sparkline-ring-color`, `--slotted-sparkline-ring-width`, `--slotted-sparkline-ring-width-sm`, `--slotted-surface-raised`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+`--slotted-border-strong`, `--slotted-border-width-medium`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-data-1`, `--slotted-data-2`, `--slotted-data-3`, `--slotted-data-4`, `--slotted-data-5`, `--slotted-data-6`, `--slotted-data-7`, `--slotted-data-8`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-standard`, `--slotted-space-11`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-7`, `--slotted-space-9`, `--slotted-sparkline-area-opacity`, `--slotted-sparkline-bar-share`, `--slotted-sparkline-block-size`, `--slotted-sparkline-block-size-lg`, `--slotted-sparkline-block-size-sm`, `--slotted-sparkline-color`, `--slotted-sparkline-line-width`, `--slotted-sparkline-line-width-sm`, `--slotted-sparkline-marker-size`, `--slotted-sparkline-marker-size-lg`, `--slotted-sparkline-marker-size-sm`, `--slotted-sparkline-min-inline-size`, `--slotted-sparkline-reference-color`, `--slotted-sparkline-ring-color`, `--slotted-sparkline-ring-width`, `--slotted-sparkline-ring-width-sm`, `--slotted-surface-raised`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-info-text`, `--slotted-tone-secondary-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
 
 ## Examples
 
@@ -108,7 +108,7 @@ Excerpt — not a complete module
 
 ### How the series is doing
 
-A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the theme’s own blue.
+A tone paints the line in the tone’s text colour: success for an error rate that fell, danger for a lead time that grew, neutral for the comparison series behind a current one. Without a tone the line is the first slot of the data scale, the accent’s own hue.
 
 Excerpt — not a complete module
 

package/dist/docs/split-button.json

@@ -10,6 +10,8 @@
     "tone": [
       "accent",
       "secondary",
+      "neutral",
+      "info",
       "success",
       "warning",
       "danger"
@@ -88,7 +90,7 @@
       "api": [
         {
           "name": "tone",
-          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "accent",
           "appliesTo": "SplitButton",
           "description": "The tone both halves are painted in. Resolved from the prop, then SplitButtonDefaultsProvider, then button’s own provider, then the contract"
@@ -263,6 +265,7 @@
     "--slotted-split-button-radius",
     "--slotted-tone-accent-solid-active",
     "--slotted-tone-danger-solid-active",
+    "--slotted-tone-info-solid-active",
     "--slotted-tone-secondary-solid-active",
     "--slotted-tone-success-solid-active",
     "--slotted-tone-warning-solid-active"