{
  "name": "Kbd",
  "source": "src/components/Kbd.tsx",
  "propsType": "KbdProps",
  "description": "Kbd — a key, or a keyboard shortcut, as printed on the keyboard.\n\n`<kbd>` is the element HTML has for this, and a combination is a `<kbd>` of\n`<kbd>`s — the spec's own shape for \"press these together\".\n\nWHAT A SCREEN READER HEARS\n\nThe symbols do not survive being read aloud: VoiceOver says \"⌘\" as \"place of\ninterest sign\" in some voices and \"⇧\" as \"upwards white arrow\". So a\nshortcut's drawn keys are hidden and a visually hidden copy spells them out\n— \"Command K\", \"Control Shift P\".",
  "import": "import { Kbd } from 'ionbase-ui';",
  "status": "stable",
  "since": "0.81.0",
  "summary": "A key, or a keyboard shortcut, drawn as keycaps in the reader's platform's own symbols and read aloud by name.",
  "useWhen": [
    "telling people a shortcut exists — beside a button, in a tooltip, in a command palette row",
    "instructions that name a key: \"press Esc to cancel\""
  ],
  "useInstead": [
    {
      "when": "the text is code, a file name or a value",
      "use": "render it directly",
      "why": "Kbd means keys to press; `<code>` is the element for code"
    }
  ],
  "a11y": {
    "guarantees": [
      "a combination is a <kbd> of <kbd>s, the HTML spec's shape for keys pressed together",
      "the drawn symbols are hidden and a visually hidden copy spells the keys out — \"Command K\", \"Control Shift P\" — because ⌘ and ⇧ are read as symbol names or not at all",
      "`mod` resolves to ⌘ on Apple platforms and Ctrl elsewhere; server rendering shows Ctrl and corrects after hydration without a mismatch"
    ],
    "requires": [
      "the shortcut to be bound somewhere — Kbd shows a key, it does not listen for one"
    ]
  },
  "antiPatterns": [
    {
      "dont": "writing `ctrl+k` or `cmd+k` for the platform's command key",
      "do": "write `mod+k`",
      "why": "`ctrl` shows a Mac user a key they do not press for it; `cmd` shows everyone else a key they do not have"
    },
    {
      "dont": "children like \"⌘K\" or \"Ctrl+K\"",
      "do": "`shortcut=\"mod+k\"`",
      "why": "hand-typed symbols are wrong on the other platform and are read aloud as symbol names"
    },
    {
      "dont": "setting `platform`",
      "why": "it overrides detection, so half the readers see the other platform's keys; it exists for docs that compare the two"
    }
  ],
  "stylesheet": "src/styles/kbd.css",
  "tokens": [
    "--border-default",
    "--border-width-default",
    "--font-family-sans",
    "--font-weight-medium",
    "--radius-xs",
    "--spacing-2",
    "--spacing-20",
    "--spacing-4",
    "--surface-subtle",
    "--text-secondary",
    "--type-caption",
    "--type-caption-line-height"
  ],
  "props": {
    "shortcut": {
      "type": "string | undefined",
      "required": false,
      "origin": "own",
      "description": "A whole shortcut, `+`-joined: `mod+k`, `mod+shift+p`, `esc`. `mod` is ⌘\non a Mac and Ctrl elsewhere, so write `mod` rather than guessing. Drawn as\none key per part, in the platform's order."
    },
    "children": {
      "type": "React.ReactNode",
      "required": false,
      "origin": "own",
      "description": "One key, as printed: `K`, `Esc`, `/`. Use `shortcut` for a combination."
    },
    "platform": {
      "type": "KbdPlatform | undefined",
      "required": false,
      "origin": "own",
      "description": "Leave it out: the reader's platform is detected. Set it only to show a\nspecific platform's keys — a docs page comparing the two.",
      "values": [
        "mac",
        "other"
      ]
    },
    "keyLabels": {
      "type": "Partial<Record<import(\"/Users/raza/Documents/Apps/ionbase-design-system/packages/ionbase-ui/src/components/shortcut\").ShortcutKeyId, { symbol?: string; macSymbol?: string; name?: string; }>> | undefined",
      "required": false,
      "origin": "own",
      "description": "What `shortcut`'s keys are printed as and read out as, for translation —\n`{ control: { symbol: 'Strg', name: 'Steuerung' } }`. English by default.\nKeyed by the physical key: `mod` is `command` on a Mac, `control` elsewhere."
    },
    "className": {
      "type": "string | undefined",
      "required": false,
      "origin": "own"
    }
  },
  "propCounts": {
    "own": 5,
    "aria": 0,
    "dom": 0,
    "other": 0
  }
}