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

package/docs/inline.md

@@ -0,0 +1,72 @@
+<!-- index: ./index.md -->
+# inline
+
+`data-ui="inline"` · Row of items with gaps that wraps.
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<div slInline [gap]="4" justify="between">
+  <button slButton variant="secondary">Cancel</button>
+  <button slButton>Save changes</button>
+</div>
+```
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `gap` | `0 \| 1 \| … \| 12` | 4 | slInline | Separation between items, as a step on the space scale |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | center | slInline | Positions items across the flow; baseline puts their type on one line |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around' \| 'evenly'` | — | slInline | Positions items along the flow, and distributes the space between them |
+| `wrap` | `'wrap' \| 'nowrap'` | wrap | slInline | nowrap keeps one line, and overflows a container narrower than it |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `gap` | `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`, `10`, `11`, `12` | `4` |
+| `align` | `start`, `center`, `end`, `stretch`, `baseline` | `center` |
+| `justify` | `start`, `center`, `end`, `between`, `around`, `evenly` | — |
+| `wrap` | `wrap`, `nowrap` | `wrap` |
+
+## Rules
+
+- slInline has no role and no ARIA. It arranges what the consumer wrote, and the items keep whatever semantics they already had.
+- The directive selector is an attribute, so the element is always the consumer’s. Write ul when the items are list items.
+- There is no input that reverses the items. Visual order stays DOM order, which is what WCAG 2.2 SC 1.3.2 asks for (technique C27, failure F1) and what keeps the Tab order matching the page.
+- Wrapping is the default because a row that cannot wrap has one answer to a narrow container: overflow it. Asking for nowrap is asking for that, and WCAG 1.4.10 Reflow is what it costs.
+- baseline is the alignment for items that carry text of different sizes. It puts the type on one line where centring only puts the boxes there.
+
+## Tokens
+
+`--slotted-space-1`, `--slotted-space-10`, `--slotted-space-11`, `--slotted-space-12`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-5`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-space-9`
+
+## Examples
+
+### A list of tags that wraps
+
+Excerpt — not a complete module
+
+```html
+<ul slInline [gap]="2">
+  @for (tag of tags; track tag) {
+    <li>
+      <span slTag>{{ tag }}</span>
+    </li>
+  }
+</ul>
+```
+
+### A label and a value on one line
+
+Excerpt — not a complete module
+
+```html
+<div slInline [gap]="5" align="baseline">
+  <span slText tone="muted">Status</span>
+  <span slText size="lg" weight="semibold">Awaiting review</span>
+</div>
+```

package/docs/kbd.json

