@slotted/angular 0.1.0-beta.1 → 0.1.0-beta.2

package/README.md

@@ -47,6 +47,10 @@ export const appConfig = {
 };
 ```
 
+## Agents
+
+`docs/AGENTS.snippet.md` is the section an application adds to the instructions its coding agent reads: `AGENTS.md`, or `CLAUDE.md` for Claude Code, directly or through `@AGENTS.md`. It points the agent at the family pages, the guidelines and the skills of the installed version.
+
 ## License
 
 MIT

package/docs/AGENTS.snippet.md

@@ -8,3 +8,13 @@ Before writing or changing UI, read `node_modules/@slotted/angular/docs/index.md
 - Change a family's appearance through its inputs (`size`, `variant`, `tone` where it has them), not with CSS that targets its parts.
 - Application CSS uses `var(--slotted-*)` tokens for color, spacing and radius, inside a layer declared after the library's: `@layer slotted, app;`.
 - In CSS and tests, select a family by `[data-ui="<family>"]` and its parts by `[data-part="<part>"]`.
+
+### Tasks
+
+Read the skill before the task:
+
+- Compose or change a screen — a list, a record, a form, an overview: `node_modules/@slotted/angular/docs/skills/compose-screen/SKILL.md`
+- Show what a screen draws while it waits, and its empty and error states: `node_modules/@slotted/angular/docs/skills/waiting-states/SKILL.md`
+- Review a screen against the guidelines, or fix what a review found: `node_modules/@slotted/angular/docs/skills/review-screen/SKILL.md`
+- Write a component or element that no family draws: `node_modules/@slotted/angular/docs/skills/build-own-element/SKILL.md`
+- Change the brand colour, the scheme, the density or a control's shape: `node_modules/@slotted/angular/docs/skills/theme-app/SKILL.md`

package/docs/checkbox.json

@@ -172,6 +172,13 @@
           "appliesTo": "SlCheckbox",
           "description": "Unset rather than false. Writes aria-invalid on the input and data-invalid on the root, which draws a thicker border in the danger tone."
         },
+        {
+          "name": "tabIndex",
+          "type": "number",
+          "defaultValue": "—",
+          "appliesTo": "SlCheckbox",
+          "description": "Written to the input as tabindex. A composite widget that owns the tab sequence, such as a data grid, passes -1 until the box’s cell is current. Unset leaves the native order."
+        },
         {
           "name": "required",
           "type": "boolean",

package/docs/checkbox.md

@@ -62,6 +62,7 @@ export class CheckboxBasic {}
 | `disabled` | `boolean` | from the form control, group or field, or false | SlCheckbox | Unset rather than false, so the box follows a disabled form control, then its checkbox group or field. Written to the input as the native attribute, which removes the box from the tab order and from form submission. |
 | `readOnly` | `boolean` | from the group or field, or false | SlCheckbox | Unset rather than false. A native checkbox has no readonly, so SlCheckbox refuses every change and writes aria-readonly. The box keeps its tab stop, its focus ring and its contrast, and its value is still submitted. |
 | `invalid` | `boolean` | from the group or field, or false | SlCheckbox | Unset rather than false. Writes aria-invalid on the input and data-invalid on the root, which draws a thicker border in the danger tone. |
+| `tabIndex` | `number` | — | SlCheckbox | Written to the input as tabindex. A composite widget that owns the tab sequence, such as a data grid, passes -1 until the box’s cell is current. Unset leaves the native order. |
 | `required` | `boolean` | — | the host element | The native attribute, read once as a static attribute and passed to the input unchanged; SlCheckbox never writes it. A field marks necessity with aria-required instead, because the native attribute turns on browser constraint validation. |
 | `name / value` | `string` | — / on | SlCheckbox | The native submission pair: a checked box submits value under name. Inside a checkbox group, a box without a name takes the group’s, and value is the entry the group’s selection holds. |
 | `exportAs="slCheckbox"` | `SlCheckbox` | — | a template | Reaches the component instance. Its inputElement is the input, whose own focus() and click() methods move focus and toggle the box. |

package/docs/event-calendar.json

@@ -559,6 +559,13 @@
           "appliesTo": "slEventCalendar",
           "description": "Read once; pass it when rendering on a server"
         },
