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

package/dist/docs/guidelines/record-pages.md

@@ -0,0 +1,178 @@
+---
+topic: record pages
+prefix: RP
+triggers:
+  [
+    record,
+    detail,
+    360,
+    customer detail,
+    entity page,
+    header,
+    marks,
+    subheading,
+    back,
+    tabs,
+    sections,
+    facts,
+    stat card,
+    related,
+    notes,
+    activity,
+    timeline,
+    archive,
+    hold,
+  ]
+families:
+  [
+    page,
+    page-header,
+    tabs,
+    stat-card,
+    grid,
+    table,
+    description-list,
+    timeline,
+    toolbar,
+    result-state,
+  ]
+---
+
+# Record pages
+
+How the page of one record is composed: what the header says about it, where
+its facts stand, how its related records are sectioned and what happens when
+the record is missing. The library gives `page-header` a title row with a
+visual, marks and a subheading, `tabs` a slot under it, `stat-card` a figure
+and `table` a listing; it does not say which fact is a mark and which a
+figure, or that the figures stand on every section.
+
+### RP-01 · The title row names, states and places the record
+
+Level: SHOULD
+Applies to: `page-header` of a record opened from a list
+Rule: The title row holds the record's visual, its name as the heading, its lifecycle state and its health as two `tag` marks at the small size, and one subheading line with the identifier, the owner and the place; the way back to the list is the header's `back` part.
+Why: A reader arriving from a list or a search asks three things first — which record, in what state, whose — and a title that answers them needs no second glance at the body.
+Do: Every mark is a `tag` at the small size — the state the reader can change (active, on hold) and the health the system computes (healthy, watch, at risk) each carry their tone — so the marks read as one row of one form beside a heading that is larger than any of them. The subheading joins the account number, the owner and the city with a middle dot. The back link names the list it returns to.
+Don't: Mix a `tag` and a `status-indicator` in the marks — two forms of indication at two heights, 4 pixels apart — or leave a mark at the medium size, which stands 28 pixels tall beside the heading. Do not put the state in the subheading as words.
+Check: With the record loaded, the title row reads the visual, the name, two small tags, then one subheading of identifier, owner and place; the list's name with the back arrow stands above it.
+
+### RP-02 · The figures stand in the body, on every section
+
+Level: SHOULD
+Applies to: the numeric facts a record page shows — exposure, balances, counts
+Rule: The record's figures are `stat-card`s in a `grid` at the top of the page body, before the section's content, and they stay while the section changes; the header's collapsible area does not hold them.
+Why: The header's content part is a column with a measure for prose; four figures in it stacked to one narrow column. In the body, above the switch, the figures read on every section and the header keeps only the title and the tabs.
+Do: Four cards at the small size in a grid that drops to two columns on a phone; each card carries the figure, its unit and one comparison line ("of R$135,000", "3 of 4 open invoices"). A threshold the domain states is said in the card's comparison line once it is crossed ("above 90% of $500,000", "under 22%: Sales approval"), in words that keep the line to one: the family's `tone` is the tone it hands to its trend and paints nothing on a card without one.
+Don't: Draw the figures in the header area, or under one section only.
+Check: Switch sections: the figures stay; at 390 pixels they stand two by two. A figure past a threshold the domain states says so in its comparison line.
+
+### RP-03 · Related records are the header's tabs, each a table
+
+Level: SHOULD
+Applies to: contacts, orders, invoices, tickets, notes and activity of a record
+Rule: Each kind of related record is a tab in the header's `tabs` slot with its count in the label; a tab's content is a `table` of that kind with a caption, or a `timeline` for activity; the empty state is the table's own `empty` part.
+Why: The related records are answers to different questions and rarely read together; one long page of six tables scrolls past the one the reader came for, and the tabs stay under the title while the section scrolls (LA-04).
+Do: Load the record once and derive the counts from it; a tab with zero items still exists and says so in its empty part. On a phone the table takes its fixed layout and keeps the columns that decide — the identifier and the amount, or the identifier and the status — so no table is wider than the frame.
+Don't: Hide a tab because it is empty, or let a table on a phone scroll sideways inside its frame.
+Check: Every tab label carries a count once the record has loaded; at 390 pixels every table fits the frame and its empty state is the table's.
+
+### RP-04 · A missing record is the page's own answer
+
+Level: MUST
+Applies to: a record page opened with an id the backend does not hold, or under a failed transport
+Rule: The page keeps its header with the way back and shows a `result-state` in the body: `not-found` for an id that does not exist, `error` with Try again for a transport failure; the URL stays.
+Why: A deep link a colleague pasted still says where it was pointing, and a reader who arrived by the back gesture leaves the same way.
+Do: Read the error's code: not found has no retry, only the way back; every other failure offers Try again and the way back.
+Don't: Redirect to the list, or show the list's empty state.
+Check: Open a record address whose id does not exist: the header names the record type with the way back, the body's `result-state` says the record does not exist, and the address keeps the id.
+
+### RP-05 · The action that adds to a tab stands in the record's toolbar
+
+Level: SHOULD
+Applies to: an action that adds a related record — a contact, a note, an address — to a record page's tab
+Rule: While its tab is open, the action stands in the record header's `toolbar` beside the record's own actions, and the form it opens takes the place of the tab's listing.
+Why: The tab's content is a `table` with a caption (RP-03) and no slot for a control; a bar of the page's own above the table is a second row of actions on a page that already has one, and the header's toolbar already folds into its menu on a phone.
+Do: Show the action only while its tab is open, and word it for what it adds ("New contact"). The form replaces the table in the tab, keeping the header, the figures and the tabs where they are (FM-07). A section that is not a tab — the addresses on the overview — uses `section`'s own `actions` instead.
+Don't: Draw a toolbar of the page's own above a tab's table, or leave the action in the header while another tab is open.
+Check: Open a tab that can be added to: the action appears in the header's toolbar and folds into its menu at phone width; open another tab and it leaves.
+
+### RP-06 · A record with a lifecycle shows where it stands before what it holds
+
+Level: SHOULD
+Applies to: a record that moves through states other people watch — an order, a quote, a shipment, a ticket
+Rule: The page answers "where is this" above the record's contents: the steps it has passed, the step it is on, what that step is waiting on, and one sentence naming what happens next.
+Why: A reader opening an order is asking what is holding it up, not what is on line seven; a status word alone says where it is and not what it is waiting for, and the lines say neither.
+Do: Draw the steps as the record's own element (CP-04) with the state each one is in, and give the stopped record its own tone — a hold and a cancellation are not the same colour as progress. The figures stay above it (RP-02) and the related records below (RP-03).
+Don't: Leave the lifecycle to a status `tag` in the header, or bury it under the lines.
+Check: Open a record waiting on a step: the page says the step, who it waits on and what happens next, above its contents.
+
+### RP-07 · A table that takes a figure apart ends in the total it adds back up
+
+Level: SHOULD
+Applies to: a table whose rows are one quantity split by place, period or party, standing under the figure that states the whole
+Rule: The table carries the column summaries the table element has for it, holding the same totals as the figures above, and says in one line what the rows are counted in.
+Why: A row of figures and a table of parts are two statements about one number, and a reader who cannot add five rows in their head has been given two numbers with no way to reconcile them — which is what a decomposition is for.
+Do: Sum each column the figures state and put the sums in the table's summary row, naming how many rows were added and in what unit. A column the rows carry but the whole has no total for — a threshold, a rate — leaves its summary cell empty rather than adding thresholds together.
+Don't: Leave the table without its summary, or sum a column whose total means nothing.
+Check: Open a record whose table takes a figure apart: the summary row's numbers equal the figure above it.
+
+### RP-08 · A figure over records of mixed units counts records
+
+Level: SHOULD
+Applies to: a `stat-card` over a set of related records whose quantities are not counted in one unit
+Rule: Where the records do not share a unit the figure counts records; a quantity is summed only where one unit covers the whole set, and the page says which unit that is.
+Why: A total over each, metres and kilograms is a number of nothing, and it is read as a quantity because that is what the card's shape says it is.
+Do: Count what the reader would act on — how many are out of stock, how many are below their reorder point — and put the units question under the table as one sentence: the unit when there is one, and that the rows are read one at a time when there is not.
+Don't: Add quantities across units, or leave a summed figure without naming its unit.
+Check: Read a figure over rows of different units: it counts rows and says so under its table; a quantity is summed only where every row shares one unit.
+
+### RP-09 · A step waiting on someone else says who, and offers nothing it gates
+
+Level: SHOULD
+Applies to: a record whose step waits on a decision the reader cannot give — an approval by a role the reader does not hold
+Rule: The step names the role it waits on and the page draws no control for the command that the decision gates; the control appears in the one state the backend accepts it.
+Why: A control the backend will refuse until someone else acts is a refusal the reader provokes, and a waiting step with no name leaves the reader to guess whom to ask.
+Do: Put the role in the step's detail and in the record's sentence (RP-06), show the approval chain under it, and derive the gated command's presence from the approval's own status.
+Don't: Draw the gated command disabled with no reason, or draw it enabled and translate the refusal afterwards.
+Check: Open a record waiting on a decision as a reader without the deciding role: the step names the role and no control for the gated command is drawn; open it in the state the backend accepts the command: the control is drawn.
+
+### RP-10 · A score is read against its peers and says what it counts
+
+Level: SHOULD
+Applies to: a figure that scores a record — a supplier's on-time share, quality and lead time
+Rule: The figure's comparison line gives the median of the record's peers, one sentence under the figures says what each score counts and who the peers are, and a score with nothing behind it is not drawn as a number.
+Why: A score alone does not say whether it is good, and a backend that writes nought or a hundred for a record with no history reads as the worst or the best of them.
+Do: Read the peers once — the records of the same category — leave out of each median the peers with nothing behind that score, say "under median" in the comparison line only where the score falls under it by a margin the product states, and state that margin in the sentence under the figures, and draw a dash with the words "no line received in full yet" where the record has no history.
+Don't: Compare with the whole tenant, draw a chart of every peer to answer one record's question, or show 100 for a supplier that has delivered nothing.
+Check: Read a scored figure: its comparison line gives the peers' median, one sentence names what each score counts and who the peers are, and a score with nothing behind it shows no number.
+
+### RP-11 · Authority that depends on an amount is said first
+
+Level: MUST
+Applies to: a command whose required role depends on the record's value — a write-off by balance, a discount by size
+Rule: The record's sentence states, before any control, which authority the current value needs, measured in the unit the policy states, and the command is drawn only in the form that authority gives the reader.
+Why: A control drawn the same for every balance is refused for the balances above the reader, and a refusal after the press teaches the policy one balance at a time.
+Do: Compute the value the backend measures — the balance in the policy's currency at the document's own rate — and name the tier it falls in with the threshold ("above US$500: only a Finance Manager writes it off"). Name the control for what it does in that tier ("Request write-off approval" where an approval follows), draw none where the reader's role is below the tier, and let the sentence name the role that decides. While an approval the command asked for is pending, the control is not drawn (RP-09).
+Don't: Draw the command for every holder of its permission and translate the refusal, or state the threshold in the document's currency when the policy states it in another.
+Check: Open a record whose value needs more authority than the reader holds: before any control, the sentence names that authority and the measure in the policy's unit, and the command is not drawn.
+
+### RP-12 · A document without a destination lives under what it changes
+
+Level: SHOULD
+Applies to: a record the navigation gives no destination — a credit memo, a refund — beside a destination whose records it changes
+Rule: The document's list and record stand under the destination whose records it changes, declared before that destination's own record address, and every record of that destination that issued or took one links to it.
+Why: A document of its own destination is a list nobody walks to, and a document kept only as a tab of one record loses the documents no record issued.
+Do: Give the list a segment under the destination (the invoices' credit memos), make its way back name the destination, open its create form from the record with the record and its customer chosen, and link each application or refund from the records it touched. A refund, which changes a credit, is written from the credit memo or the payment whose credit it spends.
+Don't: Add a destination the navigation's map does not hold, or reach the documents only through one record's tab.
+Check: Open the document's create route and a record address of the same destination: neither is read as the other, and each record that issued or took a document links to it.
+
+### RP-13 · An entry a workflow wrote names the workflow and opens its run
+
+Level: SHOULD
+Applies to: a record's activity, where an automation's action and a person's command both write entries
+Rule: An entry written by a workflow's action names the workflow as its actor and, for a reader of workflows, opens the run that wrote it; it never reads as the work of the person whose command set the workflow off.
+Why: A hold placed by a workflow and drawn under the name of the agent who escalated a ticket blames the agent for a rule they never saw, and leaves the reader no way to the rule.
+Do: Read the actor from the entry's workflow, say it as "Workflow “name”", and put "Open the run" in the timeline item's actions where the reader holds the permission to read workflows.
+Don't: Draw the automation actor's bare name, or the name of the person whose command produced the event.
+Check: Read an entry a workflow wrote: its actor is the workflow, and for a reader of workflows it opens the run that wrote it.

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/icon.json

@@ -18,6 +18,7 @@
       "default",
       "muted",
       "accent",
+      "info",
       "success",
       "warning",
       "danger",
@@ -58,7 +59,7 @@
         },
         {
           "name": "tone",
-          "type": "'inherit' | 'default' | 'muted' | 'accent' | 'success' | 'warning' | 'danger' | 'inverse'",
+          "type": "'inherit' | 'default' | 'muted' | 'accent' | 'info' | 'success' | 'warning' | 'danger' | 'inverse'",
           "defaultValue": "inherit",
           "appliesTo": "Icon",
           "description": "Colour; inherit takes the colour of the text beside it"
@@ -117,6 +118,7 @@
     "--slotted-text-muted",
     "--slotted-tone-accent-text",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-text",
     "--slotted-tone-success-text",
     "--slotted-tone-warning-text"
   ],

