Kbd

Kbd (UI) — Design System (Symfony UX Toolkit / shadcn)

BASE CONGELADA (não mude por instância): Elemento semântico <kbd> (e KbdGroup também <kbd>). Congelados: fundo bg-muted, cor text-muted-foreground, tipografia text-xs font-medium font-sans, cantos rounded-sm, dimensões h-5/min-w-5/px-1 e gap-1, pointer-events-none e select-none (é decorativo por padrão), ícones SVG travados em size-3, e o estilo invertido quando dentro de tooltip (in-data-[slot=tooltip-content]). KbdGroup congela inline-flex items-center gap-1. Nenhum enricher altera fonte, cor, cantos ou espaçamento — só conteúdo aditivo e comportamento.

USO: <twig:Kbd />

CAPACIDADES OPT-IN (ligue sem alterar o visual):
- Notação (símbolo vs por extenso): Renderiza modificadores como glifos (⌘⇧⌥⌫⏎) ou por extenso (Cmd/Shift/Backspace/Enter); troca só o conteúdo do texto, sem tocar no estilo. [select → Símbolo (⌘⇧⌥) / Por extenso (Cmd/Shift) / Símbolo + texto]- Plataforma (auto-mapear tecla Mod): Mapeia a tecla lógica 'Mod' para o modificador certo por sistema — ⌘ no macOS, Ctrl no Windows/Linux — detectando o SO ou forçando uma plataforma. [select → Automático (detecta o SO) / macOS / Windows / Linux]- Separador do grupo (KbdGroup): Insere automaticamente o separador entre as teclas do grupo, dispensando o <span>+</span> manual do markup atual. [select → + / espaço / então (sequência) / ／ / nenhum]- Atalho funcional (disparar ação): Registra o listener global do combo; ao pressionar as teclas, dispara a ação alvo (clique num seletor ou emissão de evento), tornando o Kbd decorativo realmente vivo. Suporta acordes sequenciais (ex.: 'g depois i'). [toggle]- Copiar ao clicar: Habilita clique no Kbd (que por padrão é pointer-events-none/select-none) para copiar o texto do atalho — ex.: 'Ctrl+B' — para a área de transferência, com aviso transitório 'copiado'. [toggle]- Tooltip de descrição do atalho: Anexa um tooltip explicando o que o atalho faz (ex.: ⌘K → 'Abrir busca'); a base já prevê o Kbd renderizado dentro de tooltip. [text]- Nome falado da tecla (a11y): Adiciona aria-label traduzindo o glifo para leitores de tela (⌘ → 'Command', ⏎ → 'Enter', ⌫ → 'Backspace'), enriquecendo a leitura sem alterar o visual. [toggle]- Eco ao pressionar (destaque físico): Destaca brevemente a tecla quando a tecla física correspondente é pressionada — útil em tutoriais/treino de teclado. HONESTO: reprovado no teste, pois o realce introduz um novo estado de cor/fundo — logo é decisão de BASE (vale para todos), não um enricher. [toggle]  (⚠️ borderline: revisar se não é decisão de base)FAÇA:
- Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.
- Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.
- Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}.
NÃO FAÇA:
- Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.
- Não crie variante/fork para a mesma coisa — existe UMA base por componente.
- Não reimplemente o componente nem adicione toolchain Node.
TESTE ANTES DE MUDAR: "é função ou é base?" — função = capacidade opt-in; base = mude o token na fonte única (assets/styles/app.css), para todos.

A11Y (herdada da base): Elemento semântico <kbd> (e KbdGroup também <kbd>)

