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

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

@@ -0,0 +1,165 @@
+---
+topic: list pages
+prefix: LP
+triggers:
+  [
+    list,
+    listing,
+    table,
+    grid,
+    data-grid,
+    columns,
+    rows,
+    search,
+    filter,
+    filter-bar,
+    saved view,
+    preset,
+    bulk,
+    selection,
+    action-bar,
+    pagination,
+    page size,
+    count,
+    truncate,
+    phone,
+    narrow,
+    badge,
+    tag,
+  ]
+families: [data-grid, filter-bar, action-bar, pagination, page, page-header, link, badge, tag]
+---
+
+# List pages
+
+How a screen that lists records is composed: where the search, the filters
+and the bulk actions stand, what a row shows when a value does not fit, how
+the count and the pager share the answer, and what a list of many columns
+does on a phone. The library gives `data-grid` a query, `filter-bar` a tree,
+`action-bar` a place for what a selection can do and `pagination` a page;
+it does not say which of them holds the search, how many columns a phone
+keeps, or whether a phone is offered a page size.
+
+### LP-01 · A phone keeps the row header and the columns of highest priority; the rest move into the row
+
+Level: SHOULD
+Applies to: a `data-grid` of many columns that uses the pop-in: narrower than 600 pixels, or on a touch screen narrower than 1024 (the pop-in is the default)
+Rule: The grid shows the selection column, the row header and the columns of highest priority that fit; the others move into the row's pop-in as labelled values, by `priority`, outside the column state, and no row is wider than the frame.
+Why: A grid that scrolls sideways on a phone hides the value the reader came for behind a gesture the page also answers, a grid that shrinks twelve columns into 390 pixels shows none of them, and a grid that drops the columns it cannot fit leaves the screen without the facts it exists to show.
+Do: Mark the identity column as the row header and give the key columns a `priority`, lowest for the one fact that says where to look first (for customers, the health). Columns without a priority move first. Turn the pop-in off only on a column another column already repeats. Keep the selection column: the bulk action is still the phone's. The column manager marks moved columns "Shown in row". Offer the list's sort from the list tools while the pop-in holds columns, since their headers are gone.
+Don't: Let the frame scroll sideways on a phone, compute a phone column set from a media query into the column state, draw a column's value under the row header by hand, or give the row header a priority.
+Check: At 390 pixels no row is wider than the frame, the first row's pop-in holds the moved columns as labelled `popin-field`s, and the list's sort is reachable from the list tools.
+
+### LP-02 · The bar above the grid holds search, filters and views
+
+Level: SHOULD
+Applies to: a list page composed of `page-header`, `filter-bar` and `data-grid`
+Rule: The search field, the filter pills and the saved views stand in one `filter-bar` as the first block of the page body, above the grid; the header keeps the title and the actions that create or leave the list.
+Why: The bar is a `search` landmark with three tab stops whatever the field count, and it is a query container that folds its pills behind "Filters (n)" on its own; a search field in the header's actions or filters in the grid's header row lose that fold and split one query across two regions.
+Do: Bind the bar's tree and query and the grid's query to one store; the bar's `end` slot holds what acts on the view (save, delete). Give the bar the count of the query beside the count of the tenant, so "12 of 1,146" reads as the filter's effect.
+Don't: Put the search in `page-header`'s actions, draw a second search in the grid's filter row, or keep the saved views in the header's tabs: a view is a tree the bar already edits, and its select is the bar's `preset` part.
+Check: Tab from the title: the search field, then the toolbar of pills, then the chips, then the grid. Below 36rem the pills fold behind "Filters (n)".
+
+### LP-03 · A selection's actions stand in the page footer
+
+Level: SHOULD
+Applies to: bulk actions over a `data-grid` selection
+Rule: The actions a selection allows stand in an `action-bar` in `page`'s footer part, open while the selection is not empty, with the count and Clear at the start and the action that confirms at the end.
+Why: The footer is the page's own bar for what finishes a task and stays at the bottom of the scroll; a bar drawn above the grid moves the rows when it appears, and one floating over them covers the last rows.
+Do: Open the footer on the selection; the bar takes its `plain` variant because the footer already paints a ground. Rank the actions so that the confirming one never moves and the rest give way to the overflow. On a phone the bar becomes a column; offer the mutations only — a file export is a desk's task.
+Don't: Draw the selection bar inside the grid's footer beside the pager, or leave the export in the phone's column.
+Check: Select two rows: the footer opens with the selection count, Clear, and the actions end-aligned; clear the selection and the footer leaves.
+
+### LP-04 · A value that does not fit truncates, and the row does not grow
+
+Level: MUST
+Applies to: any text cell of a listing, the row header in particular
+Rule: A value longer than its column is cut with an ellipsis and kept whole in the cell's title; a cell template that replaces the family's value carries the cut, the title and the value's own maximum.
+Why: A row that grows with its longest value pushes every other column out of the frame, a value that wraps makes rows of two heights in a list the eye scans by line, and a value wider than its column is drawn over the next one — a value in the wrong column.
+Do: Leave the column's text mode at its default, `truncate`, and let the family cut the value. Where the cell is a template — a link on the name, a name over a second line — the template carries three things and not one: the cut, the title, and a maximum of the whole width. The maximum is the part that is easy to leave out and the only one that fails silently: the families that draw a name size their box to their content, a value that never wraps has its whole string as its minimum, and the grid bounds the cell's own child and reaches no further. Give near-duplicate names a column that tells them apart: the account number.
+Don't: Put a name column in its `wrap` mode, ask for a cut without an ellipsis, or let a template's value keep its content's width inside a layout family the template wrapped it in.
+Check: Drag the column narrower than its longest value: the value ends in an ellipsis at the column's edge and nothing of it stands in the next column.
+
+### LP-05 · The count is the bar's; the range is the pager's
+
+Level: SHOULD
+Applies to: a paged listing with a `filter-bar` above and a `pagination` in the grid's footer
+Rule: The filter bar states how many rows the query kept of how many there are; the pager states the range on screen and moves the page; the grid's own range line is off.
+Why: Three numbers saying overlapping things — "1,146 of 1,146", "1–25 of 1,146", "1–25 of 1146" — are two too many; each part answers one question: what the filter did, and where in it the reader is.
+Do: The bar's `count` part reads the query's count and the tenant's total; the grid's range line is off; the pager with its `status`, its `page-size` and the two triggers is projected as the grid's `footer`. Below the phone step the page size is not offered: the footer is the range and the triggers.
+Don't: Draw the pager under the grid as a block of the page, or let the grid's range and the pager's status both stand.
+Check: One count above the grid, one range in its footer; on a phone the footer is one line.
+
+### LP-06 · A change of query empties the rows; a mutation keeps them
+
+Level: SHOULD
+Applies to: a `data-grid` in server mode over a store
+Rule: A sort, a filter, a search, a page or a view removes the rows before the request and the grid draws its placeholders; a mutation read back keeps the rows in the grid's loading state, and the grid dims them.
+Why: AF-04 and AF-02 applied to the grid: the family draws placeholders when it has no rows and dims the ones it has, so the store decides which of the two the reader sees by what it does with the rows.
+Do: In the store, empty the rows when the incoming query differs from the current one and keep them when it is the same; keep one request sequence and discard an answer that a later request has overtaken.
+Don't: Empty the rows on every request, or keep the previous page's rows under a new page while the answer is on its way.
+Check: With the network throttled to a slow profile, a page change shows placeholder rows at once, and a mutation read back keeps the rows on screen, dimmed, in the grid's loading state.
+
+### LP-07 · The grid fills the body and scrolls its own rows
+
+Status: retired · rewritten as LP-12, which keeps the page to one scroller below the compact size class as well
+
+### LP-08 · Every number on the screen names what it counts
+
+Level: SHOULD
+Applies to: a list page whose rows and whose pages count different things — contacts read account by account, lines read order by order
+Rule: The bar's count, the pager's range and its page size name their unit in words.
+Why: "62 of 62" above "1–25 of 1,146" reads as one number that contradicts itself; a reader cannot tell that one counts people and the other accounts.
+Do: Pass the words to the families that draw the numbers — `filter-bar`'s `count` label and `pagination`'s `range` and page-size labels — and write one sentence between them that says what the page holds and what the pager turns.
+Don't: Leave two bare ranges on one screen, or explain the difference only in a tooltip.
+Check: Read the screen's numbers aloud: each names what it counts — the query's count, the page size, the range.
+
+### LP-09 · A queue with no endpoint is the list its work is written against
+
+Level: SHOULD
+Applies to: a work queue the backend has no resource for — what to receive, what to ship, what to count
+Rule: The queue is the list of the records the work is written against, narrowed by the states in which the work can be done and by the reader's scope, stated as the page's place; opening a row opens the form that does the work for a reader who can do it.
+Why: A queue drawn from a resource that is not the work — a list of receipts already written — answers what was done instead of what is waiting, and a second copy of the records with a filter of its own drifts from the list it copies.
+Do: Read the records' own list with the states as the page's place (BR-01), sort the flagged records first and then by what should already be done, let the bar's pills narrow within the place, and name the record the form writes where it is read — its address under the queue's destination.
+Don't: Draw the states as the bar's pills a reader can remove, or open a row on the record and make the reader find the form.
+Check: Open the queue as a reader with a narrowed scope: every row is a record in a state where the work can be done within that scope, the page's place states the narrowing, and opening a row opens the form that does the work.
+
+### LP-10 · A chart about the list's records is the page's second tab
+
+Level: SHOULD
+Applies to: a comparison chart over the records of a list page that fills its body (LP-12)
+Rule: The chart stands in the header's second tab, beside the list's own, and never as a block above the list.
+Why: A chart above a list that fills the page takes the height the rows need: at 800 pixels a receiving queue under its chart showed two rows.
+Do: Give the header two tabs — the list and the comparison — and draw the chart at its own size in its tab; where the comparison has one category, drop the tab and state its numbers in one sentence above the bar (OV-03).
+Don't: Shrink the chart's plot under the family's smallest step to make room, or let the page scroll to reach the rows.
+Check: At 1280 by 800 the list shows its rows from the top of the body; the header's second tab draws the chart, and no chart stands above the list.
+
+### LP-11 · A control that changes nothing under the pointer is not offered
+
+Level: SHOULD
+Applies to: the list tools in the filter bar's `end` slot — the density control in particular
+Rule: Where the primary input is a touch screen, the list tools leave out the row density: the theme raises every density's rows to the touch target, and the tools keep the sort, the views and the columns on one line.
+Why: Three densities that draw the same 44-pixel rows are a control that answers nothing, and on a phone it took the line that pushed the grid down to one visible row.
+Do: Decide the density control's presence from the pointer, not from the width: a narrow window with a mouse keeps it.
+Don't: Keep every desk tool on a phone and let the `end` slot wrap to three lines above the rows.
+Check: With touch emulation at 390 pixels the filter bar's `end` slot is one line and holds no density control; with a mouse at the same width it does.
+
+### LP-12 · One scroller: the grid's above 600 pixels, the page's below
+
+Level: MUST
+Applies to: a page whose body is a `data-grid` or a `table` over a store, with a bar or a message above it
+Rule: From 600 pixels of the page's width the listing takes the height the bar and the messages leave and scrolls its own rows while the page does not scroll; below 600 the page's `fill` does not apply, the listing is as tall as its rows and the page scrolls.
+Why: Two scrollers on one screen let the wheel answer whichever is under the pointer; and on a phone a filled page left the rows 155 pixels of a 667-pixel screen under a header, a banner and the tools.
+Do: Write the page with `fill`; make the region a flex column that takes its parent's full height with a zero minimum, and give the listing `flex: 1 1 0` with `min-block-size: 0`, and below 600 pixels a flex basis of auto, so the listing fills a column that has a height and takes its rows' height in one that has none. The page's footer bar (LP-03) stays outside it.
+Don't: Keep the zero basis below 600 pixels, which collapses the listing to nothing once the column loses its height, or give it an `auto` basis above 600, where its rows' height climbs the column and the page scrolls again.
+Check: At 1280 with a full page of rows, the document's scroll height equals its client height and the wheel over a row moves the rows; at 375×667 the document scrolls and the grid is as tall as its rows.
+
+### LP-13 · A mark in a cell is the small step
+
+Level: SHOULD
+Applies to: a `badge` or a `tag` drawn in a cell of a `data-grid` or a `table`
+Rule: The mark takes the `sm` `size`; the default `md` belongs to a record's header and to a region with room around it.
+Why: A row sets its text at the small type step, 13 pixels in a 34-pixel row; an `md` badge sets 13-pixel words in a 24-pixel box and stands taller and louder than the cells beside it, so a state column outweighs the record's name.
+Do: Give every mark a cell holds — a state, a flag, a warning — the `sm` `size`: 12-pixel words in a 19-pixel box.
+Don't: Leave a cell's mark at the family's default, or size it up to make a state stand out; a tone says that.
+Check: On every list, every `badge` and `tag` inside a cell of a `data-grid` or a `table` carries the `sm` `size`.

