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

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

@@ -0,0 +1,206 @@
+---
+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, table, 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. Below 600 the grid therefore windows nothing, and a store that can pass a hundred rows is served in pages: the grid asks for the next one when its last `loadMoreThreshold` rows come into view of the page's scroller, not of its own box.
+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, the grid is as tall as its rows, opening the page over a store served 30 rows at a time requests pages only until the grid's last `loadMoreThreshold` rows are below the screen's edge, and scrolling to the end requests the next one.
+
+### 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`.
+
+### LP-14 · A list that can pass a hundred rows is a data-grid
+
+Level: MUST
+Applies to: a list of records whose count the reader does not bound — transactions, postings, imports
+Rule: A list that can hold more than a hundred rows, or more than twenty columns, is a `data-grid`, which windows rows and middle columns under its default `virtualize` of `auto` wherever it has a height of its own; below 600 pixels, where it is as tall as its rows (LP-12), the store is served in pages instead. `table` is for sets the page bounds, such as a statement's lines or a record's related rows.
+Why: `table` mounts every cell: a hundred rows of twenty columns measured 93 ms in one task with a production build of React in Chrome and 160 ms with a development build, and the count of rows the store returns sets that cost.
+Do: Give the store's list a `data-grid` with its query, and keep `table` for the bounded sets inside a record or a document.
+Don't: Render an unbounded store into a `table`, or page a `table` to keep it under a hundred rows where the grid's window would have kept the whole set reachable.
+Check: Every list over an unbounded store is a `data-grid`; every `table` on a page renders a set the page bounds.
+
+### LP-15 · A grid on the page's surface is framed
+
+Level: SHOULD
+Applies to: a `data-grid` or a `table` on a list page, a record or an overview
+Rule: A grid that stands on the page's surface beside other blocks takes the `framed` `variant`; a grid that is the page's only body under a `bleed` page may stay `ruled`; `plain` is for a grid inside a `card` or a panel that already draws the frame.
+Why: `ruled`, the grid's default, draws rules between rows and no outer edge, and on a raised page surface every grid read as a bare slab beside blocks that have edges.
+Do: Give every grid that shares the page with a header area, a filter bar or other blocks the `framed` `variant`, and leave `ruled` to the full-bleed list whose edges are the page's.
+Don't: Leave the variant at its default on a page whose width is not `bleed`, or frame a grid a second time inside a card.
+Check: Every `data-grid` with no `variant` stands on a page whose `width` is `bleed`; every grid inside a `card` is `plain`.
+
+### LP-16 · A list's header says what the list covers
+
+Level: SHOULD
+Applies to: the `page-header` of a list page
+Rule: A list page's header holds a subheading that says what the list covers, the control of the period when the list reads one, the page's figures for that period in the header area as label-over-figure pairs, and the primary action as the last, solid control; a refresh control is an icon button and never the only action.
+Why: A header with a heading and a refresh icon left the period and the totals with no place, and the reader learned what the list covered only by reading its rows.
+Do: Write the `page-header`'s `subheading` part for what the list covers, the period's control and the figures in its `header-area` as `figure` parts, and end its `actions` with the solid primary action; the refresh stands before it as the `button` family's `iconButton`.
+Don't: Leave a list's header as a heading alone, put its figures in a row of cards above the grid, or make a refresh icon the header's only control.
+Check: Every list page's header has a subheading, its figures in the header area, and a solid primary action last; no header's only control is a refresh.
+
+### LP-17 · The row header and the row's actions stay in the frame
+
+Level: SHOULD
+Applies to: a `data-grid` whose columns can scroll sideways
+Rule: The column of kind `actions` stays pinned to the end, which is the grid's default, and the row header is pinned to the start with `pinned: 'start'` when it is the first column; no other column is pinned without a reason the page states.
+Why: When the columns scrolled sideways the row's menu left the frame, and on a narrow frame the reader scrolled away from the actions to reach them.
+Do: Keep the `actions` column at its default pin, write `pinned: 'start'` on a row header that is the first column, and pin nothing else.
+Don't: Unpin the actions column, or pin a column the reader did not ask to keep in view.
+Check: In a frame narrower than the grid's columns, scrolled to the end, every row's actions cell is in view, and so is the row header when it is the first column.

package/dist/docs/guidelines/overviews.md

@@ -0,0 +1,76 @@
+---
+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.
+
+### OV-06 · The stat-cards of one row share their structure
+
+Level: SHOULD
+Applies to: a row of `stat-card`s on an overview or a record page
+Rule: The cards of one row carry a label of at most three words, the figure, and the same optional parts on every card — a comparison of one line on each, or on none.
+Why: One card with a long label and a wrapping comparison beside three cards with a label and a value made four boxes of the tallest card's height, three of them mostly empty, and the row read as broken.
+Do: Give every card a short label, its figure and one comparison line; detail that only one card has goes into its comparison or a tooltip.
+Don't: Lengthen one card's label to carry its detail, or give one card of the row a part the others lack.
+Check: In every row of `stat-card`s, every label has three words or fewer, and either every card has a comparison or none does.

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 `../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