{
    "$schema_version": "1.0",
    "id": "kbd",
    "component": "Kbd",
    "eixo": "ui",
    "particularidade": "O Kbd é o token visual fiel de uma tecla física / atalho de teclado — sua unicidade é representar teclas reais, presas a convenções de SO/plataforma e a notação de símbolos, e (opcionalmente) a uma ação de teclado de verdade. Por isso seus enriquecedores giram em torno de tradução de teclas (símbolo⇄texto, macOS⇄Windows) e de tornar o atalho decorativo realmente funcional — nunca de mudar seu visual.",
    "base_congelada": "Elemento semântico <kbd> (e KbdGroup também <kbd>). Congelados: fundo bg-muted, cor text-muted-foreground, tipografia text-xs font-medium font-sans, cantos rounded-sm, dimensões h-5/min-w-5/px-1 e gap-1, pointer-events-none e select-none (é decorativo por padrão), ícones SVG travados em size-3, e o estilo invertido quando dentro de tooltip (in-data-[slot=tooltip-content]). KbdGroup congela inline-flex items-center gap-1. Nenhum enricher altera fonte, cor, cantos ou espaçamento — só conteúdo aditivo e comportamento.",
    "props": [],
    "capacidades": [
        {
            "id": "nota-o-s-mbolo-vs-por-extenso",
            "nome": "Notação (símbolo vs por extenso)",
            "descricao": "Renderiza modificadores como glifos (⌘⇧⌥⌫⏎) ou por extenso (Cmd/Shift/Backspace/Enter); troca só o conteúdo do texto, sem tocar no estilo.",
            "controle": "select",
            "opcoes": [
                "Símbolo (⌘⇧⌥)",
                "Por extenso (Cmd/Shift)",
                "Símbolo + texto"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "plataforma-auto-mapear-tecla-mod",
            "nome": "Plataforma (auto-mapear tecla Mod)",
            "descricao": "Mapeia a tecla lógica 'Mod' para o modificador certo por sistema — ⌘ no macOS, Ctrl no Windows/Linux — detectando o SO ou forçando uma plataforma.",
            "controle": "select",
            "opcoes": [
                "Automático (detecta o SO)",
                "macOS",
                "Windows",
                "Linux"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "separador-do-grupo-kbdgroup",
            "nome": "Separador do grupo (KbdGroup)",
            "descricao": "Insere automaticamente o separador entre as teclas do grupo, dispensando o <span>+</span> manual do markup atual.",
            "controle": "select",
            "opcoes": [
                "+",
                "espaço",
                "então (sequência)",
                "／",
                "nenhum"
            ],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (select). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "atalho-funcional-disparar-a-o",
            "nome": "Atalho funcional (disparar ação)",
            "descricao": "Registra o listener global do combo; ao pressionar as teclas, dispara a ação alvo (clique num seletor ou emissão de evento), tornando o Kbd decorativo realmente vivo. Suporta acordes sequenciais (ex.: 'g depois i').",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "copiar-ao-clicar",
            "nome": "Copiar ao clicar",
            "descricao": "Habilita clique no Kbd (que por padrão é pointer-events-none/select-none) para copiar o texto do atalho — ex.: 'Ctrl+B' — para a área de transferência, com aviso transitório 'copiado'.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "tooltip-de-descri-o-do-atalho",
            "nome": "Tooltip de descrição do atalho",
            "descricao": "Anexa um tooltip explicando o que o atalho faz (ex.: ⌘K → 'Abrir busca'); a base já prevê o Kbd renderizado dentro de tooltip.",
            "controle": "text",
            "opcoes": [],
            "posicionavel": true,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (text). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "nome-falado-da-tecla-a11y",
            "nome": "Nome falado da tecla (a11y)",
            "descricao": "Adiciona aria-label traduzindo o glifo para leitores de tela (⌘ → 'Command', ⏎ → 'Enter', ⌫ → 'Backspace'), enriquecendo a leitura sem alterar o visual.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": true,
            "como_plugar": "Capacidade opt-in (toggle). Ligue no configurador em /vitrine/ui/kbd; comportamento via controller Stimulus. Não altera a base."
        },
        {
            "id": "eco-ao-pressionar-destaque-f-sico",
            "nome": "Eco ao pressionar (destaque físico)",
            "descricao": "Destaca brevemente a tecla quando a tecla física correspondente é pressionada — útil em tutoriais/treino de teclado. HONESTO: reprovado no teste, pois o realce introduz um novo estado de cor/fundo — logo é decisão de BASE (vale para todos), não um enricher.",
            "controle": "toggle",
            "opcoes": [],
            "posicionavel": false,
            "e_funcao": false,
            "como_plugar": "REPROVADO no teste 'é função ou é base' — NÃO plugar como capacidade. É decisão de BASE: mude o token na fonte única assets/styles/app.css, valendo para TODOS os componentes."
        }
    ],
    "snippet_uso": "<twig:Kbd />",
    "exemplo_demo": "<div class=\"flex flex-col items-center gap-4\">\n    <twig:KbdGroup>\n        <twig:Kbd>⌘</twig:Kbd>\n        <twig:Kbd>⇧</twig:Kbd>\n        <twig:Kbd>⌥</twig:Kbd>\n        <twig:Kbd>⌃</twig:Kbd>\n    </twig:KbdGroup>\n    <twig:KbdGroup>\n        <twig:Kbd>Ctrl</twig:Kbd>\n        <span>+</span>\n        <twig:Kbd>B</twig:Kbd>\n    </twig:KbdGroup>\n</div>",
    "regras": {
        "faca": [
            "Use <twig:Nome> — a base é congelada, você é dono do template em templates/components/.",
            "Ligue apenas capacidades opt-in listadas (e_funcao=true); a aparência não muda ao ligá-las.",
            "Passe atributos extras (id, aria-*, name, data-*) via {{ attributes }}."
        ],
        "nao_faca": [
            "Não mude cor/fonte/cantos/espaçamento por instância — é decisão de BASE, na fonte única assets/styles/app.css.",
            "Não crie variante/fork para a mesma coisa — existe UMA base por componente.",
            "Não reimplemente o componente nem adicione toolchain Node."
        ]
    },
    "a11y": "Elemento semântico <kbd> (e KbdGroup também <kbd>)",
    "mcp": {
        "tool": "get_component",
        "args": {
            "id": "kbd"
        }
    },
    "props_nota": "Sem props próprias declaradas: a base repassa atributos nativos via {{ attributes }} (id, name, type, value, aria-*, data-*). Props específicas, quando existem, ficam nos subcomponentes."
}