package/dist/docs/guidelines/overviews.md

@@ -0,0 +1,66 @@
+---
+topic: overviews
+prefix: OV
+triggers:
+  [overview, dashboard, flagship, figure, stat card, exception, summary, chart, door, phone, narrow]
+families: [stat-card, chart, list, list-item, table, section, grid]
+---
+
+# Overviews
+
+How a screen that summarises a module is composed: what its figures lead to,
+what a phone keeps first, and when a chart earns its place. The library gives
+`stat-card` a figure and an action, `chart` a comparison and its table, and
+`list` rows that are destinations; it does not say that a figure is a door, in
+which order a phone reads a summary, or that a comparison of one is not a
+chart.
+
+### OV-01 · Every figure opens the list it counts
+
+Level: SHOULD
+Applies to: a `stat-card` on an overview whose number counts records a list page holds
+Rule: The figure leads to the list page of the records it counts, and that list opens with the figure's condition applied as the bar's own pills, which the reader removes like any other.
+Why: A number the reader cannot open is a question with no way to its answer, and a list opened without the condition makes the reader rebuild the filter the figure already stood for.
+Do: Put the door in the card's `action` part at the desk. Keep the list a destination of its own in the navigation, and let the overview summarise and lead rather than hold the list in its body. Carry the condition in the address, so the door is a link a colleague can paste.
+Don't: Draw a figure with no way to the records, open the unfiltered list, or narrow the list through a place the bar does not show.
+Check: Press each figure's door: the list's bar shows the figure's pill and its count equals the figure.
+
+### OV-02 · A phone reads the summary in the order it is acted on
+
+Level: SHOULD
+Applies to: an overview in the compact size class
+Rule: Below 600 pixels the figures are one `list` of rows that are destinations — label, comparison, number — followed by the records to act on, the work in flight, the charts, and the history last.
+Why: Five cards two by two fill a phone's first screen before a single record is named, and each card's door wraps under its label below the label's floor.
+Do: Draw the same figures as `list-item` rows whose content is the link and whose `end` holds the number, and place the regions by one grid whose areas change at the expanded size class.
+Don't: Keep the desk's card grid on a phone, or put the charts above the records a reader acts on.
+Check: At 390 pixels with a coarse pointer, the first screen holds the four figures as rows at least a touch target tall and the heading of the records to act on.
+
+### OV-03 · A comparison of one is a sentence
+
+Level: SHOULD
+Applies to: a `chart` that compares categories whose number depends on the reader's scope — warehouses, teams, regions
+Rule: Where the reader's scope holds one category, the chart is not drawn and one sentence states the numbers it would have compared.
+Why: A bar chart of one category compares nothing, and it takes a chart's height to say three numbers.
+Do: Decide the chart from the scope the page already reads, and write the sentence with the numbers and their unit.
+Don't: Draw one group of bars, or leave an empty chart region for a reader scoped to one place.
+Check: Sign in as a reader whose scope holds one category: the overview draws no comparison chart, and one sentence states that category's numbers.
+
+### OV-04 · A threshold is said, not painted
+
+Level: SHOULD
+Applies to: a figure of an overview whose reading changes at a share the product states — overdue receivables against all receivables
+Rule: The thresholds are stated once in words beside the figures, and a figure past one says so in its own comparison line, on the line the placeholder reserves.
+Why: The figure card's tone is the trend's and paints nothing on a card without one, and a mark added beside the label moves the card's header to a second line.
+Do: Keep the shares in one place of the page's code and one sentence on screen ("a warning from 20 percent of receivables and a danger from 33"), and end the crossed figure's comparison with the threshold it passed ("26% of receivables, above 20%").
+Don't: Set a tone on a card with no trend and expect it to read, or add a badge to the card's header for the crossing.
+Check: Bring a figure past each stated threshold: the threshold sentence stands beside the figures, and the figure's own comparison line says it crossed, on the line its placeholder reserved.
+
+### OV-05 · A chart is framed only as a tile
+
+Level: SHOULD
+Applies to: `chart` and `stat-card` on an overview, a record's figures or a list's chart tab
+Rule: A chart takes the `card` `variant` when it is one of two or more peer tiles in one grid with no section heading of its own, and stays `plain` when it is the body of a titled section or the only content of a tab.
+Why: The section's heading and its space already frame a chart that is its body, and a card around it draws a second frame; peer tiles without headings need the frame to read as separate answers of the same height.
+Do: Give a plain chart a `title` that names the measure and not the section's words again; in a grid of peer tiles, let the chart's title be the tile's title and share the row's height, as `stat-card` always does.
+Don't: Frame every chart by habit, or leave a chart plain among framed tiles where it reads as the page's background.
+Check: For each chart, name what frames it: a titled section (plain) or a grid of peers (card); a chart with neither frame, or with both, is a finding.

