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

package/README.md

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

package/docs/AGENTS.snippet.md

@@ -1,5 +1,7 @@
 ## Slotted UI (@slotted/angular)
 
+Paths below are relative to the directory that holds node_modules.
+
 Before writing or changing UI, read `node_modules/@slotted/angular/docs/index.md`, then the file of each family you use. These files match the installed version: prefer them over prior knowledge of the library.
 
 - Import the standalone directives from the family entry point that each file's Import section shows (`@slotted/angular/<family>`), and place each on the native element its selector names: `<button slButton>`.
@@ -8,3 +10,13 @@ Before writing or changing UI, read `node_modules/@slotted/angular/docs/index.md
 - Change a family's appearance through its inputs (`size`, `variant`, `tone` where it has them), not with CSS that targets its parts.
 - Application CSS uses `var(--slotted-*)` tokens for color, spacing and radius, inside a layer declared after the library's: `@layer slotted, app;`.
 - In CSS and tests, select a family by `[data-ui="<family>"]` and its parts by `[data-part="<part>"]`.
+
+### Tasks
+
+Read the skill before the task:
+
+- Compose or change a screen — a list, a record, a form, an overview: `node_modules/@slotted/angular/docs/skills/compose-screen/SKILL.md`
+- Show what a screen draws while it waits, and its empty and error states: `node_modules/@slotted/angular/docs/skills/waiting-states/SKILL.md`
+- Review a screen against the guidelines, or fix what a review found: `node_modules/@slotted/angular/docs/skills/review-screen/SKILL.md`
+- Write a component or element that no family draws: `node_modules/@slotted/angular/docs/skills/build-own-element/SKILL.md`
+- Change the brand colour, the scheme, the density or a control's shape: `node_modules/@slotted/angular/docs/skills/theme-app/SKILL.md`

package/docs/action-bar.json

@@ -83,7 +83,7 @@
           "part": "actions",
           "element": "an element carrying slActionBarActions",
           "required": true,
-          "purpose": "The run that gives way, and the box the collapse measures. It carries margin-inline-start: auto, which anchors it to the bar’s end edge; below 24rem of container it becomes a full-width column with the action that confirms on top."
+          "purpose": "The run that gives way, and the box the collapse measures. It carries margin-inline-start: auto, which anchors it to the bar’s end edge; below 24rem of container, with no overflow control in the bar, it becomes a full-width column with the action that confirms on top."
         },
         {
           "part": "action",
@@ -166,7 +166,7 @@
           "type": "string | ((hidden: number) => string)",
           "defaultValue": "counted",
           "appliesTo": "sl-action-bar-overflow",
-          "description": "The accessible name of the control that holds what did not fit. The default counts — \"3 more actions\" — because three dots say nothing about how much is behind them. An aria-label written on the host wins over it"
+          "description": "The accessible name of the control that holds what did not fit. The default counts — \"3 more actions\" — because three dots say nothing about how much is behind them, in the language in force, with its plural (\"Mais 3 ações\" in pt-BR). An aria-label written on the host wins over it"
         },
         {
           "name": "align, side, size",
@@ -239,7 +239,7 @@
         "There is no APG pattern for a bar of actions, and the closest official guidance is the Toolbar pattern (w3.org/WAI/ARIA/apg/patterns/toolbar/). This family departs from it deliberately: there is no roving focus, so Tab reaches every action in the order the author wrote it. The controls here are the page’s own form actions, and a reader walking a form expects to arrive at Cancel and then at Save; a composite would make the whole bar one tab stop and put Save behind an arrow key that announces nothing. The cost is written down — a bar of ten icon-only actions is ten tab stops, and that bar is the Toolbar family.",
         "The role follows the departure. ARIA 1.2 makes toolbar a subclass of group, and the subclass is what is asserted when there is focus management to declare; without it, group is what is true. The bar names itself with the consumer’s aria-label or aria-labelledby, because only the page knows which task it finishes — and a role written on the host is read with HostAttributeToken before the host binding, so what the consumer wrote survives.",
         "The only keyboard this family owns is the overflow trigger’s, and it is the Menu family’s: Enter, Space and ArrowDown open the surface, Escape closes it and returns focus to the trigger. Focus is moved onto the trigger before the action holding it is hidden, so a reader who was on the fifth button lands on the control that now holds it rather than on the document body.",
-        "The trigger’s accessible name carries the count rather than the mark, so a reader hears “3 more actions” instead of three dots — and an application in another language replaces the sentence rather than translating an ellipsis. The count in the DOM, data-collapsed, is the same fact for a stylesheet or a test.",
+        "The trigger’s accessible name carries the count rather than the mark, so a reader hears “3 more actions” instead of three dots, in the language in force with its plural (“Mais 3 ações” in pt-BR). The count in the DOM, data-collapsed, is the same fact for a stylesheet or a test.",
         "A bar out of action is a fieldset around it: the platform disables every control inside and takes them out of the tab order with it. The family writes no data-disabled and declares no disabled state, because it does not own the capability — a container that refused interaction while its controls still looked operable is the defect the state precedence exists to prevent.",
         "A bar that is not present is painted out with display:none once its exit has finished, which takes it out of the accessibility tree and out of the tab order together. Carbon’s batch bar writes aria-hidden on its root instead and leaves the buttons inside reachable by Tab, which puts focus in a region the screen reader announces as absent. Appearing never moves focus either: the bar is not a dialog, and taking focus from a reader who is ticking boxes is exactly the jump a selection bar must not make.",
         "Under forced colours the rule between two runs keeps its own paint, because a background flattens to Canvas and would take the boundary between a destructive action and a frequent one with it. Everything else the reader sees belongs to the controls the consumer placed, and each keeps its own states, its own focus ring and its own contrast."
@@ -388,7 +388,7 @@
     {
       "id": "stacked",
       "title": "The bar on a phone",
-      "note": "Below 24rem of container the run becomes a full-width column with the action that confirms on top, and the collapse stops running — a column has room for everything, so there is no menu. The DOM order does not change, so Tab still reads the form’s order.",
+      "note": "Below 24rem of container a bar with no overflow control becomes a full-width column with the action that confirms on top, and the collapse stops running — a column has room for everything, so there is no menu. A bar with an overflow control keeps one row: the actions without a counterpart stay and the rest fold into the menu. The DOM order does not change, so Tab still reads the form’s order.",
       "language": "html",
       "source": "<!-- The breakpoint lives in the stylesheet's container query, and the\n     directive reads back the property that query raises rather than\n     holding a copy of the number. -->\n<footer slActionBar aria-label=\"Ações do pedido\" variant=\"raised\">\n  <div slActionBarActions>\n    <div slActionBarAction>\n      <button slButton variant=\"ghost\" type=\"button\">Descartar alterações</button>\n    </div>\n    <div slActionBarAction>\n      <button slButton type=\"button\">Guardar alterações</button>\n    </div>\n  </div>\n</footer>\n",
       "verdict": "excerpt"

package/docs/action-bar.md

@@ -52,7 +52,7 @@ Excerpt — not a complete module
 | `overflowChange` | `EventEmitter<number>` | — | slActionBar | How many actions gave way, once per change. There is no two-way binding over the collapsed set: it is a measurement, and a consumer who owned it could assert that a bar fits when the layout says it does not |
 | `slActionBarAction` | `'pinned' \| 'high' \| 'low' \| 'hide' \| 'always'` | low with a counterpart, pinned without | slActionBarAction | The selector’s own value is the rank. pinned never goes; high goes after low and hide; low is the first into the surface; hide goes first and is not offered in the surface at all; always is never in the bar. A rank that needs a counterpart and has none behaves as pinned, so a consumer error leaves the control on the bar |
 | `slActionBarActionCounterpart` | `TemplateRef<unknown>` | — | slActionBarAction | What the action becomes in the surface, as an ng-template rendered only while the action is in it — so a menu item that is never reached builds nothing. An action that declares none is pinned: pinning is the absence of a counterpart rather than a second input |
-| `label` | `string \| ((hidden: number) => string)` | counted | sl-action-bar-overflow | The accessible name of the control that holds what did not fit. The default counts — "3 more actions" — because three dots say nothing about how much is behind them. An aria-label written on the host wins over it |
+| `label` | `string \| ((hidden: number) => string)` | counted | sl-action-bar-overflow | The accessible name of the control that holds what did not fit. The default counts — "3 more actions" — because three dots say nothing about how much is behind them, in the language in force, with its plural ("Mais 3 ações" in pt-BR). An aria-label written on the host wins over it |
 | `align, side, size` | `MenuAlign \| MenuSide \| MenuSize` | from the Menu defaults | sl-action-bar-overflow | Where the surface sits against the trigger, and its own measure. Everything else about the layer an application sets once with provideMenuDefaults |
 | `aria-label` | `string` | — | slActionBar | The name of the bar. The family writes none: only the page knows which task the bar finishes. aria-labelledby works the same way |
 | `role` | `string` | group | slActionBar | group, because there is no roving focus to declare — ARIA makes toolbar a subclass of group, and the subclass is what is asserted when there is focus management. A role written on the host is read with HostAttributeToken and survives, but a consumer who wants the composite wants the Toolbar family |
@@ -77,7 +77,7 @@ Excerpt — not a complete module
 - There is no APG pattern for a bar of actions, and the closest official guidance is the Toolbar pattern (w3.org/WAI/ARIA/apg/patterns/toolbar/). This family departs from it deliberately: there is no roving focus, so Tab reaches every action in the order the author wrote it. The controls here are the page’s own form actions, and a reader walking a form expects to arrive at Cancel and then at Save; a composite would make the whole bar one tab stop and put Save behind an arrow key that announces nothing. The cost is written down — a bar of ten icon-only actions is ten tab stops, and that bar is the Toolbar family.
 - The role follows the departure. ARIA 1.2 makes toolbar a subclass of group, and the subclass is what is asserted when there is focus management to declare; without it, group is what is true. The bar names itself with the consumer’s aria-label or aria-labelledby, because only the page knows which task it finishes — and a role written on the host is read with HostAttributeToken before the host binding, so what the consumer wrote survives.
 - The only keyboard this family owns is the overflow trigger’s, and it is the Menu family’s: Enter, Space and ArrowDown open the surface, Escape closes it and returns focus to the trigger. Focus is moved onto the trigger before the action holding it is hidden, so a reader who was on the fifth button lands on the control that now holds it rather than on the document body.
-- The trigger’s accessible name carries the count rather than the mark, so a reader hears “3 more actions” instead of three dots — and an application in another language replaces the sentence rather than translating an ellipsis. The count in the DOM, data-collapsed, is the same fact for a stylesheet or a test.
+- The trigger’s accessible name carries the count rather than the mark, so a reader hears “3 more actions” instead of three dots, in the language in force with its plural (“Mais 3 ações” in pt-BR). The count in the DOM, data-collapsed, is the same fact for a stylesheet or a test.
 - A bar out of action is a fieldset around it: the platform disables every control inside and takes them out of the tab order with it. The family writes no data-disabled and declares no disabled state, because it does not own the capability — a container that refused interaction while its controls still looked operable is the defect the state precedence exists to prevent.
 - A bar that is not present is painted out with display:none once its exit has finished, which takes it out of the accessibility tree and out of the tab order together. Carbon’s batch bar writes aria-hidden on its root instead and leaves the buttons inside reachable by Tab, which puts focus in a region the screen reader announces as absent. Appearing never moves focus either: the bar is not a dialog, and taking focus from a reader who is ticking boxes is exactly the jump a selection bar must not make.
 - Under forced colours the rule between two runs keeps its own paint, because a background flattens to Canvas and would take the boundary between a destructive action and a frequent one with it. Everything else the reader sees belongs to the controls the consumer placed, and each keeps its own states, its own focus ring and its own contrast.
@@ -287,7 +287,7 @@ Excerpt — not a complete module
 
 ### The bar on a phone
 
-Below 24rem of container the run becomes a full-width column with the action that confirms on top, and the collapse stops running — a column has room for everything, so there is no menu. The DOM order does not change, so Tab still reads the form’s order.
+Below 24rem of container a bar with no overflow control becomes a full-width column with the action that confirms on top, and the collapse stops running — a column has room for everything, so there is no menu. A bar with an overflow control keeps one row: the actions without a counterpart stay and the rest fold into the menu. The DOM order does not change, so Tab still reads the form’s order.
 
 Excerpt — not a complete module
 

package/docs/alert.json

@@ -10,6 +10,7 @@
     "tone": [
       "accent",
       "secondary",
+      "info",
       "success",
       "warning",
       "danger"
@@ -120,7 +121,7 @@
       "api": [
         {
           "name": "tone",
-          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "accent",
           "appliesTo": "slAlert",
           "description": "Which of the five semantic colours the message speaks in, and which mark it draws: circle-info, none for secondary, circle-check, circle-alert, circle-x"
@@ -306,6 +307,11 @@
     "--slotted-tone-danger-solid",
     "--slotted-tone-danger-surface",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-border",
+    "--slotted-tone-info-on-solid",
+    "--slotted-tone-info-solid",
+    "--slotted-tone-info-surface",
+    "--slotted-tone-info-text",
     "--slotted-tone-secondary-border",
     "--slotted-tone-secondary-on-solid",
     "--slotted-tone-secondary-solid",

package/docs/alert.md

@@ -48,7 +48,7 @@ Excerpt — not a complete module
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | accent | slAlert | Which of the five semantic colours the message speaks in, and which mark it draws: circle-info, none for secondary, circle-check, circle-alert, circle-x |
+| `tone` | `'accent' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | accent | slAlert | Which of the five semantic colours the message speaks in, and which mark it draws: circle-info, none for secondary, circle-check, circle-alert, circle-x |
 | `variant` | `'soft' \| 'outline' \| 'solid'` | soft | slAlert | How that colour is painted. soft carries the tone’s surface and its border, outline the border alone, solid the tone’s fill and the ink the theme measures against it |
 | `reach` | `'inline' \| 'section' \| 'page'` | section | slAlert | The scope the message applies to. inline is tightest and sits beside a field group; page loses its corners and its inline edges because it runs to both edges of what holds it |
 | `live` | `'off' \| 'polite' \| 'assertive'` | off | slAlert | Whether the text announces itself. polite writes role="status" on the slAlertContent element and assertive writes role="alert"; both imply aria-live and aria-atomic, and neither is written on the box |
