@slotted/react 0.1.0-beta.0 → 0.1.0-beta.2

package/dist/docs/guidelines/reports.md

@@ -0,0 +1,123 @@
+---
+topic: reports
+prefix: RE
+triggers:
+  [
+    report,
+    analytics,
+    period,
+    comparison,
+    compare,
+    trend,
+    segment,
+    drill-down,
+    download,
+    csv,
+    anomaly,
+    annotation,
+    coverage,
+    history,
+    ranking,
+  ]
+families: [page-header, select, stat-card, chart, table, list, section, inline-message]
+---
+
+# Reports
+
+How a screen that reads records over a chosen period is composed: what it
+reads from the operational screens, how a period and its comparison are
+chosen and kept, what it says where the records are not kept, how a figure
+is flagged and how a breakdown is downloaded. The library gives `chart` a
+period of data, `stat-card` a change and its base, `table` a summary row; it
+does not say that a period lives in the address, that a figure the history
+does not hold is no number, or which rule flags a figure.
+
+### RE-01 · A report reads a period; an overview reads today
+
+Level: SHOULD
+Applies to: a report that shows a state of today beside its period's flows — receivables, a backlog, stock on hand
+Rule: A figure of the report is a flow over its period against a period of the same length; a state of today is read through the operational screen's own read, says "as of today", and opens the operational screen's door.
+Why: Two reads of one state drift — a receivables figure computed twice says two numbers on two screens — and a state read beside a period reads as the period's.
+Do: Read the overview's answer beside the report's and draw its figures from it, with the overview's door and the overview's thresholds; give the read a region of its own, so a failure of either leaves the other on screen.
+Don't: Recompute an overview's figure inside the report, or draw a state of today without saying it is today's.
+Check: Read each state of today on the report: it says "as of today", equals the figure of the operational screen it opens, and stays on screen when the report's own read fails.
+
+### RE-02 · The period is the address
+
+Level: SHOULD
+Applies to: the period, the comparison and the segment filters of a report
+Rule: They are query parameters of the report's address; a report opened without them takes the ones last chosen on any report, and the back gesture from a list it opened returns to the same period.
+Why: A period held in the page alone is lost on the way back from a drill-down, and a reader moving from one report to the next would choose it again on each.
+Do: Write each choice into the address by replacing the current history entry, so a change of period is no step of the history and the back gesture leaves the report; remember the last choice for the next report opened without one.
+Don't: Keep the period in a store the address does not name, or push a history entry per change.
+Check: Choose a period, open a figure's list and go back: the report is on the same period. Open another report with no period in its address: it takes the period last chosen.
+
+### RE-03 · What the records do not cover is not a number
+
+Level: MUST
+Applies to: a period, a comparison or a measure whose records the backend does not keep for all of its days
+Rule: The period control offers only the periods the report's records are kept for; a figure, a cell or a breakdown whose records start after its range says "not kept" and from when, and is never drawn as a number.
+Why: A sum over the days that happen to be kept is a part drawn as a whole: a ninety-day ratio over thirty days of invoices read 84 days of sales outstanding where the book held about 35.
+Do: State once, under the controls, from which day each kind of record is kept; leave a comparison that starts earlier as "kept from", and replace a breakdown that cannot be read with the sentence that says why and which period can.
+Don't: Draw a zero, a dash or a short bar for days the history does not hold, or offer a period the report will answer with nothing.
+Check: Choose the longest period offered: every figure whose records start after its range says "not kept" and from when, and the period control offers no period the records do not cover.
+
+### RE-04 · A change says its base
+
+Level: SHOULD
+Applies to: the change a `stat-card` draws against a comparison period
+Rule: The comparison line names the value compared with and the period it belongs to; an amount and a count move by a percentage, a share by points, a duration in its own unit.
+Why: "+7%" with no base is a number a reader cannot check, and a share that moves from 36% to 37% reads as a 3% rise when it is one point.
+Do: Hand the card the change and write "vs $15.22M, the 30 days before" in its `comparison`, on one line cut with its title; tell the card from the measure which direction is good, so a rise in discounts or in days to ship reads as a fall in quality.
+Don't: Draw a relative change of a share, or a change whose base period the page does not name.
+Check: Read each card with a change: the base value and its period stand on its comparison line, and a share's change ends in "pts".
+
+### RE-05 · An anomaly says its rule
+
+Level: SHOULD
+Applies to: a figure or a bucket a report flags as unusual
+Rule: A value is flagged only by a rule the page states in words, and the flag names the value, the range it fell in, the band it left and opens the records of that range.
+Why: A flag with no rule is an opinion the reader cannot weigh, and a flag that fires on noise teaches the reader to ignore the flags.
+Do: Flag a value outside the mean of its own history plus or minus two standard deviations — the six periods of the same length before it, or the earlier buckets of the period — and keep a count's band no narrower than its chance variation; state a threshold the product sets (OV-04) beside it as a second kind of flag.
+Don't: Flag by a fixed number the screen chose for itself, or by a comparison with a single earlier period.
+Check: Read each flag: the page states its rule in words, the flag names the value, its range and the band it left, and it opens the records of that range.
+
+### RE-06 · A report's filters stand in the header
+
+Level: SHOULD
+Applies to: the period, comparison and segment controls of a report
+Rule: They stand in `page-header`'s `content`, under the header's `toggle` and `pin`; below 600 pixels the area opens collapsed, so the figures lead the screen.
+Why: The header's area is the family's place for filters, and a pinned area keeps the period in sight over a long report; a block in the body scrolls away and, on a phone, filled the first screen before a single figure.
+Do: Write the controls and the one sentence of what the records cover in the `content`, and let the `subheading` say the period on the title row, where it stays when the area collapses.
+Don't: Put the controls as the first block of the body, or keep the area open on a phone.
+Check: At 1280 pixels the controls stand in the header with the pin; at 390 pixels with a coarse pointer the first screen holds the figures and the collapsed area's toggle.
+
+### RE-07 · Every number of a report opens what it counts
+
+Level: SHOULD
+Applies to: a report's figures, the bars and points of its charts, and the cells of its tables
+Rule: Each opens the list of the records it counts, with its condition and its period as the list's own pills and the same total, and a record named by its id is named in the pill by its record's words.
+Why: A breakdown the reader cannot open is a claim, and a pill reading "Account is any of cus_000412" says nothing a reader can check.
+Do: Carry the condition in the address, field by field, and the names of the records it names beside their ids; let the list read them into its bar as it reads any filter (OV-01).
+Don't: Open the unfiltered list, a list whose total differs from the number, or a pill of raw ids.
+Check: Open a figure, a bar and a cell: each list's pills name the condition and the period in words, and its total equals the number opened.
+
+### RE-08 · A ranking draws ten
+
+Level: SHOULD
+Applies to: a `horizontal` `chart` that ranks categories whose number grows with the period or the tenant — accounts, products, representatives
+Rule: The chart draws at most the ten first categories and says so in its title; the table under it holds every row and its summary.
+Why: Forty-four representatives drawn on one plot stacked their names into a column nobody could read.
+Do: Rank in the answer, cut the chart's data at ten and keep the rest — or one "other" row — to the table; place the section whose table holds every row last, since the wait cannot know its length and its growth then moves nothing.
+Don't: Grow the plot with the categories, or cut the table with the chart.
+Check: Choose the longest period: the ranking chart holds at most ten bars and says so in its title, and its table holds every row and the summary.
+
+### RE-09 · A download is the table on screen
+
+Level: SHOULD
+Applies to: the file a report's section offers
+Rule: The download is the section's table as the reader sees it — its columns, its rows and its summary row, in its words — built in the browser from the answer the page drew, for every reader of the report.
+Why: A file built by another read can say other numbers than the screen, and a column the reader may not see on screen would reach them in the file.
+Do: Offer "Download CSV" in the section's actions and write the file from the table's lines; name it by report, section and period.
+Don't: Offer a server export the reader's permissions were not applied to, or a file of raw minor units the table does not show.
+Check: Press Download CSV on a section: the file's rows are the table's rows and its summary, and a withheld column is absent from both.