package/dist/docs/guidelines/own-elements.md

@@ -0,0 +1,115 @@
+---
+topic: own elements
+prefix: OE
+triggers:
+  [custom element, own component, bespoke, widget, CSS, style, token, hover, focus, animation]
+families: [button, typography]
+---
+
+# Own elements
+
+How an element no family draws is built from the theme: which tokens it reads,
+how its states yield, and what it keeps under focus, touch, forced colours and
+reduced motion. The families meet each rule below; an element of the
+application's own meets them through the same tokens. Where a family answers
+the problem, the family is used instead (CP-04).
+
+### OE-01 · Own elements read application tokens
+
+Level: MUST
+Applies to: every element of the application's own that paints, spaces or moves
+Rule: An element of the application's own reads only tokens of the groups `node_modules/@slotted/react/dist/docs/tokens.md` lists for the application.
+Why: A token of a family-only group is that family's adjustment and changes with it; an application group is the theme's promise.
+Do: A strip of day cells spaces with `--slotted-space-2`, paints a busy day with `--slotted-tone-warning-surface` and rounds with `--slotted-radius-sm`.
+Don't: A cell takes its height from `--slotted-avatar-size-sm` because the number fit.
+Check: Every custom property of the element's own CSS that starts with --slotted- is listed in a group of tokens.md above "Read by their family only".
+
+### OE-02 · Weaker states yield
+
+Level: MUST
+Applies to: an interactive element of the application's own
+Rule: Where two states hold at once, the element paints the ground, the edge and the text colour of the stronger, in the order `disabled`, `loading`, `readonly`, `invalid`, `checked`, `selected`, `pressed`, `current`, `complete`, `active`, `hover`; the focus ring of OE-03 is drawn over every state.
+Why: A disabled element that lights under the pointer reads as operable and answers nothing.
+Do: The hover rule of a day cell excludes the disabled and the selected cell, so a selected day keeps its ground under the pointer.
+Don't: A hover ground declared after the selected ground repaints the chosen day while the pointer crosses it.
+Check: Put the pointer over a disabled, a selected and a current instance: each keeps the appearance of its stronger state; move focus to each: the ring is drawn on all three.
+
+### OE-03 · Focus draws the theme's ring
+
+Level: MUST
+Applies to: every element of the application's own that takes focus
+Rule: In its `focus-visible` state the element draws an outline of `--slotted-focus-ring-width` in `--slotted-focus-ring-color`, offset by `--slotted-focus-ring-offset`.
+Why: The ring is the one focus indicator the families share, and the theme maps its colour to the system highlight under forced colours.
+Do: A day cell draws the outline in `focus-visible` and keeps it while selected; in error it points `--slotted-focus-ring-color` at `--slotted-focus-ring-color-invalid`.
+Don't: `outline: none` on the cell, with a change of ground as the only sign of focus.
+Check: Move focus with the keyboard in the light, dark and high-contrast schemes: the ring is drawn at the theme's width and offset in each.
+
+### OE-04 · Targets meet the minimum
+
+Level: MUST
+Applies to: every element of the application's own that a pointer activates
+Rule: The element's hit area measures at least `--slotted-target-min` in both axes, and at least `--slotted-target-comfortable` under `pointer: coarse`.
+Why: A target below the minimum fails WCAG 2.2 target size, and a fingertip misses a target sized for a mouse.
+Do: A day cell narrower than the minimum keeps its drawing and extends its hit area to the minimum.
+Don't: Day cells 16 pixels wide, side by side with no gap.
+Check: Measure the hit area of the smallest instance with a fine pointer and under coarse-pointer emulation.
+
+### OE-05 · One control size step
+
+Level: SHOULD
+Applies to: an element of the application's own that stands in a row of controls
+Rule: The element takes its height, inline padding, font size and gap from `--slotted-control-*` tokens of one size step, the step of the controls beside it.
+Why: The control tokens follow density; a control sized by hand keeps its height when the row around it shrinks.
+Do: A week picker beside a `button` at the medium step reads `--slotted-control-height-md`, `--slotted-control-padding-inline-md`, `--slotted-control-font-size-md` and `--slotted-control-gap-md`.
+Don't: A height taken from the space scale that matches the button only at the comfortable density.
+Check: Switch the density among comfortable, compact and dense: the element's height equals the height of the button beside it in each.
+
+### OE-06 · Forced colours keep states
+
+Level: MUST
+Applies to: an element of the application's own that shows a state
+Rule: Under `forced-colors: active`, each state the element shows differs from rest by a border, an outline or text, not by a ground or a shadow alone.
+Why: The system replaces every ground with its own and removes shadows, so a state carried by colour alone disappears.
+Do: A selected day adds an edge of `--slotted-border-width-thick` to its tinted ground.
+Don't: A selected day told apart only by `--slotted-tone-accent-surface`.
+Check: Emulate forced colours and step through every state: each reads differently from rest.
+
+### OE-07 · Motion follows the scale
+
+Level: MUST
+Applies to: every transition and animation of an element of the application's own
+Rule: A transition takes its duration from the `duration` group or `--slotted-control-transition-duration`, its curve from the `easing` group or `--slotted-control-transition-easing`, and an animation that repeats stops under `prefers-reduced-motion: reduce`.
+Why: The theme collapses transition durations under reduced motion; a literal duration and a loop stay outside that collapse.
+Do: A cell eases its ground over `--slotted-duration-short` with `--slotted-easing-standard`; its pulsing marker stops under reduced motion and keeps its shape.
+Don't: A 300 ms transition written as a literal, and a pulse that only slows down.
+Check: Emulate reduced motion: no animation of the element runs, and its transitions complete at once.
+
+### OE-08 · Own CSS stays outside families
+
+Level: SHOULD
+Applies to: the stylesheet and the markup of an element of the application's own
+Rule: The element's rules stand in a layer of the application ordered after the library's, and never select or set `data-ui` or `data-part`.
+Why: Those attributes name a family and its parts; a rule keyed on them changes a family, and a node that carries them is taken for one.
+Do: The strip's layer is declared after the library's in the application's entry stylesheet, and its rules key on its own class names.
+Don't: A rule keyed on a family's `data-part` that restyles the family beside the strip.
+Check: Search the element's CSS and markup for data-ui and data-part, and read the application's layer statement: the library's layer comes first.
+
+### OE-09 · Reflow follows the container
+
+Level: SHOULD
+Applies to: an element of the application's own that changes layout with width
+Rule: The element reflows by a container query on a `container-name` of its own; a change that follows the page uses the size classes, at 600 and 1024 pixels.
+Why: The families reflow by their own container and the page by its size class; a viewport query disagrees with both inside a split view.
+Do: The strip names its container and drops to two rows of cells below its own threshold.
+Don't: A viewport media query that folds the strip after its panel is already narrow.
+Check: At a fixed viewport, resize the element's container across its threshold and the page across 600 and 1024 pixels.
+
+### OE-10 · Elevation pairs surface and shadow
+
+Level: SHOULD
+Applies to: an element of the application's own that stands above another surface
+Rule: A surface above another takes `--slotted-surface-raised` with one step of the `shadow` group, and a layer that floats over the page takes its stacking order from the `z-index` group.
+Why: The theme pairs each elevation with a ground per scheme and drops shadows under forced colours; a shadow or a stacking order written by hand stays outside both.
+Do: A day's detail card floats with `--slotted-surface-raised`, `--slotted-shadow-md` and `--slotted-z-index-popover`.
+Don't: A shadow written as a literal and a stacking order of 9999.
+Check: Every shadow and every stacking order of the element's own CSS reads a token of these two groups.