@@ -74,7 +74,7 @@ Excerpt — not a complete module
 
 | Axis | Values | Default |
 | --- | --- | --- |
-| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent` |
+| `tone` | `accent`, `secondary`, `info`, `success`, `warning`, `danger` | `accent` |
 | `variant` | `soft`, `outline`, `solid` | `soft` |
 | `reach` | `inline`, `section`, `page` | `section` |
 | `live` | `off`, `polite`, `assertive` | `off` |
@@ -92,7 +92,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-alert-actions-gap`, `--slotted-alert-border-width`, `--slotted-alert-column-gap`, `--slotted-alert-dismiss-radius`, `--slotted-alert-dismiss-size`, `--slotted-alert-font-family`, `--slotted-alert-padding-block`, `--slotted-alert-padding-inline`, `--slotted-alert-radius`, `--slotted-alert-row-gap`, `--slotted-alert-state-layer-active`, `--slotted-alert-state-layer-hover`, `--slotted-alert-text-gap`, `--slotted-alert-title-font-family`, `--slotted-alert-title-font-weight`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+`--slotted-alert-actions-gap`, `--slotted-alert-border-width`, `--slotted-alert-column-gap`, `--slotted-alert-dismiss-radius`, `--slotted-alert-dismiss-size`, `--slotted-alert-font-family`, `--slotted-alert-padding-block`, `--slotted-alert-padding-inline`, `--slotted-alert-radius`, `--slotted-alert-row-gap`, `--slotted-alert-state-layer-active`, `--slotted-alert-state-layer-hover`, `--slotted-alert-text-gap`, `--slotted-alert-title-font-family`, `--slotted-alert-title-font-weight`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-icon-size-lg`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-control-inner-size-lg`, `--slotted-control-inner-size-md`, `--slotted-control-inner-size-sm`, `--slotted-control-radius`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-family-heading`, `--slotted-font-family-sans`, `--slotted-font-weight-semibold`, `--slotted-line-height-md`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-target-comfortable`, `--slotted-target-min`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-info-border`, `--slotted-tone-info-on-solid`, `--slotted-tone-info-solid`, `--slotted-tone-info-surface`, `--slotted-tone-info-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
 
 ## Examples
 