+        {
+          "name": "now",
+          "type": "PlainDateTime",
+          "defaultValue": "the clock in timeZone, ticked each minute",
+          "appliesTo": "slEventCalendar",
+          "description": "Present means the consumer owns it: the clock is no longer read, and today and the now line follow it. A page dated by its content passes it."
+        },
         {
           "name": "view",
           "type": "model<EventCalendarView | undefined>",

package/docs/event-calendar.md

@@ -112,6 +112,7 @@ Excerpt — not a complete module
 | `calendars` | `readonly EventCalendarCalendar[]` | [] | slEventCalendar | Key, label and an optional colour slot 1–8 |
 | `date` | `model<PlainDate \| undefined>` | — | slEventCalendar | The day the calendar is on; [(date)] two-way |
 | `defaultDate` | `PlainDate` | today in timeZone | slEventCalendar | Read once; pass it when rendering on a server |
+| `now` | `PlainDateTime` | the clock in timeZone, ticked each minute | slEventCalendar | Present means the consumer owns it: the clock is no longer read, and today and the now line follow it. A page dated by its content passes it. |
 | `view` | `model<EventCalendarView \| undefined>` | month | slEventCalendar | [(view)] two-way; unbound opens on the first of views |
 | `defaultView` | `EventCalendarView` | views[0] | slEventCalendar | Read once |
 | `views` | `readonly EventCalendarView[]` | month,week,day,list | slEventCalendar | The switcher, in order |

package/docs/guidelines/README.md

@@ -0,0 +1,27 @@
+# Guidelines
+
+Rules for composing screens from the Slotted families: what the reference
+pages do not state. A family's page states what it is — its parts, states,
+tokens and keyboard. It does not state where a pager stands, what a region
+shows before its first answer, or which family a bar's search slot is for.
+
+## Reading protocol
+
+For a reader with a task — a person or a model about to write or review a
+screen:
+
+1. Read `index.md`: every active rule in one line, with its level and its file.
+2. Match the task against the `triggers` in each topic file's front matter.
+   Read the topic files that match, and `composition.md` always.
+3. Before writing an element beside a family, read that family's page in
+   `node_modules/@slotted/angular/docs`. Before writing an element no family draws, read
+   `own-elements.md` and `node_modules/@slotted/angular/docs/tokens.md`.
+4. Apply the rules by level: a `MUST` broken is a defect, a `SHOULD` broken is
+   stated with its reason, a `MAY` is a permission.
+5. A screen is done when each `Check` of the rules read passes.
+
+## Rule identity
+
+An id (`AF-03`) never changes meaning. A rule whose meaning or level changes
+is retired, keeps its heading with `Status: retired`, and is rewritten under a
+new id. The release notes of each version list the ids added and retired.

package/docs/guidelines/async-feedback.md

@@ -0,0 +1,108 @@
+---
+topic: async feedback
+prefix: AF
+triggers:
+  [
+    loading,
+    pending,
+    busy,
+    empty,
+    skeleton,
+    placeholder,
+    request,
+    fetch,
+    mutation,
+    tab,
+    view,
+    page,
+    pagination,
+    popover,
+    refresh,
+    latency,
+    spinner,
+    submit,
+    action,
+  ]
+families:
+  [skeleton, button, popover, list, list-item, notification-center, tabs, pagination, result-state]
+---
+
+# Async feedback
+
+What a screen shows between a request starting and its answer arriving. The
+library gives the states — `skeleton` for a region, `loading` on a control,
+`data-loading` and `aria-busy` on the families that fill themselves — and does
+not say which one a screen owes at which moment. A request answers within a
+second on a fast network and takes several on a slow one; a screen that shows
+nothing for that long reads as a stall, and a screen that shows its empty
+state reads as an answer.
+
+### AF-01 · Pending is not empty
+
+Level: MUST
+Applies to: any region filled by a request — a `popover` body, a `list`, a `data-grid`, a `notification-center` feed, a page section
+Rule: A region whose first answer has not arrived shows its pending state; the empty state appears only after an answer holding zero items.
+Why: An empty state is a statement about the data, and before the answer there is no data to state anything about.
+Do: Keep a loading fact beside the items, set before the request and cleared after it. Render placeholders while the fact is true and the items are none; render the empty state while the fact is false and the items are none.
+Don't: Branch on the items alone. A region that opens on "Nothing waiting for you" while the request is in flight tells the reader the queue is clear, for as long as the request takes.
+Check: Throttle the network to a slow profile and open the region cold; the empty words do not appear before the answer.
+
+### AF-02 · First answer draws placeholders, later answers keep the rows
+
+Level: SHOULD
+Applies to: every region under AF-01 that is filled more than once — a panel opened again, a list read back after a mutation
+Rule: A region with no items yet draws placeholders; a region that already shows items keeps them on screen and marks itself busy while a newer answer is on its way.
+Why: Placeholders in place of rows the reader was looking at erase their place; rows silently replaced give no sign anything happened.
+Do: Placeholders are the family `skeleton`: a region carrying the state and, inside it, the rows' own boxes — the mark, the label line, the description line — so the answer lands without a layout shift. A placeholder line is a fraction of its row, never a length: a length wider than a phone's row overflows the page and scrolls it sideways. While items are shown and a request runs, the list carries `aria-busy` and the rows stay.
+Don't: Draw placeholders on every request, or clear the items before every request. Reading a list back after marking one row is a refresh, not a first load.
+Check: Open the region twice with the network throttled to a slow profile: placeholders on the first open, the previous rows and no placeholders on the second.
+
+### AF-03 · The control that starts a request waits on it
+
+Level: MUST
+Applies to: any `button` member — button, icon button, toggle button — whose activation runs a request — mark as read, archive, approve, save, submit
+Rule: From activation until the answer, the control is in its `loading` state: it refuses a second activation and shows the family's indicator.
+Why: A control that looks idle invites a second press, and the second request is a duplicate the backend has to refuse or the reader has to undo.
+Do: Keep, beside the data, the identity of what is in flight — the row's key for a row action, one fact for a list-wide action — and bind the control's `loading` to it. The family refuses activation on its own and names the wait for assistive technology through its loading label.
+Don't: Disable the control by hand, hide it, or leave it as it was until the row disappears. Disabled says "not allowed"; loading says "working on it".
+Check: Press the control with the network throttled to a slow profile: the indicator appears, a second press does nothing, the row changes once.
+
+### AF-04 · A change of view or page draws placeholders
+
+Level: SHOULD
+Applies to: `tabs` that switch the content of a region, `pagination`, any filter whose answer replaces the rows rather than refreshing them
+Rule: When the reader asks for different rows, the rows on screen are removed and placeholders stand in their place until the answer arrives.
+Why: The rows on screen are the previous answer; leaving them under the new tab says the tab did nothing until, half a second later, it does.
+Do: Empty the items on the change and let AF-01 draw the placeholders. Keep what does not change — the tab strip, the pager, the header — where it is.
+Don't: Keep the old rows until the new ones arrive, or replace the whole region including the tab strip with a placeholder block.
+Check: Switch the view with the network throttled to a slow profile: placeholders at once, the tab strip and the pager still in place, rows on the answer.
+
+### AF-05 · An indicator may wait for the request to be slow
+
+Level: MAY
+Applies to: a control under AF-03 whose request usually answers under the indicator's own entrance
+Rule: A control's indicator may be delayed by the family's loading delay, so a request that answers first shows no indicator; a region's placeholders are never delayed.
+Why: An indicator that appears and leaves within one frame is a flicker, and a region with nothing in it is a stall from the first frame.
+Do: Use the family's delay on a control whose request is short in the normal case and leave the control refusing activation from the first instant, which the family does regardless of the delay.
+Don't: Delay a region's placeholders, or delay a control's refusal of activation.
+Check: On an unthrottled network a short request shows no indicator and still ignores a second press; with the network throttled to a slow profile, the indicator appears.
+
+### AF-06 · Placeholders are held once they are drawn
+
+Level: SHOULD
+Applies to: every region under AF-01, through the application's own defaults for the family
+Rule: The application states one minimum duration for the whole product: once placeholders are painted they stay for it, even when the answer has already arrived.
+Why: A request on a fast network answers within a few hundred milliseconds, so an undelayed region paints and is replaced inside a few frames — a blink the reader reads as a fault rather than as a wait.
+Do: State the minimum where the application states its other family defaults, and leave the delay at nothing: AF-05 keeps a region's placeholders undelayed, and the minimum is the other half of the same decision.
+Don't: Set the minimum per screen, or reach for a delay to stop the blink — a delay is a region showing nothing for as long as it lasts.
+Check: On an unthrottled network, open a screen of placeholders twice: the placeholders are visible on both, and no region paints and empties within one frame.
+
+### AF-07 · A record another actor changes offers Refresh
+
+Level: SHOULD
+Applies to: a record page, or a list, whose data another person or process can change while it is open — an order, an invoice, a customer another writer edits
+Rule: The page offers Refresh among the header's actions, and a refresh keeps the values on screen, marks the page busy and replaces them when the answer arrives.
+Why: Without it the reader reloads the browser, which loses the scroll, the open tab and any draft, and a refresh that blanks the record flickers what was already read.
+Do: Put an icon button named "Refresh" in the header's actions toolbar with its menu counterpart, in its `loading` state until the answer (AF-03); bind the page's `loading` to "reading again while a record is shown", so the body takes `aria-busy` and draws no placeholder.
+Don't: Offer Refresh on a record nothing else writes, or clear the record and draw its skeleton on every read after the first.
+Check: Press Refresh on a record another writer changes: the values stay, the page body is busy until the answer, and the button waits on it.

package/docs/guidelines/browsing.md

@@ -0,0 +1,74 @@
+---
+topic: browsing
+prefix: BR
+triggers:
+  [
+    tree,
+    category,
+    categories,
+    hierarchy,
+    branch,
+    leaf,
+    taxonomy,
+    browse,
+    facet,
+    drill,
+    place,
+    scope,
+    breadcrumb,
+    count,
+    grain,
+    catalogue,
+  ]
+families: [tree, breadcrumb, page-header, filter-bar, data-grid]
+---
+
+# Browsing
+
+How a reader moves through a set that is arranged rather than listed: a tree
+of categories over a list of records, and one concept a backend answers for at
+two grains. The library gives `tree` a hierarchy with a keyboard and a query,
+`breadcrumb` a trail and `filter-bar` a tree of conditions; it does not say
+whether a branch is a filter or a place, which of a node's two counts a row
+draws, or how a list that reads products and a list that reads stock lead to
+each other.
+
+### BR-01 · A branch is the list's place, not one of its pills
+
+Level: SHOULD
+Applies to: a list reached by choosing a node in a `tree`, and the `filter-bar` above that list
+Rule: The branch a reader chose is the list's heading and its `breadcrumb`; the filter bar keeps the facets and holds no pill for it.
+Why: A place is where the reader is and a facet is what they asked for; a branch drawn as a pill reads as one condition among many, and the way back out of it becomes a chip to delete rather than a trail to walk.
+Do: Name the list after the branch, put the trail from the catalogue's root in the header's breadcrumb with every ancestor a link, and narrow the query from the place rather than from the bar. The way out is the trail's first crumb, which names the whole set.
+Don't: Write the branch into the bar's tree, or leave the list titled after the resource while its rows come from one branch.
+Check: Open a branch from the tree: the heading is the branch's name, the trail stands above it, and the bar's pill count is unchanged.
+
+### BR-02 · A place holds what is under it, and says how much of it there is
+
+Level: MUST
+Applies to: a list narrowed to a branch of a hierarchy
+Rule: The query covers the branch and every node beneath it, and the page states how many nodes that is beside how many records they hold.
+Why: A backend that files a record on a leaf answers nothing for the branch above it; a list that asked for the branch alone would tell a reader a whole department is empty, and a list that asks for the subtree without saying so leaves a count nobody can reconcile with the tree.
+Do: Read the hierarchy before the rows, send the branch and its descendants as one condition, and write the sentence under the title: how many records the place holds, how many nodes it covers, and how many the whole set holds.
+Don't: Narrow to the chosen node alone, or state a count without saying what it is counted over.
+Check: Open a branch whose own records are none: the list is not empty and the sentence names the nodes it covers.
+
+### BR-03 · A node's own count and its branch's count are two numbers
+
+Level: MUST
+Applies to: a count drawn on a `tree` node
+Rule: The number on a row is one of the two and the screen says which; where a node holds records of its own and has nodes under it, the second number is said apart from the first.
+Why: The two answer different questions — how big this branch is, and how much is filed at this level — and a tree that prints one of them without saying which is read as the other.
+Do: Put the branch's whole count in the row's trailing cell, the one the family keeps at its intrinsic width, and say in the region's own words what that number counts. Where a node also holds records directly, say how many on the row's second line, which the family already draws in the muted step.
+Don't: Draw the backend's own field without adding the descendants, or print two bare numbers on one row.
+Check: A branch whose records are all on its leaves shows the leaves' total, not nought.
+
+### BR-04 · One concept at two grains is two lists that name each other
+
+Level: SHOULD
+Applies to: a resource the backend answers for at two grains — a family header and the item that is counted, ordered and priced
+Rule: Each grain is its own route with its own columns and its own filters, and each page names the other above its rows.
+Why: The two grains are asked different questions and filtered by different fields; one bar cannot hold both sets of conditions, and a reader looking for what is below its reorder point is not looking for a family header.
+Do: Give each list the filters its own resource offers, say in one sentence what the grain is and what the other one is for, and carry the reader's place from one to the other so a branch survives the move.
+Don't: Put a view switch over one filter bar whose fields belong to one of the two, or leave the second grain reachable only through a record of the first.
+Check: The two routes are in the navigation, each header links to the other, and a place chosen on one is still the place on the other.

package/docs/guidelines/builders.md

@@ -0,0 +1,97 @@
+---
+topic: builders
+prefix: BD
+triggers:
+  [
+    builder,
+    rule,
+    rule builder,
+    condition,
+    condition tree,
+    nested group,
+    workflow,
+    automation,
+    designer,
+    definition,
+    and,
+    or,
+    drag,
+    reorder,
+    move,
+    limit,
+    depth,
+    flow,
+    trace,
+    run history,
+  ]
+families: [segmented-control, select, multi-select, menu, inline-message, typography]
+---
+
+# Builders
+
+How a screen lets a person write a rule the system runs later — a trigger, a
+tree of conditions, the actions — and how that rule is read by someone who
+cannot change it. The library gives `filter-bar` a builder for a filter
+applied to a list, `menu` a place for a node's commands and the field families
+an operand; it does not say how a stored rule reads aloud, where a limit the
+backend enforces is said, or how a tree narrows to a phone.
+
+### BD-01 · A definition reads as a rule before a form
+
+Level: SHOULD
+Applies to: a stored rule — a workflow's trigger, conditions and actions — on its record
+Rule: The record shows the rule as it reads — When, If, Then, Otherwise — every later line of the condition tree led by its join in words and every nested group opened by its own ("any of:", "all of:"); the editor opens from that reading in the section it is read in; a reader without the permission to edit reads the rule and is not shown an editor.
+Why: A rule shown only as a form makes a reader who cannot edit it decode disabled controls, and makes one who can open an editor to learn what the rule does.
+Do: Set the trigger beside "When", the conditions the way a query is set — the join in a column of its own at the start of each later line, a group's children stepped in one step under the line that opens it, a guide down every level — and the actions numbered under "Then". The editor is a query parameter of the record (FM-12) and stands in the same section (FM-07).
+Don't: Draw the editor in a read-only state for a reader, or join the conditions by colour, a border or indentation alone.
+Check: Open a stored rule as a reader who may edit it and as one who may not: both read When, If, Then, Otherwise with every later line led by its join in words, and only the first is offered the editor.
+
+### BD-02 · A structural limit is said before it is reached
+
+Level: SHOULD
+Applies to: a builder whose backend limits the tree — conditions per rule, levels of nesting
+Rule: Under the tree the builder states what it holds and what remains of each limit, and a control that would cross a limit is disabled with the limit as its stated reason.
+Why: A limit met only as a refusal after the save is a tree written past what the backend accepts, and a control that silently does nothing at the limit reads as a broken control.
+Do: Write one line under the root: the conditions and levels used of their maxima, and how many more of each can be added. At a limit, the add control in the group's foot is disabled and the same item in the group's `menu` carries the limit in its `description`.
+Don't: Let the add control stay live at the limit and answer with the backend's refusal.
+Check: Fill a tree to one of its limits: the line under the tree says nothing remains of it, and each control that would cross it is disabled with the limit as its reason.
+
+### BD-03 · A refusal that names no node is marked at the node before the request
+
+Level: MUST
+Applies to: a tree the backend validates and refuses under one field, with no path to the node
+Rule: The builder runs the backend's own check on every change and, once a save is tried, marks each node it would refuse with its message before any request is sent; a group with nothing in it is marked from the moment it is empty.
+Why: After the request the screen knows only that the conditions were refused, not which of fifty; before it, the same check knows the node.
+Do: Run the backend's validation code in the browser rather than writing a second one, key its issues by the node's path, outline the node and put the message under it, and keep the form's summary for the same messages (FM-03).
+Don't: Send the tree and translate the backend's list of messages back onto nodes, or mark every node as invalid while the reader is still writing.
+Check: Save a tree that holds an empty group and a node past a limit: each is marked at its node with its message, and the network log holds no request.
+
+### BD-04 · The keyboard and the pointer make the same moves
+
+Level: SHOULD
+Applies to: moving the nodes of a tree — up, down, into the group above, out of the group
+Rule: Every node's menu carries its moves and its removal, the grip's drag makes the same moves, and both refuse the same places — a group into itself, a level past the limit — with the reason said.
+Why: A drag with no menu shuts out the keyboard and a phone's scrolling finger, and two code paths with two sets of boundaries let one of them build a tree the other refuses.
+Do: Compute every move from one function over the tree and its limits; disable a menu move that would be refused, with the reason as the item's `description`; outline the place a drag is over when it is refused and announce the reason politely; keep the focus on the moved node's menu after a keyboard move.
+Don't: Offer dragging alone, or let the drop answer with a backend refusal.
+Check: Move one node with the keyboard from its menu and the same node by its grip: both reach the same places, both refuse a group dropped into itself with the reason said, and after the keyboard move the focus is on the node's menu.
+
+### BD-05 · A tree narrows by stepping in, never by scrolling
+
+Level: SHOULD
+Applies to: a nested builder below the width its rows' three controls need, at 570 pixels and on a phone
+Rule: Each level steps in by one space step behind a rule, and below the width a condition's field, operator and value fit on one line the field takes its own line and the operator and the value share the next; the tree never scrolls sideways.
+Why: A tree five levels deep that indents by a column, or keeps three controls on one line, is wider than a phone, and a builder that scrolls sideways hides the join of the level the reader is in.
+Do: Make the builder a container and switch the row's grid on its own width (OE-09), keep the grip and the node's menu at the row's two ends with the words between them wrapping, and leave the operator's popup to the family, which keeps it inside the viewport.
+Don't: Indent by more than one space step per level, or give the tree a horizontal scroller.
+Check: At 390 and 360 pixels open a tree five levels deep: nothing scrolls sideways, each level steps in by one space step, and a condition's field stands on its own line.
+
+### BD-06 · A rule's record shows what flowed through it, and the rule carries its own figures
+
+Level: SHOULD
+Applies to: a stored rule's record, its run history and its editor — a trigger, a decision over a condition tree, the actions in order
+Rule: The record opens on how the rule runs — every event of a stated period split where the conditions decide, the events let through split again by how their run ended, each band as thick as the events in it, the three totals over its columns — and then the rule itself, with each step's own figure at the end of its line. A run opens on the same rule as its trace, the rail lit as far as the run went; the editor, where the container has room, sets the draft the same way beside the form.
+Why: Read as text, the rule says what it does and not how often; read as rows, the history says what happened and not where in the rule. The split by volume answers the first question a reader of a rule brings — how much of what arrives does it act on — in one look, and the figure at the end of each line answers where.
+Do: Draw the split as an element of the screen's own (OE-01) from the measured width, with the figures in words over it. Set the rule as a sheet of four lines — When, If, Then, Otherwise — down a rail, the figures in an end column aligned across the lines, and no card, tile or badge around a step. Narrow, stand each label over its step and the end column under it.
+Don't: Build the flow from stat cards, tiles and tags; give a figure only by a band's thickness or a tone; keep a second rendering of the rule for the trace and the preview.
+Check: Open a rule's record: the split of its period's events comes before the rule with its totals in words, each line of the rule ends in its own figure, a run opens on the same rule lit as far as it went, and at 390 pixels nothing scrolls sideways.

package/docs/guidelines/composition.md

@@ -0,0 +1,129 @@
+---
+topic: composition
+prefix: CP
+triggers:
+  [
+    slot,
+    part,
+    anatomy,
+    where,
+    place,
+    compose,
+    wrap,
+    body,
+    header,
+    inside,
+    beside,
+    own element,
+    custom,
+    creative,
+    bespoke,
+    no family,
+    token,
+    literal,
+    hard-coded,
+  ]
+families:
+  [
+    page-header,
+    app-shell,
+    top-navigation,
+    popover,
+    drawer,
+    dialog,
+    tabs,
+    toolbar,
+    inline,
+    stack,
+    grid,
+    typography,
+  ]
+---
+
+# Composition
+
+Where a consumer's element goes in relation to a family: in a slot the family
+names, or beside the family as a block of the consumer's own. Every family
+publishes its anatomy — the parts it draws and the slots it leaves for the
+consumer — and a screen that improvises a block where a slot exists loses what
+the slot carries: a position, a sticky edge, a fold, a keyboard order.
+
+### CP-01 · A slot the family names before a block of your own
+
+Level: MUST
+Applies to: any element a page places inside or beside a family — a tab strip, a toolbar, a search field, a workspace row, a footer link
+Rule: Before writing an element next to a family, the family's anatomy is read; when it names a slot for that element, the element stands in the slot.
+Why: The slot is where the family's promises hold — the header's tabs stay pinned, the bar's search folds, the column's header takes the row inset; a block written beside the family carries none of them and reads as a defect of the family.
+Do: Open the reference page's anatomy table and match the element to a part described as "the slot a … sits in". Compose with the family's own members; wrap a family's part in a component of the page's own only when the host has no box.
+Don't: Place a family's content as the first block of a body, a sibling of the family or a child of the wrong part because the markup is shorter that way.
+Check: For every element of the page's own inside a family's root, the family's anatomy names the part it stands in; every "slot a … sits in" the page needs is used rather than imitated.
+
+### CP-02 · Siblings of the page's own stand in a layout family
+
+Level: MUST
+Applies to: two or more elements a page writes beside each other with no family between them — a name and a badge, a run of tags, the lines of an address, a figure and its caption
+Rule: Sibling elements of the page's own stand in `inline` (one row) or `stack` (one column) with a gap from the space scale, and text of the page's own takes its size from the typography family; bare inline siblings and bare text are not written.
+Why: Two inline elements with nothing between them touch, and a badge beside a word sits on the text baseline rather than the row's centre; bare text takes the document's 16-pixel body size inside a region whose families set 13.
+Do: Wrap the run in `inline` (centre-aligned by default, a two-step gap for marks beside a word) and each line of a block in `stack`; give every span of the page's own the typography family's `size`. The families' own parts — a list item's label, a cell's value, a description — already carry their size and gap and need none of this.
+Don't: Write a name and a `badge` run together as text in a cell, a `description-list` value holding three tags with nothing between them, or address lines as plain spans.
+Check: Every element of the page's own that has a sibling is a child of `inline` or `stack`; no bare span inside a family's part carries the body size.
+
+### CP-03 · A track that holds a family states a zero minimum
+
+Level: MUST
+Applies to: a `grid` or a flex line of the page's own holding a family that scrolls its own content — `table`, `data-grid`, `scroll-area`
+Rule: The track the family stands in is written with a zero minimum (`minmax(0, 1fr)`, or `min-inline-size: 0` on a flex child), so the family's scroller is what scrolls.
+Why: A track is `auto` by default and a grid item's minimum is its content, so a table wider than the page stretches the track and pushes every sibling — the figures, the header — out of the frame, instead of scrolling inside the scroller the family already draws.
+Do: State the single column as `minmax(0, 1fr)` on the region that holds the listing, and let the family's `scroll` part take the overflow.
+Don't: Rely on the family to constrain itself: it cannot measure a parent that grows with it.
+Check: At 1280 with the widest tab open, the page's scroll width equals the viewport and the family's own scroller is the only thing wider than its box.
+
+### CP-04 · Where no family answers the problem, the screen composes its own
+
+Level: MAY
+Applies to: a problem no published family covers — two versions of one value side by side, a step of a lifecycle drawn on a row, a figure with its own shape, a summary that is neither a list nor a table
+Rule: When the families' anatomies have been read and none of them answers the problem, the screen writes an element of its own rather than bending a family into a shape it does not have.
+Why: A family used against its anatomy reads as a defect of the library — a `list-item` made to hold a chart, a `badge` made to hold a sentence — and the screen still does not answer the problem; a screen that draws only what a family draws cannot answer anything the library has not met yet.
+Do: Read the anatomies first, and name the one that came closest and what it does not carry (CP-01 is the earlier question, not a veto). Then compose: the layout families for the arrangement (`inline`, `stack`, `grid`), the families that do fit for the parts they own, the typography family for every word, and the theme's tokens for every value the element paints (CP-05). The element takes one of three shapes, and each is legitimate — a block in the screen's template, a component of the screen's own named after what it shows, or a component the module's screens share — and it carries the state attributes the vocabulary already has, so it reads as part of the system. A screen whose problem is dense is expected to reach this rule: a flagship screen composed only of untouched families is usually a screen that gave up on its problem. Add a ledger row when a family would plausibly have covered the case: that row is what grows the library.
+Don't: Reach for the nearest family and override its stylesheet; copy a family's parts into markup of your own; or leave the problem half-answered because no family draws it.
+Check: For every element of the page's own, the family that came closest is named in a comment or a ledger row, and what it does not carry is named as a **part of its anatomy** — not as an impression of its examples. A claim that a family "does not do this" which its anatomy table contradicts is the defect; the approval chain was written by hand beside `timeline`, whose `rail`, `marker` and `connector` are exactly that shape, and the hand-drawn thread broke on the first step that carried a comment.
+
+### CP-05 · An element of the page's own is built from the theme's tokens
+
+Level: MUST
+Applies to: any CSS a screen writes for an element of its own, under CP-04 or beside a family
+Rule: Every value the element paints comes from the theme — space, type, ink, border, radius, elevation and motion — where the theme has a token for it; a literal is written only beside a comment that says what decided it and why no token covers it.
+Why: A literal is what makes a screen look adjacent to the product rather than part of it: it ignores the scheme switch, the three densities and the theme's own retuning, and it is the first thing that drifts when the theme moves.
+Do: Read `--slotted-space-*` for every gap and inset, `--slotted-text-*` and `--slotted-surface-*` for ink and ground, the typography family's `size` for every word, and the published measures of the family the element stands in — `--slotted-app-shell-row-inset` inside the navigation column, the control heights beside a control. Some values have no token and never will: a measure a column is capped at, a container query's step, an optical nudge of a pixel, the geometry of a shape the screen draws. Write those, in rem where the value scales with the type and in pixels where it does not, and put the reason beside them — the check reads that comment and passes. The escape is for a value the theme does not hold, not for a value it does.
+Don't: Write a hex colour, a font size or a gap the theme already holds a token for, and do not read another family's private custom property. A literal with no reason beside it is the defect this rule is about; a reasoned one is a decision the next reader can weigh.
+Check: Read every stylesheet of the screen, skipping media and container queries, hairlines and any line whose comment gives its reason: no colour, type size or gap remains that a theme token covers.
+
+### CP-06 · A state the family already draws is not drawn again
+
+Level: SHOULD
+Applies to: the axes a screen passes to a family — `variant`, `tone`, `size`, `current`, `complete` — and any mark a screen adds beside a part the family fills
+Rule: A screen states a state once. Where the family has a state for it, the screen sets that state and adds nothing louder beside it.
+Why: The second statement is never the same size as the first: `current` on a `timeline` item draws a target, and the `solid` `variant` over it adds a halo two rules wide that crowds the title; a `badge` beside a description that already says "Waiting on this role" says it twice at two weights.
+Do: Set the state the family names, read what it draws, and stop. Where an axis is passed as well, the screen can say what that axis adds which the state does not already carry.
+Don't: Reach for the loudest variant to make a state visible, or add a mark beside a part that already carries the words.
+Check: For every axis a screen passes to a family, the screen can name what it adds beyond the family's own state.
+
+### CP-07 · A page's width is its type's
+
+Level: SHOULD
+Applies to: every `page`
+Rule: A list page is `bleed` with `fill`; a record, a dashboard and an overview keep the default `wide`; a create or edit form is `content`; a page of preferences read as prose is `measure`.
+Why: The page's width is the one measure its header and its body share, and a form capped in its own stylesheet ran its body to 736 pixels under a header of 1280, so the two end edges did not meet.
+Do: Set the width on the page and nowhere else; a form with a table of lines keeps `content` and lets the table's columns truncate.
+Don't: Cap a form's body with a width of the screen's own, or leave a form at `wide` so its fields run the length of a monitor.
+Check: On every form the header's end edge and the body's end edge are the same line.
+
+### CP-08 · A control that changes mode keeps every box where it was
+
+Level: MUST
+Applies to: a segmented control, a tab or a toggle that switches what one region holds — a reply or an internal note, one view or another — and the text beside it
+Rule: Switching the mode changes the words and the values in the region, never the size, the line count or the position of any box in it or around it; text whose length differs between modes stands on one line, cut with an ellipsis and read whole from its title.
+Why: The line beside Reply and Internal note was longer in one mode and wrapped under the control at narrow widths, so every switch moved the composer and the conversation above it under the reader's eyes and pointer.
+Do: Give the varying text `flex: 1 1 0`, `min-inline-size: 0` and a one-line cut, write the two texts to similar lengths, and keep a control's label set fixed across modes.
+Don't: Let a mode add or remove a line, a hint or a control that changes the region's height, or let a row wrap differently in one mode than in the other.
+Check: At 1280, 570 and 390 pixels, switch the mode and read the bounding box of each box in the region: every top and height is the same in both modes.

package/docs/guidelines/conversations.md

@@ -0,0 +1,59 @@
+---
+topic: conversations
+prefix: CV
+triggers:
+  [
+    conversation,
+    thread,
+    message,
+    reply,
+    composer,
+    internal note,
+    ticket,
+    inbox,
+    sla,
+    clock,
+    business hours,
+    queue,
+  ]
+families: [message, message-scroller, prompt-composer, filter-bar, tabs, page-header]
+---
+
+# Conversations
+
+How a record that is a conversation with a clock is read and answered: a
+support ticket, and anything else whose body is messages. The library gives
+`message` a thread row, `message-scroller` a log that follows new rows and
+`prompt-composer` a field that sends; it does not say where the composer
+stands when the thread is long, how a service-level clock is said, or how an
+inbox's queues and its filters stay one thing.
+
+### CV-01 · The composer stays in reach of a scrolled conversation
+
+Level: MUST
+Applies to: a record whose body is a conversation the reader answers
+Rule: From 600 pixels the conversation fills its region and scrolls on its own with the composer under it, and the record's context scrolls on its own beside it or behind a tab of the header; below 600 pixels the page scrolls, the composer is stuck to the bottom of the screen, and the record opens on its last message.
+Why: A thread of 120 messages scrolled with the page put the composer 120 messages away from the line it answers, and a context that scrolled with the thread left the customer and the clocks behind.
+Do: Give the thread a `message-scroller` that opens at its `end`, keep the composer in the row under it, and draw the context as its own scrolling column; on a phone, make the composer's row sticky on the page's ground.
+Don't: Put the composer at the end of the page's flow, or let the context scroll away with the thread.
+Check: Open a conversation of more than one screen of messages at 1280 and at 390 pixels: it opens on its last message, and the composer is on screen without a scroll at both widths.
+
+### CV-02 · A service-level clock is said in business time, with the hour it falls due
+
+Level: SHOULD
+Applies to: a clock counted in business hours — a first response, a resolution
+Rule: A running clock says the business time left and the hour it falls due in the organization's zone, a passed one by how much and when it was due, a paused one that it is stopped and why; a queue's row says the span alone, and no clock is ever said in raw minutes.
+Why: "1 h 20 min left" read at 19:00 is tomorrow morning: the span alone hides that the time outside business hours does not count, and the hour alone hides how much work time is left.
+Do: Take the remaining minutes from the backend, say them in minutes, hours and business days of the organization's own length, and add the due hour; state the policy once beside the clocks, with the business hours.
+Don't: Recompute a clock in the client, or let a colour alone say that a clock is at risk or passed.
+Check: Read a running, a passed and a paused clock: the first names its due hour, the second how much it passed by, the third that it is stopped and why; none is a count of minutes above 59.
+
+### CV-03 · A queue is a view of the bar, never a second filter
+
+Level: SHOULD
+Applies to: a list worked as named queues — mine, unassigned, at risk, escalated
+Rule: Each queue is a view of the list's `filter-bar`, a tree of the bar's own fields, labelled with the count of the rows it opens on; choosing it writes its pills, and editing a pill leaves a view the bar marks as changed.
+Why: A queue picker beside the bar's pills is two answers to "what am I looking at", and they disagree the moment the reader edits a pill.
+Do: Hand the queues to the bar as its `preset` views, count each with the list's own total for its tree, and let a door open a queue by naming it in the address.
+Don't: Keep the chosen queue in a state of its own, or count a queue with a figure the list does not reproduce.
+Check: Choose each queue: the bar shows its pills and the list's total equals the queue's count; remove one pill: the bar marks the view as changed.