@@ -0,0 +1,350 @@
+{
+  "family": "kbd",
+  "ui": "kbd",
+  "binding": "angular",
+  "catalog": {
+    "group": "Data display",
+    "summary": "Keyboard key or shortcut."
+  },
+  "axes": {
+    "size": [
+      "xs",
+      "sm",
+      "md",
+      "lg",
+      "inherit"
+    ],
+    "variant": [
+      "raised",
+      "outline",
+      "soft",
+      "plain"
+    ],
+    "platform": [
+      "auto",
+      "mac",
+      "windows",
+      "linux",
+      "other"
+    ]
+  },
+  "members": {
+    "kbd": {
+      "nativeElement": "kbd",
+      "defaults": {
+        "size": "md",
+        "variant": "raised",
+        "platform": "auto",
+        "disabled": false,
+        "separator": "+"
+      },
+      "capabilities": [
+        "appearance",
+        "size",
+        "disabled"
+      ],
+      "states": [
+        "default",
+        "disabled"
+      ],
+      "parts": [
+        "root",
+        "legend",
+        "name",
+        "shortcut",
+        "separator"
+      ]
+    }
+  },
+  "docs": {
+    "kbd": {
+      "imports": {
+        "source": "import { SlKbd, SlShortcut, provideKbdDefaults } from '@slotted/angular/kbd';",
+        "selector": "kbd[slKbd] · kbd[slShortcut]",
+        "exportAs": "slKbd · slShortcut"
+      },
+      "anatomy": [
+        {
+          "part": "root",
+          "element": "kbd",
+          "required": true,
+          "purpose": "One key — the consumer’s own kbd element, which the directive attaches to. Carries data-ui=\"kbd\", the axes as data attributes, and data-key when the token is in the vocabulary."
+        },
+        {
+          "part": "legend",
+          "element": "span",
+          "required": true,
+          "purpose": "What the eye sees. Hidden from assistive technology whenever the key is in the vocabulary, and marked data-legend=\"symbol\" when what it draws is a mark rather than a word."
+        },
+        {
+          "part": "name",
+          "element": "span",
+          "required": false,
+          "purpose": "What a reader hears in place of the legend — “Command”, “Control”, “Up arrow”. Clipped from view by the family’s own rule. Rendered only for a key in the vocabulary."
+        },
+        {
+          "part": "shortcut",
+          "element": "kbd",
+          "required": false,
+          "purpose": "A whole combination, holding the key roots. The one part that contains the family’s root instead of sitting inside it, so it carries data-ui itself, plus data-platform for the resolution it made."
+        },
+        {
+          "part": "separator",
+          "element": "span",
+          "required": false,
+          "purpose": "Between two keys. data-separator=\"plus\" joins keys pressed together and is hidden from assistive technology; data-separator=\"then\" joins two steps of a sequence and is read aloud."
+        }
+      ],
+      "api": [
+        {
+          "name": "keyName",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slKbd",
+          "description": "A token from the vocabulary — mod, meta, ctrl, alt, shift, fn, enter, escape, tab, space, backspace, delete, capslock, pageup, pagedown, home, end, plus, up, down, left, right — or an alias such as cmd, option, esc or arrowup. Wins over projected content where both are written"
+        },
+        {
+          "name": "keys",
+          "type": "string",
+          "defaultValue": "—",
+          "appliesTo": "slShortcut",
+          "description": "The whole combination: + joins keys pressed together, whitespace joins the steps of a sequence"
+        },
+        {
+          "name": "platform",
+          "type": "'auto' | 'mac' | 'windows' | 'linux' | 'other'",
+          "defaultValue": "auto",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "Which keyboard the legends are drawn for. auto reads the browser and never the server, so a server-rendered application states it through provideKbdDefaults"
+        },
+        {
+          "name": "size",
+          "type": "'xs' | 'sm' | 'md' | 'lg' | 'inherit'",
+          "defaultValue": "md",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "xs to lg are fixed heights of 16, 20, 24 and 28 pixels whose legend answers density; inherit reads the text around the key and stays inside its line"
+        },
+        {
+          "name": "variant",
+          "type": "'raised' | 'outline' | 'soft' | 'plain'",
+          "defaultValue": "raised",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "raised is a key with a bottom edge, outline owns no ground, soft is the tinted chip, plain takes the colour of the text it sits in"
+        },
+        {
+          "name": "disabled",
+          "type": "boolean",
+          "defaultValue": "false",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "Dims the key without writing aria-disabled, which kbd may not carry. The item the shortcut belongs to owns the semantics"
+        },
+        {
+          "name": "separator",
+          "type": "string",
+          "defaultValue": "+",
+          "appliesTo": "slShortcut",
+          "description": "Between two simultaneous keys. A Mac joins with nothing whatever this says"
+        },
+        {
+          "name": "messages",
+          "type": "PartialMessages<KeysMessages>",
+          "defaultValue": "—",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "Words laid over the keys catalog of the language in force, key by key: legends.*, names.*, and then — the word between two steps of a sequence, read aloud"
+        },
+        {
+          "name": "legends",
+          "type": "Record<string, string>",
+          "defaultValue": "—",
+          "appliesTo": "slShortcut",
+          "description": "Replaces what the eye sees, per key token: { ctrl: \"Strg\" }. Falls back to the injection token"
+        },
+        {
+          "name": "names",
+          "type": "Record<string, string>",
+          "defaultValue": "—",
+          "appliesTo": "slShortcut",
+          "description": "Replaces what a reader hears, per key token: { ctrl: \"Steuerung\" }. Falls back to the injection token"
+        }
+      ],
+      "composition": [
+        {
+          "name": "projected content",
+          "type": "ng-content",
+          "defaultValue": "—",
+          "appliesTo": "slKbd",
+          "description": "The legend written verbatim — the application’s own word, neither resolved nor given a hidden name"
+        },
+        {
+          "name": "projected content",
+          "type": "ng-content",
+          "defaultValue": "—",
+          "appliesTo": "slShortcut",
+          "description": "Keys authored one by one. They are rendered in the order written, which is the way out of the platform reordering, and they take the combination’s painting"
+        },
+        {
+          "name": "the host element",
+          "type": "kbd",
+          "defaultValue": "—",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "The directive is written on the consumer’s own kbd, so substituting the element is the default rather than a prop. Every static attribute on it survives the host bindings"
+        },
+        {
+          "name": "exportAs",
+          "type": "'slKbd' | 'slShortcut'",
+          "defaultValue": "—",
+          "appliesTo": "slKbd, slShortcut",
+          "description": "Reaches the instance from a template. There is no imperative method on it: the family has no action a template cannot express declaratively"
+        },
+        {
+          "name": "provideKbdDefaults",
+          "type": "{ platform, size, variant, separator, legends, names }",
+          "defaultValue": "—",
+          "appliesTo": "an injector",
+          "description": "Sets all six once for everything under it; an explicit input on a key still wins"
+        }
+      ],
+      "events": [],
+      "accessibility": [
+        "There is no kbd pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry — and ARIA in HTML (W3C Recommendation, 11 August 2026) maps the kbd element to no corresponding role and declares it Naming Prohibited. The family therefore writes no role, no aria-label and no aria-disabled, and every word a reader hears is content.",
+        "A key in the vocabulary hides its legend with aria-hidden and carries the word in a name part the family clips from view itself. ⌘ is U+2318 PLACE OF INTEREST SIGN and would otherwise be read as one; Ctrl is an abbreviation whose pronunciation belongs to the screen reader’s dictionary. Both are announced “Control” or “Command” here.",
+        "The plus between two keys is aria-hidden — it is punctuation joining two caps, and “Command Shift K” is what the operating systems announce for the same shortcut. The word between two steps of a sequence is not hidden, because it is the only thing that distinguishes “G then I” from “G and I together”.",
+        "Nothing here is focusable and nothing here binds a key. WCAG 2.2 2.1.4 Character Key Shortcuts belongs to whoever registers the shortcut, because only the application knows whether a single-character shortcut can be turned off.",
+        "The keys inside a combination keep their left-to-right order in a right-to-left document. A combination is one formula, the bidi algorithm renders the same string as one left-to-right run inside an Arabic paragraph, and a mirrored K + ⌘ is a shortcut no operating system displays. The combination as a whole still sits where the paragraph puts it.",
+        "An arrow legend is never mirrored: ← is the physical Left arrow key, not a direction of travel.",
+        "A key label is never truncated. A shortcut too wide for its column wraps between caps and never inside one, because half a key name is a wrong instruction where a wrapped shortcut is only a taller row.",
+        "The platform is resolved in the browser and never on the server, so a server-rendered application calls provideKbdDefaults({ platform }) — a development-mode warning says so rather than leaving a reader to discover Ctrl on their Mac."
+      ]
+    }
+  },
+  "tokens": [
+    "--slotted-border-strong",
+    "--slotted-border-width-thick",
+    "--slotted-border-width-thin",
+    "--slotted-control-border-color",
+    "--slotted-control-font-family",
+    "--slotted-control-font-size-lg",
+    "--slotted-control-font-size-md",
+    "--slotted-control-font-size-sm",
+    "--slotted-control-inner-size",
+    "--slotted-control-transition-duration",
+    "--slotted-control-transition-easing",
+    "--slotted-disabled-background",
+    "--slotted-disabled-border",
+    "--slotted-disabled-foreground",
+    "--slotted-font-family-sans",
+    "--slotted-font-weight-medium",
+    "--slotted-kbd-base-width",
+    "--slotted-kbd-border-width",
+    "--slotted-kbd-font-family",
+    "--slotted-kbd-font-weight",
+    "--slotted-kbd-radius",
+    "--slotted-kbd-symbol-font-family",
+    "--slotted-radius-lg",
+    "--slotted-radius-md",
+    "--slotted-radius-sm",
+    "--slotted-space-1",
+    "--slotted-space-2",
+    "--slotted-space-3",
+    "--slotted-space-4",
+    "--slotted-space-6",
+    "--slotted-space-7",
+    "--slotted-space-8",
+    "--slotted-surface-raised",
+    "--slotted-text",
+    "--slotted-text-muted",
+    "--slotted-tone-secondary-border",
+    "--slotted-tone-secondary-surface",
+    "--slotted-tone-secondary-text"
+  ],
+  "examples": [
+    {
+      "id": "playground",
+      "title": "Playground",
+      "note": "One key with every input on it, driven by the controls below the canvas. Change platform and watch the legend change without the template changing.",
+      "language": "html",
+      "source": "<kbd slKbd keyName=\"mod\"></kbd>\n\n<!-- Or a word this library has never heard of. -->\n<kbd slKbd>Any key</kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "variants",
+      "title": "How the key is painted",
+      "note": "raised is the only value that looks like an object; outline owns no ground, so it survives on a solid surface where raised would cut a white hole.",
+      "language": "html",
+      "source": "<kbd slShortcut keys=\"mod+b\"></kbd>\n<kbd slShortcut keys=\"mod+b\" variant=\"outline\"></kbd>\n<kbd slShortcut keys=\"mod+b\" variant=\"soft\"></kbd>\n<kbd slShortcut keys=\"mod+b\" variant=\"plain\"></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sizes",
+      "title": "How large the key is",
+      "note": "Four absolute heights, 16, 20, 24 and 28 pixels, that no legend and no variant changes; the legend reads the control type scale, so it shrinks with density inside the same box. xs fits a caption or a tooltip. inherit reads the text around it and stays inside its line, which is the step a heading and a footnote both need.",
+      "language": "html",
+      "source": "<kbd slKbd keyName=\"escape\" size=\"xs\"></kbd>\n<kbd slKbd keyName=\"escape\" size=\"sm\"></kbd>\n<kbd slKbd keyName=\"escape\" size=\"lg\"></kbd>\n\n<h2>Press <kbd slKbd keyName=\"escape\" size=\"inherit\"></kbd> to close</h2>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "shortcut",
+      "title": "A whole combination",
+      "note": "One kbd nested inside another, which is what the HTML Standard says a combination is. The plus is a part of its own, so an application can restyle or replace it.",
+      "language": "html",
+      "source": "<kbd slShortcut keys=\"mod+shift+p\"></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "platform",
+      "title": "The same string on three keyboards",
+      "note": "The modifiers are reordered into each platform’s own convention and the legends redrawn; on a Mac the separator is not rendered at all, because a Mac joins with nothing.",
+      "language": "html",
+      "source": "<kbd slShortcut keys=\"mod+shift+alt+p\" platform=\"mac\"></kbd>\n<kbd slShortcut keys=\"mod+shift+alt+p\" platform=\"windows\"></kbd>\n\n<!-- Left to itself it asks the reader’s browser. -->\n<kbd slShortcut keys=\"mod+shift+alt+p\"></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "sequence",
+      "title": "One key after another",
+      "note": "Whitespace between two groups is a step break, so “g i” is G then I. The word is read aloud where the plus is not, because it is the only thing that tells a sequence from a chord.",
+      "language": "html",
+      "source": "<kbd slShortcut keys=\"g i\"></kbd>\n<kbd slShortcut keys=\"mod+k mod+s\"></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "context",
+      "title": "Where a shortcut actually lives",
+      "note": "A menu, where the label takes the room and the shortcut takes the end of the row. plain inherits the row’s colour, so a row that dims dims its shortcut with no state to set.",
+      "language": "html",
+      "source": "<li>\n  <span>Open command palette</span>\n  <kbd slShortcut keys=\"mod+k\" variant=\"plain\"></kbd>\n</li>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "states",
+      "title": "Available and unavailable",
+      "note": "disabled dims the ground, the rim and the ink, and writes no aria-disabled: kbd may carry only the global ARIA attributes, so the item owns the semantics.",
+      "language": "html",
+      "source": "<kbd slShortcut keys=\"mod+z\"></kbd>\n<kbd slShortcut keys=\"mod+z\" disabled></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "content",
+      "title": "Content the family did not choose",
+      "note": "The longest real key name, a German legend replaced through the injection token, and a four-key combination in a narrow column: it wraps between caps and never inside one.",
+      "language": "ts",
+      "source": "provideKbdDefaults({\n  platform: 'windows',\n  legends: { ctrl: 'Strg', shift: 'Umschalt', delete: 'Entf' },\n  names: { ctrl: 'Steuerung', delete: 'Entfernen' },\n});\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "composition",
+      "title": "Composition and escape hatches",
+      "note": "Projected keys are rendered in the order written, which is the way out of the platform reordering. The directive is already on the consumer’s element, so no render prop is needed.",
+      "language": "html",
+      "source": "<kbd slShortcut>\n  <kbd slKbd keyName=\"mod\"></kbd>\n  <kbd slKbd>K</kbd>\n</kbd>\n\n<kbd slShortcut keys=\"mod+k\" #combination=\"slShortcut\"></kbd>\n",
+      "verdict": "excerpt"
+    },
+    {
+      "id": "accessibility",
+      "title": "What a reader hears",
+      "note": "Every mark and every abbreviation hides its legend and carries the word beside it, so ⌘ is announced “Command” rather than “place of interest sign” and Ctrl is not left to a pronunciation dictionary.",
+      "language": "html",
+      "source": "<!-- “Command Shift K” -->\n<kbd slShortcut keys=\"mod+shift+k\" platform=\"mac\"></kbd>\n\n<!-- “G then I” -->\n<kbd slShortcut keys=\"g i\"></kbd>\n\n<!-- “Any key” — a word the page wrote, so the page owns it. -->\n<kbd slKbd>Any key</kbd>\n",
+      "verdict": "excerpt"
+    }
+  ]
+}