package/docs/app-shell.examples.md

@@ -281,7 +281,7 @@ Excerpt — not a complete module
 
 ### The first thing a keyboard meets
 
-Press Tab from the top of the frame: a link to the content appears, then one to the navigation, then one to the pane — one per region that rendered and is open, out of the flow until focused. The content region carries tabindex="-1", so the link moves the focus as well as the scroll.
+Press Tab from the top of the frame: a link to the content appears, then one to the navigation, then one to the pane — one per region that rendered and is open, out of the flow until focused. The link makes the content region focusable for that one focus, so it moves the focus as well as the scroll.
 
 Excerpt — not a complete module
 

package/docs/app-shell.json

@@ -196,7 +196,7 @@
           "part": "nav",
           "element": "nav",
           "required": false,
-          "purpose": "The navigation landmark, and one element across all three modes: the rail is this nav at another inline size, which keeps the focus and the scroll position where the reader left them. A query container of its own, named slotted-app-shell-nav, so the rows inside answer the rail without the shell telling them anything."
+          "purpose": "The navigation landmark, and one element across all three modes: the rail is this nav at another inline size, which keeps the focus and the scroll position where the reader left them. Its inline axis clips and its block axis scrolls, so a single column taller than the region keeps its foot reachable. A footer that must stay visible goes in nav-footer, between nav-header and a nav-body that scrolls. A query container of its own, named slotted-app-shell-nav, so the rows inside answer the rail without the shell telling them anything."
         },
         {
           "part": "nav-rail",
@@ -230,9 +230,9 @@
         },
         {
           "part": "main",
-          "element": "main with tabindex=\"-1\"",
+          "element": "main",
           "required": true,
-          "purpose": "The main landmark and the skip link’s destination. Without the tabindex the link moves the scroll and leaves the focus behind, in Safari and in Firefox."
+          "purpose": "The main landmark and the skip link’s destination. The skip link and focusMain() write tabindex=\"-1\" for the focus they move, and blur or the next pointer press inside removes it: a main focusable all the time takes the focus of every click on its text, and the next key draws the ring around the page."
         },
         {
           "part": "progress",
@@ -559,7 +559,7 @@
         "The structure is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/), and every one of the five is earned from the element rather than written as a role: header in the context of the body is banner, nav is navigation, main is main, aside is complementary, footer is contentinfo. The root is a div for exactly that reason — a main inside a sectioning element stops being a landmark, and the shell has to be placeable anywhere.",
         "Both controls are the APG’s Disclosure pattern (w3.org/WAI/ARIA/apg/patterns/disclosure/): real buttons, so Enter and Space activate them natively, carrying aria-expanded and aria-controls pointing at their region. One departure is written and costed: under collapsedTo=\"rail\" the navigation does not disappear, it narrows — aria-expanded is still true or false about the region’s full form, and the region stays in the tab order because a rail whose destinations cannot be reached is not a rail. The pane has no such departure: closed, it leaves the layout and the tab order.",
         "A document with more than one navigation or complementary landmark needs a unique label on each, so both regions carry the family’s strings and a consumer may replace either per instance. Each control’s own name changes with the state — “Open navigation” and “Close navigation”, “Open side panel” and “Close side panel” — because a control whose name never changes leaves the reader to infer the state from aria-expanded alone.",
-        "The skip links are written from the regions that rendered and are open, so no link ever points at a target nobody built or the reader closed, and main carries tabindex=\"-1\": without it the browser moves the scroll and leaves the focus behind in Safari and Firefox, which is a link that appears to work and moves nothing a screen reader follows.",
+        "The skip links are written from the regions that rendered and are open, so no link ever points at a target nobody built or the reader closed, and the main link writes tabindex=\"-1\" on main before it moves the focus: without it the browser moves the scroll and leaves the focus behind in Safari and Firefox. Blur or the next pointer press inside removes the attribute, so a click on the content never focuses main.",
         "While an overlaid region is modal, @slotted/core/focus contains the keyboard inside it and returns it to the control that opened it on close, and every region beside it — the banner included — takes inert, so Tab cannot reach them and a screen reader does not read them. The ways out are Escape, the veil, a destination, and whatever control the product put in the panel. Two layers can be open together only with both modes forced, and @slotted/core/dismissable-layer keeps one stack, so Escape reaches the topmost.",
         "The pane’s edge is the APG’s Window Splitter (w3.org/WAI/ARIA/apg/patterns/windowsplitter/): a focusable separator with aria-orientation=\"vertical\", aria-controls pointing at the pane and aria-valuemin, aria-valuemax and aria-valuenow as whole percentages of the shell, named “Resize panel”. ArrowLeft and ArrowRight move it sixteen pixels, sixty-four with Shift, by the direction on the screen — so ArrowLeft grows an end pane and shrinks a start one, mirrored in right-to-left — and Home and End go to the limits.",
         "Nothing important depends on hover, the frame answers its own inline size rather than the window’s — which is what makes a 400% zoom behave like a narrow window — and every transition comes from the motion scale, so prefers-reduced-motion collapses all of them at once."
@@ -786,7 +786,7 @@
     {
       "id": "skipLinks",
       "title": "The first thing a keyboard meets",
-      "note": "Press Tab from the top of the frame: a link to the content appears, then one to the navigation, then one to the pane — one per region that rendered and is open, out of the flow until focused. The content region carries tabindex=\"-1\", so the link moves the focus as well as the scroll.",
+      "note": "Press Tab from the top of the frame: a link to the content appears, then one to the navigation, then one to the pane — one per region that rendered and is open, out of the flow until focused. The link makes the content region focusable for that one focus, so it moves the focus as well as the scroll.",
       "language": "html",
       "source": "<div slAppShell [messages]=\"{ skipToMain: 'Skip to the order' }\">\n  <main slAppShellMain>…</main>\n</div>\n",
       "verdict": "excerpt"

package/docs/app-shell.md

@@ -116,7 +116,7 @@ export class AppShellBasic {}
 | `nav-body` | div | no |
 | `nav-footer` | div | no |
 | `scrim` | div | no |
-| `main` | main with tabindex="-1" | yes |
+| `main` | main | yes |
 | `progress` | the consumer’s element, holding one [slProgressBar] at placement="edge-start" | no |
 | `aside` | aside | no |
 | `aside-resizer` | any element carrying slAppShellAsideResizer | no |
@@ -200,7 +200,7 @@ export class AppShellBasic {}
 - The structure is the WAI-ARIA APG’s Landmark Regions (w3.org/WAI/ARIA/apg/practices/landmark-regions/), and every one of the five is earned from the element rather than written as a role: header in the context of the body is banner, nav is navigation, main is main, aside is complementary, footer is contentinfo. The root is a div for exactly that reason — a main inside a sectioning element stops being a landmark, and the shell has to be placeable anywhere.
 - Both controls are the APG’s Disclosure pattern (w3.org/WAI/ARIA/apg/patterns/disclosure/): real buttons, so Enter and Space activate them natively, carrying aria-expanded and aria-controls pointing at their region. One departure is written and costed: under collapsedTo="rail" the navigation does not disappear, it narrows — aria-expanded is still true or false about the region’s full form, and the region stays in the tab order because a rail whose destinations cannot be reached is not a rail. The pane has no such departure: closed, it leaves the layout and the tab order.
 - A document with more than one navigation or complementary landmark needs a unique label on each, so both regions carry the family’s strings and a consumer may replace either per instance. Each control’s own name changes with the state — “Open navigation” and “Close navigation”, “Open side panel” and “Close side panel” — because a control whose name never changes leaves the reader to infer the state from aria-expanded alone.
-- The skip links are written from the regions that rendered and are open, so no link ever points at a target nobody built or the reader closed, and main carries tabindex="-1": without it the browser moves the scroll and leaves the focus behind in Safari and Firefox, which is a link that appears to work and moves nothing a screen reader follows.
+- The skip links are written from the regions that rendered and are open, so no link ever points at a target nobody built or the reader closed, and the main link writes tabindex="-1" on main before it moves the focus: without it the browser moves the scroll and leaves the focus behind in Safari and Firefox. Blur or the next pointer press inside removes the attribute, so a click on the content never focuses main.
 - While an overlaid region is modal, @slotted/core/focus contains the keyboard inside it and returns it to the control that opened it on close, and every region beside it — the banner included — takes inert, so Tab cannot reach them and a screen reader does not read them. The ways out are Escape, the veil, a destination, and whatever control the product put in the panel. Two layers can be open together only with both modes forced, and @slotted/core/dismissable-layer keeps one stack, so Escape reaches the topmost.
 - The pane’s edge is the APG’s Window Splitter (w3.org/WAI/ARIA/apg/patterns/windowsplitter/): a focusable separator with aria-orientation="vertical", aria-controls pointing at the pane and aria-valuemin, aria-valuemax and aria-valuenow as whole percentages of the shell, named “Resize panel”. ArrowLeft and ArrowRight move it sixteen pixels, sixty-four with Shift, by the direction on the screen — so ArrowLeft grows an end pane and shrinks a start one, mirrored in right-to-left — and Home and End go to the limits.
 - Nothing important depends on hover, the frame answers its own inline size rather than the window’s — which is what makes a 400% zoom behave like a narrow window — and every transition comes from the motion scale, so prefers-reduced-motion collapses all of them at once.

package/docs/avatar.json

@@ -22,6 +22,7 @@
       "auto",
       "accent",
       "secondary",
+      "info",
       "success",
       "warning",
       "danger"
@@ -30,6 +31,11 @@
       "soft",
       "solid"
     ],
+    "surface": [
+      "tone",
+      "none",
+      "plate"
+    ],
     "status": [
       "idle",
       "loading",
@@ -45,6 +51,7 @@
         "shape": "circle",
         "tone": "auto",
         "variant": "soft",
+        "surface": "tone",
         "decorative": false,
         "disabled": false
       },
@@ -97,7 +104,7 @@
         },
         {
           "name": "tone",
-          "type": "'auto' | 'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'auto' | 'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "auto",
           "appliesTo": "slAvatar",
           "description": "Which of the five semantic colours the fallback is painted in. auto derives it from the name"
@@ -116,6 +123,13 @@
           "appliesTo": "slAvatar",
           "description": "How that colour is painted: tinted, or filled"
         },
