@slotted/angular 0.0.0-stage → 0.1.0-beta.1

package/docs/alert.json

@@ -0,0 +1,407 @@
+{
+  "family": "alert",
+  "ui": "alert",
+  "binding": "angular",
+  "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  provideAlertDefaults,\n  SlAlert,\n  SlAlertActions,\n  SlAlertContent,\n  SlAlertDescription,\n  SlAlertIcon,\n  SlAlertTitle,\n} from '@slotted/angular/alert';",
+        "selector": "[slAlert]",
+        "exportAs": "slAlert"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "the element the consumer wrote — a section",
+          "required": true,
+          "purpose": "The box. Carries data-ui=\"alert\", the four axes, data-open, hidden when closed, and tabindex=\"-1\". Written on a section it is a region landmark once its title names it; on anything else 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 whatever is projected with slAlertIcon."
+        },
+        {
+          "part": "content",
+          "element": "the element carrying slAlertContent",
+          "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": "the element carrying slAlertTitle — a div, or a heading",
+          "required": false,
+          "purpose": "The message’s name, and the box’s: the root points aria-labelledby at it. The element is the page’s own, so writing <h3 slAlertTitle> is how a message joins the document outline."
+        },
+        {
+          "part": "description",
+          "element": "the element carrying slAlertDescription — a p",
+          "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": "the element carrying slAlertActions",
+          "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": "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"
+        },
+        {
+          "name": "variant",
+          "type": "'soft' | 'outline' | 'solid'",
+          "defaultValue": "soft",
+          "appliesTo": "slAlert",
+          "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": "slAlert",
+          "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": "slAlert",
+          "description": "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"
+        },
+        {
+          "name": "hideIcon",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAlert",
+          "description": "Draws no mark at all, for a callout that carries its own artwork in the body"
+        },
+        {
+          "name": "dismissible",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slAlert",
+          "description": "Renders the control that closes the message. Angular cannot see whether an output is subscribed, so the opt-in is stated — the asymmetry with React that tag recorded first"
+        },
+        {
+          "name": "messages",
+          "type": "Partial<AlertMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slAlert",
+          "description": "Words laid over the language in force, key by key: what that control announces (dismiss)"
+        },
+        {
+          "name": "open",
+          "type": "boolean",
+          "defaultValue": "—",
+          "appliesTo": "slAlert",
+          "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": "slAlert",
+          "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": "slAlert",
+          "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": "slAlertIcon",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "any element inside slAlert",
+          "description": "Replaces the tone’s mark, keeping the box, the size and the place on the message’s first line. React passes a node in icon instead; content projection is what an Angular consumer has"
+        },
+        {
+          "name": "setOpen",
+          "type": "(open: boolean) => void",
+          "defaultValue": "—",
+          "appliesTo": "slAlert, through exportAs",
+          "description": "Opens or closes the message from a template, emitting programmatic as the reason. It is the reach a template has and React does not: JSX can re-render an input, and a template can only call a method"
+        },
+        {
+          "name": "focus",
+          "type": "() => void",
+          "defaultValue": "—",
+          "appliesTo": "slAlert, through exportAs",
+          "description": "Sends the keyboard to the box, which carries tabindex=\"-1\". The family never does this by itself, because the APG says an alert must not affect keyboard focus"
+        },
+        {
+          "name": "provideAlertDefaults",
+          "type": "{ tone, variant, reach, live }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets all four once for every alert under it; an explicit input on one message still wins"
+        },
+        {
+          "name": "ng-content",
+          "type": "projected content",
+          "defaultValue": "—",
+          "appliesTo": "slAlertContent",
+          "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": "(openChange)",
+          "payload": "ChangeRequest<boolean> — value, previous, reason, source, cancel()",
+          "when": "The dismiss control is activated, or a template calls setOpen(). reason is dismiss or programmatic, source is the originating event, and $event.cancel() refuses the change — the message stays open and the keyboard stays where it is. Nothing is emitted when the consumer moves open itself."
+        }
+      ],
+      "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 directive belongs on a section, named by its own title through aria-labelledby, and the region that announces is the slAlertContent element, 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 removes, 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 writes its own @if and never uses 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": "html",
+      "source": "<section slAlert tone=\"warning\">\n  <div slAlertContent>\n    <div slAlertTitle>Sua assinatura expira em três dias</div>\n    <p slAlertDescription>Renove para manter o acesso da equipe.</p>\n  </div>\n</section>\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": "html",
+      "source": "<!-- accent is information, secondary a neutral note, success something\n     finished, warning something needing attention, danger something failed. -->\n<section slAlert tone=\"danger\">\n  <div slAlertContent>\n    <div slAlertTitle>Não foi possível salvar</div>\n  </div>\n</section>\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": "html",
+      "source": "<section slAlert variant=\"soft\"></section>\n<section slAlert variant=\"outline\"></section>\n<section slAlert variant=\"solid\"></section>\n\n<!-- A dark region is a scheme rather than a surface. -->\n<div data-slotted-scheme=\"dark\">\n  <section slAlert variant=\"outline\"></section>\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": "html",
+      "source": "<section slAlert reach=\"inline\" tone=\"danger\">\n  <div slAlertContent>\n    <p slAlertDescription>Informe um CNPJ válido.</p>\n  </div>\n</section>\n\n<section slAlert reach=\"page\" tone=\"warning\"></section>\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": "html",
+      "source": "<section slAlert dismissible></section>\n\n<section slAlert dismissible [open]=\"open()\" (openChange)=\"open.set($event.value)\"></section>\n\n<section slAlert dismissible (openChange)=\"confirmed() ? null : $event.cancel()\"></section>\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": "html",
+      "source": "<section slAlert tone=\"warning\">\n  <div slAlertContent>\n    <div slAlertTitle>Sua assinatura expira em três dias</div>\n  </div>\n  <div slAlertActions>\n    <button slButton size=\"sm\" tone=\"warning\" type=\"button\">Renovar</button>\n    <button slButton size=\"sm\" tone=\"warning\" variant=\"ghost\" type=\"button\">Ver planos</button>\n  </div>\n</section>\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": "html",
+      "source": "<!-- role=\"status\" on the text, which implies aria-live and aria-atomic. -->\n<section slAlert live=\"polite\" tone=\"success\"></section>\n\n<!-- role=\"alert\": a failed save, a lost connection, an expiring session. -->\n<section slAlert live=\"assertive\" tone=\"danger\"></section>\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": "html",
+      "source": "<section slAlert hideIcon>\n  <div slAlertContent>\n    <div slAlertTitle>O deploy falhou</div>\n    <p slAlertDescription>{{ digest }}</p>\n  </div>\n</section>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "provideAlertDefaults sets the defaults once, the element of every part is the page’s own, slAlertIcon replaces the mark, and exportAs reaches the instance so a template can move focus to the message.",
+      "language": "ts",
+      "source": "bootstrapApplication(App, {\n  providers: [provideAlertDefaults({ reach: 'page' })],\n});\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": "html",
+      "source": "<!-- A region landmark named \"Manutenção\", holding a polite status region. -->\n<section slAlert live=\"polite\">\n  <div slAlertContent>\n    <div slAlertTitle>Manutenção</div>\n  </div>\n</section>\n\n<!-- No title: a plain grouping element, and no landmark to jump to. -->\n<section slAlert>\n  <div slAlertContent>Pronto.</div>\n</section>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/alert.md