package/docs/kbd.md

@@ -0,0 +1,210 @@
+<!-- index: ./index.md -->
+# kbd
+
+`data-ui="kbd"` · Keyboard key or shortcut.
+
+## Import
+
+```ts
+import { SlKbd, SlShortcut, provideKbdDefaults } from '@slotted/angular/kbd';
+```
+
+Selector: `kbd[slKbd] · kbd[slShortcut]` · exportAs: `slKbd · slShortcut`
+
+## Minimal example
+
+Excerpt — not a complete module
+
+```html
+<kbd slKbd keyName="mod"></kbd>
+
+<!-- Or a word this library has never heard of. -->
+<kbd slKbd>Any key</kbd>
+```
+
+## Anatomy
+
+| Part | Element | Required |
+| --- | --- | --- |
+| `root` | kbd | yes |
+| `legend` | span | yes |
+| `name` | span | no |
+| `shortcut` | kbd | no |
+| `separator` | span | no |
+
+## Props
+
+| Name | Type | Default | Applies to | Description |
+| --- | --- | --- | --- | --- |
+| `keyName` | `string` | — | slKbd | A token from the vocabulary — mod, meta, ctrl, alt, shift, fn, enter, escape, tab, space, backspace, delete, capslock, pageup, pagedown, home, end, plus, up, down, left, right — or an alias such as cmd, option, esc or arrowup. Wins over projected content where both are written |
+| `keys` | `string` | — | slShortcut | The whole combination: + joins keys pressed together, whitespace joins the steps of a sequence |
+| `platform` | `'auto' \| 'mac' \| 'windows' \| 'linux' \| 'other'` | auto | slKbd, slShortcut | Which keyboard the legends are drawn for. auto reads the browser and never the server, so a server-rendered application states it through provideKbdDefaults |
+| `size` | `'xs' \| 'sm' \| 'md' \| 'lg' \| 'inherit'` | md | slKbd, slShortcut | xs to lg are fixed heights of 16, 20, 24 and 28 pixels whose legend answers density; inherit reads the text around the key and stays inside its line |
+| `variant` | `'raised' \| 'outline' \| 'soft' \| 'plain'` | raised | slKbd, slShortcut | raised is a key with a bottom edge, outline owns no ground, soft is the tinted chip, plain takes the colour of the text it sits in |
+| `disabled` | `boolean` | false | slKbd, slShortcut | Dims the key without writing aria-disabled, which kbd may not carry. The item the shortcut belongs to owns the semantics |
+| `separator` | `string` | + | slShortcut | Between two simultaneous keys. A Mac joins with nothing whatever this says |
+| `messages` | `PartialMessages<KeysMessages>` | — | slKbd, slShortcut | Words laid over the keys catalog of the language in force, key by key: legends.*, names.*, and then — the word between two steps of a sequence, read aloud |
+| `legends` | `Record<string, string>` | — | slShortcut | Replaces what the eye sees, per key token: { ctrl: "Strg" }. Falls back to the injection token |
+| `names` | `Record<string, string>` | — | slShortcut | Replaces what a reader hears, per key token: { ctrl: "Steuerung" }. Falls back to the injection token |
+| `projected content` | `ng-content` | — | slKbd | The legend written verbatim — the application’s own word, neither resolved nor given a hidden name |
+| `projected content` | `ng-content` | — | slShortcut | Keys authored one by one. They are rendered in the order written, which is the way out of the platform reordering, and they take the combination’s painting |
+| `the host element` | `kbd` | — | slKbd, slShortcut | The directive is written on the consumer’s own kbd, so substituting the element is the default rather than a prop. Every static attribute on it survives the host bindings |
+| `exportAs` | `'slKbd' \| 'slShortcut'` | — | slKbd, slShortcut | Reaches the instance from a template. There is no imperative method on it: the family has no action a template cannot express declaratively |
+| `provideKbdDefaults` | `{ platform, size, variant, separator, legends, names }` | — | an injector | Sets all six once for everything under it; an explicit input on a key still wins |
+
+## Axes and defaults
+
+| Axis | Values | Default |
+| --- | --- | --- |
+| `size` | `xs`, `sm`, `md`, `lg`, `inherit` | `md` |
+| `variant` | `raised`, `outline`, `soft`, `plain` | `raised` |
+| `platform` | `auto`, `mac`, `windows`, `linux`, `other` | `auto` |
+
+## Rules
+
+- There is no kbd pattern in the WAI-ARIA Authoring Practices — the pattern index carries no entry — and ARIA in HTML (W3C Recommendation, 11 August 2026) maps the kbd element to no corresponding role and declares it Naming Prohibited. The family therefore writes no role, no aria-label and no aria-disabled, and every word a reader hears is content.
+- A key in the vocabulary hides its legend with aria-hidden and carries the word in a name part the family clips from view itself. ⌘ is U+2318 PLACE OF INTEREST SIGN and would otherwise be read as one; Ctrl is an abbreviation whose pronunciation belongs to the screen reader’s dictionary. Both are announced “Control” or “Command” here.
+- The plus between two keys is aria-hidden — it is punctuation joining two caps, and “Command Shift K” is what the operating systems announce for the same shortcut. The word between two steps of a sequence is not hidden, because it is the only thing that distinguishes “G then I” from “G and I together”.
+- Nothing here is focusable and nothing here binds a key. WCAG 2.2 2.1.4 Character Key Shortcuts belongs to whoever registers the shortcut, because only the application knows whether a single-character shortcut can be turned off.
+- The keys inside a combination keep their left-to-right order in a right-to-left document. A combination is one formula, the bidi algorithm renders the same string as one left-to-right run inside an Arabic paragraph, and a mirrored K + ⌘ is a shortcut no operating system displays. The combination as a whole still sits where the paragraph puts it.
+- An arrow legend is never mirrored: ← is the physical Left arrow key, not a direction of travel.
+- A key label is never truncated. A shortcut too wide for its column wraps between caps and never inside one, because half a key name is a wrong instruction where a wrapped shortcut is only a taller row.
+- The platform is resolved in the browser and never on the server, so a server-rendered application calls provideKbdDefaults({ platform }) — a development-mode warning says so rather than leaving a reader to discover Ctrl on their Mac.
+
+## Tokens
+
+`--slotted-border-strong`, `--slotted-border-width-thick`, `--slotted-border-width-thin`, `--slotted-control-border-color`, `--slotted-control-font-family`, `--slotted-control-font-size-lg`, `--slotted-control-font-size-md`, `--slotted-control-font-size-sm`, `--slotted-control-inner-size`, `--slotted-control-transition-duration`, `--slotted-control-transition-easing`, `--slotted-disabled-background`, `--slotted-disabled-border`, `--slotted-disabled-foreground`, `--slotted-font-family-sans`, `--slotted-font-weight-medium`, `--slotted-kbd-base-width`, `--slotted-kbd-border-width`, `--slotted-kbd-font-family`, `--slotted-kbd-font-weight`, `--slotted-kbd-radius`, `--slotted-kbd-symbol-font-family`, `--slotted-radius-lg`, `--slotted-radius-md`, `--slotted-radius-sm`, `--slotted-space-1`, `--slotted-space-2`, `--slotted-space-3`, `--slotted-space-4`, `--slotted-space-6`, `--slotted-space-7`, `--slotted-space-8`, `--slotted-surface-raised`, `--slotted-text`, `--slotted-text-muted`, `--slotted-tone-secondary-border`, `--slotted-tone-secondary-surface`, `--slotted-tone-secondary-text`
+
+## Examples
+
+### How the key is painted
+
+raised is the only value that looks like an object; outline owns no ground, so it survives on a solid surface where raised would cut a white hole.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut keys="mod+b"></kbd>
+<kbd slShortcut keys="mod+b" variant="outline"></kbd>
+<kbd slShortcut keys="mod+b" variant="soft"></kbd>
+<kbd slShortcut keys="mod+b" variant="plain"></kbd>
+```
+
+### How large the key is
+
+Four absolute heights, 16, 20, 24 and 28 pixels, that no legend and no variant changes; the legend reads the control type scale, so it shrinks with density inside the same box. xs fits a caption or a tooltip. inherit reads the text around it and stays inside its line, which is the step a heading and a footnote both need.
+
+Excerpt — not a complete module
+
+```html
+<kbd slKbd keyName="escape" size="xs"></kbd>
+<kbd slKbd keyName="escape" size="sm"></kbd>
+<kbd slKbd keyName="escape" size="lg"></kbd>
+
+<h2>Press <kbd slKbd keyName="escape" size="inherit"></kbd> to close</h2>
+```
+
+### A whole combination
+
+One kbd nested inside another, which is what the HTML Standard says a combination is. The plus is a part of its own, so an application can restyle or replace it.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut keys="mod+shift+p"></kbd>
+```
+
+### The same string on three keyboards
+
+The modifiers are reordered into each platform’s own convention and the legends redrawn; on a Mac the separator is not rendered at all, because a Mac joins with nothing.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut keys="mod+shift+alt+p" platform="mac"></kbd>
+<kbd slShortcut keys="mod+shift+alt+p" platform="windows"></kbd>
+
+<!-- Left to itself it asks the reader’s browser. -->
+<kbd slShortcut keys="mod+shift+alt+p"></kbd>
+```
+
+### One key after another
+
+Whitespace between two groups is a step break, so “g i” is G then I. The word is read aloud where the plus is not, because it is the only thing that tells a sequence from a chord.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut keys="g i"></kbd>
+<kbd slShortcut keys="mod+k mod+s"></kbd>
+```
+
+### Where a shortcut actually lives
+
+A menu, where the label takes the room and the shortcut takes the end of the row. plain inherits the row’s colour, so a row that dims dims its shortcut with no state to set.
+
+Excerpt — not a complete module
+
+```html
+<li>
+  <span>Open command palette</span>
+  <kbd slShortcut keys="mod+k" variant="plain"></kbd>
+</li>
+```
+
+### Available and unavailable
+
+disabled dims the ground, the rim and the ink, and writes no aria-disabled: kbd may carry only the global ARIA attributes, so the item owns the semantics.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut keys="mod+z"></kbd>
+<kbd slShortcut keys="mod+z" disabled></kbd>
+```
+
+### Content the family did not choose
+
+The longest real key name, a German legend replaced through the injection token, and a four-key combination in a narrow column: it wraps between caps and never inside one.
+
+Excerpt — not a complete module
+
+```ts
+provideKbdDefaults({
+  platform: 'windows',
+  legends: { ctrl: 'Strg', shift: 'Umschalt', delete: 'Entf' },
+  names: { ctrl: 'Steuerung', delete: 'Entfernen' },
+});
+```
+
+### Composition and escape hatches
+
+Projected keys are rendered in the order written, which is the way out of the platform reordering. The directive is already on the consumer’s element, so no render prop is needed.
+
+Excerpt — not a complete module
+
+```html
+<kbd slShortcut>
+  <kbd slKbd keyName="mod"></kbd>
+  <kbd slKbd>K</kbd>
+</kbd>
+
+<kbd slShortcut keys="mod+k" #combination="slShortcut"></kbd>
+```
+
+### What a reader hears
+
+Every mark and every abbreviation hides its legend and carries the word beside it, so ⌘ is announced “Command” rather than “place of interest sign” and Ctrl is not left to a pronunciation dictionary.
+
+Excerpt — not a complete module
+
+```html
+<!-- “Command Shift K” -->
+<kbd slShortcut keys="mod+shift+k" platform="mac"></kbd>
+
+<!-- “G then I” -->
+<kbd slShortcut keys="g i"></kbd>
+
+<!-- “Any key” — a word the page wrote, so the page owns it. -->
+<kbd slKbd>Any key</kbd>
+```