package/dist/docs/guidelines/shell-composition.md

@@ -0,0 +1,94 @@
+---
+topic: shell composition
+prefix: SC
+triggers:
+  [
+    app-shell,
+    shell,
+    banner,
+    header bar,
+    top-navigation,
+    search,
+    command palette,
+    magnifier,
+    mobile,
+    narrow,
+    overlay,
+    drawer,
+    dialog,
+    layer,
+    host,
+    popover,
+    notification-center,
+    brand,
+  ]
+families: [app-shell, top-navigation, command-palette, popover, drawer, dialog, notification-center]
+---
+
+# Shell composition
+
+How the application frame is put together from `app-shell`, the bar inside its
+banner and the layers the bar opens. Each family states its own anatomy; the
+seams between them — what stands in the search slot, what a component host
+costs in a flex row, how wide a panel is when its content has no width — are
+the consumer's to get right.
+
+### SC-01 · A palette trigger is not a search field
+
+Level: MUST
+Applies to: `top-navigation`'s `search` region when what stands in it opens a `command-palette` rather than filtering in place
+Rule: Below the bar's medium step, the magnifier opens the palette directly; the search region is never expanded over the bar.
+Why: The bar's fold is written for a text field — open the region, move focus to its input. A region holding a trigger button costs the reader a second press and shows a button beside a close control, aligned with nothing.
+Do: Answer the bar's request to open the search by cancelling it and opening the palette. Above the step the region shows the trigger as it always did.
+Don't: Let the region open, or hide the magnifier and leave a narrow bar with no way to the palette.
+Check: At a width under the medium step, one press on the magnifier shows the palette and the bar does not carry the open-search state.
+
+### SC-02 · Layer hosts leave the banner's row
+
+Level: MUST
+Applies to: a consumer component placed inside `app-shell`'s `banner` whose only output is a layer — a palette, a drawer, a dialog
+Rule: A component host inside the banner that draws no box of its own contributes no box to the banner's row.
+Why: The banner is a flex row with a gap; an empty host is still a flex item and costs one gap, which is air on one end of the bar and not the other.
+Do: Give such a host no box — the library's own layer hosts have none — or place the component outside the banner.
+Don't: Leave a consumer host in the row because its content is portalled anyway.
+Check: The bar's first and last controls stand the same distance from the frame's two edges.
+
+### SC-03 · A panel around a query container states its measure
+
+Level: SHOULD
+Applies to: a `popover` whose content is a family that is a container query — `notification-center`, any consumer region with inline-size containment
+Rule: The consumer states the content's inline size, and its block cap, on the content; the popover's measure alone does not size it.
+Why: A query container contributes no intrinsic width, so a panel sized to its content settles at the family's floor whatever the popover's measure says, and a panel with no cap runs to the bottom of the viewport.
+Do: Size the content to the popover's measure less the layer's own gap, bounded by the viewport on a phone, and cap its block size so the family's scrolling part scrolls.
+Don't: Retune the popover's measure and expect a query container to grow into it.
+Check: The panel is as wide as the popover's measure allows and no taller than the stated cap; the feed scrolls inside it.
+
+### SC-04 · The search slot stands one space step off the brand
+
+Level: SHOULD
+Applies to: `top-navigation`'s `search` region when nothing — no context, no destinations — stands between it and `brand`
+Rule: The search region carries one space step of leading margin beyond the bar's own gap.
+Why: The bar's gap is the air between the mark and the wordmark; a bordered field at that distance reads as a third part of the brand.
+Do: Add one space step at the region's start. When the region takes the whole bar below the medium step it has its own inset and the margin does not apply.
+Don't: Widen the bar's gap, which also moves the actions apart.
+Check: The field's left edge stands one space step further from the wordmark than the wordmark stands from the mark.
+
+### SC-05 · A phone's bar holds five controls
+
+Level: SHOULD
+Applies to: what a consumer places in `top-navigation`'s `actions` — `action` controls of the product's own, beside the family's bell, help and account
+Rule: Below the bar's high step the actions hold the search toggle, the bell, the help and the account; a product's own `action` leaves the bar and stays reachable from the navigation column or the palette.
+Why: On a touch screen every control is a 44-pixel target; nine of them with the mark and the shell's toggle are wider than a phone, and the family folds none of a consumer's actions.
+Do: Hide the product's own actions under the bar's own container query at the high step, and keep each one a destination in the column or a command in the palette.
+Don't: Keep every action in the bar and let the cluster overflow, or shrink the controls under the touch target.
+Check: At 390px with a coarse pointer, the bar's first and last controls are whole and no control overlaps another.
+
+### SC-06 · No key legends where there are no keys
+
+Level: SHOULD
+Applies to: a `kbd` or `shortcut` drawn as a hint beside a control — the search trigger's hotkey, a menu item's shortcut, a footer of hints
+Rule: Where the primary input is a touch screen — `(hover: none) and (pointer: coarse)` — a shortcut drawn as a hint is not shown.
+Why: The legend names a key the reader has no way to press; on a phone it is noise beside the control it decorates.
+Do: Hide the hint under the media query. Keep a `kbd` that is content — a settings page listing the application's shortcuts — because it documents rather than hints.
+Don't: Hide the control the hint stands beside, or key the rule on width: a narrow window on a laptop still has a keyboard.
+Check: On a touch screen the search trigger shows the magnifier and the words alone, and the palette's footer is absent.

