@slotted/react 0.0.0-stage → 0.1.0-beta.0

package/dist/docs/alert.json

@@ -0,0 +1,405 @@
+{
+  "family": "alert",
+  "ui": "alert",
+  "binding": "react",
+  "catalog": {
+    "group": "Feedback",
+    "summary": "Static message with a tone, icon and actions."
+  },
+  "axes": {
+    "tone": [
+      "accent",
+      "secondary",
+      "success",
+      "warning",
+      "danger"
+    ],
+    "variant": [
+      "soft",
+      "outline",
+      "solid"
+    ],
+    "reach": [
+      "inline",
+      "section",
+      "page"
+    ],
+    "live": [
+      "off",
+      "polite",
+      "assertive"
+    ]
+  },
+  "members": {
+    "alert": {
+      "nativeElement": "section",
+      "defaults": {
+        "tone": "accent",
+        "variant": "soft",
+        "reach": "section",
+        "live": "off",
+        "hideIcon": false,
+        "dismissible": false,
+        "defaultOpen": true,
+        "restoreFocus": true
+      },
+      "capabilities": [
+        "appearance",
+        "live",
+        "open"
+      ],
+      "states": [
+        "default",
+        "hover",
+        "active",
+        "focus-visible",
+        "open"
+      ],
+      "parts": [
+        "root",
+        "icon",
+        "content",
+        "title",
+        "description",
+        "actions",
+        "dismiss"
+      ]
+    }
+  },
+  "docs": {
+    "alert": {
+      "imports": {
+        "source": "import {\n  Alert,\n  AlertActions,\n  AlertContent,\n  AlertDefaultsProvider,\n  AlertDescription,\n  AlertTitle,\n} from '@slotted/react';"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "section",
+          "required": true,
+          "purpose": "The box. Carries data-ui=\"alert\", the four axes, data-open, hidden when closed, and tabindex=\"-1\". A section named by its own title is a region landmark; unnamed it is a plain grouping element."
+        },
+        {
+          "part": "icon",
+          "element": "span",
+          "required": false,
+          "purpose": "The tone’s mark, drawn as a mask from the foundation’s status glyph set and hidden from assistive technology. Absent when hideIcon; holds the page’s own artwork when icon is passed."
+        },
+        {
+          "part": "content",
+          "element": "div",
+          "required": true,
+          "purpose": "The title and the description, and nothing else. This is the live region: role=\"status\" or role=\"alert\" is written here, so the controls beside it are outside what a reader hears."
+        },
+        {
+          "part": "title",
+          "element": "div, or the element render returns",
+          "required": false,
+          "purpose": "The message’s name, and the box’s: the root points aria-labelledby at it. A div by default, because a heading belongs in the document outline and only the page knows whether this message does."
+        },
+        {
+          "part": "description",
+          "element": "p, or the element render returns",
+          "required": false,
+          "purpose": "The message. It breaks a string no language can break — a digest, a host name — rather than overflowing, and removes nothing from the DOM to do it."
+        },
+        {
+          "part": "actions",
+          "element": "div",
+          "required": false,
+          "purpose": "The controls that act on the message, outside the live region. They stack at a narrow container width, and rejoin the message’s own line on a page banner past 40rem."
+        },
+        {
+          "part": "dismiss",
+          "element": "button",
+          "required": false,
+          "purpose": "Closes the message. Rendered when dismissible, named by the catalog’s dismiss, and sized from its glyph plus a step of air, floored at the WCAG 2.2 minimum so the target holds at every density (R2)."
+        }
+      ],
+      "api": [
+        {
+          "name": "tone",
+          "type": "'accent' | 'secondary' | 'success' | 'warning' | 'danger'",
+          "defaultValue": "accent",
+          "appliesTo": "Alert",
+          "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"
+        },
+        {
+          "name": "variant",
+          "type": "'soft' | 'outline' | 'solid'",
+          "defaultValue": "soft",
+          "appliesTo": "Alert",
+          "description": "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"
+        },
+        {
+          "name": "reach",
+          "type": "'inline' | 'section' | 'page'",
+          "defaultValue": "section",
+          "appliesTo": "Alert",
+          "description": "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"
+        },
+        {
+          "name": "live",
+          "type": "'off' | 'polite' | 'assertive'",
+          "defaultValue": "off",
+          "appliesTo": "Alert",
+          "description": "Whether the text announces itself. polite writes role=\"status\" on the content part and assertive writes role=\"alert\"; both imply aria-live and aria-atomic, and neither is written on the box"
+        },
+        {
+          "name": "hideIcon",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Alert",
+          "description": "Draws no mark at all, for a callout that carries its own artwork in the body"
+        },
+        {
+          "name": "icon",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Alert",
+          "description": "Replaces the tone’s mark, keeping the box, the size and the place on the message’s first line. Angular projects an element carrying slAlertIcon instead"
+        },
+        {
+          "name": "dismissible",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "Alert",
+          "description": "Renders the control that closes the message. A critical banner should not have one: the guide’s rule is that it does not go away on its own"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<AlertMessages>",
+          "defaultValue": "—",
+          "appliesTo": "Alert",
+          "description": "Words laid over the language in force, key by key: what that control announces (dismiss)"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "Alert",
+          "description": "The openness the consumer owns. Passing it puts the alert in controlled mode for good, and the family then only asks"
+        },
+        {
+          "name": "defaultOpen",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Alert",
+          "description": "The openness an uncontrolled alert starts from, read once. A later change to it is not silently adopted"
+        },
+        {
+          "name": "restoreFocus",
+          "type": "boolean",
+          "defaultValue": "true",
+          "appliesTo": "Alert",
+          "description": "Returns the keyboard to the element it came from when the message closes with focus inside it. Nothing moves when focus was never there"
+        }
+      ],
+      "composition": [
+        {
+          "name": "render",
+          "type": "(props) => ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "Alert, AlertContent, AlertTitle, AlertDescription, AlertActions",
+          "description": "Substitutes the rendered element of a part, and hands it every data attribute. A title rendered as a heading is how a page puts the message in its outline"
+        },
+        {
+          "name": "ref",
+          "type": "Ref<HTMLElement>",
+          "defaultValue": "—",
+          "appliesTo": "Alert",
+          "description": "Reaches the section, which carries tabindex=\"-1\" so focus() works. There is no imperative handle beyond it: the family never moves focus on its own, because the APG says an alert must not"
+        },
+        {
+          "name": "AlertDefaultsProvider",
+          "type": "{ tone, variant, reach, live }",
+          "defaultValue": "—",
+          "appliesTo": "a subtree",
+          "description": "Sets all four once for every alert under it; an explicit prop on one message still wins"
+        },
+        {
+          "name": "children",
+          "type": "ReactNode",
+          "defaultValue": "—",
+          "appliesTo": "AlertContent",
+          "description": "The title and the description. Anything else placed here joins the live region, which is why the actions are a part of their own"
+        }
+      ],
+      "events": [
+        {
+          "name": "onOpenChange",
+          "payload": "open: boolean, request: ChangeRequest<boolean>",
+          "when": "The dismiss control is activated. request.reason is dismiss, request.source is the click event, and request.cancel() refuses the change — the message stays open and the keyboard stays where it is. Nothing is emitted when the consumer moves open themselves."
+        }
+      ],
+      "accessibility": [
+        "The applicable pattern is the WAI-ARIA APG Alert Pattern (w3.org/WAI/ARIA/apg/patterns/alert/). It declares one role and no keyboard interaction: an alert is not a widget, so it holds no keys. Its two prose requirements — that an alert must not affect keyboard focus, and must not disappear on its own — are what this family declines automatic focus and automatic dismissal for.",
+        "The box is a landmark, not a live region. MDN’s alert role reference states that the role “should only be used for text content, not interactive elements such as links or buttons”, and every alert worth shipping has a dismiss control. The root renders a section named by its own title through aria-labelledby, and the region that announces is the content part, which holds the title and the description alone.",
+        "live defaults to off because the APG records that “screen readers do not inform users of alerts that are present on the page before page load completes”. An alert already on the page announces nothing whatever role it carries; polite and assertive are for a message that arrives while the reader is working, and both are written as a role that already implies aria-live and aria-atomic.",
+        "Every tone with a severity carries a mark as well as a colour, and secondary carries none: a neutral note has no severity to state. Under forced colours the five grounds become one system colour and the five borders one more, so the mark, and its absence on a note, is the only thing distinguishing an error from a note — WCAG 2.2 1.4.1.",
+        "The dismiss control is a real button with a real name and an inner control rather than a Button (R2): its box is the glyph plus a step of air on each side, floored at --slotted-target-min, which is the WCAG 2.2 2.5.8 minimum of 24 CSS pixels; at rest it has no frame and no ground, and hover moves only the ground.",
+        "When the message closes with focus inside it, the keyboard goes back to the element it came from. None of the ten surveyed implementations answers this, and the failure it prevents is the one a real product hits first: the dismiss control is destroyed, focus falls to the document body, and the next Tab starts again at the top of the page.",
+        "Closing hides rather than unmounts, so the live region is still in the document if the message comes back and data-open is a state a consumer can style. An application that must not pay for the hidden subtree renders the alert conditionally and never passes defaultOpen.",
+        "Escape does not close the message. An alert is not a dismissable layer, and one inside a dialog would swallow the dialog’s own Escape; a message that must interrupt the reader is an alert dialog rather than an alert."
+      ]
+    }
+  },
+  "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"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One message with every axis on it, driven by the controls below the canvas. Change the tone and the mark changes with it, which is what makes the five distinguishable in greyscale.",
+      "language": "tsx",
+      "source": "<Alert tone=\"warning\">\n  <AlertContent>\n    <AlertTitle>Sua assinatura expira em três dias</AlertTitle>\n    <AlertDescription>Renove para manter o acesso da equipe.</AlertDescription>\n  </AlertContent>\n</Alert>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "tones",
+      "title": "What the message is about",
+      "note": "Five tones and five marks. The mark is the answer to WCAG 2.2 1.4.1: read in greyscale, or under forced colours where every ground becomes one system colour, the silhouette is the only thing left.",
+      "language": "tsx",
+      "source": "// accent is information, secondary a neutral note, success something\n// finished, warning something that needs attention, danger something failed.\n<Alert tone=\"danger\">\n  <AlertContent>\n    <AlertTitle>Não foi possível salvar</AlertTitle>\n  </AlertContent>\n</Alert>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "How that tone is painted",
+      "note": "soft and solid bring a ground with them and survive any surface; outline takes the one underneath, so it reads on the page’s own surfaces and goes quiet on a ground the theme never measured its ink against.",
+      "language": "tsx",
+      "source": "<Alert variant=\"soft\" />;\n<Alert variant=\"outline\" />;\n<Alert variant=\"solid\" />;\n\n// A dark region is a scheme rather than a surface.\n<div data-slotted-scheme=\"dark\">\n  <Alert variant=\"outline\" />\n</div>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "reach",
+      "title": "How far the message reaches",
+      "note": "The guide’s three recipes as one axis: inline beside the thing it is about, section inside a page section, page across an application. A page banner loses its corners because it runs to both edges.",
+      "language": "tsx",
+      "source": "<Alert reach=\"inline\" tone=\"danger\">\n  <AlertContent>\n    <AlertDescription>Informe um CNPJ válido.</AlertDescription>\n  </AlertContent>\n</Alert>;\n\n<Alert reach=\"page\" tone=\"warning\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "dismissal",
+      "title": "Putting the message away",
+      "note": "The left one owns its own openness and needs no state at all; the right one hands it to the application, which can refuse the request. Watch where the keyboard lands after either of them closes.",
+      "language": "tsx",
+      "source": "<Alert dismissible />;\n\n<Alert dismissible onOpenChange={setOpen} open={open} />;\n\n<Alert\n  dismissible\n  onOpenChange={(next, request) => {\n    if (!confirmed) request.cancel();\n  }}\n/>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "actions",
+      "title": "What the message asks for",
+      "note": "The controls are the consumer’s own Buttons, in a part outside the live region — a reader hearing the message is not read two button labels in the middle of it. They stack when the box is narrow.",
+      "language": "tsx",
+      "source": "<Alert tone=\"warning\">\n  <AlertContent>\n    <AlertTitle>Sua assinatura expira em três dias</AlertTitle>\n  </AlertContent>\n  <AlertActions>\n    <Button size=\"sm\" tone=\"warning\">\n      Renovar\n    </Button>\n    <Button size=\"sm\" tone=\"warning\" variant=\"ghost\">\n      Ver planos\n    </Button>\n  </AlertActions>\n</Alert>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "live",
+      "title": "What a reader hears, and when",
+      "note": "off by default, because the APG records that alerts already on the page when it loads are not announced at all. Press the button and the message arrives while the reader is elsewhere, which is what polite and assertive are for.",
+      "language": "tsx",
+      "source": "// role=\"status\" on the text, which implies aria-live and aria-atomic.\n<Alert live=\"polite\" tone=\"success\" />;\n\n// role=\"alert\": a failed save, a lost connection, an expiring session.\n<Alert live=\"assertive\" tone=\"danger\" />;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "A German compound that wraps, a container digest with no break opportunity, a message with no mark, and a title standing alone — all in a column narrow enough to make each of them a problem.",
+      "language": "tsx",
+      "source": "<Alert hideIcon>\n  <AlertContent>\n    <AlertTitle>O deploy falhou</AlertTitle>\n    <AlertDescription>{digest}</AlertDescription>\n  </AlertContent>\n</Alert>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "The provider sets the defaults once, render substitutes the element of any part, icon replaces the mark, and ref reaches the section so a page that must move focus to the message can.",
+      "language": "tsx",
+      "source": "<AlertDefaultsProvider reach=\"page\">\n  <App />\n</AlertDefaultsProvider>;\n\n<Alert icon={<ShieldIcon />} render={(props) => <aside {...props} />}>\n  <AlertContent>\n    <AlertTitle render={(props) => <h3 {...props} />}>Manutenção</AlertTitle>\n  </AlertContent>\n</Alert>;\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "The landmark, the region and the keyboard",
+      "note": "Tab into the message and out of it: the box is a region a reader can jump to, the text is the only thing that announces, and closing the message puts the keyboard back where it came from.",
+      "language": "tsx",
+      "source": "// A region landmark named \"Manutenção\", holding a polite status region.\n<Alert live=\"polite\">\n  <AlertContent>\n    <AlertTitle>Manutenção</AlertTitle>\n  </AlertContent>\n</Alert>;\n\n// No title: a plain grouping element, and no landmark to jump to.\n<Alert>\n  <AlertContent>Pronto.</AlertContent>\n</Alert>;\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/dist/docs/alert.md