package/dist/docs/icon.md

@@ -20,7 +20,7 @@ Excerpt — not a complete module
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
 | `size` | `'text' \| 'sm' \| 'md' \| 'lg'` | md | Icon | Box size; sm, md and lg read the control icon scale, text follows the type |
-| `tone` | `'inherit' \| 'default' \| 'muted' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'inverse'` | inherit | Icon | Colour; inherit takes the colour of the text beside it |
+| `tone` | `'inherit' \| 'default' \| 'muted' \| 'accent' \| 'info' \| 'success' \| 'warning' \| 'danger' \| 'inverse'` | inherit | Icon | Colour; inherit takes the colour of the text beside it |
 | `directional` | `boolean` | false | Icon | The artwork points somewhere, so it mirrors in a right-to-left document |
 | `label` | `string` | — | Icon | The name the icon carries; absent, the icon leaves the accessibility tree |
 | `children` | `ReactNode` | — | Icon | The glyph — a Lucide component, an svg, any artwork |
@@ -31,7 +31,7 @@ Excerpt — not a complete module
 | Axis | Values | Default |
 | --- | --- | --- |
 | `size` | `text`, `sm`, `md`, `lg` | `md` |
-| `tone` | `inherit`, `default`, `muted`, `accent`, `success`, `warning`, `danger`, `inverse` | `inherit` |
+| `tone` | `inherit`, `default`, `muted`, `accent`, `info`, `success`, `warning`, `danger`, `inverse` | `inherit` |
 
 ## Rules
 