+        {
+          "name": "surface",
+          "type": "'tone' | 'none' | 'plate'",
+          "defaultValue": "tone",
+          "appliesTo": "slAvatar",
+          "description": "The ground behind the avatar: the tone behind the fallback and nothing behind a loaded picture; nothing at all; or a light plate in every scheme, for a logo made for a white ground (--slotted-avatar-plate-surface)"
+        },
         {
           "name": "size",
           "type": "'xs' | 'sm' | 'md' | 'lg' | 'xl'",
@@ -217,6 +231,8 @@
     "--slotted-avatar-font-weight",
     "--slotted-avatar-glyph-size",
     "--slotted-avatar-initials-size",
+    "--slotted-avatar-plate-color",
+    "--slotted-avatar-plate-surface",
     "--slotted-avatar-radius",
     "--slotted-avatar-ring-color",
     "--slotted-avatar-ring-width",
@@ -257,6 +273,11 @@
     "--slotted-tone-danger-solid",
     "--slotted-tone-danger-surface",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-border",
+    "--slotted-tone-info-on-solid",
+    "--slotted-tone-info-solid",
+    "--slotted-tone-info-surface",
+    "--slotted-tone-info-text",
     "--slotted-tone-secondary-border",
     "--slotted-tone-secondary-on-solid",
     "--slotted-tone-secondary-solid-hover",

package/docs/avatar.md

@@ -18,9 +18,10 @@ Excerpt — not a complete module
 | `name` | `string` | — | slAvatar | The person or entity. It is the accessible name in every status, the source of the initials, and the seed of the colour |
 | `src` | `string` | — | slAvatar | The picture the component renders itself. Project an img slAvatarImage instead when the element must be yours |
 | `initials` | `string` | — | slAvatar | The letters to draw, in place of the ones derived from the name |
-| `tone` | `'auto' \| 'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | auto | slAvatar | Which of the five semantic colours the fallback is painted in. auto derives it from the name |
+| `tone` | `'auto' \| 'accent' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | auto | slAvatar | Which of the five semantic colours the fallback is painted in. auto derives it from the name |
 | `idFor` | `string` | — | slAvatar | A stable identifier to derive the colour from, when the name is not stable or two people share one |
 | `variant` | `'soft' \| 'solid'` | soft | slAvatar | How that colour is painted: tinted, or filled |
+| `surface` | `'tone' \| 'none' \| 'plate'` | tone | slAvatar | The ground behind the avatar: the tone behind the fallback and nothing behind a loaded picture; nothing at all; or a light plate in every scheme, for a logo made for a white ground (--slotted-avatar-plate-surface) |
 | `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | md | slAvatar | Five steps, each of which answers density. --slotted-avatar-size states a size no step holds |
 | `shape` | `'circle' \| 'square'` | circle | slAvatar | A circle is a person; a square is a team, an organisation or a bot |
 | `status` | `'idle' \| 'loading' \| 'loaded' \| 'error'` | — | slAvatar | Where the picture is. Supplied, it wins over what the component derives from the element |
@@ -39,8 +40,9 @@ Excerpt — not a complete module
 | --- | --- | --- |
 | `size` | `xs`, `sm`, `md`, `lg`, `xl` | `md` |
 | `shape` | `circle`, `square` | `circle` |
-| `tone` | `auto`, `accent`, `secondary`, `success`, `warning`, `danger` | `auto` |
+| `tone` | `auto`, `accent`, `secondary`, `info`, `success`, `warning`, `danger` | `auto` |
 | `variant` | `soft`, `solid` | `soft` |
+| `surface` | `tone`, `none`, `plate` | `tone` |
 | `status` | `idle`, `loading`, `loaded`, `error` | — |
 
 ## Rules
@@ -57,7 +59,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-avatar-border-width`, `--slotted-avatar-disabled-image-filter`, `--slotted-avatar-elevation`, `--slotted-avatar-font-family`, `--slotted-avatar-font-weight`, `--slotted-avatar-glyph-size`, `--slotted-avatar-initials-size`, `--slotted-avatar-radius`, `--slotted-avatar-ring-color`, `--slotted-avatar-ring-width`, `--slotted-avatar-size`, `--slotted-avatar-size-lg`, `--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xl`, `--slotted-avatar-size-xs`, `--slotted-avatar-state-layer-active`, `--slotted-avatar-state-layer-hover`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-radius-full`, `--slotted-surface`, `--slotted-target-min`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+`--slotted-avatar-border-width`, `--slotted-avatar-disabled-image-filter`, `--slotted-avatar-elevation`, `--slotted-avatar-font-family`, `--slotted-avatar-font-weight`, `--slotted-avatar-glyph-size`, `--slotted-avatar-initials-size`, `--slotted-avatar-plate-color`, `--slotted-avatar-plate-surface`, `--slotted-avatar-radius`, `--slotted-avatar-ring-color`, `--slotted-avatar-ring-width`, `--slotted-avatar-size`, `--slotted-avatar-size-lg`, `--slotted-avatar-size-md`, `--slotted-avatar-size-sm`, `--slotted-avatar-size-xl`, `--slotted-avatar-size-xs`, `--slotted-avatar-state-layer-active`, `--slotted-avatar-state-layer-hover`, `--slotted-border-strong`, `--slotted-border-subtle`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-duration-short`, `--slotted-easing-enter`, `--slotted-easing-exit`, `--slotted-easing-standard`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-radius-full`, `--slotted-surface`, `--slotted-target-min`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-info-border`, `--slotted-tone-info-on-solid`, `--slotted-tone-info-solid`, `--slotted-tone-info-surface`, `--slotted-tone-info-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
 
 ## Examples
 

package/docs/badge.json

@@ -10,6 +10,7 @@
     "tone": [
       "accent",
       "secondary",
+      "info",
       "success",
       "warning",
       "danger"
@@ -88,7 +89,7 @@
       "api": [
         {
           "name": "tone",
-          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "type": "'accent' | 'secondary' | 'info' | 'success' | 'warning' | 'danger'",
           "defaultValue": "secondary",
           "appliesTo": "slBadge",
           "description": "Which of the five semantic colours the badge speaks in"
@@ -257,6 +258,11 @@
     "--slotted-tone-danger-solid",
     "--slotted-tone-danger-surface",
     "--slotted-tone-danger-text",
+    "--slotted-tone-info-border",
+    "--slotted-tone-info-on-solid",
+    "--slotted-tone-info-solid",
+    "--slotted-tone-info-surface",
+    "--slotted-tone-info-text",
     "--slotted-tone-secondary-border",
     "--slotted-tone-secondary-on-solid",
     "--slotted-tone-secondary-solid-hover",

package/docs/badge.md

@@ -15,7 +15,7 @@ Excerpt — not a complete module
 
 | Name | Type | Default | Applies to | Description |
 | --- | --- | --- | --- | --- |
-| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | secondary | slBadge | Which of the five semantic colours the badge speaks in |
+| `tone` | `'accent' \| 'secondary' \| 'info' \| 'success' \| 'warning' \| 'danger'` | secondary | slBadge | Which of the five semantic colours the badge speaks in |
 | `variant` | `'solid' \| 'soft' \| 'outline'` | soft | slBadge | How that colour is painted: filled, tinted, or an edge alone. All three draw the same tone edge |
 | `size` | `'sm' \| 'md' \| 'lg'` | md | slBadge | Type and glyph come from the control scale, so a badge shrinks with density beside the controls it sits with |
 | `shape` | `'pill' \| 'square' \| 'dot'` | pill | slBadge | A dot is the same badge, tone and hidden text, drawn without a value |
@@ -36,7 +36,7 @@ Excerpt — not a complete module
 
 | Axis | Values | Default |
 | --- | --- | --- |
-| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `secondary` |
+| `tone` | `accent`, `secondary`, `info`, `success`, `warning`, `danger` | `secondary` |
 | `variant` | `solid`, `soft`, `outline` | `soft` |
 | `size` | `sm`, `md`, `lg` | `md` |
 | `shape` | `pill`, `square`, `dot` | `pill` |
@@ -59,7 +59,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-badge-anchor-offset-x`, `--slotted-badge-anchor-offset-y`, `--slotted-badge-border-width`, `--slotted-badge-dot-border-color`, `--slotted-badge-font-family`, `--slotted-badge-font-weight`, `--slotted-badge-radius`, `--slotted-badge-ring-color`, `--slotted-badge-ring-width`, `--slotted-border-strong`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
+`--slotted-badge-anchor-offset-x`, `--slotted-badge-anchor-offset-y`, `--slotted-badge-border-width`, `--slotted-badge-dot-border-color`, `--slotted-badge-font-family`, `--slotted-badge-font-weight`, `--slotted-badge-radius`, `--slotted-badge-ring-color`, `--slotted-badge-ring-width`, `--slotted-border-strong`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-icon-size-md`, `--slotted-control-icon-size-sm`, `--slotted-focus-ring-color`, `--slotted-focus-ring-offset`, `--slotted-focus-ring-width`, `--slotted-font-weight-medium`, `--slotted-line-height-xs`, `--slotted-radius-full`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-surface`, `--slotted-tone-accent-border`, `--slotted-tone-accent-on-solid`, `--slotted-tone-accent-solid`, `--slotted-tone-accent-surface`, `--slotted-tone-accent-text`, `--slotted-tone-danger-border`, `--slotted-tone-danger-on-solid`, `--slotted-tone-danger-solid`, `--slotted-tone-danger-surface`, `--slotted-tone-danger-text`, `--slotted-tone-info-border`, `--slotted-tone-info-on-solid`, `--slotted-tone-info-solid`, `--slotted-tone-info-surface`, `--slotted-tone-info-text`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-on-solid`, `--slotted-tone-secondary-solid-hover`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`, `--slotted-tone-success-border`, `--slotted-tone-success-on-solid`, `--slotted-tone-success-solid`, `--slotted-tone-success-surface`, `--slotted-tone-success-text`, `--slotted-tone-warning-border`, `--slotted-tone-warning-on-solid`, `--slotted-tone-warning-solid`, `--slotted-tone-warning-surface`, `--slotted-tone-warning-text`
 
 ## Examples
 

package/docs/button-group.json

@@ -133,6 +133,8 @@
     "--slotted-text-muted",
     "--slotted-tone-accent-solid-active",
     "--slotted-tone-danger-solid-active",
+    "--slotted-tone-info-solid-active",
+    "--slotted-tone-neutral-solid-active",
     "--slotted-tone-secondary-solid-active",
     "--slotted-tone-success-solid-active",
     "--slotted-tone-warning-solid-active"

package/docs/button-group.md

@@ -50,7 +50,7 @@ Excerpt — not a complete module
 
 ## Tokens
 
-`--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-radius`, `--slotted-text-muted`, `--slotted-tone-accent-solid-active`, `--slotted-tone-danger-solid-active`, `--slotted-tone-secondary-solid-active`, `--slotted-tone-success-solid-active`, `--slotted-tone-warning-solid-active`
+`--slotted-control-border-color`, `--slotted-control-border-width`, `--slotted-control-radius`, `--slotted-text-muted`, `--slotted-tone-accent-solid-active`, `--slotted-tone-danger-solid-active`, `--slotted-tone-info-solid-active`, `--slotted-tone-neutral-solid-active`, `--slotted-tone-secondary-solid-active`, `--slotted-tone-success-solid-active`, `--slotted-tone-warning-solid-active`
 
 ## Examples