@@ -0,0 +1,251 @@
+<!-- index: ./index.md -->
+# alert
+
+`data-ui="alert"` · Static message with a tone, icon and actions.
+
+## Import
+
+```tsx
+import {
+  Alert,
+  AlertActions,
+  AlertContent,
+  AlertDefaultsProvider,
+  AlertDescription,
+  AlertTitle,
+} from '@slotted/react';
+```
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```tsx
+<Alert tone="warning">
+  <AlertContent>
+    <AlertTitle>Sua assinatura expira em três dias</AlertTitle>
+    <AlertDescription>Renove para manter o acesso da equipe.</AlertDescription>
+  </AlertContent>
+</Alert>;
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | section | yes |
+| `icon` | span | no |
+| `content` | div | yes |
+| `title` | div, or the element render returns | no |
+| `description` | p, or the element render returns | no |
+| `actions` | div | no |
+| `dismiss` | button | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `tone` | `'accent' \| 'secondary' \| 'success' \| 'warning' \| 'danger'` | accent | Alert | 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 | Alert | 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 | Alert | 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 | Alert | Whether the text announces itself. polite writes role="status" on the content part and assertive writes role="alert"; both imply aria-live and aria-atomic, and neither is written on the box |
+| `hideIcon` | `boolean` | false | Alert | Draws no mark at all, for a callout that carries its own artwork in the body |
+| `icon` | `ReactNode` | — | Alert | Replaces the tone’s mark, keeping the box, the size and the place on the message’s first line. Angular projects an element carrying slAlertIcon instead |
+| `dismissible` | `boolean` | false | Alert | Renders the control that closes the message. A critical banner should not have one: the guide’s rule is that it does not go away on its own |
+| `messages` | `Partial<AlertMessages>` | — | Alert | Words laid over the language in force, key by key: what that control announces (dismiss) |
+| `open` | `boolean` | — | Alert | The openness the consumer owns. Passing it puts the alert in controlled mode for good, and the family then only asks |
+| `defaultOpen` | `boolean` | true | Alert | The openness an uncontrolled alert starts from, read once. A later change to it is not silently adopted |
+| `restoreFocus` | `boolean` | true | Alert | Returns the keyboard to the element it came from when the message closes with focus inside it. Nothing moves when focus was never there |
+| `render` | `(props) => ReactNode` | — | Alert, AlertContent, AlertTitle, AlertDescription, AlertActions | Substitutes the rendered element of a part, and hands it every data attribute. A title rendered as a heading is how a page puts the message in its outline |
+| `ref` | `Ref<HTMLElement>` | — | Alert | Reaches the section, which carries tabindex="-1" so focus() works. There is no imperative handle beyond it: the family never moves focus on its own, because the APG says an alert must not |
+| `AlertDefaultsProvider` | `{ tone, variant, reach, live }` | — | a subtree | Sets all four once for every alert under it; an explicit prop on one message still wins |
+| `children` | `ReactNode` | — | AlertContent | The title and the description. Anything else placed here joins the live region, which is why the actions are a part of their own |
+
+## Events
+
+| Name | Payload | When |
+| --- | --- | --- |
+| `onOpenChange` | `open: boolean, request: ChangeRequest<boolean>` | The dismiss control is activated. request.reason is dismiss, request.source is the click event, and request.cancel() refuses the change — the message stays open and the keyboard stays where it is. Nothing is emitted when the consumer moves open themselves. |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `tone` | `accent`, `secondary`, `success`, `warning`, `danger` | `accent` |
+| `variant` | `soft`, `outline`, `solid` | `soft` |
+| `reach` | `inline`, `section`, `page` | `section` |
+| `live` | `off`, `polite`, `assertive` | `off` |
+
+## Rules
+
+- The applicable pattern is the WAI-ARIA APG Alert Pattern (w3.org/WAI/ARIA/apg/patterns/alert/). It declares one role and no keyboard interaction: an alert is not a widget, so it holds no keys. Its two prose requirements — that an alert must not affect keyboard focus, and must not disappear on its own — are what this family declines automatic focus and automatic dismissal for.
+- The box is a landmark, not a live region. MDN’s alert role reference states that the role “should only be used for text content, not interactive elements such as links or buttons”, and every alert worth shipping has a dismiss control. The root renders a section named by its own title through aria-labelledby, and the region that announces is the content part, which holds the title and the description alone.
+- live defaults to off because the APG records that “screen readers do not inform users of alerts that are present on the page before page load completes”. An alert already on the page announces nothing whatever role it carries; polite and assertive are for a message that arrives while the reader is working, and both are written as a role that already implies aria-live and aria-atomic.
+- Every tone with a severity carries a mark as well as a colour, and secondary carries none: a neutral note has no severity to state. Under forced colours the five grounds become one system colour and the five borders one more, so the mark, and its absence on a note, is the only thing distinguishing an error from a note — WCAG 2.2 1.4.1.
+- The dismiss control is a real button with a real name and an inner control rather than a Button (R2): its box is the glyph plus a step of air on each side, floored at --slotted-target-min, which is the WCAG 2.2 2.5.8 minimum of 24 CSS pixels; at rest it has no frame and no ground, and hover moves only the ground.
+- When the message closes with focus inside it, the keyboard goes back to the element it came from. None of the ten surveyed implementations answers this, and the failure it prevents is the one a real product hits first: the dismiss control is destroyed, focus falls to the document body, and the next Tab starts again at the top of the page.
+- Closing hides rather than unmounts, so the live region is still in the document if the message comes back and data-open is a state a consumer can style. An application that must not pay for the hidden subtree renders the alert conditionally and never passes defaultOpen.
+- Escape does not close the message. An alert is not a dismissable layer, and one inside a dialog would swallow the dialog’s own Escape; a message that must interrupt the reader is an alert dialog rather than an alert.
+
+## 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`
+
+## Examples
+
+### What the message is about
+
+Five tones and five marks. The mark is the answer to WCAG 2.2 1.4.1: read in greyscale, or under forced colours where every ground becomes one system colour, the silhouette is the only thing left.
+
+Excerpt — not a complete module
+
+```tsx
+// accent is information, secondary a neutral note, success something
+// finished, warning something that needs attention, danger something failed.
+<Alert tone="danger">
+  <AlertContent>
+    <AlertTitle>Não foi possível salvar</AlertTitle>
+  </AlertContent>
+</Alert>;
+```
+
+### How that tone is painted
+
+soft and solid bring a ground with them and survive any surface; outline takes the one underneath, so it reads on the page’s own surfaces and goes quiet on a ground the theme never measured its ink against.
+
+Excerpt — not a complete module
+
+```tsx
+<Alert variant="soft" />;
+<Alert variant="outline" />;
+<Alert variant="solid" />;
+
+// A dark region is a scheme rather than a surface.
+<div data-slotted-scheme="dark">
+  <Alert variant="outline" />
+</div>;
+```
+
+### How far the message reaches
+
+The guide’s three recipes as one axis: inline beside the thing it is about, section inside a page section, page across an application. A page banner loses its corners because it runs to both edges.
+
+Excerpt — not a complete module
+
+```tsx
+<Alert reach="inline" tone="danger">
+  <AlertContent>
+    <AlertDescription>Informe um CNPJ válido.</AlertDescription>
+  </AlertContent>
+</Alert>;
+
+<Alert reach="page" tone="warning" />;
+```
+
+### Putting the message away
+
+The left one owns its own openness and needs no state at all; the right one hands it to the application, which can refuse the request. Watch where the keyboard lands after either of them closes.
+
+Excerpt — not a complete module
+
+```tsx
+<Alert dismissible />;
+
+<Alert dismissible onOpenChange={setOpen} open={open} />;
+
+<Alert
+  dismissible
+  onOpenChange={(next, request) => {
+    if (!confirmed) request.cancel();
+  }}
+/>;
+```
+
+### What the message asks for
+
+The controls are the consumer’s own Buttons, in a part outside the live region — a reader hearing the message is not read two button labels in the middle of it. They stack when the box is narrow.
+
+Excerpt — not a complete module
+
+```tsx
+<Alert tone="warning">
+  <AlertContent>
+    <AlertTitle>Sua assinatura expira em três dias</AlertTitle>
+  </AlertContent>
+  <AlertActions>
+    <Button size="sm" tone="warning">
+      Renovar
+    </Button>
+    <Button size="sm" tone="warning" variant="ghost">
+      Ver planos
+    </Button>
+  </AlertActions>
+</Alert>;
+```
+
+### What a reader hears, and when
+
+off by default, because the APG records that alerts already on the page when it loads are not announced at all. Press the button and the message arrives while the reader is elsewhere, which is what polite and assertive are for.
+
+Excerpt — not a complete module
+
+```tsx
+// role="status" on the text, which implies aria-live and aria-atomic.
+<Alert live="polite" tone="success" />;
+
+// role="alert": a failed save, a lost connection, an expiring session.
+<Alert live="assertive" tone="danger" />;
+```
+
+### Content the family did not choose
+
+A German compound that wraps, a container digest with no break opportunity, a message with no mark, and a title standing alone — all in a column narrow enough to make each of them a problem.
+
+Excerpt — not a complete module
+
+```tsx
+<Alert hideIcon>
+  <AlertContent>
+    <AlertTitle>O deploy falhou</AlertTitle>
+    <AlertDescription>{digest}</AlertDescription>
+  </AlertContent>
+</Alert>;
+```
+
+### Composition and escape hatches
+
+The provider sets the defaults once, render substitutes the element of any part, icon replaces the mark, and ref reaches the section so a page that must move focus to the message can.
+
+Excerpt — not a complete module
+
+```tsx
+<AlertDefaultsProvider reach="page">
+  <App />
+</AlertDefaultsProvider>;
+
+<Alert icon={<ShieldIcon />} render={(props) => <aside {...props} />}>
+  <AlertContent>
+    <AlertTitle render={(props) => <h3 {...props} />}>Manutenção</AlertTitle>
+  </AlertContent>
+</Alert>;
+```
+
+### The landmark, the region and the keyboard
+
+Tab into the message and out of it: the box is a region a reader can jump to, the text is the only thing that announces, and closing the message puts the keyboard back where it came from.
+
+Excerpt — not a complete module
+
+```tsx
+// A region landmark named "Manutenção", holding a polite status region.
+<Alert live="polite">
+  <AlertContent>
+    <AlertTitle>Manutenção</AlertTitle>
+  </AlertContent>
+</Alert>;
+
+// No title: a plain grouping element, and no landmark to jump to.
+<Alert>
+  <AlertContent>Pronto.</AlertContent>
+</Alert>;
+```