@@ -46,7 +46,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-icon-baseline-shift`, `--slotted-icon-size`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+`--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-icon-baseline-shift`, `--slotted-icon-size`, `--slotted-text`, `--slotted-text-inverse`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-info-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
 
 ## Examples
 

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/inline-message.json

@@ -10,6 +10,7 @@
     "tone": [
       "accent",
       "secondary",
+      "info",
       "success",
       "warning",
       "danger"
@@ -57,14 +58,15 @@
         "root",
         "prefix",
         "icon",
-        "text"
+        "text",
+        "actions"
       ]
     }
   },
   "docs": {
     "inlineMessage": {
       "imports": {
-        "source": "import {\n  InlineMessage,\n  InlineMessageDefaultsProvider,\n} from '@slotted/react';"
+        "source": "import {\n  InlineMessage,\n  InlineMessageActions,\n  InlineMessageDefaultsProvider,\n} from '@slotted/react';"
       },
       "anatomy": [
         {
@@ -90,12 +92,18 @@
           "element": "span",
           "required": true,
           "purpose": "The sentence. Written by the family around children, which is what makes “is there a message?” a question the stylesheet can ask and keeps a message holding a link one grid item rather than two."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "The answers the message offers (InlineMessageActions), after the sentence and wrapping under it. Present, the root is a div with role=\"group\" named by the sentence, the live role moves to the sentence, and the buttons take the message size."
         }
       ],
       "api": [
         {
           "name": "tone",
-          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "secondary",
           "appliesTo": "InlineMessage",
           "description": "What the message is about, and therefore which mark it draws and which word a reader hears first. secondary is help: no mark, no word, and the neutral muted ink"
@@ -220,15 +228,19 @@
     "--slotted-control-font-size-sm",
     "--slotted-disabled-foreground",
     "--slotted-duration-loop-fast",
+    "--slotted-inline-message-actions-gap",
+    "--slotted-inline-message-actions-offset",
     "--slotted-inline-message-column-gap",
     "--slotted-inline-message-font-family",
     "--slotted-inline-message-line-height",
     "--slotted-line-height-md",
     "--slotted-radius-full",
+    "--slotted-space-2",
     "--slotted-space-4",
     "--slotted-text-muted",
     "--slotted-tone-accent-text",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-text",
     "--slotted-tone-success-text",
     "--slotted-tone-warning-text"
   ],

package/dist/docs/inline-message.md

@@ -8,6 +8,7 @@
 ```tsx
 import {
   InlineMessage,
+  InlineMessageActions,
   InlineMessageDefaultsProvider,
 } from '@slotted/react';
 ```
@@ -28,12 +29,13 @@ Excerpt — not a complete module
 | `prefix` | span | no |
 | `icon` | span | no |
 | `text` | span | yes |
+| `actions` | div | no |
 
 ## Props
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary | InlineMessage | What the message is about, and therefore which mark it draws and which word a reader hears first. secondary is help: no mark, no word, and the neutral muted ink |
+| `tone` | `'accent' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | secondary | InlineMessage | What the message is about, and therefore which mark it draws and which word a reader hears first. secondary is help: no mark, no word, and the neutral muted ink |
 | `size` | `'sm' \| 'md'` | sm | InlineMessage | The type step. sm is the message of a field, md the message of a section; both read the control scales, which the theme restates per density |
 | `live` | `'off' \| 'polite' \| 'assertive'` | off | InlineMessage | Whether the message announces itself. polite writes role="status" and assertive writes role="alert", both on this element — there are no controls inside it to keep out of the region |
 | `mark` | `'glyph' \| 'dot' \| 'none'` | glyph | InlineMessage | Which mark is drawn. glyph is the tone’s own silhouette; dot is one neutral bullet in the tone’s ink, the same shape for every tone including help; none draws nothing, and the tone is said by the ink and the weight of the sentence. Field and FieldGroup ask for none, because a silhouette under every control of a form is texture rather than a warning |