package/dist/docs/guidelines/reading-permissions.md

@@ -0,0 +1,55 @@
+---
+topic: reading under permissions
+prefix: PM
+triggers:
+  [
+    permission,
+    role,
+    persona,
+    cost,
+    price,
+    pricing,
+    hidden,
+    blank,
+    zero,
+    redacted,
+    column,
+    figure,
+    absent,
+    forbidden,
+    scope,
+  ]
+families: [data-grid, table, stat-card, inline-message, tabs, filter-bar]
+---
+
+# Reading under permissions
+
+What a screen draws when the answer it received was shaped by the reader's
+role rather than by the record. A backend that refuses a whole resource is
+answered by the route's own refusal; a backend that answers and writes one
+field down to a placeholder is answered here. The library draws whatever it
+is handed and has no way to know that a zero is a redaction.
+
+### PM-01 · A value a permission blanks is absent, not drawn
+
+Level: MUST
+Applies to: a field the backend writes down or empties for a reader who lacks a permission — a cost written to nought, a list of prices returned empty
+Rule: The column, the figure and the section that would carry the value are not built for that reader; nothing is drawn for the value, and nothing is hidden in a place the reader can bring back.
+Why: A redacted value drawn as a value is the screen lying with the backend's own numbers: a cost of nought reads as free, and the margin computed from it reads as a hundred percent.
+Do: Decide the column model and the filter fields from the permissions, so the value is absent from the model rather than hidden in it — a hidden column is one the reader restores through the family's own column control, and what would come back is the redaction. Where a whole section is empty for the same reason, leave the section out with its tab.
+Don't: Hide the column, grey the number, or draw an em dash where a value the reader may not see would have been: an em dash says the record has no value, and the record has one.
+Check: Sign in as a reader without the cost permission and open a record that carries costs: no margin figure, no cost column, and no currency amount of zero anywhere.
+
+### PM-02 · What is missing is named once, with who sees it
+
+Level: SHOULD
+Applies to: a screen that left a value out under PM-01, where its absence changes what the remaining numbers mean
+Rule: One statement names the permission the value needs and the roles that hold it; two missing permissions are one statement, not two.
+Why: A figure row with a hole in it reads as a screen that failed rather than as a screen that was told not to say; and a reader who holds neither permission does not need to be told twice in two tones.
+Do: Put the statement where the absence changes the reading — under the figures on a record, above the rows on a list — and use the permission's own name, which is what a reader asks an administrator for.
+Don't: Repeat the statement per tab, per column or per card, or leave the absence unexplained where the rest of the numbers depend on it.
+Check: Sign in as a reader holding neither the price nor the cost permission: one sentence names both permissions and the roles that hold them.
+
+### PM-03 · A price paid is a cost
+
+Status: retired · a domain rule, kept by the application that observed it

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.