Kbd#

키보드 키를 시각적으로 표현하는 컴포넌트입니다. 단축키 안내, 도움말 페이지, 커맨드 팔레트 등에서 활용합니다. 양쪽 플랫폼이 동일한 토큰 (labelSmall, surfaceContainer 배경, outline 보더, field radius) 으로 렌더됩니다.

Live Preview#

class KbdDefaultExample extends StatelessComponent {
  const KbdDefaultExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoKbd(keys: ['Ctrl', 'C']);
  }
}

class KbdDefaultExample extends StatelessWidget {
  const KbdDefaultExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoKbd(keys: ['Ctrl', 'C']);
  }
}

class KbdComboExample extends StatelessComponent {
  const KbdComboExample({super.key});

  @override
  Component build(BuildContext context) {
    return const CoKbd(keys: ['Ctrl', 'Shift', 'P']);
  }
}

class KbdComboExample extends StatelessWidget {
  const KbdComboExample({super.key});

  @override
  Widget build(BuildContext context) {
    return const CoKbd(keys: ['Ctrl', 'Shift', 'P']);
  }
}

사용 시기 (When to Use)#

이 컴포넌트를 사용하세요:

• 단축키나 키보드 조합을 사용자에게 시각적으로 안내할 때
• 도움말 페이지나 온보딩에서 키보드 인터랙션을 설명할 때
• 커맨드 팔레트의 항목 옆에 단축키를 표시할 때
• 접근성 안내 문서에서 키보드 탐색 방법을 설명할 때

대신 다른 컴포넌트를 사용하세요:

• CodeSnippet: 여러 줄의 코드나 명령어를 표시할 때
• Text: 단순 텍스트로 키 이름을 표현해도 충분할 때
• KeyboardShortcut: 라벨/플랫폼별 표기와 함께 단축키를 표시할 때 (별도 컴포넌트)

기본 사용법 (Basic Usage)#

// 단일 키
const CoKbd(keys: ['Ctrl'])

// 키 조합
const CoKbd(keys: ['Ctrl', 'C'])

// 복잡한 단축키
const CoKbd(keys: ['Ctrl', 'Shift', 'P'])

// 맥 스타일
const CoKbd(keys: ['⌘', 'K'])

// 방향키
const CoKbd(keys: ['↑'])

// 단일 키 named ctor
CoKbd.single(keyText: '⌘')

// 단일 키
const CoKbd(keys: ['Ctrl'])

// 키 조합
const CoKbd(keys: ['Ctrl', 'C'])

// 복잡한 단축키
const CoKbd(keys: ['Ctrl', 'Shift', 'P'])

// 맥 스타일
const CoKbd(keys: ['⌘', 'K'])

// 단일 키 named ctor
CoKbd.single(keyText: '⌘')

Props / Parameters#

동작 스펙 (Behavior)#

인터랙션#

• 표시 전용 컴포넌트 — 클릭/호버 인터랙션 없음.

레이아웃#

• 루트는 inline-flex row — key + (sep + spacing) * (n-1) 순서로 나열.
• 각 키 박스: min-height: CoreSize.size20 + padding CoreSpace.space4 (수직) / CoreSpace.space6 (수평).
• 보더 1px (CoreColorScheme.outline), 배경 surfaceContainer, 라운드 CoreRadius.field.
• separator (+) 는 labelMedium 토큰 + mx-space2.

토큰#

예시 단축키#

// 복사
const CoKbd(keys: ['Ctrl', 'C'])

// 붙여넣기
const CoKbd(keys: ['Ctrl', 'V'])

// 전체 선택
const CoKbd(keys: ['Ctrl', 'A'])

// 커맨드 팔레트 (macOS)
const CoKbd(keys: ['⌘', 'K'])

// 저장
const CoKbd(keys: ['Ctrl', 'S'])

// 실행 취소
const CoKbd(keys: ['Ctrl', 'Z'])

사용 가이드라인 (Usage Guidelines)#

✅ Do#

플랫폼에 따라 다른 키 표기를 사용하세요:

const CoKbd(keys: ['⌘', 'K']) // macOS
const CoKbd(keys: ['Ctrl', 'K']) // Windows / Linux

KeyboardShortcut 컴포넌트는 platform-aware 자동 매핑을 제공하므로 사용자 OS 자동 분기에는 그쪽이 더 편합니다.

❌ Don't#

4개 이상의 키 조합을 단일 CoKbd 에 넣지 마세요. 가독성이 급격히 저하됩니다 (최대 3개 권장).

// ❌
const CoKbd(keys: ['Ctrl', 'Alt', 'Shift', 'F5'])

CoKbd 를 클릭 가능한 버튼처럼 사용하지 마세요. 표시 전용입니다 — 클릭이 필요하면 CoButton 을 쓰세요.

접근성 (Accessibility)#

• 표시 전용 — 키보드 포커스 / 인터랙션 대상 아님.
• 스크린 리더는 텍스트로 "Ctrl + C" 처럼 읽도록 의미있는 라벨이 필요하면 부모 컨테이너에 Semantics(label: ...) 를 적용하세요.

관련 컴포넌트 (Related Components)#

• CodeSnippet: 여러 줄 코드나 명령어 블록 표시
• KeyboardShortcut: 단축키 + 라벨, platform-aware 매핑
• Tooltip: 아이콘 버튼의 단축키 안내에 함께 사용