@@ -53,7 +55,7 @@ Excerpt — not a complete module
 
 | Axis | Values | Default |
 | --- | --- | --- |
-| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `secondary` |
+| `tone` | `accent`, `secondary`, `info`, `success`, `warning`, `danger` | `secondary` |
 | `size` | `sm`, `md` | `sm` |
 | `mark` | `glyph`, `dot`, `none` | `glyph` |
 | `live` | `off`, `polite`, `assertive` | `off` |
@@ -70,7 +72,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-disabled-foreground`, `--slotted-duration-loop-fast`, `--slotted-inline-message-column-gap`, `--slotted-inline-message-font-family`, `--slotted-inline-message-line-height`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-space-4`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
+`--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-disabled-foreground`, `--slotted-duration-loop-fast`, `--slotted-inline-message-actions-gap`, `--slotted-inline-message-actions-offset`, `--slotted-inline-message-column-gap`, `--slotted-inline-message-font-family`, `--slotted-inline-message-line-height`, `--slotted-line-height-md`, `--slotted-radius-full`, `--slotted-space-2`, `--slotted-space-4`, `--slotted-text-muted`, `--slotted-tone-accent-text`, `--slotted-tone-danger-text`, `--slotted-tone-info-text`, `--slotted-tone-success-text`, `--slotted-tone-warning-text`
 
 ## Examples