Kbd

목적

Kbd는 키보드 키 또는 단축키 조합을 본문과 구분해 표시한다. 사용자가 마우스 없이 반복 업무를 빠르게 수행할 수 있다는 사실을 발견하게 하되, 단축키 자체가 유일한 조작 경로가 되지 않게 한다.

선택 기준

• 메뉴 항목, 도움말, tooltip에서 실제로 등록된 단축키를 안내할 때 사용한다.
• 일반 코드, 변수, 상태값에는 code를 사용한다.
• 사용자가 누를 수 없는 장식적인 키 조합을 표시하지 않는다.
• 초보 사용자의 기본 흐름을 단축키 설명으로 대체하지 않는다.

구조

• semantic kbd 요소로 렌더된다.
• children에 하나의 키 이름 또는 읽을 수 있는 조합을 넣는다.
• 여러 키를 각각 구분해야 하면 여러 Kbd를 텍스트와 함께 조합한다.

변형과 크기

• 별도 variant와 size prop은 없다.
• 기본 높이는 24px이며 monospace 글꼴, border와 중립 배경을 사용한다.
• className은 주변 문장과의 배치에만 제한적으로 사용한다.

상태와 동작

• 자체 상호작용, focus, pressed 상태가 없다.
• 실제 단축키 등록 여부나 충돌 처리는 소비 제품이 소유한다.
• 플랫폼에 따라 키 이름이 달라지면 현재 환경에 맞는 문자열을 제품에서 전달한다.
• 입력창과 content-editable 영역에서는 전역 단축키가 사용자 입력을 가로채지 않게 한다.

콘텐츠

• Esc, Enter, Shift, ⌘처럼 사용자가 키보드에서 찾을 수 있는 이름을 쓴다.
• 조합 순서를 실제 입력 순서와 같게 표시한다.
• 단축키가 수행하는 행동은 인접한 텍스트나 메뉴 레이블로 설명한다.
• 내부 이벤트 코드나 구현 상수명을 표시하지 않는다.

접근성

• kbd는 키 입력을 나타내는 semantic element다.
• 기호만으로 이해하기 어려운 키는 눈에 보이는 이름 또는 인접 설명을 함께 제공한다.
• 단축키가 있는 행동에도 클릭·터치·키보드 탐색으로 접근 가능한 기본 control이 있어야 한다.
• 실제 control에는 필요한 경우 aria-keyshortcuts를 별도로 제공한다.

좁은 화면과 긴 콘텐츠

• 터치 중심의 작은 화면에서 실행할 수 없는 단축키는 숨기거나 해당 환경에 맞는 대체 조작을 안내한다.
• 긴 키 이름을 한 Kbd 안에 넣지 말고 읽을 수 있는 단위로 나눈다.
• 문장 안에서 줄바꿈되더라도 키와 수행 행동의 관계가 끊기지 않게 묶는다.

공개 API

Kbd는 React.HTMLAttributes<HTMLSpanElement>와 같은 표준 속성을 받으며 실제 요소는 kbd로 렌더된다.

예제

import { Kbd } from '@classum/dot-design-system/ui';

export function SearchShortcutHint() {
  return (
    <p className="text-sm text-ink-subtle">
      어디서나 검색하려면 <Kbd>⌘</Kbd> + <Kbd>K</Kbd>를 누르세요.
    </p>
  );
}

피해야 할 사용

• 클릭 가능한 버튼처럼 사용하는 경우
• 실제로 동작하지 않는 단축키 표시
• 키보드 경로만 제공하고 동일한 기능의 기본 control 생략
• 기술 코드값을 사용자 키 이름으로 표시
• 모바일에서도 실행 불가능한 키 안내를 핵심 행동처럼 노출

관련 항목

• 행동과 레이블
• 검색과 필터
• DotTheme