@reliability-design/web 1.4.6 → 1.4.7

package/dist/components/rel-kbd/README.md

@@ -1,151 +1,141 @@
-# rel-kbd
-
-A keyboard key/shortcut pill component for displaying keyboard shortcuts and key combinations in a visually consistent way.
-
-## Usage
-
-```html
-<!-- Basic usage -->
-<rel-kbd>K</rel-kbd>
-
-<!-- Keyboard shortcut combination -->
-<rel-kbd>Ctrl</rel-kbd> + <rel-kbd>K</rel-kbd>
-
-<!-- With variants -->
-<rel-kbd variant="muted">⌘</rel-kbd>
-<rel-kbd variant="default">Shift</rel-kbd>
-
-<!-- Different sizes -->
-<rel-kbd size="sm">Esc</rel-kbd>
-<rel-kbd size="md">Enter</rel-kbd>
-<rel-kbd size="lg">Space</rel-kbd>
-
-<!-- Pill shape -->
-<rel-kbd pill>R</rel-kbd>
-
-<!-- Inset (pressed) appearance -->
-<rel-kbd inset>Tab</rel-kbd>
-```
-
-## API
-
-### Properties
-
-| Property | Type | Default | Description |
-|----------|------|---------|-------------|
-| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Controls the size of the kbd element |
-| `variant` | `"default" \| "muted"` | `"default"` | Visual style variant |
-| `pill` | `boolean` | `false` | When true, renders with full rounded corners |
-| `inset` | `boolean` | `false` | When true, renders with pressed/inset appearance |
-
-### Slots
-
-| Slot | Description |
-|------|-------------|
-| (default) | The keyboard key label or character |
-
-### CSS Custom Properties
-
-The component uses design tokens from the Reliability Design System:
-
-#### Colors
-- `--rel-bg-surface-elevated` - Default background
-- `--rel-bg-neutral-elevated-1` - Muted and inset backgrounds
-- `--rel-text-label` - Default text color
-- `--rel-text-placeholder` - Muted text color
-- `--rel-border-default` - Default border
-- `--rel-border-default` - Muted border
-
-#### Typography
-- `--rel-fonts-font-family` - Font family (Poppins)
-- `--rel-fonts-weight-body-medium` - Font weight (500)
-- `--rel-body-xs-regular-font-size` - Small size font
-- `--rel-body-sm-regular-font-size` - Medium size font
-- `--rel-body-md-regular-font-size` - Large size font
-
-#### Spacing
-- `--rel-spacing-3xs` (2px)
-- `--rel-spacing-2xs` (4px)
-- `--rel-spacing-xs` (8px)
-- `--rel-spacing-sm` (12px)
-- `--rel-spacing-md` (16px)
-
-#### Borders
-- `--rel-stroke-sm` (1px)
-- `--rel-border-radius-xs` (2px)
-- `--rel-border-radius-sm` (8px)
-- `--rel-border-radius-full-rounded` (1000px - pill shape)
-
-## Examples
-
-### Search Shortcut
-```html
-<p>Press <rel-kbd>Ctrl</rel-kbd> + <rel-kbd>K</rel-kbd> to search</p>
-```
-
-### Mac Shortcut
-```html
-<p>Press <rel-kbd variant="muted">⌘</rel-kbd> + <rel-kbd>Shift</rel-kbd> + <rel-kbd pill>R</rel-kbd> to reload</p>
-```
-
-### Multiple Sizes
-```html
-<div style="display: flex; gap: 8px; align-items: center;">
-  <rel-kbd size="sm">S</rel-kbd>
-  <rel-kbd size="md">M</rel-kbd>
-  <rel-kbd size="lg">L</rel-kbd>
-</div>
-```
-
-### Pressed State
-```html
-<p>Hold <rel-kbd inset>Space</rel-kbd> to preview</p>
-```
-
-## Accessibility
-
-- Uses semantic `<kbd>` HTML element for proper semantics
-- `role="presentation"` is set to avoid redundant announcements
-- Non-interactive by default (no tabindex)
-- Text content is fully accessible to screen readers
-- Inherits text color that maintains sufficient contrast ratios
-
-## Styling Notes
-
-### Default Appearance
-- Subtle background with light border
-- Small inset highlight shadow for raised appearance
-- Monospaced font weight for technical look
-
-### Muted Variant
-- Lower contrast for secondary shortcuts
-- Softer colors and reduced shadow
-
-### Pill Modifier
-- Fully rounded corners using border-radius-500 token
-- Ideal for single character keys
-
-### Inset Modifier
-- Inverted shadow for pressed/active appearance
-- Slight vertical translation for depth effect
-- Darker background to indicate pressed state
-
-## Dark Mode Support
-
-The component automatically supports dark mode when design tokens are configured with dark mode variants, as it exclusively uses CSS custom properties.
-
-## Browser Support
-
-Compatible with all modern browsers that support:
-- Web Components
-- CSS Custom Properties
-- Shadow DOM
-
-## Framework Integration
-
-Works seamlessly with:
-- Vanilla JavaScript
-- Angular
-- React (via wrapper)
-- Vue
-- Any framework that supports Web Components
+# rel-kbd
+
+`<rel-kbd>` is the single key cap from the Figma "Kbd" component (node 6316:284): a flat, bordered chip that shows a keyboard key or shortcut inline with text, in three heights (20 / 24 / 28px) and two fills (`default`, `muted`), with an `inset` pressed look. `<rel-kbd-group>` (Figma Kbd Items=1–4) renders a multi-key shortcut from an `items` array, one `<rel-kbd>` per key joined by "+" separators. Use them in help text, tooltips, menus and command palettes to display shortcuts. They are display-only — do not use them as buttons, and use `rel-chip` for tags or `rel-badge` for counts.
+
+## Usage
+
+```html
+<!-- Single key -->
+<rel-kbd>K</rel-kbd>
+
+<!-- Sizes -->
+<rel-kbd size="small">Esc</rel-kbd>
+<rel-kbd size="medium">Enter</rel-kbd>
+<rel-kbd size="large">Space</rel-kbd>
+
+<!-- Variants -->
+<rel-kbd variant="default">Shift</rel-kbd>
+<rel-kbd variant="muted">⌘</rel-kbd>
+
+<!-- Pressed look -->
+<p>Hold <rel-kbd inset>Space</rel-kbd> to preview</p>
+
+<!-- Multi-key shortcut from an items array (JSON attribute or property) -->
+<rel-kbd-group items='["Ctrl","Shift","P"]' size="medium"></rel-kbd-group>
+<rel-kbd-group id="palette" variant="muted" size="small"></rel-kbd-group>
+<script>
+  document.getElementById("palette").items = ["⌘", "K"];
+</script>
+
+<!-- Inline with text -->
+<p>Press <rel-kbd-group items='["Ctrl","K"]'></rel-kbd-group> to search</p>
+```
+
+### Deprecated aliases
+
+```html
+<!-- sm / md / lg → small / medium / large (accepted silently; no console notice) -->
+<rel-kbd size="sm">S</rel-kbd>
+<rel-kbd size="md">M</rel-kbd>
+<rel-kbd size="lg">L</rel-kbd>
+<rel-kbd-group items='["Ctrl","C"]' size="md"></rel-kbd-group>
+
+<!-- `pill` is deprecated → use the default 4px radius. Still renders fully rounded corners and logs once:
+     [rel-kbd] "pill" is deprecated and will be removed in 3.0 — use "the default radius (4px at every size)" instead. The Kbd spec has one radius at every size; pill keeps working but is not part of the design. -->
+<rel-kbd pill>R</rel-kbd>
+```
+
+<!-- readme-gen:start -->
+
+<!-- Generated from rel-kbd.ts — do not edit; run readme-generate.mjs -->
+
+## Elements
+
+| Element | Class | Source |
+| --- | --- | --- |
+| `<rel-kbd>` | `RelKbd` | `rel-kbd.ts` |
+| `<rel-kbd-group>` | `RelKbdGroup` | `rel-kbd.ts` |
+
+## API
+
+### `<rel-kbd>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Key-cap scale (Figma Size): `small` 20px tall / label-sm, `medium` 24px / label-md, `large` 28px / label-lg; 4px radius at every size. `sm` / `md` / `lg` are the legacy short spellings and stay accepted. Reflected. |
+| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Fill / text contrast: `default` = elevated-1 background with label text; `muted` = elevated-2 background with placeholder-tone text for secondary shortcuts. Both are flat with a 1px border. Reflected. |
+| `inset` | `inset` | `boolean` | `false` | Pressed look: border-strong stroke, 1px downward nudge and (muted variant) a darker fill. Reflected. |
+
+##### Deprecated (still supported — removal targeted for 3.0)
+
+| Property | Attribute | Type | Use instead |
+| --- | --- | --- | --- |
+| `pill` | `pill` | `boolean` | The Kbd spec has a single 4px radius at every size (audit 16); `pill` is kept working as an alias but logs a one-time notice. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | The key label (e.g. `Ctrl`, `K`, `⌘`) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| — | None exposed. |
+
+### `<rel-kbd-group>`
+
+#### Attributes / Properties
+
+| Property | Attribute | Type | Default | Description |
+| --- | --- | --- | --- | --- |
+| `items` | `items` | `string[]` | `[]` | Key labels to render, one `<rel-kbd>` each, joined by `+` separators. Set as a property or as a JSON array attribute (`items='["Ctrl","K"]'`). |
+| `size` | `size` | `"sm" \| "md" \| "lg" \| "small" \| "medium" \| "large"` | `"md"` | Passed through to every generated <rel-kbd>: `small` / `medium` / `large` (legacy `sm` / `md` / `lg` still accepted). Reflected. |
+| `variant` | `variant` | `"default" \| "muted"` | `"default"` | Passed through to every generated <rel-kbd>: `default` or `muted`. Reflected. |
+
+### Events
+
+| Event | Detail | Bubbles / composed | Description |
+| --- | --- | --- | --- |
+| — | — | — | This element emits no custom events. |
+
+### Slots
+
+| Slot | Description |
+| --- | --- |
+| (default) | Extra content rendered after the generated keys (e.g. hand-written `<rel-kbd>` children) |
+
+### CSS Parts
+
+| Part | Description |
+| --- | --- |
+| `label` | The `+` separator between generated keys |
+| `item` | Each generated `<rel-kbd>` key cap |
+
+<!-- readme-gen:end -->
+
+## Accessibility
+
+- Both elements are purely presentational: no ARIA role, no `tabindex`, no keyboard handling and no events. `<rel-kbd>` renders only its default slot, so the key label is plain text for screen readers.
+- Neither element wraps its content in a native `<kbd>`. If you need that semantics, put the `<kbd>` in light DOM: `<kbd><rel-kbd>Ctrl</rel-kbd></kbd>`.
+- In `<rel-kbd-group>` the "+" separators are `aria-hidden="true"`, so a shortcut reads as the sequence of key labels only.
+- Text is `user-select: none` on the key caps and separators, so shortcuts are not copied along with surrounding prose.
+- Colours come from the neutral elevated backgrounds with `--rel-text-label` (default) and `--rel-text-placeholder` (muted) text; the muted variant is intended for secondary shortcuts and has lower contrast by design.
+
+## Notes / Edge Cases
+
+- Heights are the Figma frame heights (20 / 24 / 28px) with the 1px border inside them (`box-sizing: border-box`), and the corner radius is 4px at every size. The key cap is flat — fill plus 1px stroke, no shadow — matching the Figma component.
+- `small` / `medium` / `large` and `sm` / `md` / `lg` are interchangeable at the CSS level (`:host([size="md"])` and `:host([size="medium"])` share rules); the default value is `md`.
+- `inset` swaps the stroke to `--rel-border-strong` and nudges the cap 1px down; in the `muted` variant it also darkens the fill.
+- A `<span>` slotted into `<rel-kbd>` picks up body-sm-regular type (Figma hint text) instead of the label type.
+- `<rel-kbd-group>` passes its `size` and `variant` to every generated key; `items` set as an attribute must be a JSON array string. Slotted `<rel-kbd>` children render after the generated keys with no automatic "+" separators — either use `items` or hand-write the whole shortcut.
+- The `item` and `label` parts exist only on `<rel-kbd-group>`; a standalone `<rel-kbd>` exposes no parts.