Kbd

Utilitarioserver safe

Representa uma tecla de atalho ou, com o KbdGroup, uma sequência como Ctrl mais K.

Carregando

Instalação

Recebe correções por update de versão. O caminho recomendado.

npm i @trdr/ui

import { Kbd } from "@trdr/ui/kbd"

Uso

import { Kbd, KbdGroup } from "@trdr/ui/kbd"

export function Exemplo() {
  return <Kbd />
}

Props

KbdPropsestende React.HTMLAttributes<HTMLElement>
KbdGroupPropsestende React.HTMLAttributes<HTMLElement>

Quando usar

Use o Kbd para documentar um atalho de teclado: numa dica de tooltip, numa linha de ajuda, num item de menu ou numa tela de configuracao de atalhos. Ele existe para o usuario reconhecer visualmente "isto e uma tecla", nao para ser mais um texto solto na interface.

Para uma sequencia de teclas (Ctrl mais K, Ctrl mais Shift mais F), use o KbdGroup em volta de varios Kbd: ele cuida do separador entre as teclas e da semantica de leitor de tela.

Quando nao usar

Nao use Kbd como botao clicavel: ele e uma representacao visual, sem onClick, sem foco por Tab, sem papel interativo. Se o atalho tambem precisa ser acionavel por clique, o Kbd fica dentro de um Button ou de um item de menu, nunca no lugar deles. Nao use para exibir texto que nao e uma tecla (um valor, uma sigla, um codigo de erro): para isso o padrao e outro (texto monoespacado comum ou Badge).

Anatomia

  • Kbd (data-slot="kbd"): uma tecla isolada. Renderiza o elemento semantico <kbd>, com borda, fundo e tipografia da variante unica que o componente tem.
  • KbdGroup (data-slot="kbd-group"): agrupa dois ou mais Kbd numa sequencia, tambem como <kbd> (kbd aninhado dentro de kbd e o padrao do HTML para combinacoes de teclas).
  • kbd-group-separator (data-slot="kbd-group-separator"): o sinal "+" entre cada tecla do grupo, inserido automaticamente entre os filhos, exceto antes do primeiro.

Decisao de visual

A referencia legada e o .trdr-tooltip-hotkey do Hub antigo: texto colorido com content-secondary, 12px, peso 500, 0.2px de tracking, sem caixa nenhuma, porque so existia dentro do balao do Tooltip. O Kbd deste pacote mantem exatamente essa tipografia (via text-b4, que bate com as mesmas tres medidas), mas ganhou borda e fundo (os mesmos tokens do Badge neutro: border-border-subtle e bg-surface-secondary), porque fora do contexto de um tooltip colorido, um texto sem contorno nao le como tecla.

Acessibilidade

O elemento e <kbd>, que ja carrega significado semantico proprio (o navegador e leitores de tela entendem como "entrada de teclado") sem precisar de role ou aria-label adicional. Dentro do KbdGroup, o separador "+" e texto visivel de verdade, nao aria-hidden: a leitura por voz de "Ctrl mais K" depende dele estar la. Nao ha estado de foco ou interacao para tratar, porque o componente e puramente apresentacional.

Slots e tokens

Todo elemento renderizado carrega um data-slot para estilizar partes internas sem depender de classe da biblioteca. Os tokens listados são extraídos do código fonte.

[data-slot="kbd"][data-slot="kbd-group"][data-slot="kbd-group-separator"]
5 tokens usados
bg-surface-secondaryborder-border-subtletext-b4text-content-secondarytext-content-tertiary