package/dist/docs/guidelines/workspaces.md

@@ -0,0 +1,46 @@
+---
+topic: workspaces
+prefix: WS
+triggers:
+  [
+    workspace,
+    reconciliation,
+    match,
+    candidate,
+    confidence,
+    score,
+    queue,
+    three columns,
+    dense,
+    phone,
+  ]
+families: [detail-panel, list, list-item, table, filter-bar, scroll-area, tag]
+---
+
+# Workspaces
+
+How a dense screen that works a queue against candidates is composed: what a
+phone keeps of its regions, and how a machine's score is put before a person
+who confirms it. The library gives `detail-panel` a main column and an aside,
+`list` rows that lead somewhere and `table` a summary row; it does not say
+how three regions become one on a phone, or that a score is shown taken apart.
+
+### WS-01 · A phone reads one region at a time
+
+Level: SHOULD
+Applies to: a workspace of three regions — a queue, the record opened from it, and what the record is matched against
+Rule: Below 600 pixels the workspace shows the queue, and opening a row goes to the row's own address, where the record's page holds the other two regions, the third under the second; the back gesture returns to the queue.
+Why: Three columns in 390 pixels are three columns nobody can read, and a region hidden on a phone is work a phone reader cannot finish.
+Do: Make the opened record a place in the address at every width, so the selection is a link and the back gesture walks it back. From 600 pixels keep the queue beside the record and draw the record as a `detail-panel` whose `aside` is the third region, so the family decides whether it stands beside or under. Drop nothing: the phone reaches every region, one at a time.
+Don't: Scroll the workspace sideways, hide the third region on a phone, or keep the selection in the page's state alone.
+Check: At 390 pixels, open a row of the queue: the address changes, the record and the third region stand one under the other with no sideways scroll, and the back gesture returns to the queue.
+
+### WS-02 · A score that decides is taken apart
+
+Level: SHOULD
+Applies to: a score a person confirms or refuses — a match confidence, a risk rating the reader acts on
+Rule: The score is shown as a table of its criteria, each with the points it earned or none of its points, ending in the summary row that adds back up to the score and says where a cap applies, and its band is one mark beside one sentence giving the thresholds.
+Why: A number or a band alone asks the reader to trust the machine, and a confirmation given on trust is the one a person was asked to give.
+Do: Map each criterion the backend reports to its points, draw the ones the candidate did not earn as "0 of N", sum them in the table's `summary` (RP-07), and state the bands once ("high from 85, medium from 60"). Say the difference between the two compared amounts beside the command that confirms.
+Don't: Show the band twice at two weights (CP-06), or put the reasons in a tooltip.
+Check: Read one score: its criteria rows add up to the summary row, the summary equals the score or names its cap, and the band is stated once with its thresholds.