@@ -0,0 +1,239 @@
+<!-- index: ./index.md -->
+# alert
+
+`data-ui="alert"` · Static message with a tone, icon and actions.
+
+## Import
+
+```ts
+import {
+  provideAlertDefaults,
+  SlAlert,
+  SlAlertActions,
+  SlAlertContent,
+  SlAlertDescription,
+  SlAlertIcon,
+  SlAlertTitle,
+} from '@slotted/angular/alert';
+```
+
+Selector: `[slAlert]` · exportAs: `slAlert`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<section slAlert tone="warning">
+  <div slAlertContent>
+    <div slAlertTitle>Sua assinatura expira em três dias</div>
+    <p slAlertDescription>Renove para manter o acesso da equipe.</p>
+  </div>
+</section>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | the element the consumer wrote — a section | yes |
+| `icon` | span | no |
+| `content` | the element carrying slAlertContent | yes |
+| `title` | the element carrying slAlertTitle — a div, or a heading | no |
+| `description` | the element carrying slAlertDescription — a p | no |
+| `actions` | the element carrying slAlertActions | no |
+| `dismiss` | button | no |
+
+## Props
+
+| 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 |
+| `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 |
+| `hideIcon` | `boolean` | false | slAlert | Draws no mark at all, for a callout that carries its own artwork in the body |
+| `dismissible` | `boolean` | false | slAlert | Renders the control that closes the message. Angular cannot see whether an output is subscribed, so the opt-in is stated — the asymmetry with React that tag recorded first |
+| `messages` | `Partial<AlertMessages>` | — | slAlert | Words laid over the language in force, key by key: what that control announces (dismiss) |
+| `open` | `boolean` | — | slAlert | The openness the consumer owns. Passing it puts the alert in controlled mode for good, and the family then only asks |
+| `defaultOpen` | `boolean` | true | slAlert | The openness an uncontrolled alert starts from, read once. A later change to it is not silently adopted |
+| `restoreFocus` | `boolean` | true | slAlert | Returns the keyboard to the element it came from when the message closes with focus inside it. Nothing moves when focus was never there |
+| `slAlertIcon` | `projected content` | — | any element inside slAlert | Replaces the tone’s mark, keeping the box, the size and the place on the message’s first line. React passes a node in icon instead; content projection is what an Angular consumer has |
+| `setOpen` | `(open: boolean) => void` | — | slAlert, through exportAs | Opens or closes the message from a template, emitting programmatic as the reason. It is the reach a template has and React does not: JSX can re-render an input, and a template can only call a method |
+| `focus` | `() => void` | — | slAlert, through exportAs | Sends the keyboard to the box, which carries tabindex="-1". The family never does this by itself, because the APG says an alert must not affect keyboard focus |
+| `provideAlertDefaults` | `{ tone, variant, reach, live }` | — | an injector | Sets all four once for every alert under it; an explicit input on one message still wins |
+| `ng-content` | `projected content` | — | slAlertContent | 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 |
+| --- | --- | --- |
+| `(openChange)` | `ChangeRequest<boolean> — value, previous, reason, source, cancel()` | The dismiss control is activated, or a template calls setOpen(). reason is dismiss or programmatic, source is the originating event, and $event.cancel() refuses the change — the message stays open and the keyboard stays where it is. Nothing is emitted when the consumer moves open itself. |
+
+## 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 directive belongs on a section, named by its own title through aria-labelledby, and the region that announces is the slAlertContent element, 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 removes, 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 writes its own @if and never uses 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
+
+```html
+<!-- accent is information, secondary a neutral note, success something
+     finished, warning something needing attention, danger something failed. -->
+<section slAlert tone="danger">
+  <div slAlertContent>
+    <div slAlertTitle>Não foi possível salvar</div>
+  </div>
+</section>
+```
+
+### 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
+
+```html
+<section slAlert variant="soft"></section>
+<section slAlert variant="outline"></section>
+<section slAlert variant="solid"></section>
+
+<!-- A dark region is a scheme rather than a surface. -->
+<div data-slotted-scheme="dark">
+  <section slAlert variant="outline"></section>
+</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
+
+```html
+<section slAlert reach="inline" tone="danger">
+  <div slAlertContent>
+    <p slAlertDescription>Informe um CNPJ válido.</p>
+  </div>
+</section>
+
+<section slAlert reach="page" tone="warning"></section>
+```
+
+### 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
+
+```html
+<section slAlert dismissible></section>
+
+<section slAlert dismissible [open]="open()" (openChange)="open.set($event.value)"></section>
+
+<section slAlert dismissible (openChange)="confirmed() ? null : $event.cancel()"></section>
+```
+
+### 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
+
+```html
+<section slAlert tone="warning">
+  <div slAlertContent>
+    <div slAlertTitle>Sua assinatura expira em três dias</div>
+  </div>
+  <div slAlertActions>
+    <button slButton size="sm" tone="warning" type="button">Renovar</button>
+    <button slButton size="sm" tone="warning" variant="ghost" type="button">Ver planos</button>
+  </div>
+</section>
+```
+
+### 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
+
+```html
+<!-- role="status" on the text, which implies aria-live and aria-atomic. -->
+<section slAlert live="polite" tone="success"></section>
+
+<!-- role="alert": a failed save, a lost connection, an expiring session. -->
+<section slAlert live="assertive" tone="danger"></section>
+```
+
+### 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
+
+```html
+<section slAlert hideIcon>
+  <div slAlertContent>
+    <div slAlertTitle>O deploy falhou</div>
+    <p slAlertDescription>{{ digest }}</p>
+  </div>
+</section>
+```
+
+### Composition and escape hatches
+
+provideAlertDefaults sets the defaults once, the element of every part is the page’s own, slAlertIcon replaces the mark, and exportAs reaches the instance so a template can move focus to the message.
+
+Excerpt — not a complete module
+
+```ts
+bootstrapApplication(App, {
+  providers: [provideAlertDefaults({ reach: 'page' })],
+});
+```
+
+### 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
+
+```html
+<!-- A region landmark named "Manutenção", holding a polite status region. -->
+<section slAlert live="polite">
+  <div slAlertContent>
+    <div slAlertTitle>Manutenção</div>
+  </div>
+</section>
+
+<!-- No title: a plain grouping element, and no landmark to jump to. -->
+<section slAlert>
+  <div slAlertContent>Pronto.</div>
+</section>
+```