package/dist/docs/index.md

@@ -139,3 +139,15 @@ Each family is documented in `./<family>.md`.
 - splitter: Resizable panes divided by a handle.
 - stack: Column of items with a gap.
 - visually-hidden: Hides content visually, keeps it for readers.
+
+## Tokens
+
+What each theme token is for, with its default value: `./tokens.md`.
+
+## Guidelines
+
+Rules for composing screens from these families: `./guidelines/index.md`. Read it before writing a screen.
+
+## Skills
+
+Procedures for whole tasks, each with when it applies: `./skills/index.md`.

package/dist/docs/progress-indicator.json

@@ -330,7 +330,6 @@
     "--slotted-progress-indicator-wave-phase",
     "--slotted-radius-full",
     "--slotted-radius-none",
-    "--slotted-space-1",
     "--slotted-space-2",
     "--slotted-space-3",
     "--slotted-space-4",
@@ -419,7 +418,7 @@
     {
       "id": "waveSizes",
       "title": "The wave is measured in thicknesses",
-      "note": "One wavelength is ten thicknesses and a crest is three quarters of one at every size, so the small bar’s wave is twenty pixels long and the large bar’s eighty. Every ring carries eight crests, because the wave is wound on the viewBox and the viewBox scales.",
+      "note": "One wavelength is ten thicknesses and a crest is three quarters of one at every size, so the small bar’s wave is forty pixels long and the large bar’s eighty. Every ring carries eight crests, because the wave is wound on the viewBox and the viewBox scales.",
       "language": "tsx",
       "source": "<ProgressBar label=\"Small\" size=\"sm\" value={55} wave />;\n<ProgressBar label=\"Large\" size=\"lg\" value={55} wave />;\n<ProgressCircle label=\"Saving\" size=\"lg\" value={55} wave />;\n",
       "verdict": "excerpt"

package/dist/docs/progress-indicator.md

@@ -82,7 +82,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-strong`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-duration-long`, `--slotted-duration-loop`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-emphasized`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-line-height-md`, `--slotted-progress-indicator-buffer-color`, `--slotted-progress-indicator-buffer-percent`, `--slotted-progress-indicator-gap`, `--slotted-progress-indicator-indicator-color`, `--slotted-progress-indicator-percent`, `--slotted-progress-indicator-position`, `--slotted-progress-indicator-radius`, `--slotted-progress-indicator-size`, `--slotted-progress-indicator-stroke`, `--slotted-progress-indicator-thickness`, `--slotted-progress-indicator-track-color`, `--slotted-progress-indicator-travel-size`, `--slotted-progress-indicator-travel-start`, `--slotted-progress-indicator-wave-amplitude`, `--slotted-progress-indicator-wave-phase`, `--slotted-radius-full`, `--slotted-radius-none`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-surface`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-sticky`
+`--slotted-border-strong`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-height-lg`, `--slotted-control-height-md`, `--slotted-control-height-sm`, `--slotted-duration-long`, `--slotted-duration-loop`, `--slotted-duration-loop-slow`, `--slotted-duration-medium`, `--slotted-duration-short`, `--slotted-easing-emphasized`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-line-height-md`, `--slotted-progress-indicator-buffer-color`, `--slotted-progress-indicator-buffer-percent`, `--slotted-progress-indicator-gap`, `--slotted-progress-indicator-indicator-color`, `--slotted-progress-indicator-percent`, `--slotted-progress-indicator-position`, `--slotted-progress-indicator-radius`, `--slotted-progress-indicator-size`, `--slotted-progress-indicator-stroke`, `--slotted-progress-indicator-thickness`, `--slotted-progress-indicator-track-color`, `--slotted-progress-indicator-travel-size`, `--slotted-progress-indicator-travel-start`, `--slotted-progress-indicator-wave-amplitude`, `--slotted-progress-indicator-wave-phase`, `--slotted-radius-full`, `--slotted-radius-none`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-surface`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`, `--slotted-z-index-sticky`
 
 ## Examples
 
@@ -191,7 +191,7 @@ Excerpt — not a complete module
 
 ### The wave is measured in thicknesses
 
-One wavelength is ten thicknesses and a crest is three quarters of one at every size, so the small bar’s wave is twenty pixels long and the large bar’s eighty. Every ring carries eight crests, because the wave is wound on the viewBox and the viewBox scales.
+One wavelength is ten thicknesses and a crest is three quarters of one at every size, so the small bar’s wave is forty pixels long and the large bar’s eighty. Every ring carries eight crests, because the wave is wound on the viewBox and the viewBox scales.
 
 Excerpt — not a complete module
 

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 `node_modules/@slotted/react/dist/docs/index.md` and list the families whose line is near the
+   element.
+2. Read `node_modules/@slotted/react/dist/docs/<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
+  `node_modules/@slotted/react/dist/docs/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 `node_modules/@slotted/react/dist/docs/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 `node_modules/@slotted/react/dist/docs/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
+   `node_modules/@slotted/react/dist/docs/tokens.md` above "Read by their family only".

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

@@ -0,0 +1,76 @@
+---
+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. 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.
+
+## 2. Read
+
+1. `node_modules/@slotted/react/dist/docs/guidelines/index.md`.
+2. `node_modules/@slotted/react/dist/docs/guidelines/composition.md`, always.
+3. The topic of step 1. 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
+   `node_modules/@slotted/react/dist/docs/skills/build-own-element/SKILL.md`.
+
+## 3. Read each family before writing beside it
+
+For each family the screen uses, read `node_modules/@slotted/react/dist/docs/<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.
+
+## 4. Compose
+
+- The page's width follows its type: a list is `bleed` with `fill`; a record,
+  a dashboard and an overview keep `wide`; a create or edit form is `content`;
+  preferences read as prose are `measure` (CP-07).
+- 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).
+- 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 `node_modules/@slotted/react/dist/docs/skills/build-own-element/SKILL.md`.
+
+## 5. Waits
+
+Every region filled by a request and every control that starts one follow
+`node_modules/@slotted/react/dist/docs/skills/waiting-states/SKILL.md`.
+
+## 6. 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.

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,70 @@
+---
+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 `node_modules/@slotted/react/dist/docs/<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
+   `node_modules/@slotted/react/dist/docs/skills/compose-screen/SKILL.md`.
+
+## 2. Read
+
+1. `node_modules/@slotted/react/dist/docs/guidelines/index.md` and
+   `node_modules/@slotted/react/dist/docs/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. `node_modules/@slotted/react/dist/docs/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                                       | a control that fires twice                               | AF-03        |
+| 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 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 `node_modules/@slotted/react/dist/docs/tokens.md` lists for
+   that decision.
+4. Run the searches of step 3 again on the changed files: none finds anything.