# BestOW UI — 전체 문서 (LLM 용)

> 한국 서비스를 만들 때 바로 쓰는, 접근성이 검증된 React 디자인 시스템. npm `@bestow-ui/react`.
> 저장소 main 의 소스(@bestow-ui/react 2.1.0 기준)에서 자동으로 만든 파일이에요 — npm 최신 버전보다 앞선 내용이 있을 수 있어요.

사용 규칙 요약:
- 앱 진입점에서 `import '@bestow-ui/react/styles.css'` 를 한 번, 최상위를 `<ThemeProvider theme="light">` 로 감싼다(Toast 를 쓰면 `<ToastProvider>` 도).
- Next.js App Router: Provider 는 'use client' 파일로. Card·Typography·Stack 같은 표시용 컴포넌트와 서식 함수는 서버 컴포넌트에서도 쓴다.
- 폼 컴포넌트는 `label`·`helperText`·`error`·`required` 로 접근성 연결이 자동이다. 값을 고르는 컴포넌트는 `value`/`onValueChange`.
- 한국 서비스 입력(전화번호·사업자번호·금액 등)은 숫자만 든 문자열·number 를 값으로 주고받는다(하이픈·쉼표는 화면 표시용).
- 색·간격은 하드코딩하지 말고 테마(`createTheme`·`createIntentColors`·`vars`)로.

## README — @bestow-ui/react

**한국 서비스를 만들 때 바로 쓰는, 접근성이 검증된 React 디자인 시스템이에요.**
[vanilla-extract](https://vanilla-extract.style) 와 [Radix UI](https://www.radix-ui.com) 위에 만들었어요.

> A React design system for Korean services, with accessibility verified in CI. Docs are in Korean.


- **한국 서비스 키트** — 약관 동의(전체 동의), 인증번호(문자 자동 채우기·남은 시간), 전화번호·사업자등록번호(검증)·
  금액("12만 5,000원" 읽기)·주소(카카오 우편번호)·날짜(일요일 시작·공휴일)·기간(빠른 선택) 입력.
- **검사로 증명하는 접근성** — 모든 스토리를 실제 브라우저(Chromium·WebKit·Firefox)에서 라이트·다크 두 테마로 axe 검사해요.
  고대비 모드·320px 리플로·기본 글꼴 2배도 CI 로 확인하고, [KWCAG 2.2 항목별 대응 근거](https://dev-bestow.github.io/BestOW-UI/?path=/docs/accessibility-kwcag-2-2-%EB%8C%80%EC%9D%91--docs)를 문서로 정리했어요.
  주요 컴포넌트는 스크린리더(VoiceOver·NVDA)로 직접 들어 보고 [점검 기록](https://github.com/Dev-BestOW/BestOW-UI/blob/main/docs/SCREEN-READER-CHECKLIST.md)을 남겼어요.
- **대표색 하나로 테마** — 브랜드 색을 넣어도 글자 대비 4.5:1(hover 포함)과 포커스 링 3:1 을 라이트·다크 모두 지켜요.
  [테마 빌더](https://dev-bestow.github.io/BestOW-UI/?path=/story/foundations-theme-builder--builder)에서 바로 해 볼 수 있어요.
- **가볍고 서버 컴포넌트 친화적** — 런타임 CSS 0, Next.js App Router 지원, 쓰는 컴포넌트만 번들에 들어가요
  (Button 하나 약 1.7 kB, NativeSelect 로 만든 입력 폼 7종 약 4 kB, 모든 컴포넌트 CSS 를 합쳐도 약 11 kB — minify + brotli).
- **기본 문구는 한국어** — 닫기·결과 없음·달력 등 기본 문구가 한국어이고, `LocaleProvider` 로 한 번에 바꿀 수 있어요(영어 묶음 포함).

⚡ **[StackBlitz 에서 바로 써 보기](https://stackblitz.com/github/Dev-BestOW/BestOW-UI/tree/main/examples/vite-starter?file=src%2FApp.tsx)** (설치 없이 브라우저에서)

📖 **문서와 실제 예제:** [Storybook](https://dev-bestow.github.io/BestOW-UI/) · [Next.js 예제 앱](https://dev-bestow.github.io/BestOW-UI/playground/)

### 설치

```bash
npm install @bestow-ui/react
```

React 18 이상이 필요해요. [`@bestow-ui/icons`](https://www.npmjs.com/package/@bestow-ui/icons) 와 [`@bestow-ui/tokens`](https://www.npmjs.com/package/@bestow-ui/tokens) 는 함께 설치돼요.

### 시작하기

```tsx
import '@bestow-ui/react/styles.css'; // 앱 진입점에서 한 번
import { ThemeProvider, ToastProvider, Button, useToast } from '@bestow-ui/react';

export function App() {
  return (
    <ThemeProvider theme="light">
      <ToastProvider>
        <SaveButton />
      </ToastProvider>
    </ThemeProvider>
  );
}

function SaveButton() {
  const { toast } = useToast();
  return <Button onClick={() => toast({ title: '저장했어요', color: 'success' })}>저장</Button>;
}
```

Next.js App Router 에서는 Provider 를 `'use client'` 파일로 분리해 `app/layout.tsx` 에서 감싸면 돼요. 컴포넌트는 서버 컴포넌트에서도 바로 쓸 수 있어요.
상태가 없는 표시용 컴포넌트(`Typography`, `Stack`, `Grid`, `Container`, `Card`, `Badge`, `Divider`, `EmptyState`, `Progress`, `Skeleton`, `DescriptionList`, `VisuallyHidden`)는
서버 컴포넌트로 렌더링되고(클라이언트 JS 없음), `createTheme`·`createIntentColors`·`vars`·`formatKoreanAmount` 같은 함수·값도 서버에서 그대로 불러요.
자세한 설정은 [Storybook 시작하기](https://dev-bestow.github.io/BestOW-UI/)에 있어요.

`styles.css` 의 스타일은 CSS 레이어 `bestow` 안에 있어요. 레이어 밖에 쓴 CSS(`className` 등)가 선택자 우선순위와 관계없이 이기고,
리셋 CSS 는 `@layer base { … }` 에 넣어요. Tailwind 와 함께 쓰는 법은 Storybook **Guides › Tailwind 와 함께 쓰기**.

0.x 에서 올리시나요? [마이그레이션 가이드](https://github.com/Dev-BestOW/BestOW-UI/blob/main/docs/MIGRATION-1.0.md)를 보세요.

### 다크 모드

```tsx
const [mode, setMode] = useState<ThemeMode>('system'); // 'light' | 'dark' | 'system'

<ThemeProvider theme={mode}>…</ThemeProvider>;
```

Modal·Tooltip·Select·Toast 처럼 portal 로 띄우는 요소도 테마를 자동으로 따라가요.
`'system'` 은 OS 설정을 따르고, 서버 렌더링에서도 CSS 미디어쿼리로 그려 첫 화면이 깜빡이지 않아요.
사용자가 고른 모드를 쿠키로 저장해 서버에서 읽는 방법은 [Storybook 시작하기 › 다크 모드](https://dev-bestow.github.io/BestOW-UI/)에 있어요.

### 브랜드 테마

```tsx
import { ThemeProvider, createTheme, createIntentColors } from '@bestow-ui/react';

const brand = createTheme(
  createIntentColors('primary', '#7c3aed'), // 라이트·다크 색 세트, 글자 대비 4.5:1 보장
  { common: { radius: { md: '6px' } } },
);

<ThemeProvider theme={mode} overrides={brand}>…</ThemeProvider>;
```

입력 칸·체크 컨트롤(Checkbox·Radio·Switch) 테두리는 기본으로 배경과 3:1 이상이에요(2.0). 색만 바꾸려면 `color.border.input`·`inputHover`·`control` 토큰을 지정해요.

모든 토큰은 이름이 고정된 CSS 변수라 CSS 로도 덮어쓸 수 있어요.

```css
:root {
  --bestow-color-primary-solid: #7c3aed;
}
```

### 문구 바꾸기

기본 문구(닫기 버튼, "결과가 없어요", 달력 이름 등)는 한국어예요. `LocaleProvider` 로 한 번에 바꿔요.

```tsx
import { LocaleProvider, en } from '@bestow-ui/react';

<LocaleProvider messages={en}>…</LocaleProvider>
```

### 폼 라이브러리

react-hook-form 과 함께 쓸 수 있어요. 입력창은 `register` 를 그대로 펼치고, 값을 고르는 컴포넌트는 `Controller` 로 연결해요.
제출에 실패하면 `ErrorSummary` 가 포커스를 받아 고칠 곳을 알려요. 자세한 방법은 [화면 패턴](https://dev-bestow.github.io/BestOW-UI/?path=/docs/guides-%ED%99%94%EB%A9%B4-%ED%8C%A8%ED%84%B4--docs) 가이드에 있어요.

### 컴포넌트

| 분류 | 컴포넌트 |
|---|---|
| 레이아웃 | `Stack`(구간별 값 `{ base, md }`), `Grid`, `Container`, `Divider`, `Card`, `VisuallyHidden` — 구간 `media`(sm 640 · md 768 · lg 1024 · xl 1280px) |
| 글자 | `Typography` |
| 동작 | `Button`, `IconButton`, `Link` |
| 폼 | `Input`, `TextField`, `PasswordInput`(보기 버튼), `SearchInput`(지우기·Enter 검색), `FormField`(직접 만든 입력에 레이블·오류 연결), `Textarea`, `Select`, `NativeSelect`, `Combobox`, `MultiCombobox`(여러 개, 칸 안 칩), `NumberInput`, `FileUpload`, `Checkbox`, `CheckboxGroup`, `RadioGroup`, `Switch`, `Slider` |
| 피드백 | `Alert`, `ErrorSummary`, `Progress`, `ToastProvider` + `useToast`, `Spinner`, `Skeleton`, `Badge`, `Tag` + `TagGroup`(고른 필터·필터 칩), `EmptyState` |
| 오버레이 | `Modal`, `Drawer`, `Popover`, `Tooltip`, `DropdownMenu` |
| 탐색 | `Tabs`, `SegmentedControl`, `Accordion`, `Pagination`, `Breadcrumb`, `SkipLink`, `Stepper` |
| 표시 | `Avatar`, `Table`(+ `TableEmpty`, `TableSkeleton`, `useTableSelection`), `DescriptionList` |
| 한국 서비스 키트 | `AgreementGroup`(약관 동의), `VerificationCodeInput`(인증번호), `PhoneNumberInput`, `BusinessNumberInput`, `CorporateNumberInput`(법인등록번호), `CardNumberInput`, `AccountNumberInput`(+ 은행 목록 `KOREAN_BANKS`), `ResidentNumberInput`(주민·외국인등록번호, 뒷자리 가림), `AmountInput`, `AddressInput`, `DatePicker`, `DateRangePicker`(+ `dateRangePresets`), `Calendar` (+ `formatPhoneNumber`, `formatBusinessNumber`, `isValidBusinessNumber`, `formatKoreanAmount`, `formatKoreanDate`, 주민번호 `formatResidentNumber`·`isValidResidentNumber`·`parseResidentNumber`, 마스킹 `maskName`·`maskPhoneNumber`·`maskResidentNumber`·`maskCardNumber`·`maskDigits`, `parseISODate`, `toISODate` — 서식 함수는 React 없이도 쓰는 [`@bestow-ui/korean-utils`](https://www.npmjs.com/package/@bestow-ui/korean-utils) 에서 다시 내보내요) |
| 문구 | `LocaleProvider`, `en`(영어 문구 묶음) |
| 테마 | `ThemeProvider`, `createTheme`, `createIntentColors`, `vars`, `useTheme`, `usePortalProps` |
| 도움 함수 | `focusField` |

어떤 컴포넌트를 골라야 할지는 [언제 무엇을 쓰나](https://dev-bestow.github.io/BestOW-UI/?path=/docs/guides-%EC%96%B8%EC%A0%9C-%EB%AC%B4%EC%97%87%EC%9D%84-%EC%93%B0%EB%82%98--docs) 가이드를 보세요.

### 지원 범위

Chrome·Edge·Firefox·Safari 최근 2개 메이저 버전(모바일 포함), React 18·19, Next.js App Router 를 CI 로 확인해요.
**실서비스(프로덕션)에 써도 돼요** — 세 브라우저 엔진·모바일 E2E, React 18·19 CI, 스크린리더 수동 점검(VoiceOver·NVDA),
실제 화면 파일럿, 지원·보안 정책까지 갖췄어요.
버전 정책(semver·deprecated 절차)과 배포 주기는 [SUPPORT.md](https://github.com/Dev-BestOW/BestOW-UI/blob/main/SUPPORT.md),
보안 문제는 공개 이슈 대신 [SECURITY.md](https://github.com/Dev-BestOW/BestOW-UI/blob/main/SECURITY.md) 의 방법으로 알려 주세요.

### 링크

- [Storybook](https://dev-bestow.github.io/BestOW-UI/) — 문서, 디자인 토큰, 모든 컴포넌트
- [llms.txt](https://dev-bestow.github.io/BestOW-UI/llms.txt) · [llms-full.txt](https://dev-bestow.github.io/BestOW-UI/llms-full.txt) — Cursor·Claude 같은 AI 코딩 도구에 넣는 문서(모든 컴포넌트의 props 정의 포함)
- [GitHub](https://github.com/Dev-BestOW/BestOW-UI) — 소스, [이슈](https://github.com/Dev-BestOW/BestOW-UI/issues), [기여 방법](https://github.com/Dev-BestOW/BestOW-UI/blob/main/CONTRIBUTING.md)
- [변경 내역](https://github.com/Dev-BestOW/BestOW-UI/blob/main/packages/react/CHANGELOG.md) · [0.x 에서 올리기 (MIGRATION-1.0)](https://github.com/Dev-BestOW/BestOW-UI/blob/main/docs/MIGRATION-1.0.md)

### 라이선스

[MIT](https://github.com/Dev-BestOW/BestOW-UI/blob/main/LICENSE) © Dev-BestOW

## README — @bestow-ui/korean-utils

> Formatting, validation and masking helpers for Korean services — phone numbers, business, corporate and resident registration numbers, card and bank account numbers, KRW amounts in Korean, dates. Zero dependencies. Docs are in Korean.

**한국 서비스에 늘 필요한 서식·검증 함수를 모았어요.** 전화번호 하이픈, 사업자·법인등록번호 검증 공식, 주민등록번호 생년월일·성별 읽기, 카드번호(Luhn)·계좌번호와 은행 목록(금융결제원 코드),
"12만 5,000원" 금액 읽기, 한국어 날짜, 카카오 우편번호 참고항목, 화면에 보여 줄 때의 마스킹(`홍*동`, `010-****-5678`)까지.

- **의존성 0, 프레임워크 무관** — React·Vue·Svelte·Node 서버 어디서나 써요. 전체 약 2 kB(은행 목록 포함), 함수 하나만 쓰면 그만큼만 번들에 들어가요(`maskName` 하나 99 B, 카드번호 서식·검증 260 B, minify + brotli).
- **입력 중인 값도 자연스럽게** — `formatPhoneNumber('0101234')` → `'010-123-4'` 처럼 덜 입력한 값도 나눠서, 입력창의 onChange 에 그대로 쓸 수 있어요.
- **하이픈이 섞여도 됨** — 숫자가 아닌 글자는 무시해요.
- [BestOW UI](https://github.com/Dev-BestOW/BestOW-UI) 디자인 시스템의 `PhoneNumberInput`·`BusinessNumberInput`·`CardNumberInput`·`AmountInput` 등이 쓰는 함수 그대로예요.

### 설치

```bash
npm install @bestow-ui/korean-utils
```

### 사용하기

```ts
import {
  formatPhoneNumber,
  formatBusinessNumber,
  isValidBusinessNumber,
  formatKoreanAmount,
  formatKoreanDate,
} from '@bestow-ui/korean-utils';

formatPhoneNumber('01012345678'); // '010-1234-5678'
formatPhoneNumber('021234567'); //   '02-123-4567'
formatPhoneNumber('15881234'); //    '1588-1234'

formatBusinessNumber('1248100998'); //   '124-81-00998'
isValidBusinessNumber('124-81-00998'); // true (검증 공식)

formatKoreanAmount(125000); //    '12만 5,000원'
formatKoreanAmount(150000000); // '1억 5,000만원'
formatKoreanAmount(20000, '포인트'); // '2만포인트'

formatKoreanDate(new Date(2026, 9, 15)); //        '2026년 10월 15일 목요일'
formatKoreanDate(new Date(2026, 9, 15), false); // '2026년 10월 15일'

formatResidentNumber('9001011234567'); //  '900101-1234567'
isValidResidentNumber('900101-1234567'); // true (생년월일·뒷자리 첫 숫자)
parseResidentNumber('900101-1'); //        { birthDate: '1990-01-01', sex: 'male', foreigner: false }

maskName('홍길동'); //                  '홍*동'
maskPhoneNumber('01012345678'); //     '010-****-5678'
maskResidentNumber('9001011234567'); // '900101-1******'
maskCardNumber('1234-5678-9012-3456'); // '1234-****-****-3456'
maskDigits('110-123-456789', { end: 4 }); // '***-***-**6789' (계좌번호처럼 형식이 제각각인 번호)
```

### 함수

| 함수 | 하는 일 |
|---|---|
| `formatPhoneNumber(input)` | 하이픈 넣기. 서울(02)·대표번호(15xx·16xx·18xx)·휴대폰·지역번호·070 을 구분하고, 최대 자릿수를 넘으면 자른다 |
| `phoneNumberDigits(input)` | 국내 번호 숫자로 바꿈(`+82` → `0`, 숫자만 남기고 최대 자릿수로 자름) |
| `phoneNumberMaxDigits(digits)` | 그 번호의 최대 자릿수(02 → 10, 대표번호 → 8, 050 → 12, 나머지 → 11). 입력창 `maxLength` 계산에 |
| `formatBusinessNumber(input)` | 사업자등록번호 3-2-5 하이픈 |
| `isValidBusinessNumber(input)` | 사업자등록번호 검증 공식(가중치 1,3,7,1,3,7,1,3,5) 확인. **실제로 등록된 번호인지는 국세청 조회가 필요해요** |
| `formatCorporateNumber(input)` | 법인등록번호 6-7 하이픈 |
| `isValidCorporateNumber(input)` | 법인등록번호 검증 공식(앞 12자리에 가중치 1,2 를 번갈아 곱한 합) 확인. **실제로 등기된 법인인지는 등기소 조회가 필요해요** |
| `formatCardNumber(input)` | 카드번호 4-4-4-4 하이픈(아메리칸 익스프레스 15자리는 4-6-5) |
| `isValidCardNumber(input)` | 자릿수(15·16)와 검사 공식(Luhn)으로 오타 확인. **쓸 수 있는 카드인지는 결제사가 확인해요** |
| `cardNumberLength(input)` | 그 카드번호의 자릿수(34·37 로 시작하면 15, 나머지 16). 입력창 최대 자릿수에 |
| `KOREAN_BANKS` | 국내 은행 26곳 `{ code, name }` — 금융결제원 표준 코드 3자리(예: `'090'` 카카오뱅크). 많이 쓰는 은행부터. 합병·이름 변경이 있으면 갱신해요(2026-11 기준) |
| `accountNumberDigits(input)` | 계좌번호를 숫자로(하이픈·공백 제거, 최대 16자리). 은행·상품마다 하이픈 위치가 달라 서식은 넣지 않아요 |
| `isValidAccountNumber(input)` | 계좌번호 자릿수(10~16)만 확인. **은행마다 검증 공식이 공개돼 있지 않아요** — 실제 계좌·예금주는 예금주 조회 API 로 |
| `formatKoreanAmount(amount, unit = '원')` | 만·억·조 단위로 읽기 쉽게. 음수는 `-` 를 붙인다 |
| `formatKoreanDate(date, withWeekday = true)` | `2026년 10월 15일 목요일`. 스크린리더용 날짜 이름에도 좋아요 |
| `KOREAN_WEEKDAYS` | `['일', '월', '화', '수', '목', '금', '토']` |
| `formatResidentNumber(input)` | 주민·외국인등록번호 6-7 하이픈 |
| `parseResidentNumber(input)` | 앞 7자리로 생년월일(`YYYY-MM-DD`)·성별·외국인 여부. 없는 날짜면 `null`. 앞 7자리만 받는 화면에도 |
| `isValidResidentNumber(input)` | 13자리 + 생년월일·뒷자리 첫 숫자 확인. **마지막 검증 숫자는 보지 않아요** — 2020년 10월 이후 번호는 뒤 6자리가 임의 번호라 예전 공식으로는 올바른 번호도 틀렸다고 나와요. 실제 번호인지는 본인확인 기관 조회가 필요해요 |
| `maskName(name)` | 가운데 글자 가리기(`홍*동`, `남**수`, 두 글자는 `이*`, 한 글자는 `*`) |
| `maskPhoneNumber(input)` | 가운데 자리 가리기(`010-****-5678`). 대표번호는 그대로, 형식을 모르는 번호는 모두 가림 |
| `maskResidentNumber(input)` | 뒤 6자리 가리기(`900101-1******`) |
| `maskCardNumber(input)` | 앞 4·뒤 4자리만 남기기. 13자리 미만이면 모두 가림 |
| `maskDigits(input, { start, end })` | 숫자 중 앞 `start`·뒤 `end` 개만 남기고 가리기(구분 글자는 그대로). 남길 자리가 전체를 덮으면 모두 가림 |
| `composeExtraAddress(data)` | [카카오(다음) 우편번호 서비스](https://postcode.map.kakao.com/guide) 결과로 도로명 주소 참고항목(법정동, 공동주택 건물명)을 만든다 — 예: `' (역삼동, 래미안)'` |

#### 입력창에서 쓰기

```tsx
const [phone, setPhone] = useState('');

<input
  type="tel"
  inputMode="numeric"
  autoComplete="tel"
  value={formatPhoneNumber(phone)}
  // 서식을 거치면 최대 자릿수에서 잘리고, 숫자만 남겨 저장한다
  onChange={(e) => setPhone(formatPhoneNumber(e.target.value).replace(/\D/g, ''))}
/>;
```

숫자만 저장하고 보여 줄 때 서식을 입혀요. 이렇게 하면 중간에 글자를 지울 때 커서가 맨 끝으로 튀는데,
BestOW UI 의 [`PhoneNumberInput`](https://dev-bestow.github.io/BestOW-UI/?path=/docs/korean-kit-phonenumberinput--docs) 은 커서 위치와
하이픈 뒤 Backspace 까지 처리해 두었어요.

> 마스킹은 **화면 표시용**이에요. 저장·전송·로그에는 가린 값이 아니라 꼭 필요한 값만 남기세요.
> 주민등록번호는 법령에 근거가 있을 때만 수집할 수 있어요(개인정보 보호법 제24조의2).

### React 컴포넌트가 필요하면

[`@bestow-ui/react`](https://www.npmjs.com/package/@bestow-ui/react) 에 이 함수들을 쓰는 입력 컴포넌트가 있어요 — 전화번호·사업자등록번호·주민등록번호·금액·주소·인증번호·약관 동의·날짜.
접근성(KWCAG 2.2)을 CI 로 검사하고, 대표색 하나로 브랜드 테마를 만들 수 있어요. → [Storybook › Korean Kit](https://dev-bestow.github.io/BestOW-UI/?path=/docs/korean-kit-agreementgroup--docs)

`@bestow-ui/react` 1.5 까지 쓰던 `import { formatPhoneNumber } from '@bestow-ui/react'` 도 그대로 동작해요(같은 함수를 다시 내보내요).

### 라이선스

[MIT](https://github.com/Dev-BestOW/BestOW-UI/blob/main/LICENSE) © Dev-BestOW

## 언제 무엇을 쓰나

### 하나 고르기
선택지가 적고 한눈에 보여야 하면 RadioGroup·SegmentedControl, 많으면 Select(가볍게는 NativeSelect), 아주 많아 찾아야 하면 Combobox.
- RadioGroup: 폼 안에서 2~5개 중 하나. 선택지마다 설명이 필요할 때. 피할 때: 고르자마자 화면이 바뀌는 보기 전환 (→ SegmentedControl).
- SegmentedControl: 2~5개 짧은 이름 중 하나를 고르면 바로 반영(기간 일/주/월, 목록·격자 보기). 피할 때: 아래 내용(패널)이 통째로 바뀜 (→ Tabs). 폼 제출 값 (→ RadioGroup).
- Select: 6개 이상이거나 자리가 좁을 때. 목록이 길지 않아 훑어보면 찾을 수 있을 때. 피할 때: 20개 넘게 길어 찾기 어려움 (→ Combobox).
- NativeSelect: Select 와 같은 경우인데 번들을 줄이고 싶거나, 모바일 사용자가 많아 운영체제 선택 창이 나을 때. react-hook-form register 를 그대로. 피할 때: 목록 항목에 아이콘·설명을 넣거나 모양을 꾸며야 함 (→ Select).
- Combobox: 선택지가 많아 글자를 입력해 걸러야 할 때(도시·은행·상품). 피할 때: 선택지가 몇 개뿐 (→ Select·RadioGroup).
- DropdownMenu (라디오 항목): 정렬·간격처럼 화면 보기 설정을 메뉴 안에서. 피할 때: 폼에 제출하는 값 (→ Select·RadioGroup).

### 여러 개 고르기 · 켜고 끄기
폼에서 여러 개면 CheckboxGroup(하나뿐이면 Checkbox), 선택지가 많아 찾아야 하면 MultiCombobox, 약관은 AgreementGroup, 표의 행은 useTableSelection. 바로 적용되는 설정은 Switch.
- CheckboxGroup: 폼에서 여러 선택지 중 여러 개(관심 분야·받을 알림). 묶음 레이블·오류·"하나 이상" 필수 표시. 피할 때: 선택지가 많아(10개 넘게) 한눈에 안 들어옴 (→ MultiCombobox).
- MultiCombobox: 많은 선택지에서 글자를 입력해 찾아 여러 개(업무 지역·담당자·태그). 고른 값은 칸 안의 칩, 최대 개수(maxSelected). 피할 때: 선택지가 몇 개뿐이라 모두 보여 줄 수 있음 (→ CheckboxGroup).
- Checkbox: 제출할 때 함께 적용되는 동의·옵션 하나.
- AgreementGroup: 전체 동의 + 필수/선택 약관(보기 펼침 포함).
- Switch: 누르는 즉시 적용되는 켜기/끄기(알림 받기). 피할 때: "저장" 을 눌러야 적용되는 폼 값 (→ Checkbox).
- Table + useTableSelection: 목록의 행을 골라 일괄 작업.

### 글자 입력
한 줄은 TextField, 여러 줄은 Textarea. 비밀번호·검색처럼 버튼이 붙는 칸은 전용 컴포넌트를 쓴다.
- TextField: 이름·이메일처럼 한 줄 글자. 레이블·도움말·오류 연결이 들어 있다.
- Textarea: 메모·문의처럼 여러 줄(글자 수 표시·자동 높이).
- PasswordInput: 로그인·회원가입 비밀번호. 보기 버튼과 비밀번호 관리자 자동 완성. 피할 때: 인증번호(문자로 받는 숫자) (→ VerificationCodeInput).
- SearchInput: 목록을 거르는 검색어, 검색 페이지의 검색창. 지우기 버튼·Escape·Enter 검색. 피할 때: 정해진 목록에서 하나를 골라야 함 (→ Combobox).

### 숫자 · 금액 · 날짜
정확한 값은 입력창, 대략적인 값·범위는 Slider. 서식(쉼표·하이픈)은 컴포넌트가 맡는다.
- NumberInput: 수량·인원처럼 작은 범위의 정수·소수(−/+, ↑/↓).
- AmountInput: 금액. 천 단위 쉼표와 "12만 5,000원" 읽기.
- Slider: 대략적인 값이나 범위(음량·가격대)를 눈으로 고를 때. 피할 때: 정확한 값이 중요 (→ NumberInput, 또는 함께 둔다).
- DateRangePicker: 조회·예약 기간(시작일~종료일). 오늘·1주일·1개월 같은 빠른 선택.
- DatePicker: 날짜 하나. 숫자 입력(YYYY-MM-DD)과 달력 둘 다. 피할 때: 생년월일처럼 먼 날짜 — 숫자 입력이 더 빠르다는 것을 안내.
- 시간 (전용 컴포넌트 없음): 정해진 시간대(예약·배송)는 RadioGroup·Select, 아무 시각은 FormField + <input type="time">(min·max·step). 화면 패턴 "시간 고르기" 참고.

### 위에 띄우기 · 알리기
결정이 필요하면 Modal, 옆에서 길게 보면 Drawer, 짧은 추가 정보는 Popover, 결과 알림은 Toast, 페이지에 남겨야 하면 Alert.
- Modal: 흐름을 멈추고 확인·짧은 입력이 필요할 때(삭제 확인, 초대). 피할 때: 긴 내용·참고용 상세 (→ Drawer).
- Drawer: 목록에서 상세 보기·필터처럼 옆에서 길게 보는 내용.
- Popover: 버튼 옆의 짧은 추가 정보·작은 폼(공유 설정). 바깥을 누르면 닫힘.
- Tooltip: 아이콘 버튼 이름 같은 짧은 보조 설명. 피할 때: 꼭 알아야 할 정보·링크·버튼 (터치 기기에서 보기 어렵다).
- DropdownMenu: 버튼 하나에 모은 동작 목록(편집·복제·삭제). 피할 때: 페이지 이동 목록 (→ 링크 목록).
- Toast: 동작 결과를 잠깐 알림(저장했어요). 피할 때: 되돌리기처럼 놓치면 안 되는 동작만 두기 (사라진다).
- Alert: 페이지에 남아 있어야 하는 안내·경고. 일반 안내는 color="info"(브랜드 색과 따로 파랑), 브랜드를 드러내는 소개는 primary.
- ErrorSummary: 폼 제출에 실패했을 때 고칠 곳 모음(포커스·링크).

### 배치 · 페이지 틀
한 줄(가로·세로)로 늘어놓으면 Stack, 같은 폭 칸을 여러 열로 깔면 Grid, 페이지 본문의 최대 폭·좌우 여백은 Container.
- Stack: 버튼 줄·폼 칸처럼 한 방향으로 늘어놓음. 좁은 화면은 세로, 넓으면 가로 — direction={{ base: "column", md: "row" }}. 피할 때: 칸 폭이 같아야 하는 카드 목록 (→ Grid).
- Grid: 카드·상품처럼 같은 폭 칸을 여러 열로. 열 수를 구간별로(columns) 또는 칸 최소 폭만(minItemWidth). 피할 때: 행·열 머리글이 있는 데이터 (→ Table).
- Container: 페이지 본문을 가운데에 두고 최대 폭(sm~xl)과 좌우 여백(좁은 화면 16px · md 이상 24px)을 맞춤.

### 화면 나누기 · 이동
같은 페이지에서 내용을 바꾸면 Tabs, 세로로 접으면 Accordion, 진행 위치는 Stepper, 다른 페이지로 가면 Link.
- Tabs: 선택에 따라 아래 패널이 바뀜. 탭이 많거나 이름이 길면 세로. 피할 때: 값만 고르고 패널이 없음 (→ SegmentedControl).
- Accordion: 자주 묻는 질문처럼 여러 섹션을 세로로 펼쳐 봄.
- Stepper: 가입·결제처럼 단계가 정해진 흐름의 현재 위치 표시. 피할 때: 단계 간 자유 이동 (→ Tabs).
- Pagination: 긴 목록을 페이지로 나눔.
- Link · Button: 다른 페이지·주소로 가면 Link, 이 화면에서 동작하면 Button. 페이지 이동이 주요 동작이면 Button asChild 로 링크를 감싼다.

### 기다림 · 상태 표시
얼마나 남았는지 알면 Progress, 모르면 Spinner, 내용 자리를 미리 보여 주면 Skeleton. 상태 라벨은 Badge, 분류·필터는 Tag, 비어 있으면 EmptyState.
- Progress: 업로드처럼 진행률을 알 때(모르면 value 없이).
- Spinner: 짧은 대기·버튼 안 로딩(Button loading).
- Skeleton · TableSkeleton: 불러오는 동안 내용 모양을 미리(aria-busy 와 함께).
- Badge: 짧은 상태 라벨(결제 완료·배송 중).
- Tag: 분류·키워드, 고른 필터를 보여 주고 지우기(onRemove + TagGroup), 바로 켜고 끄는 필터 칩(selected). 피할 때: 상태 라벨 (→ Badge). 폼에 제출하는 여러 선택 (→ CheckboxGroup).
- EmptyState: 보여 줄 것이 없을 때(검색 결과 없음, 아직 만든 것 없음) — 무엇을 하면 되는지와 행동 버튼. 표 안은 TableEmpty 에 넣는다.

## 키보드·스크린리더 동작

- Button — 키보드: Enter·Space 로 실행. / 스크린리더: button. loading 이면 aria-busy·aria-disabled — 포커스는 유지되고(위치를 잃지 않음) 클릭·제출만 막힌다. 스피너는 장식으로 숨김. asChild 로 링크가 되면 역할은 link 이고, disabled 는 aria-disabled + Tab 제외 + 클릭 차단으로 나타낸다. / 사용하는 쪽: 아이콘만 있는 버튼은 IconButton 을 쓴다. 페이지를 이동하면 asChild 로 링크를 감싼다(링크는 되도록 비활성으로 두지 않는다).
- IconButton — 키보드: Enter·Space 로 실행. / 스크린리더: button. aria-label 이 타입으로 필수라 이름 없는 버튼을 만들 수 없다. 아이콘은 숨김. / 사용하는 쪽: 이름은 동작으로 ("닫기", "검색"). 같은 화면의 같은 아이콘은 같은 이름.
- Link — 키보드: Enter 로 이동. / 스크린리더: link. external 이면 새 창 안내("(새 창)")를 이름에 덧붙이고 rel="noopener noreferrer". as/asChild 로 라우터 링크를 써도 같은 스타일·속성. / 사용하는 쪽: 링크 글자만으로 목적지를 알 수 있게 ("여기" 대신 "환불 정책").
- TextField · Textarea · Input — 키보드: 기본 입력 동작. / 스크린리더: <label> 로 이름 연결, helperText 는 aria-describedby, error 면 aria-invalid. required 는 required 속성으로 알리고 화면의 * 표시는 스크린리더에서 숨김. Input 은 레이블 없는 단독 컨트롤 — 바깥에서 이름을 준다. / 사용하는 쪽: 오류 문구는 무엇이 틀렸고 어떻게 고치는지를 helperText 로.
- PasswordInput — 키보드: 보기 버튼은 입력창 다음 Tab 순서에 있고 Space·Enter 로 바꾼다. 마우스로 눌러도 입력창 포커스와 커서 위치가 그대로다. / 스크린리더: 보기 버튼은 이름 "비밀번호 보기" 고정 + aria-pressed(켜짐/꺼짐), aria-controls 로 입력창 연결. 글자로 보일 때는 일반 입력(type=text)으로 읽힌다. 자동 대문자·맞춤법 검사는 끈다. / 사용하는 쪽: 비밀번호 규칙은 helperText 로 미리 알린다. 회원가입·변경의 새 비밀번호는 autoComplete="new-password". 붙여넣기를 막지 않는다(KWCAG 7.3.3).
- SearchInput — 키보드: Enter → onSearch(한글 조합을 끝내는 Enter 는 무시), Escape → 검색어 지우기(빈 칸이면 아무것도 안 해서 바깥 Modal 등이 받는다). 지우기 버튼은 Escape 가 대신해 Tab 순서에서 빠져 있고, 누르면 입력창으로 포커스가 온다. / 스크린리더: searchbox(type=search). 레이블이 없으면 이름 "검색". 지우기 버튼 "검색어 지우기", 돋보기는 숨김. 모바일 키보드 Enter 키가 "검색" 으로 보인다(enterKeyHint). / 사용하는 쪽: 페이지의 주요 검색이면 감싸는 form 에 role="search"(랜드마크). 입력하는 대로 결과가 바뀌면 결과 수를 role="status" 로 알린다(/orders 예제). Modal 안에서는 Escape 가 검색어를 지우면서 Modal 도 닫는다(Radix 가 먼저 받음).
- Checkbox — 키보드: Space 로 체크. / 스크린리더: 네이티브 checkbox 라 모든 보조기기에서 동작. indeterminate 는 "혼합" 상태로 읽힌다.
- Switch — 키보드: Space·Enter 로 켜고 끔. / 스크린리더: switch, 켬/끔 상태. 네이티브 button(role=switch) — form 안에서는 숨긴 checkbox(aria-hidden)가 값 제출·required 검증을 맡는다. / 사용하는 쪽: 즉시 적용되는 설정에만. 제출해야 반영되는 값은 Checkbox.
- RadioGroup — 키보드: Tab 으로 그룹에 들어가면 선택된 항목(없으면 첫 항목)에 포커스, 화살표로 이동하며 바로 선택(비활성 건너뜀). 브라우저 기본 radio 라 키 입력 방식과 상관없이 같게 동작하고, 세부는 브라우저를 따른다 — 끝에서 처음으로 도는 것은 Chrome·Firefox, Safari 는 멈춤. Safari 는 마우스로 누르면 포커스를 주지 않는다. / 스크린리더: radiogroup (label 이 그룹 이름) 안의 네이티브 radio — "n개 중 m번째" 와 선택 상태를 읽는다. 보조 설명은 각 radio 의 설명으로, helperText·error·required 는 그룹에 연결.
- CheckboxGroup — 키보드: Tab 으로 체크박스마다 이동, Space 로 켜고 끈다(네이티브 checkbox). Safari 는 기본 설정에서 Tab 이 체크박스를 건너뛴다(Option+Tab). / 스크린리더: group (label 이 묶음 이름) 안의 네이티브 checkbox. group 에는 aria-required 가 없어 required 면 이름에 "필수" 를 넣는다(* 는 숨김). helperText·error 는 묶음 설명으로, 오류면 체크박스마다 aria-invalid. 보조 설명은 각 체크박스의 설명으로. / 사용하는 쪽: "하나 이상" 같은 검증은 폼에서 하고, 오류 문구에 무엇을 고칠지 적는다.
- FormField — 키보드: 감싼 입력을 따른다. / 스크린리더: <label for> 로 이름, helperText 를 aria-describedby 로, error·required 를 aria-invalid·aria-required 로 넘긴다. label 로 이름을 받을 수 없는 요소는 둘째 인자의 labelId 를 aria-labelledby 에. / 사용하는 쪽: 받은 속성을 실제로 포커스를 받는 요소에 펼친다. group 처럼 aria-invalid·aria-required 를 받지 못하는 역할이면 그 둘은 빼고 안의 컨트롤에 준다.
- FileUpload — 키보드: "파일 선택" 버튼(Enter·Space)으로 운영체제 파일 창을 연다 — 끌어다 놓기는 덤. 목록의 "○○ 삭제" 버튼으로 지우면 포커스가 다음 삭제 버튼, 없으면 "파일 선택" 으로 간다. / 스크린리더: group(레이블이 이름) + 도움말·거부 이유를 설명으로 연결. 선택한 파일은 목록 "선택한 파일", 추가·삭제·거부는 상태 알림(role=status)으로 읽는다("파일 2개 선택됨"). 삭제 알림은 포커스를 다음 버튼으로 옮긴 뒤 0.5초 있다가 넣고, 삭제 버튼은 파일 크기를 설명으로 읽는다(VoiceOver+Safari 수동 확인 2026-10-21). / 사용하는 쪽: 받는 형식·크기·개수를 helperText 로 미리 알린다. 서버 전송·진행률은 직접(Progress 와 함께).
- NumberInput — 키보드: ↑/↓ 한 단계(step), PageUp/PageDown 큰 단계(largeStep), min·max 가 있으면 Home/End 로 끝값. −/+ 버튼은 ↑/↓ 가 대신해 Tab 순서에서 빠져 있고, 눌러도 입력창 포커스를 뺏지 않는다. / 스크린리더: spinbutton — 현재 값(aria-valuenow)·최소·최대, 단위를 붙인 읽기 값(aria-valuetext "3개"). 키·버튼으로 바꾼 값은 숨은 알림 영역(assertive)으로도 알린다(VoiceOver+Safari 가 글자 편집으로만 읽어서 — 수동 확인 2026-10-21). 버튼은 "줄이기"/"늘리기"(aria-controls 로 입력창 연결), 범위 끝에서 비활성. / 사용하는 쪽: 입력 중에는 범위 밖 값도 받고 포커스가 빠질 때 맞춘다 — 범위를 helperText 로도 알린다(예: "최대 8명"). 금액은 AmountInput.
- SegmentedControl — 키보드: Tab 으로 들어가면 선택된 칸, ←/→ 로 옮기면 바로 선택(끝에서 처음으로 돈다, 비활성 칸은 건너뜀). / 스크린리더: radiogroup(label 또는 aria-label 이 이름) / radio 의 선택 상태. 아이콘은 숨김. / 사용하는 쪽: 선택에 따라 아래 내용(패널)이 바뀌면 Tabs 를 쓴다. 칸이 5개를 넘으면 Select.
- Select — 키보드: Enter·Space·↓ 로 열기, 화살표 이동, 글자 입력으로 항목 찾기, Enter 선택, Esc 닫기. / 스크린리더: combobox 버튼 + listbox. 선택된 값이 버튼 글자로 읽힌다.
- NativeSelect — 키보드: 브라우저 기본 select — 키 동작은 운영체제를 따른다(Windows 는 닫힌 채 ↑/↓ 로 바로 바뀜, macOS 는 Space·↓ 로 목록을 연다). 모바일은 운영체제 선택 창. 클릭(pointerup)으로 열려 6.5.2 걱정이 없다. / 스크린리더: combobox(네이티브 select) — 레이블·선택된 값·"n개 중 m번째" 를 보조기기가 직접 읽는다. placeholder 는 값이 빈 고를 수 없는 첫 항목. / 사용하는 쪽: 목록 모양·항목 아이콘을 꾸밀 수 없다(운영체제 창). 꾸며야 하면 Select.
- Combobox — 키보드: 입력하면 목록이 걸러진다. ↓/↑ 열기·이동(비활성 항목 건너뜀), Enter 선택(목록이 열려 있으면 폼 제출 대신), Esc 닫기, Tab 은 닫고 다음으로. 글자를 모두 지우고 닫으면(Enter·Esc·Tab) 선택이 지워진다. 한글 조합 중 누른 키는 조합을 끝내는 데만 쓴다. / 스크린리더: combobox(aria-autocomplete="list") + listbox. 포커스는 입력에 둔 채 aria-activedescendant 로 현재 항목을 알린다. "결과가 없어요" 는 처음부터 있는 숨은 status 영역에, 입력이 0.8초 멈춘 뒤 넣어 읽힌다(새로 생긴 live region·입력과 같은 순간의 변경은 VoiceOver 가 읽지 않음 — VoiceOver+Safari 수동 확인 2026-10-21). clearable 의 "선택 지우기" 버튼은 마우스용이라 Tab 순서에서 빠진다(키보드는 글자를 지워서 지운다).
- MultiCombobox — 키보드: 입력하면 목록이 걸러진다. ↓/↑ 열기·이동(비활성·최대 개수에 걸린 항목 건너뜀), Enter 고르기·풀기(목록은 열린 채 검색어만 지움), Esc 닫기, Tab 은 닫고 다음으로. 빈 입력창 맨 앞에서 Backspace 는 마지막 칩을 지운다. 칩 삭제 버튼은 Tab 순서(칩 → 입력창)에 있고 Enter·Space·Delete·Backspace 로 지운다. 한글 조합 중 누른 키는 조합을 끝내는 데만 쓴다. / 스크린리더: combobox + listbox(aria-multiselectable), 고른 항목은 aria-selected. 칩은 "고른 항목" 목록(ul), 삭제 버튼 이름 "서울 삭제". 칩을 지우면 포커스가 다음 칩 → 앞 칩 → 입력창으로 가고, "서울 삭제됨" 을 처음부터 있는 숨은 status 영역에 0.5초 뒤 넣는다(포커스 이동과 같은 순간이면 VoiceOver 가 버림). maxSelected 를 다 채우면 "최대 n개까지 고를 수 있어요" 를 같은 방식으로 알리고 칸 설명(aria-describedby)에도 둔다. "모두 지우기" 버튼은 마우스용이라 Tab 순서에서 빠진다. / 사용하는 쪽: 칩이 많아질 수 있으면 maxSelected 로 개수를 정한다. 스크린리더 수동 점검(VoiceOver·NVDA)은 아직 하지 않았다.
- Slider — 키보드: ←/→·↑/↓ 한 단계, PageUp/PageDown 큰 단계, Home/End 최소·최대. / 스크린리더: slider, 현재 값·최소·최대. 범위 슬라이더는 손잡이마다 "최소"/"최대" 가 이름에 붙는다. formatValue 가 화면 값과 aria-valuetext 에 함께 쓰인다. / 사용하는 쪽: 값에 단위가 있으면 formatValue 를 준다 (예: v => `${v.toLocaleString()}원`).
- DatePicker — 키보드: 숫자만 입력하면 YYYY-MM-DD 로 서식. "달력 열기" 버튼으로 열면 선택된(없으면 오늘) 날짜에 포커스, Esc 로 닫고 버튼으로 복귀. / 스크린리더: 입력 + "달력 열기" 버튼. 잘못된 날짜·범위 밖·덜 입력은 helperText 로 이유를 알리고 aria-invalid. 8자리를 채운 순간 생긴 오류는 숨은 status 영역에 입력이 0.8초 멈춘 뒤 넣어 바로 읽힌다(벗어날 때의 자릿수 안내는 설명으로만). 달력은 아래 Calendar 와 같다.
- DateRangePicker — 키보드: 시작일·종료일 칸은 DatePicker 와 같다. 빠른 선택은 버튼(Enter·Space)으로 두 칸을 한 번에 채운다. / 스크린리더: fieldset(legend 가 이름) 안에 "시작일"·"종료일" 칸. 시작일이 종료일보다 늦으면 그 칸이 aria-invalid + 이유. 빠른 선택은 group "빠른 선택", 현재 기간과 같은 버튼은 aria-pressed=true. "~" 는 숨김. / 사용하는 쪽: 조회 결과가 바뀌면 개수를 role="status" 로 알린다.
- Calendar — 키보드: 날짜 하나만 Tab 정지점. 화살표 하루/한 주, Home/End 주의 처음·끝, PageUp/PageDown 한 달, Shift+PageUp/PageDown 한 해, Enter·Space 선택. / 스크린리더: grid, 달 제목이 grid 이름이고 달이 바뀌면 aria-live 로 알림. 날짜 이름은 화면 숫자로 시작("15, 2026년 10월 목요일"), 오늘·공휴일·선택(aria-selected)·선택 불가(aria-disabled) 포함.
- PhoneNumberInput · BusinessNumberInput · AmountInput — 키보드: 하이픈·쉼표는 자동. 서식 문자 뒤에서 Backspace/Delete 를 누르면 그 너머 숫자를 지운다(커서 위치 유지). / 스크린리더: 모바일에서 숫자 키패드(전화번호는 inputMode="tel", 나머지는 "numeric"). AmountInput 은 "12만 3,400원" 같은 한글 금액을 helperText 로 함께 읽는다. 사업자번호는 검증 실패를 aria-invalid + 문구로 — 10자리를 채운 순간의 오류는 숨은 status 영역에 입력이 0.8초 멈춘 뒤 넣어 다시 들어가지 않아도 읽힌다(VoiceOver 점검 2026-10-21 의 개선 후보).
- CardNumberInput · CorporateNumberInput · AccountNumberInput — 키보드: BusinessNumberInput 과 같다 — 하이픈은 자동, 서식 문자 뒤 Backspace 는 그 너머 숫자를 지운다(계좌번호는 서식 없음). / 스크린리더: 숫자 키패드(inputMode="numeric"). 카드번호는 다 채운 순간의 검사 공식(Luhn) 오류, 법인등록번호는 검증 공식 오류를 숨은 status 영역에 입력이 0.8초 멈춘 뒤 넣는다(BusinessNumberInput 과 같은 내부 구현). 덜 채운 채 벗어나면 "끝까지 입력" 안내를 aria-describedby 로. 카드번호는 autocomplete="cc-number". / 사용하는 쪽: 은행은 KOREAN_BANKS 로 Combobox·NativeSelect 를 계좌번호 칸과 함께 두고 각각 레이블을 준다. 카드번호를 다시 보여 줄 때는 maskCardNumber. 붙여넣기를 막지 않는다.
- ResidentNumberInput — 키보드: 앞 6자리·뒷자리 두 칸을 Tab 으로 오간다. 앞칸을 채워도 포커스를 옮기지 않고(예고 없는 이동 금지, KWCAG 7.2.1), 번호를 통째로 붙여 넣으면 두 칸에 나눈다. 빈 뒷칸에서 Backspace 는 앞칸으로. / 스크린리더: group(레이블이 묶음 이름) 안의 두 칸 — "앞 6자리", "뒤 7자리"(password 라 "보안 텍스트" 로 읽힘). 모바일 숫자 키패드(inputMode="numeric"), 자동 완성 끔. 다 채운 순간의 검증 오류는 사업자번호와 같이 0.8초 뒤 status 로 알린다. / 사용하는 쪽: 법령 근거가 있을 때만 받는다. 나이·성별만 필요하면 digits={7}. 화면에 다시 보일 때는 maskResidentNumber.
- VerificationCodeInput — 키보드: 입력 하나라 붙여넣기·자동 채우기(autoComplete="one-time-code")가 그대로 된다. 숫자 외 글자는 걸러진다. / 스크린리더: 안내("6자리 숫자를 입력하세요.")를 aria-describedby 로. 남은 시간은 timer 역할이라 매초 읽지 않고, 만료되면 항상 있는 status 영역에 문구를 넣어 한 번 알린다. 글자 칸은 화면용(숨김). / 사용하는 쪽: 만료 시간은 충분히 (KWCAG 6.3.1 — 연장 수단인 재전송 버튼 제공).
- AgreementGroup — 키보드: 체크박스는 Space, "보기" 버튼으로 약관 펼침. / 스크린리더: fieldset(legend = label). "전체 동의" 는 일부 선택 시 혼합 상태. 항목 이름이 "필수 서비스 이용약관" 처럼 필수/선택으로 시작. 보기 버튼은 aria-expanded·aria-controls, 펼친 약관은 이름 있는 region(스크롤 가능하면 포커스 가능).
- AddressInput — 키보드: "주소 검색" 버튼 → 검색 창(Modal)에서 선택 → 상세 주소 입력으로 포커스 이동. / 스크린리더: fieldset. 우편번호·기본 주소는 읽기 전용 입력이라 값이 읽힌다. 검색 스크립트 로딩·실패는 status 로. / 사용하는 쪽: 카카오 우편번호 화면 자체의 접근성은 공급자 몫 — 직접 입력이 필요한 서비스는 대안을 둔다.
- Modal · Drawer — 키보드: 열리면 안으로 포커스, Tab 이 안에서만 돈다(포커스 가둠), Esc 로 닫고 연 요소로 포커스 복귀(trigger 없이 제어해도 복귀). / 스크린리더: dialog, title 이 이름·description 이 설명. 열려 있는 동안 바깥 내용은 스크린리더에서 숨겨진다. / 사용하는 쪽: title 은 꼭 준다. 닫기 버튼을 숨기면 다른 닫기 수단을 둔다.
- Popover — 키보드: 열리면 안으로 포커스, Esc 로 닫고 트리거로 복귀. 바깥을 누르면 닫힘. / 스크린리더: dialog(비모달). title 또는 aria-label 이 이름.
- DropdownMenu — 키보드: Enter·Space·↓ 로 열면 첫 항목, 화살표 이동(비활성 건너뜀), 글자 입력으로 찾기, Enter 실행, Esc 닫고 트리거로 복귀. 체크·라디오 항목은 Enter·Space 로 바꿈. 하위 메뉴는 →·Enter·Space 로 열어 첫 항목, ← 로 닫고 여는 항목으로 복귀. / 스크린리더: menu / menuitem / group. 체크 항목은 menuitemcheckbox, 라디오 항목은 menuitemradio + aria-checked(일부 선택은 mixed). 하위 메뉴를 여는 항목은 aria-haspopup="menu" + aria-expanded. 단축키·체크·화살표 표시는 이름에 섞이지 않게 숨김. / 사용하는 쪽: 메뉴는 "동작" 목록 — 페이지 이동 목록은 링크 목록(nav)으로. 체크 항목을 여러 개 이어서 바꾸게 하려면 onSelect 에서 preventDefault 로 열어 둔다. 하위 메뉴는 한 단계까지만.
- Tooltip — 키보드: 트리거에 포커스·마우스를 올리면 표시, Esc 로 닫힘. 툴팁 위로 마우스를 옮겨도 유지(KWCAG 6.1.4 계열). / 스크린리더: 트리거의 설명(aria-describedby)으로 읽힌다. / 사용하는 쪽: 꼭 필요한 정보는 툴팁에만 두지 않는다 (터치 기기에서는 보기 어렵다).
- Toast — 키보드: F8 로 알림 영역에 포커스, 포커스·마우스가 머무는 동안 자동 닫힘 멈춤, Esc 닫기. / 스크린리더: 알림 영역(region "알림") + 내용이 즉시 읽힘. action 은 altText 로 대체 방법을 알린다. / 사용하는 쪽: 되돌리기 같은 중요한 동작은 토스트에만 두지 않는다 (사라진다).
- Stepper — 키보드: 포커스를 받지 않는다 (표시용). 단계 이동은 "이전"·"다음" 버튼으로. / 스크린리더: 순서 목록(ol, 이름 "진행 단계") — "4개 중 2번째" 를 읽는다. 현재 단계는 aria-current="step", 완료한 단계는 "(완료)", loading 이면 현재 단계에 "(진행 중)" 을 함께 읽고, 원 안의 숫자·체크·스피너는 숨김. / 사용하는 쪽: 단계가 바뀌면 새 단계의 제목(h1 등)으로 포커스를 옮겨 바뀐 것을 알린다. 자동으로 진행되는 단계는 role="status" 영역으로 알린다.
- Tabs — 키보드: Tab 으로 탭 목록에 들어가면 선택된 탭, ←/→ 이동하며 전환(세로 orientation 이면 ↑/↓), Home/End. 비활성 탭은 건너뜀. / 스크린리더: tablist(aria-orientation 가로·세로) / tab(선택 상태) / tabpanel 연결. / 사용하는 쪽: 탭이 많거나 이름이 길어 가로로 넘치면 orientation="vertical" — 좁은 화면에서는 가로로 바꾸거나 Select 를 검토한다.
- Accordion — 키보드: Enter·Space 로 펼침, ↑/↓·Home/End 로 머리글 사이 이동. / 스크린리더: 머리글 button 의 aria-expanded, 본문은 머리글로 이름 붙은 region.
- SkipLink — 키보드: 페이지에서 첫 Tab 에 왼쪽 위에 나타나고, Enter 로 본문으로 포커스가 간다. macOS Safari 는 기본 설정에서 Tab 이 링크를 건너뛰어 Option+Tab(또는 설정 "Tab 키로 각 항목 강조")으로 닿는다 — 브라우저 동작. / 스크린리더: link "본문 바로가기". 숨김은 위치로만 해서(display:none 아님) Tab·스크린리더 모두 닿는다. / 사용하는 쪽: 페이지 맨 앞에 두고 본문 요소에 id="main"(기본 href) 을 준다.
- Breadcrumb — 키보드: 링크를 Tab 으로. / 스크린리더: nav "이동 경로", 현재 페이지는 aria-current="page". 구분자는 숨김.
- Pagination — 키보드: 버튼을 Tab 으로, Enter·Space. / 스크린리더: nav "페이지 탐색", 현재 페이지 aria-current, 버튼 이름 "3 페이지"·"이전 페이지". 생략(…)은 숨김.
- Table — 키보드: 넘치면 스크롤 영역에 포커스가 가서 화살표로 스크롤. 정렬 가능한 머리글은 버튼. / 스크린리더: caption 이 표·스크롤 영역 이름. 정렬 상태는 aria-sort. 행 머리글은 TableHead(scope). TableEmpty 는 표 전체 폭의 안내 셀, TableSkeleton 행은 숨김(표에 aria-busy). / 사용하는 쪽: caption(또는 aria-label)을 준다. 레이아웃용으로 표를 쓰지 않는다. 검색·필터로 결과가 바뀌면 개수를 role="status" 로 알린다. 행 선택 체크박스 이름은 "○○ 선택" (useTableSelection).
- ErrorSummary — 키보드: 나타나면(또는 focusKey 가 바뀌면) 요약으로 포커스. 링크(Enter)로 해당 칸에 간다 — 묶음은 선택된·첫 항목, FileUpload 는 "파일 선택" 버튼(focusField). / 스크린리더: 포커스를 받은 묶음의 이름이 제목("입력한 내용에 고칠 곳이 N개 있어요")이라 제목과 목록을 읽는다. role="alert" 는 쓰지 않는다(포커스와 함께 쓰면 두 번 읽힘). / 사용하는 쪽: 칸마다 error·helperText 도 함께 준다. react-hook-form 은 shouldFocusError: false + focusKey={submitCount}.
- Alert — 키보드: 닫기 버튼(onClose 를 줄 때). / 스크린리더: 기본은 역할 없음(처음부터 있는 안내). 동작 뒤에 새로 나타나면 role="alert"(긴급) 또는 role="status" 를 넘긴다. 아이콘은 숨기고 의미는 글자로.
- Progress — 키보드: 포커스를 받지 않는다. / 스크린리더: progressbar, 값·최대(aria-valuetext 로 "40%"), label 이 이름. value=null 이면 진행률 모름.
- Spinner — 키보드: 포커스를 받지 않는다. / 스크린리더: status "로딩 중". label="" 이면 장식(숨김) — 바깥에서 상태를 알릴 때(Button loading).
- Skeleton — 키보드: 포커스를 받지 않는다. / 스크린리더: 숨김(aria-hidden). / 사용하는 쪽: 로딩 중인 영역에 aria-busy="true" 를 붙인다.
- Badge · Avatar — 키보드: 포커스를 받지 않는다. / 스크린리더: Badge 는 글자 그대로. Avatar 는 alt 또는 name 이 있으면 img 와 그 이름(이미지 로딩·실패와 관계없이 같은 이름, 실패 시 화면은 이니셜), 없으면 장식으로 숨김. / 사용하는 쪽: 색만으로 상태를 구분하지 않게 Badge 글자에 상태를 쓴다.
- Tag · TagGroup — 키보드: 삭제 버튼은 Tab 순서에 있고 Enter·Space, 그리고 Delete·Backspace 로도 지운다. TagGroup 안에서 지우면 포커스가 그 자리의 다음 태그(없으면 앞 태그) 삭제 버튼으로, 다 지우면 목록으로 간다. 고르는 칩은 button 이라 Space·Enter. / 스크린리더: TagGroup 은 이름 있는 목록(ul, 태그마다 li). 삭제 버튼 이름 "<글자> 삭제", 지우면 포커스를 옮긴 0.5초 뒤 처음부터 있는 status 영역에 "<글자> 삭제됨". 고르는 칩은 aria-pressed(켜짐/꺼짐), 켜지면 체크 아이콘도 보여 색만으로 상태를 보이지 않는다(고대비 모드는 시스템 강조색). / 사용하는 쪽: 목록 이름(aria-label·aria-labelledby)을 준다. 고르는 칩 묶음은 role="group" + 이름으로 감싼다. 지우는 것(목록에서 빼기)은 onRemove 에서 직접. 글자가 문자열이 아니면 removeLabel.
- EmptyState — 키보드: Tab 으로 포커스만(또는 포커스 없음) / 스크린리더: 제목은 기본 h3(titleAs 로 수준을 맞추거나 표·카드 안에서는 p), 아이콘은 숨김. 나타날 때 스스로 알리지는 않는다. / 사용하는 쪽: 검색·필터로 결과가 0건이 되면 결과 수를 role="status" 로 알린다(/orders 예제). 제목은 무엇이 없는지, 설명은 무엇을 하면 되는지.
- Stack · Grid · Container · Card · Divider · Typography — 키보드: 포커스를 받지 않는다. / 스크린리더: 의미 없는 div 가 기본 — as 로 section·ul·main·h2 등 의미 요소를 고른다(목록 Grid 는 as="ul" + li, 페이지 본문 Container 는 as="main"). 반응형 Stack·Grid 는 보이는 배치만 바꾸고 읽는 순서(DOM)는 그대로다 — row-reverse 처럼 순서를 뒤집으면 보이는 순서와 읽는 순서가 달라지니 피한다. Typography 의 variant(모양)와 as(제목 단계)는 따로. Divider 는 기본 separator, 꾸밈용이면 decorative 로 숨긴다. / 사용하는 쪽: 제목 단계(h1~h6)는 모양이 아니라 문서 구조로 정한다.
- DescriptionList — 키보드: 포커스를 받지 않는다. / 스크린리더: dl 안의 dt·dd 쌍 — 이름과 값을 짝지어 읽는다(목록·항목 수를 알리는 스크린리더도 있다). aria-label 로 목록 이름을 줄 수 있다. / 사용하는 쪽: 같은 종류의 여러 줄을 비교해야 하면 Table.
- VisuallyHidden — 키보드: 포커스를 받지 않는다. / 스크린리더: 화면에는 안 보이지만 읽힌다(위치로 숨김, display:none 아님). 아이콘만 있는 열 머리글·보충 설명에. / 사용하는 쪽: 버튼·링크의 이름은 aria-label 이 더 간단하다. 보이는 글자와 다른 이름을 붙이지 않는다(KWCAG 6.5.3).

## 컴포넌트 API (props 정의 — 소스 그대로)

### Accordion

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Accordion/Accordion.tsx
```ts
/**
 * `type="single"`: 한 번에 하나만 열린다 (`value: string`). `collapsible` 이면 열린 항목을 다시 눌러 닫을 수 있다.
 * `type="multiple"`: 여러 개를 함께 열 수 있다 (`value: string[]`).
 */
export type AccordionProps = ComponentPropsWithoutRef<typeof RadixAccordion.Root>;

export interface AccordionItemProps extends Omit<ComponentPropsWithoutRef<typeof RadixAccordion.Item>, 'title'> {
  /** 항목 값. Accordion 의 value 와 비교한다 */
  value: string;
  /** 항목 제목 (펼침 버튼의 이름) */
  title: ReactNode;
  /** 제목을 감싸는 heading 수준. 페이지의 heading 구조에 맞춘다 (기본 3) */
  headingLevel?: 2 | 3 | 4 | 5 | 6;
  /** 펼쳤을 때 보이는 내용 */
  children?: ReactNode;
}
```

### AccountNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AccountNumberInput/AccountNumberInput.tsx
AccountNumberInput: 계좌번호 입력. 은행·상품마다 자릿수와 하이픈 위치가 달라 서식을 넣지 않고 숫자만 받는다(최대 16자리) —
은행 앱에서 "110-123-456789" 처럼 복사해 붙여 넣어도 숫자만 남는다. 10자리보다 짧게 두고 벗어나면 안내한다.
은행은 KOREAN_BANKS 로 Combobox·Select 를 함께 둔다. 실제 계좌·예금주 확인은 은행·결제사의 예금주 조회가 필요하다.
```ts
export interface AccountNumberInputProps extends CheckedNumberProps {
  // ── 아래는 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 숫자만 있는 값 (제어 모드). 예: "110123456789" */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 10자리 이상일 때 자릿수(10~16자리) 검증 통과 여부로 호출된다 (그 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /** 10자리보다 짧은 채 입력창을 벗어나면 자동으로 오류를 보여 준다 (기본 true). 직접 error·helperText 를 주면 그 값이 우선한다 */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
  /** 입력창 위에 표시할 레이블 — 기본 "계좌번호" */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### AddressInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AddressInput/AddressInput.tsx
AddressInput: 주소 입력 (우편번호 · 기본 주소 · 상세 주소). "주소 검색" 을 누르면 검색 창(Modal)에서 주소를 고르고,
고르면 상세 주소 입력창으로 포커스를 옮긴다.
```ts
export interface AddressValue {
  /** 우편번호 */
  zonecode: string;
  /** 기본 주소 */
  address: string;
  /** 참고 항목 (예: " (역삼동, 래미안아파트)") */
  extraAddress?: string;
  /** 상세 주소 (사용자가 입력) */
  detail: string;
}

export interface AddressInputProps {
  /** 주소 값 (제어 모드) */
  value?: AddressValue;
  /** 처음 값 (비제어 모드) */
  defaultValue?: AddressValue;
  /** 주소를 고르거나 상세 주소를 입력할 때 호출된다 */
  onValueChange?: (value: AddressValue) => void;
  /** 그룹 제목 */
  label?: ReactNode;
  required?: boolean;
  /** 아래 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  error?: boolean;
  disabled?: boolean;
  /** 주소 검색 공급자. 기본은 카카오(다음) 우편번호 서비스 — 처음 검색할 때 스크립트를 불러온다 */
  provider?: AddressProvider;
  /** 검색 버튼·검색 창 제목 */
  searchLabel?: string;
  detailPlaceholder?: string;
  /** 검색 화면을 불러오지 못했을 때 문구 */
  loadErrorText?: string;
  /** form 제출 시 이름. `${name}[zonecode]`, `${name}[address]`, `${name}[detail]` 로 제출된다 */
  name?: string;
  className?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AddressInput/addressProviders.ts
kakaoPostcodeProvider: 기본 공급자: 카카오(다음) 우편번호 서비스. 처음 쓸 때 스크립트를 불러오므로 코어 번들 크기에 영향이 없다.
사용 조건은 서비스 가이드를 따른다.
```ts
/** 주소 검색 결과 */
export interface AddressSearchResult {
  /** 우편번호 (5자리 국가기초구역번호) */
  zonecode: string;
  /** 기본 주소 (도로명 또는 지번) */
  address: string;
  /** 참고 항목 (도로명 주소일 때 법정동·건물명, 예: " (역삼동, 래미안아파트)") */
  extraAddress?: string;
}

/**
 * 주소 검색 공급자. container 안에 검색 화면을 그리고, 사용자가 고르면 onSelect 를 부른다.
 * 정리 함수를 돌려주면 검색 창이 닫힐 때 부른다. 다른 주소 서비스(행정안전부 도로명주소 API 등)로 바꿔 끼울 수 있다.
 */
export type AddressProvider = (
  container: HTMLElement,
  onSelect: (result: AddressSearchResult) => void,
) => void | (() => void) | Promise<void | (() => void)>;
```

### AgreementGroup

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AgreementGroup/AgreementGroup.tsx
AgreementGroup: 약관 동의 묶음. "전체 동의" 와 개별 항목이 서로 맞춰지고(일부만 동의하면 전체 동의는 부분 선택 상태),
항목마다 필수·선택 표시와 약관 내용 펼쳐 보기를 지원한다.
```ts
export interface AgreementGroupProps {
  items: AgreementItem[];
  /** 동의한 항목의 value 목록 (제어 모드) */
  value?: string[];
  /** 처음 동의한 항목 (비제어 모드) */
  defaultValue?: string[];
  /** 동의 항목이 바뀔 때 호출된다 */
  onValueChange?: (value: string[]) => void;
  /** 그룹 제목 (fieldset 의 legend) */
  label?: ReactNode;
  /** "전체 동의" 문구 */
  allLabel?: ReactNode;
  /** 아래 도움말. error 일 때는 에러 메시지로 표시된다 (예: "필수 약관에 동의해 주세요") */
  helperText?: ReactNode;
  error?: boolean;
  disabled?: boolean;
  /** 필수·선택 표시 문구 (다국어) */
  requiredText?: string;
  optionalText?: string;
  /** 약관 내용 펼치기 버튼 문구 */
  showText?: string;
  hideText?: string;
  /** form 제출 시 사용할 이름. 동의한 value 마다 hidden input 이 생긴다 */
  name?: string;
  /** fieldset 의 id — ErrorSummary 링크 등에서 이 묶음을 가리킬 때 */
  id?: string;
  className?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AgreementGroup/agreements.ts
```ts
export interface AgreementItem {
  value: string;
  /** 약관 이름 (예: "서비스 이용약관 동의") */
  label: ReactNode;
  /** 필수 동의 여부. 이름 앞에 "필수"/"선택" 이 붙는다 */
  required?: boolean;
  /** 펼쳐서 보여 줄 약관 내용. 있으면 "보기" 버튼이 생긴다 */
  content?: ReactNode;
}
```

### Alert

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Alert/Alert.tsx
Alert: 페이지 안에 고정으로 보여 주는 안내 문구. 기본으로 role 이 없다.
사용자 동작 뒤에 새로 나타나는 메시지라면 스크린리더가 바로 읽도록 `role="alert"`(중요·긴급) 또는
`role="status"`(일반 알림)를 넘긴다. 잠깐 떴다 사라지는 알림은 Toast 를 쓴다.
```ts
export type AlertColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';

export interface AlertProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color' | 'title'> {
  /** 시각적 스타일 */
  variant?: 'soft' | 'outline' | 'solid';
  /** 의미 색상. 일반 안내(공지·도움말)는 info — 브랜드 색(primary)을 바꿔도 파랑으로 남는다 */
  color?: AlertColor;
  /** 굵게 표시되는 제목 */
  title?: ReactNode;
  /** 앞에 표시할 아이콘. 생략하면 color 에 맞는 기본 아이콘, false 면 표시하지 않는다 (장식용 — 의미는 텍스트로 전달) */
  icon?: ReactNode | false;
  /** 오른쪽에 둘 버튼 등 */
  action?: ReactNode;
  /** 넘기면 닫기(X) 버튼을 표시하고, 누르면 호출한다. 실제로 숨기는 것은 사용하는 쪽이 한다 */
  onClose?: () => void;
  /** 닫기 버튼의 접근 가능한 이름 */
  closeLabel?: string;
}
```

### AmountInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/AmountInput/AmountInput.tsx
AmountInput: 금액 입력. 천 단위 쉼표를 넣고 뒤에 단위("원")를 붙이며, 아래에 "12만 5,000원" 처럼 읽기 쉬운 금액을 보여 준다.
값은 숫자(number)로 넘긴다.
```ts
export interface AmountInputProps extends Omit<
  TextFieldProps,
  'value' | 'defaultValue' | 'onChange' | 'type' | 'inputMode' | 'endAdornment'
> {
  /** 금액 (제어 모드). 비어 있으면 null */
  value?: number | null;
  /** 처음 금액 (비제어 모드) */
  defaultValue?: number | null;
  /** 금액이 바뀔 때 호출된다. 비우면 null */
  onValueChange?: (amount: number | null) => void;
  /** 최댓값. 넘게 입력하면 최댓값으로 맞춘다 */
  max?: number;
  /** 단위 (입력창 뒤에 표시, 한글 읽기에도 붙는다) */
  unit?: string;
  /**
   * 아래에 "12만 5,000원" 처럼 읽기 쉬운 금액을 보여 준다 (기본 true).
   * helperText 를 주면 그 아래 줄로 함께 보여 준다.
   */
  showKoreanAmount?: boolean;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### Avatar

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Avatar/Avatar.tsx
```ts
export interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
  /** 이미지 주소. 없거나 불러오지 못하면 fallback 을 보여 준다 */
  src?: string;
  /** 스크린리더가 읽을 이름. 없으면 `name` 을 쓰고, 둘 다 없으면 장식용으로 숨긴다 */
  alt?: string;
  /** 사용자 이름. fallback 이니셜과 기본 접근 가능한 이름에 쓴다 */
  name?: string;
  /** fallback 을 직접 지정한다 (기본: 이니셜 → 사용자 아이콘) */
  fallback?: ReactNode;
  /** 크기 (sm 28px, md 36px, lg 48px) */
  size?: 'sm' | 'md' | 'lg';
  /** 모양 */
  shape?: 'circle' | 'square';
}
```

### Badge

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Badge/Badge.tsx
```ts
export interface BadgeProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
  /** 시각적 스타일 */
  variant?: 'solid' | 'soft' | 'outline';
  /** 의미 색상. 일반 안내는 info (브랜드 색과 따로 파랑) */
  color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 텍스트 앞에 표시할 아이콘 (장식용 — 의미는 텍스트로 전달한다) */
  startIcon?: ReactNode;
}
```

### Breadcrumb

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Breadcrumb/Breadcrumb.tsx
Breadcrumb: 현재 페이지까지의 경로를 보여 주는 탐색. `<nav>` > `<ol>` 구조이고 마지막 항목에 `aria-current="page"` 를 붙인다.
```ts
export interface BreadcrumbItemData {
  /** 표시할 이름 */
  label: ReactNode;
  /** 이동할 주소. 마지막 항목(현재 페이지)은 링크로 만들지 않는다 */
  href?: string;
}

export interface BreadcrumbProps extends HTMLAttributes<HTMLElement> {
  /** 상위 → 현재 순서의 경로. 마지막 항목이 현재 페이지(aria-current="page")다 */
  items: BreadcrumbItemData[];
  /**
   * 링크로 렌더링할 컴포넌트 (예: Next.js 의 Link). 기본 `<a>`.
   * 컴포넌트(함수)를 넘기므로 클라이언트 컴포넌트에서만 쓸 수 있다 (서버 컴포넌트에서는 생략하면 일반 `<a>` 로 동작)
   */
  linkAs?: ElementType;
  /** 항목 사이 구분 기호 (장식용 — 스크린리더는 읽지 않는다) */
  separator?: ReactNode;
  /** 탐색 영역의 이름 */
  'aria-label'?: string;
}
```

### BusinessNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/BusinessNumberInput/BusinessNumberInput.tsx
BusinessNumberInput: 사업자등록번호 입력. 123-45-67890 형식으로 하이픈을 넣고, 10자리를 채우면 검증 공식으로 확인한다.
(검증 공식은 오타를 거르는 용도 — 실제 등록·휴폐업 여부는 국세청 조회가 필요하다)
```ts
export interface BusinessNumberInputProps extends Omit<
  TextFieldProps,
  'value' | 'defaultValue' | 'onChange' | 'type' | 'inputMode'
> {
  /** 숫자만 있는 사업자등록번호 (제어 모드). 예: "1248100998" */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 10자리를 다 채웠을 때 검증 공식 통과 여부로 호출된다 (다 채우기 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /**
   * 10자리를 다 채웠는데 검증 공식에 맞지 않으면 자동으로 오류를 보여 준다 (기본 true).
   * 직접 error·helperText 를 주면 그 값이 우선한다.
   */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### Button

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Button/Button.tsx
```ts
export interface ButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'color'> {
  /** 시각적 스타일 */
  variant?: 'solid' | 'soft' | 'outline' | 'ghost';
  /** 의미 색상 */
  color?: 'primary' | 'neutral' | 'danger';
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  /** 레이블 앞에 표시할 아이콘 */
  startIcon?: ReactNode;
  /** 레이블 뒤에 표시할 아이콘 */
  endIcon?: ReactNode;
  /**
   * 진행 중 상태. `startIcon` 자리에 스피너를 보여 주고 `aria-busy` 를 붙이며 클릭(폼 제출 포함)을 막는다.
   * `disabled` 와 달리 포커스는 유지된다.
   */
  loading?: boolean;
  /**
   * 자식 요소(라우터 링크 등)에 버튼 모양과 속성을 입혀 그대로 렌더링한다. 서버 컴포넌트에서도 쓸 수 있다.
   * 페이지를 이동하는 주요 동작에 쓰고, 자식은 요소 하나여야 한다.
   * `disabled` 면 `aria-disabled` 를 붙이고 Tab 순서에서 빼며 클릭을 막는다. 휠 클릭은 막지 못하니 링크는 되도록 비활성으로 두지 않는다.
   * @example <Button asChild><NextLink href="/signup">시작하기</NextLink></Button>
   */
  asChild?: boolean;
}
```

### Calendar

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Calendar/Calendar.tsx
Calendar: 달력 (WAI-ARIA grid). 일요일부터 시작하고 일요일·공휴일은 빨강, 토요일은 파랑으로 표시한다.
키보드: ←→ 하루, ↑↓ 일주일, Home/End 주의 처음·끝, PageUp/PageDown 한 달(Shift 와 함께 1년), Enter/Space 선택.
```ts
export interface CalendarProps {
  /** 선택된 날짜 'YYYY-MM-DD' (제어 모드) */
  value?: string;
  /** 처음 선택된 날짜 (비제어 모드) */
  defaultValue?: string;
  /** 날짜를 고를 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 고를 수 있는 가장 이른 날짜 'YYYY-MM-DD' */
  min?: string;
  /** 고를 수 있는 가장 늦은 날짜 'YYYY-MM-DD' */
  max?: string;
  /** 고를 수 없는 날짜 (예: 주말 제외) */
  isDateDisabled?: (date: Date) => boolean;
  /** 공휴일. 일요일처럼 빨갛게 표시하고 스크린리더에 "공휴일" 을 덧붙인다 */
  isHoliday?: (date: Date) => boolean;
  /**
   * 오늘 날짜 'YYYY-MM-DD'. 기본은 브라우저의 오늘 — 테스트·스크린샷에서 고정할 때 쓴다.
   * 서버 렌더링에서는 서버와 브라우저의 날짜(시간대)가 다를 수 있어, 없으면 hydration 이 끝난 뒤에 정한다
   * (선택된 날짜도 없으면 그 전까지 날짜 칸을 비워 둔다).
   */
  today?: string;
  /** 처음 그릴 때 날짜(선택된 날짜, 없으면 오늘)로 포커스를 옮긴다 — 팝업 안에서 쓸 때 */
  initialFocus?: boolean;
  /** 이전·다음 달 버튼 이름 */
  prevMonthLabel?: string;
  nextMonthLabel?: string;
  className?: string;
}
```

### Card

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Card/Card.tsx
```ts
export interface CardProps extends HTMLAttributes<HTMLElement> {
  /** 시각적 스타일. outline 은 테두리, elevated 는 그림자(다크 모드는 가장자리 ring 포함), soft 는 옅은 배경 */
  variant?: 'outline' | 'elevated' | 'soft';
  /** 안쪽 여백 (sm 16px, md 24px, lg 32px). 이미지를 가장자리까지 붙이려면 none */
  padding?: 'none' | 'sm' | 'md' | 'lg';
  /** 렌더링할 요소 (기본 div). 목록이면 li, 독립된 콘텐츠면 article 등 */
  as?: ElementType;
}

export type CardSectionProps = HTMLAttributes<HTMLDivElement>;
```

### CardNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/CardNumberInput/CardNumberInput.tsx
CardNumberInput: 카드번호 입력. 4자리씩 하이픈을 넣고(아메리칸 익스프레스는 4-6-5), 다 채우면 검사 공식(Luhn)으로 오타를 거른다.
브라우저·비밀번호 관리자의 카드 자동 완성(cc-number)을 받는다. 실제로 쓸 수 있는 카드인지는 결제사가 확인한다.
화면에 다시 보일 때는 maskCardNumber 로 가린다.
```ts
export interface CardNumberInputProps extends CheckedNumberProps {
  // ── 아래는 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 숫자만 있는 값 (제어 모드). 예: "1234567890123456" */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 다 채웠을 때(16자리, 아메리칸 익스프레스 15자리) 검사 공식(Luhn) 검증 통과 여부로 호출된다 (그 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /** 다 채웠는데 검사 공식에 맞지 않거나 덜 채운 채 벗어나면 자동으로 오류를 보여 준다 (기본 true). 직접 error·helperText 를 주면 그 값이 우선한다 */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
  /** 입력창 위에 표시할 레이블 — 기본 "카드번호" */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### Checkbox

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Checkbox/Checkbox.tsx
```ts
export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size' | 'type'> {
  /** 체크박스 옆에 표시할 레이블 */
  label?: ReactNode;
  /** 크기 */
  size?: 'sm' | 'md';
  /** 일부 선택 상태 (전체 선택 체크박스 등) */
  indeterminate?: boolean;
  /** 에러 상태 */
  invalid?: boolean;
  /** 체크 상태가 바뀌면 호출된다 (Switch 와 같은 이름). 기본 `onChange` 도 그대로 쓸 수 있다 */
  onCheckedChange?: (checked: boolean) => void;
}
```

### CheckboxGroup

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/CheckboxGroup/CheckboxGroup.tsx
CheckboxGroup: 여러 선택지 중 여러 개를 고르는 체크박스 묶음. 묶음 레이블·도움말·오류를 한 번에 연결한다.
약관 동의(전체 동의·필수/선택 표시·보기)는 AgreementGroup 을 쓴다.
```ts
export interface CheckboxOption {
  value: string;
  label: ReactNode;
  /** 레이블 아래 보조 설명 (접근 가능한 이름이 아니라 설명으로 읽힌다) */
  description?: ReactNode;
  disabled?: boolean;
}

export interface CheckboxGroupProps {
  /** 선택지 목록 */
  options: CheckboxOption[];
  /** 선택된 값들 (제어 모드). undefined 를 넘기면 아무것도 선택하지 않은 상태 */
  value?: string[];
  /** 처음 선택된 값들 (비제어 모드) */
  defaultValue?: string[];
  /** 값이 바뀔 때 호출된다 — options 순서대로 정렬한 배열 */
  onValueChange?: (value: string[]) => void;
  /** 묶음 위에 표시할 레이블 */
  label?: ReactNode;
  /** 묶음 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 오류 상태 — 각 체크박스에 aria-invalid */
  error?: boolean;
  /** 배치 방향 */
  orientation?: 'vertical' | 'horizontal';
  /** 크기 */
  size?: 'sm' | 'md';
  disabled?: boolean;
  /**
   * 하나 이상 골라야 함 — 레이블에 * 와 스크린리더용 "필수" 를 붙인다. "몇 개 이상" 검증은 폼(react-hook-form 등)에서 한다
   * (체크박스마다 네이티브 required 를 주면 "모두 골라야 함" 이 되어 쓰지 않는다).
   */
  required?: boolean;
  /** form 제출 시 사용할 이름 — 고른 값마다 같은 이름으로 제출된다(FormData.getAll) */
  name?: string;
  /** 묶음의 id (ErrorSummary 링크·focusField 가 이 id 로 첫(또는 선택된) 체크박스를 찾는다) */
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 바깥 래퍼 className */
  className?: string;
}
```

### Combobox

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Combobox/Combobox.tsx
Combobox: 입력해서 거르며 고르는 선택 상자 (WAI-ARIA combobox + listbox 패턴).
↓/↑ 로 목록을 열고 이동, Enter 로 선택, Esc 로 닫는다. 목록에 없는 값은 입력할 수 없다(선택만).
여러 개를 고르려면 MultiCombobox.
```ts
export interface ComboboxOption {
  value: string;
  /** 표시·검색에 쓰는 이름 */
  label: string;
  disabled?: boolean;
}

export interface ComboboxProps {
  /** 선택지 목록 */
  options: ComboboxOption[];
  /** 선택된 값 (제어 모드). undefined 면 선택 없음 */
  value?: string;
  /** 처음 선택된 값 (비제어 모드) */
  defaultValue?: string;
  /** 값이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 입력한 글자로 선택지를 거르는 함수 (기본: 대소문자 구분 없이 label 에 포함) */
  filter?: (option: ComboboxOption, query: string) => boolean;
  /** 검색 결과가 없을 때 문구 */
  emptyMessage?: ReactNode;
  placeholder?: string;
  /** 위에 표시할 레이블 */
  label?: ReactNode;
  /** 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  error?: boolean;
  size?: 'sm' | 'md' | 'lg';
  fullWidth?: boolean;
  disabled?: boolean;
  required?: boolean;
  /** form 제출 시 사용할 이름 (선택된 value 가 제출된다) */
  name?: string;
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 목록 열기 버튼의 이름 */
  toggleLabel?: string;
  /**
   * 값이 있을 때 "선택 지우기" 버튼을 보여 준다. 버튼이 없어도 입력창 글자를 모두 지우고 닫으면(포커스 이동·Esc·Enter) 선택이 지워진다.
   * 지우면 `onValueChange('')` 가 호출된다.
   */
  clearable?: boolean;
  /** "선택 지우기" 버튼의 이름 */
  clearLabel?: string;
  /** 입력창 래퍼 className */
  className?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Combobox/MultiCombobox.tsx
MultiCombobox: 입력해서 거르며 여러 개를 고르는 선택 상자 (WAI-ARIA combobox + 다중 선택 listbox).
고른 값은 입력창 안에 칩으로 보인다. ↓/↑ 로 목록을 열고 이동, Enter 로 고르기·풀기(목록은 열린 채), Esc 로 닫는다.
빈 입력창에서 Backspace 는 마지막 칩을 지운다. 칩 삭제 버튼은 Tab 순서에 있다.
```ts
export interface MultiComboboxProps {
  /** 선택지 목록 */
  options: ComboboxOption[];
  /** 고른 값들 (제어 모드). 칩은 이 순서대로 보인다. options 에 없는 값은 값 그대로 이름이 된다 */
  value?: string[];
  /** 처음 고른 값들 (비제어 모드) */
  defaultValue?: string[];
  /** 고른 값이 바뀔 때 호출된다 */
  onValueChange?: (values: string[]) => void;
  /** 입력한 글자로 선택지를 거르는 함수 (기본: 대소문자 구분 없이 label 에 포함) */
  filter?: (option: ComboboxOption, query: string) => boolean;
  /** 검색 결과가 없을 때 문구 */
  emptyMessage?: ReactNode;
  placeholder?: string;
  /** 위에 표시할 레이블 */
  label?: ReactNode;
  /** 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  error?: boolean;
  size?: 'sm' | 'md' | 'lg';
  fullWidth?: boolean;
  disabled?: boolean;
  required?: boolean;
  /** form 제출 시 사용할 이름 — 고른 값마다 하나씩 제출된다 (`name=a&name=b`) */
  name?: string;
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 고를 수 있는 최대 개수. 다 고르면 고르지 않은 항목은 비활성이 되고 칸 아래에 안내가 보인다 */
  maxSelected?: number;
  /** 칩 삭제 버튼 이름 — 기본 "<이름> 삭제" */
  removeLabel?: (label: string) => string;
  /** 목록 열기 버튼의 이름 */
  toggleLabel?: string;
  /** 고른 값이 있을 때 "모두 지우기" 버튼을 보여 준다(마우스용 — 키보드는 Backspace·칩 삭제 버튼). 지우면 `onValueChange([])` */
  clearable?: boolean;
  /** "모두 지우기" 버튼의 이름 */
  clearLabel?: string;
  /** 입력창 래퍼 className */
  className?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Combobox/useComboboxList.ts
isComposingKey: 한글 조합 중의 키는 조합을 끝내는 입력이다. 여기서 항목을 고르면 조합이 끝나며 글자가 이름 뒤에 붙는다("국민은행국").
Safari 는 조합을 끝낸 뒤 isComposing=false 로 보내 keyCode 229 로도 확인한다.
useComboboxList: Combobox·MultiCombobox 가 함께 쓰는 목록 상태 (내부용).
열림·검색어·활성 항목, 거르기, 이동, 활성 항목 스크롤, "결과가 없어요" 지연 알림을 맡는다. 선택 값은 부르는 쪽이 든다.

### Container

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Container/Container.tsx
```ts
export interface ContainerProps extends HTMLAttributes<HTMLElement> {
  /** 렌더링할 요소 (페이지 본문이면 'main') */
  as?: ElementType;
  /** 최대 폭 — sm 640 · md 768 · lg 1024(기본) · xl 1280px(구간 폭과 같음, 기본 글꼴 크기를 따름), full 은 제한 없음 */
  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
  /** 좌우 여백을 없앤다 (기본은 좁은 화면 16px, md 구간부터 24px) */
  flush?: boolean;
}
```

### CorporateNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/CorporateNumberInput/CorporateNumberInput.tsx
CorporateNumberInput: 법인등록번호 입력. 000000-0000000 형식으로 하이픈을 넣고, 13자리를 채우면 검증 공식으로 오타를 거른다.
(실제로 등기된 법인인지는 등기소 조회가 필요하다. 사업자등록번호는 BusinessNumberInput)
```ts
export interface CorporateNumberInputProps extends CheckedNumberProps {
  // ── 아래는 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 숫자만 있는 값 (제어 모드). 예: "1301110006246" */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 13자리를 다 채웠을 때 검증 공식 검증 통과 여부로 호출된다 (그 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /** 13자리를 채웠는데 검증 공식에 맞지 않거나 덜 채운 채 벗어나면 자동으로 오류를 보여 준다 (기본 true). 직접 error·helperText 를 주면 그 값이 우선한다 */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
  /** 입력창 위에 표시할 레이블 — 기본 "법인등록번호" */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### DatePicker

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/DatePicker/DatePicker.tsx
DatePicker: 날짜 입력. `YYYY-MM-DD` 로 직접 입력하거나(숫자만 쳐도 하이픈이 들어간다) 달력 버튼으로 고른다.
달력은 일요일부터 시작하고, 열면 선택된 날짜(없으면 오늘)로 포커스가 간다. 값은 시간대 문제가 없는 'YYYY-MM-DD' 문자열이다.
```ts
export interface DatePickerProps {
  /** 날짜 'YYYY-MM-DD' (제어 모드). 비어 있으면 '' */
  value?: string;
  /** 처음 날짜 (비제어 모드) */
  defaultValue?: string;
  /** 올바른 날짜를 다 입력하거나 달력에서 고르면 'YYYY-MM-DD', 지우거나 잘못되면 '' 로 호출된다 */
  onValueChange?: (value: string) => void;
  /** 고를 수 있는 가장 이른·늦은 날짜 'YYYY-MM-DD' */
  min?: string;
  max?: string;
  /** 고를 수 없는 날짜 */
  isDateDisabled?: (date: Date) => boolean;
  /** 공휴일 (달력에 빨갛게 표시) */
  isHoliday?: (date: Date) => boolean;
  /** 오늘 날짜 'YYYY-MM-DD' (테스트·스크린샷 고정용) */
  today?: string;
  label?: ReactNode;
  /** 아래 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  error?: boolean;
  required?: boolean;
  disabled?: boolean;
  fullWidth?: boolean;
  placeholder?: string;
  /** 달력 버튼·달력 창 이름 */
  calendarLabel?: string;
  /** 자동 검증 문구 */
  invalidText?: string;
  unavailableText?: string;
  incompleteText?: string;
  /** form 제출 시 이름 ('YYYY-MM-DD' 가 제출된다) */
  name?: string;
  id?: string;
  className?: string;
}
```

### DateRangePicker

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/DateRangePicker/DateRangePicker.tsx
DateRangePicker: 기간 선택 (조회 기간, 예약 기간). 시작일·종료일 DatePicker 두 개를 묶고, 시작일은 종료일보다 늦을 수 없게 서로 제한한다.
빠른 선택(오늘·1주일·1개월…)은 현재 기간과 같으면 눌린 상태(aria-pressed)로 보인다.
```ts
export interface DateRangePickerProps {
  /** 기간 (제어 모드) */
  value?: DateRange;
  /** 처음 기간 (비제어 모드) */
  defaultValue?: DateRange;
  /** 시작일·종료일이 바뀔 때. 비었거나 고를 수 없는 날짜면 '' */
  onValueChange?: (range: DateRange) => void;
  /** 묶음 이름 (legend) — 예: "조회 기간" */
  label?: ReactNode;
  /** 시작일 칸 레이블 (기본 "시작일") */
  startLabel?: string;
  /** 종료일 칸 레이블 (기본 "종료일") */
  endLabel?: string;
  /** 빠른 선택 버튼 — 오늘에서 거슬러 올라간 기간 (`dateRangePresets` 를 그대로 넘겨도 된다) */
  presets?: DateRangePreset[];
  /** 고를 수 있는 가장 이른 날 */
  min?: string;
  /** 고를 수 있는 가장 늦은 날 */
  max?: string;
  isDateDisabled?: (date: Date) => boolean;
  isHoliday?: (date: Date) => boolean;
  /** "오늘" 을 고정한다 (빠른 선택의 기준, 달력의 오늘 표시 — 테스트·시각 회귀용) */
  today?: string;
  /** 묶음 아래 도움말 */
  helperText?: ReactNode;
  error?: boolean;
  required?: boolean;
  disabled?: boolean;
  /** form 제출용 이름 — 시작일·종료일 */
  startName?: string;
  endName?: string;
  /** fieldset 의 id (시작·종료 칸은 `${id}-start`, `${id}-end`) — ErrorSummary 링크가 가리키면 시작일로 간다 */
  id?: string;
  className?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/DateRangePicker/presets.ts
```ts
export interface DateRange {
  /** 시작일 'YYYY-MM-DD' (없으면 '') */
  start: string;
  /** 종료일 'YYYY-MM-DD' (없으면 '') */
  end: string;
}

/** 빠른 선택 — 오늘에서 거슬러 올라간 기간. `days: 0` 은 오늘 하루 */
export interface DateRangePreset {
  label: string;
  days?: number;
  months?: number;
}
```

### DescriptionList

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/DescriptionList/DescriptionList.tsx
DescriptionList: 이름–값 목록(주문 상세의 고객·연락처·금액 등). `<dl>` 안에 항목마다 `<div><dt/><dd/></div>` 로 그려 스크린리더가 쌍으로 읽는다.
hook 이 없어 서버 컴포넌트로도 렌더링된다.
```ts
export interface DescriptionListItem {
  /** 이름 (dt) */
  term: ReactNode;
  /** 값 (dd) */
  description: ReactNode;
}

export interface DescriptionListProps extends HTMLAttributes<HTMLDListElement> {
  /** 이름–값 목록 */
  items: DescriptionListItem[];
  /** horizontal(기본): 이름 왼쪽·값 오른쪽. vertical: 이름 위·값 아래(좁은 곳·긴 값) */
  layout?: 'horizontal' | 'vertical';
  /** horizontal 일 때 이름 열의 폭 (기본 30%) — 예: "8rem" */
  termWidth?: string;
  /** 항목 사이에 구분선 */
  divided?: boolean;
}
```

### Divider

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Divider/Divider.tsx
```ts
export interface DividerProps extends HTMLAttributes<HTMLDivElement> {
  /** 방향. vertical 은 flex 행 안에서 부모 높이를 채운다 */
  orientation?: 'horizontal' | 'vertical';
  /** 시각적 구분만 하고 의미가 없으면 true — 스크린리더에서 숨긴다 */
  decorative?: boolean;
  /**
   * 가운데에 표시할 텍스트 (예: "또는"). horizontal 에서만 쓴다.
   * separator 역할의 자식은 스크린리더가 읽지 않으므로, 텍스트가 있으면 선만 숨기고 텍스트는 읽히게 둔다.
   */
  children?: ReactNode;
}
```

### Drawer

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Drawer/Drawer.tsx
Drawer: 화면 가장자리에서 밀려 나오는 패널(시트). 필터·상세 보기·모바일 메뉴 등에 쓴다.
Modal 과 같은 Radix Dialog 기반이라 포커스 가두기, Esc 로 닫기, 닫힌 뒤 trigger 로 포커스 복귀를 지원한다.
DrawerClose: 감싼 요소를 클릭하면 패널이 닫힌다.
@example <DrawerClose asChild><Button>취소</Button></DrawerClose>
```ts
export interface DrawerProps {
  /** 열림 상태 (제어 모드) */
  open?: boolean;
  /** 처음 열림 상태 (비제어 모드) */
  defaultOpen?: boolean;
  /** 열림 상태가 바뀔 때 호출된다 */
  onOpenChange?: (open: boolean) => void;
  /** 클릭하면 패널을 여는 요소. 버튼 등 포커스 가능한 요소 하나여야 한다 */
  trigger?: ReactNode;
  /** 제목 (스크린리더가 패널 이름으로 읽는다) */
  title: ReactNode;
  /** 제목 아래 설명 */
  description?: ReactNode;
  /** 본문. 길면 본문 영역만 스크롤된다 */
  children?: ReactNode;
  /** 하단 고정 버튼 영역. 닫기 버튼은 DrawerClose 로 감싼다 */
  footer?: ReactNode;
  /** 나타나는 방향 (기본 right) */
  side?: 'right' | 'left' | 'top' | 'bottom';
  /** 크기. 좌우는 너비 320/420/640px, 위아래는 높이 30/50/80vh */
  size?: 'sm' | 'md' | 'lg';
  /** 오른쪽 위 닫기(X) 버튼 숨기기 */
  hideCloseButton?: boolean;
  /** 바깥 영역 클릭으로 닫기 (기본 true) */
  closeOnOverlayClick?: boolean;
  /** 패널 className */
  className?: string;
}
```

### DropdownMenu

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/DropdownMenu/DropdownMenu.tsx
DropdownMenuCheckboxItem: 켜고 끄는 항목 (role="menuitemcheckbox" + aria-checked). 기본으로 고르면 메뉴가 닫힌다 —
여러 개를 이어서 바꾸게 하려면 `onSelect={(e) => e.preventDefault()}` 로 열어 둔다.
DropdownMenuRadioGroup: 하나만 고르는 항목 묶음 (role="group"). 안에 `DropdownMenuRadioItem` 을 둔다.
선택 상태를 스스로 갖지 않는다 — 항상 `value` + `onValueChange` 로 제어한다.
```ts
export type DropdownMenuProps = ComponentPropsWithoutRef<typeof RadixMenu.Root>;

export type DropdownMenuTriggerProps = ComponentPropsWithoutRef<typeof RadixMenu.Trigger>;

export interface DropdownMenuContentProps extends ComponentPropsWithoutRef<typeof RadixMenu.Content> {
  /** 트리거 기준 표시 방향 */
  side?: 'top' | 'right' | 'bottom' | 'left';
  /** 정렬 */
  align?: 'start' | 'center' | 'end';
}

export interface DropdownMenuItemProps extends Omit<ComponentPropsWithoutRef<typeof RadixMenu.Item>, 'color'> {
  /** 텍스트 앞 아이콘 (장식용) */
  icon?: ReactNode;
  /** 오른쪽에 표시할 단축키 (예: "⌘K"). 표시용이라 항목 이름에는 포함되지 않는다 */
  shortcut?: string;
  /** danger 는 삭제처럼 되돌리기 어려운 동작 */
  color?: 'neutral' | 'danger';
}

export type DropdownMenuLabelProps = ComponentPropsWithoutRef<typeof RadixMenu.Label>;

export type DropdownMenuSeparatorProps = ComponentPropsWithoutRef<typeof RadixMenu.Separator>;

export interface DropdownMenuCheckboxItemProps extends ComponentPropsWithoutRef<typeof RadixMenu.CheckboxItem> {
  /** 켜짐 여부. `'indeterminate'` 는 일부만 선택된 상태(− 표시) */
  checked?: boolean | 'indeterminate';
  /** 상태가 바뀔 때 */
  onCheckedChange?: (checked: boolean) => void;
}

export type DropdownMenuRadioGroupProps = ComponentPropsWithoutRef<typeof RadixMenu.RadioGroup>;

export interface DropdownMenuRadioItemProps extends ComponentPropsWithoutRef<typeof RadixMenu.RadioItem> {
  /** 이 항목을 고르면 RadioGroup 의 value 가 된다 */
  value: string;
}

export type DropdownMenuSubProps = ComponentPropsWithoutRef<typeof RadixMenu.Sub>;

export interface DropdownMenuSubTriggerProps extends ComponentPropsWithoutRef<typeof RadixMenu.SubTrigger> {
  /** 텍스트 앞 아이콘 (장식용) */
  icon?: ReactNode;
}

export type DropdownMenuSubContentProps = ComponentPropsWithoutRef<typeof RadixMenu.SubContent>;
```

### EmptyState

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/EmptyState/EmptyState.tsx
EmptyState: 보여 줄 것이 없을 때의 안내 (검색 결과 없음, 아직 만든 것 없음, 불러오기 실패 후 등).
hook 이 없는 표시용이라 서버 컴포넌트에서도 쓴다. 검색·필터로 결과가 바뀌어 나타나면 결과 수를 role="status" 로 따로 알린다.
```ts
export interface EmptyStateProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
  /** 제목 — 무엇이 없는지 (예: "검색 결과가 없어요") */
  title: ReactNode;
  /** 설명 — 왜 없는지, 무엇을 하면 되는지 */
  description?: ReactNode;
  /** 위의 아이콘 (장식용 — 스크린리더에서 숨긴다) */
  icon?: ReactNode;
  /** 아래 행동 버튼들 (조건 초기화, 처음 만들기 등) */
  action?: ReactNode;
  /**
   * 제목 요소 — 기본 h3. 페이지 구조에 맞는 수준을 준다. 표 안(TableEmpty)이나 카드처럼 제목이 어울리지 않는 곳은 "p".
   */
  titleAs?: 'h2' | 'h3' | 'h4' | 'p';
  /** 크기 — sm 은 표·카드 안, md 는 페이지 본문 */
  size?: 'sm' | 'md';
}
```

### ErrorSummary

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/ErrorSummary/ErrorSummary.tsx
ErrorSummary: 폼 제출에 실패했을 때 고칠 곳을 모아 보여 주는 요약(GOV.UK error summary 패턴). 나타나면 포커스가 와서 스크린리더가 제목·목록을
읽고, 각 링크로 해당 칸에 바로 간다. 칸마다 `error`·`helperText` 도 함께 표시한다.
react-hook-form 과 쓸 때는 `shouldFocusError: false` 로 두고 이 요약이 포커스를 받게 한다.
```ts
export interface ErrorSummaryItem {
  /** 오류가 난 칸의 id — 링크를 누르면 그 칸으로 포커스가 간다(묶음이면 선택된·첫 항목) */
  id: string;
  /** 고칠 내용 (칸 아래 helperText 와 같은 문구를 권장) */
  message: ReactNode;
}

export interface ErrorSummaryProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
  /** 고칠 곳 목록. 비어 있으면 아무것도 그리지 않는다 */
  errors: ErrorSummaryItem[];
  /** 제목 (기본 "입력한 내용에 고칠 곳이 N개 있어요") */
  title?: ReactNode;
  /**
   * 이 값이 바뀔 때마다(오류가 있으면) 요약으로 포커스를 옮긴다. 기본은 처음 나타날 때 한 번.
   * 다시 제출해도 오류가 남아 있으면 옮기도록 제출 횟수를 넘긴다 (react-hook-form: `formState.submitCount`).
   */
  focusKey?: unknown;
}
```

### FileUpload

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/FileUpload/FileUpload.tsx
FileUpload: 파일 첨부. "파일 선택" 버튼(또는 끌어다 놓기)으로 고르고, 선택한 파일을 이름·크기·삭제 버튼 목록으로 보여 준다.
끌어다 놓기는 덤이고 버튼으로 모두 할 수 있다(KWCAG 2.5.7). 조건에 맞지 않는 파일은 이유를 보여 주고 스크린리더에 알린다.
업로드(서버 전송)는 하지 않는다 — onValueChange 로 받은 File 을 직접 보낸다.
```ts
export type FileRejectionReason = 'type' | 'size' | 'count';

export interface FileRejection {
  file: File;
  reason: FileRejectionReason;
}

export interface FileUploadProps {
  /** 선택한 파일 (제어 모드) */
  value?: File[];
  /** 처음 파일 (비제어 모드) */
  defaultValue?: File[];
  /** 선택한 파일이 바뀔 때 (조건에 맞는 파일만) */
  onValueChange?: (files: File[]) => void;
  /** 조건(accept·maxSize·maxFiles)에 맞지 않아 빠진 파일. 이유는 화면에도 보여 준다 */
  onReject?: (rejections: FileRejection[]) => void;
  /** 받을 형식 — input accept 와 같다 (예: ".pdf,image/*") */
  accept?: string;
  /** 여러 개 선택 (기본 false — 새로 고르면 바꾼다) */
  multiple?: boolean;
  /** 파일 하나의 최대 크기 (바이트) */
  maxSize?: number;
  /** 최대 개수 (multiple 일 때) */
  maxFiles?: number;
  /** 위에 표시할 레이블 */
  label?: ReactNode;
  /** 아래 도움말 (받는 형식·크기 안내 등). error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  required?: boolean;
  disabled?: boolean;
  /** form 제출 시 사용할 이름 — 네이티브 input 의 files 를 맞춰 두어 그대로 제출된다 */
  name?: string;
  id?: string;
  /** 바깥 래퍼 className */
  className?: string;
}
```

### FormField

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/FormField/FormField.tsx
FormField: 직접 만든 입력·다른 라이브러리 입력에 TextField 와 같은 레이블·도움말·오류 연결을 붙인다.
hook 은 useId 뿐이라 서버 컴포넌트에서도 쓸 수 있다.
```ts
/**
 * FormField 가 자식에게 넘기는 연결 속성. 입력 요소(또는 입력 역할을 하는 요소)에 그대로 펼쳐 넣는다.
 * role="group" 처럼 aria-invalid·aria-required 를 받지 못하는 역할이면 그 둘은 빼고 안의 컨트롤에 준다(axe aria-allowed-attr).
 */
export interface FormFieldControlProps {
  id: string;
  'aria-describedby'?: string;
  'aria-invalid'?: true;
  'aria-required'?: true;
}

/** render 함수의 둘째 인자 — 입력에 펼치지 않는 정보 */
export interface FormFieldMeta {
  /** 레이블 요소의 id — label 로 이름을 받을 수 없는 요소(div role="combobox" 등)는 aria-labelledby 에 넣는다 */
  labelId?: string;
  /** 도움말 요소의 id */
  helperId?: string;
}

export interface FormFieldProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children' | 'id'> {
  /** 입력 위에 표시할 레이블 (짧게 — 보조 설명은 helperText) */
  label?: ReactNode;
  /** 입력 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 오류 상태 — 자식에 aria-invalid 를 넘기고 helperText 를 오류 색으로 */
  error?: boolean;
  /** 필수 — 레이블에 * 를 붙이고 자식에 aria-required 를 넘긴다(네이티브 검증이 필요하면 입력에 required 를 직접) */
  required?: boolean;
  /** 입력 요소의 id. 생략하면 만든다 (ErrorSummary 링크·focusField 가 이 id 로 찾아간다) */
  id?: string;
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  /**
   * 입력을 그리는 함수. 첫째 인자를 입력 요소에 그대로 펼쳐 넣는다.
   * @example {(field) => <input {...field} />}
   * @example {(field, { labelId }) => <CustomSelect {...field} aria-labelledby={labelId} />}
   */
  children: (control: FormFieldControlProps, meta: FormFieldMeta) => ReactNode;
}
```

### Grid

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Grid/Grid.tsx
```ts
export interface GridProps extends HTMLAttributes<HTMLElement> {
  /** 렌더링할 요소 (목록이면 'ul') */
  as?: ElementType;
  /** 열 개수 (같은 폭). 구간별로: `{ base: 1, md: 2, lg: 3 }`. 생략하면 한 열 */
  columns?: Responsive<number>;
  /**
   * 칸의 최소 폭(CSS 길이, 예: '220px'·'14rem'). 주면 화면 폭에 맞춰 열 개수를 자동으로 정한다(columns 대신).
   * 화면이 이 폭보다 좁으면 칸이 화면 폭으로 줄어든다(가로 스크롤 없음).
   */
  minItemWidth?: string;
  /** 칸 사이 간격 (space 토큰 키). 구간별 값도 받는다 */
  gap?: Responsive<keyof typeof space>;
}
```

### IconButton

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/IconButton/IconButton.tsx
IconButton: 아이콘만 있는 정사각형 버튼. Button 과 같은 variant·color·size·loading 을 받고, 기본은 ghost·neutral 이다.
마우스 사용자에게도 이름을 보여 주려면 Tooltip 으로 감싼다.
```ts
export interface IconButtonProps extends Omit<
  ButtonProps,
  'startIcon' | 'endIcon' | 'fullWidth' | 'children' | 'variant' | 'color' | 'size' | 'loading'
> {
  /** 시각적 스타일 (기본 ghost) */
  variant?: 'solid' | 'soft' | 'outline' | 'ghost';
  /** 의미 색상 (기본 neutral) */
  color?: 'primary' | 'neutral' | 'danger';
  /** 크기. 버튼 32·40·48px, 아이콘 16·20·24px */
  size?: 'sm' | 'md' | 'lg';
  /** 진행 중 상태. 아이콘 자리에 스피너를 보여 주고 `aria-busy` 를 붙이며 클릭을 막는다 (포커스는 유지) */
  loading?: boolean;
  /** 버튼이 하는 일을 설명하는 이름 (예: "삭제"). 아이콘만으로는 스크린리더가 알 수 없어 필수다 */
  'aria-label': string;
  /** 자식 요소(라우터 링크 등)에 모양과 속성을 입혀 그대로 렌더링한다. 아이콘은 그 요소 안에 넣는다 */
  asChild?: boolean;
  /** 아이콘. 크기는 버튼 size 에 맞춰 자동으로 조절된다 (sm 16px · md 20px · lg 24px) */
  children: ReactNode;
}
```

### Input

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Input/CheckedNumberField.tsx
CheckedNumberField: 숫자 번호 입력의 공통 동작: 입력하는 대로 서식, 다 채우면 검증, 덜 채운 채 벗어나면 "끝까지 입력" 안내.
다 채운 순간 생긴 오류는 입력이 멈춘 뒤 처음부터 있는 status 영역으로 알린다(설명으로는 다시 들어가야 들린다 — 스크린리더 수동 점검 2026-10-21).
```ts
/** 숫자 번호 입력(사업자등록번호·카드번호·법인등록번호·계좌번호)이 공통으로 받는 prop */
export interface CheckedNumberProps extends Omit<
  TextFieldProps,
  'value' | 'defaultValue' | 'onChange' | 'type' | 'inputMode'
> {
  /** 숫자만 있는 값 (제어 모드) */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 다 채웠을 때 검증 통과 여부로 호출된다 (다 채우기 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /**
   * 다 채웠는데 검증에 맞지 않거나, 덜 채운 채 입력창을 벗어나면 자동으로 오류를 보여 준다 (기본 true).
   * 직접 error·helperText 를 주면 그 값이 우선한다.
   */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
}

/** 번호마다 다른 부분 — 내부용(공개 API 아님) */
export interface CheckedNumberRules {
  /** 입력에서 숫자만 남기고 최대 자릿수로 자른다 */
  sanitize: (input: string) => string;
  /** 화면에 보일 서식 (하이픈) */
  format: (digits: string) => string;
  /** 검증할 만큼 채웠는지 — 채운 순간 바로 검증한다. 덜 채운 값은 입력창을 벗어날 때 */
  isComplete: (digits: string) => boolean;
  isValid: (digits: string) => boolean;
  defaultLabel: string;
  defaultInvalidText: string;
  incompleteText: string;
  autoComplete?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Input/Input.tsx
```ts
export interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 에러 상태 표시 (aria-invalid 도 함께 설정된다) */
  invalid?: boolean;
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  /** 입력창 앞에 표시할 요소 (아이콘, 단위 등) */
  startAdornment?: ReactNode;
  /** 입력창 뒤에 표시할 요소 */
  endAdornment?: ReactNode;
  /** 바깥 래퍼에 적용할 className. className 은 input 요소에 적용된다 */
  rootClassName?: string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Input/TextField.tsx
```ts
export interface TextFieldProps extends Omit<InputProps, 'invalid'> {
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  // ── 아래는 InputProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  /** 입력창 앞에 표시할 요소 (아이콘, 단위 등) */
  startAdornment?: ReactNode;
  /** 입력창 뒤에 표시할 요소 */
  endAdornment?: ReactNode;
  placeholder?: string;
  type?: InputHTMLAttributes<HTMLInputElement>['type'];
}
```

### Link

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Link/Link.tsx
```ts
export interface LinkProps extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, 'color'> {
  /**
   * 렌더링할 요소. Next.js 등의 라우터 링크를 넘기면 그 컴포넌트로 렌더링한다 (예: `as={NextLink}`).
   * 컴포넌트(함수)를 넘기므로 서버 컴포넌트에서는 쓸 수 없다 → 그때는 asChild 를 쓴다
   */
  as?: ElementType;
  /**
   * 자식 요소(라우터 링크 등)에 스타일과 속성을 입혀 그대로 렌더링한다. 서버 컴포넌트에서도 쓸 수 있다.
   * external 아이콘·안내는 붙지 않는다.
   * @example <Link asChild><NextLink href="/">홈</NextLink></Link>
   */
  asChild?: boolean;
  /** 글자색. inherit 은 부모 글자색을 그대로 쓴다 */
  color?: 'primary' | 'neutral' | 'inherit';
  /** 밑줄. 문장 안의 링크는 색만으로 구분되지 않도록 always(기본)를 쓴다. 메뉴·목록처럼 링크임이 분명할 때 hover */
  underline?: 'always' | 'hover';
  /**
   * 새 창으로 여는 외부 링크. `target="_blank"`·`rel="noopener noreferrer"` 를 붙이고,
   * 아이콘과 스크린리더용 "(새 창)" 안내를 덧붙인다
   */
  external?: boolean;
  /** external 일 때 스크린리더에 덧붙이는 안내 */
  externalLabel?: string;
}
```

### Modal

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Modal/Modal.tsx
ModalClose: 감싼 요소를 클릭하면 모달이 닫힌다.
@example <ModalClose asChild><Button>취소</Button></ModalClose>
```ts
export interface ModalProps {
  /** 열림 상태 (제어 모드) */
  open?: boolean;
  /** 처음 열림 상태 (비제어 모드) */
  defaultOpen?: boolean;
  /** 열림 상태가 바뀔 때 호출된다 */
  onOpenChange?: (open: boolean) => void;
  /** 클릭하면 모달을 여는 요소. 버튼 등 포커스 가능한 요소 하나여야 한다 */
  trigger?: ReactNode;
  /** 제목 (스크린리더가 모달 이름으로 읽는다) */
  title: ReactNode;
  /** 제목 아래 설명 */
  description?: ReactNode;
  /** 본문 */
  children?: ReactNode;
  /** 하단 버튼 영역. 닫기 버튼은 ModalClose 로 감싼다 */
  footer?: ReactNode;
  /** 너비 */
  size?: 'sm' | 'md' | 'lg';
  /** 오른쪽 위 닫기(X) 버튼 숨기기 */
  hideCloseButton?: boolean;
  /** 바깥 영역 클릭으로 닫기 (기본 true) */
  closeOnOverlayClick?: boolean;
  /** 내용 영역 className */
  className?: string;
  /**
   * 닫힐 때 포커스를 어디로 보낼지 정한다. 기본은 모달을 연 요소로 돌아간다.
   * `event.preventDefault()` 후 원하는 요소에 focus() 하면 그쪽으로 보낸다 (예: 주소 선택 뒤 상세 주소 입력창).
   */
  onCloseAutoFocus?: (event: Event) => void;
}
```

### NativeSelect

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/NativeSelect/NativeSelect.tsx
NativeSelect: 브라우저 기본 `<select>` 에 Select 와 같은 모양을 입힌 것. Radix 가 없어 가볍고(폼 세트 번들이 크게 준다),
모바일에서는 운영체제의 선택 화면이 열린다. `register(...)` 를 그대로 펼칠 수 있다.
목록 모양을 꾸미거나 항목에 아이콘을 넣어야 하면 Select 를 쓴다.
```ts
export interface NativeSelectOption {
  value: string;
  /** `<option>` 은 글자만 담을 수 있어 문자열 */
  label: string;
  disabled?: boolean;
}

export interface NativeSelectProps extends Omit<SelectHTMLAttributes<HTMLSelectElement>, 'size' | 'multiple'> {
  /** 선택지 목록. 없으면 children 의 `<option>`·`<optgroup>` 을 그대로 쓴다 */
  options?: NativeSelectOption[];
  /** 값이 바뀔 때 새 값으로 호출된다 (Select 와 같은 이름). 네이티브 onChange 도 함께 쓸 수 있다 */
  onValueChange?: (value: string) => void;
  /** 선택 전 표시할 문구 — 값이 '' 인 고를 수 없는 첫 항목으로 들어간다 */
  placeholder?: string;
  /** 위에 표시할 레이블 */
  label?: ReactNode;
  /** 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
}
```

### NumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/NumberInput/NumberInput.tsx
NumberInput: 숫자 입력 (수량·인원·나이 등). −/+ 버튼, ↑/↓·PageUp/PageDown 으로 바꾸고, 천 단위 쉼표를 넣는다.
WAI-ARIA spinbutton 패턴 — 스크린리더가 현재 값·최소·최대를 읽는다. 금액은 AmountInput(한글 금액 읽기)을 쓴다.
```ts
export interface NumberInputProps extends Omit<
  TextFieldProps,
  | 'value'
  | 'defaultValue'
  | 'onChange'
  | 'type'
  | 'inputMode'
  | 'startAdornment'
  | 'endAdornment'
  | 'min'
  | 'max'
  | 'step'
  | 'role'
> {
  /** 값 (제어 모드). 비어 있으면 null */
  value?: number | null;
  /** 처음 값 (비제어 모드) */
  defaultValue?: number | null;
  /** 값이 바뀔 때 호출된다. 비우면 null. 입력 중에는 범위를 벗어난 값도 오고, 포커스가 빠질 때 범위 안으로 맞춘 값이 온다 */
  onValueChange?: (value: number | null) => void;
  /** 최솟값. 0 이상이면 "-" 를 입력할 수 없다 */
  min?: number;
  /** 최댓값 */
  max?: number;
  /** ↑/↓·버튼으로 바꾸는 단위 (기본 1) */
  step?: number;
  /** PageUp/PageDown 으로 바꾸는 단위 (기본 step × 10) */
  largeStep?: number;
  /** 소수 자릿수 (기본: step 의 소수 자릿수 — step 0.1 이면 1). 0 이면 정수만 */
  precision?: number;
  /** 단위 (입력창 뒤에 표시, 스크린리더 값에도 붙는다 — 예: "개", "명") */
  unit?: string;
  /** 천 단위 쉼표 (기본 true) */
  thousandSeparator?: boolean;
  /** −/+ 버튼을 숨긴다 (키보드 ↑/↓ 는 그대로) */
  hideStepper?: boolean;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 (쉼표 없는 숫자로 제출된다) */
  name?: string;
}
```

### Pagination

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Pagination/Pagination.tsx
```ts
/** getItemLabel 이 이름을 만드는 버튼 종류 */
export type PaginationItemType = 'previous' | 'next' | 'page';

export interface PaginationProps extends Omit<HTMLAttributes<HTMLElement>, 'onChange'> {
  /** 전체 페이지 수. 1 미만이면 아무것도 렌더링하지 않는다 */
  totalPages: number;
  /** 현재 페이지, 1부터 (제어 모드) */
  page?: number;
  /** 처음 페이지 (비제어 모드, 기본 1) */
  defaultPage?: number;
  /** 페이지를 바꿀 때 호출된다 */
  onPageChange?: (page: number) => void;
  /** 현재 페이지 양옆에 항상 보일 페이지 수 (기본 1) */
  siblingCount?: number;
  /** 처음과 끝에 항상 보일 페이지 수 (기본 1) */
  boundaryCount?: number;
  /** 크기 */
  size?: 'sm' | 'md';
  /** 버튼의 스크린리더용 이름 (다국어 대응). 기본: "이전 페이지", "다음 페이지", "3 페이지" */
  getItemLabel?: (type: PaginationItemType, page: number) => string;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Pagination/getPaginationItems.ts
getPaginationItems: 표시할 페이지 번호와 생략 부호(…) 목록을 만든다.
현재 페이지가 움직여도 항목 개수가 일정하게 유지되어 버튼 위치가 흔들리지 않는다.

@param page 현재 페이지 (1부터)
@param totalPages 전체 페이지 수
@param siblingCount 현재 페이지 양옆에 항상 보일 페이지 수
@param boundaryCount 처음과 끝에 항상 보일 페이지 수
```ts
export type PaginationItem = number | 'ellipsis-start' | 'ellipsis-end';
```

### PasswordInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/PasswordInput/PasswordInput.tsx
PasswordInput: 비밀번호 입력. 입력창 끝의 보기 버튼으로 글자를 보이거나 가린다.
보기 버튼은 Tab 으로 닿고 켜짐/꺼짐을 aria-pressed 로 알린다. 마우스로 눌러도 입력창 포커스와 커서 위치가 그대로다.
```ts
export interface PasswordInputProps extends Omit<TextFieldProps, 'type' | 'endAdornment'> {
  /** 비밀번호를 글자로 보여 준다 (제어 모드) */
  visible?: boolean;
  /** 처음에 보여 줄지 (비제어 모드, 기본 false) */
  defaultVisible?: boolean;
  /** 보기 버튼을 눌러 보이기가 바뀔 때 */
  onVisibleChange?: (visible: boolean) => void;
  /** 보기 버튼 이름 — 기본 "비밀번호 보기". 켜짐/꺼짐은 aria-pressed 로 알린다 */
  toggleLabel?: string;
  /**
   * 브라우저 자동 완성 — 기본 "current-password"(로그인).
   * 회원가입·비밀번호 변경의 새 비밀번호 칸은 "new-password" 로 주면 브라우저가 강한 비밀번호를 제안한다.
   */
  autoComplete?: string;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블 — 기본 "비밀번호" */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말(비밀번호 규칙 등). error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### PhoneNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/PhoneNumberInput/PhoneNumberInput.tsx
PhoneNumberInput: 전화번호 입력. 입력하는 대로 하이픈을 넣고(010-1234-5678, 02-123-4567, 1588-1234), 값은 숫자만 넘긴다.
휴대폰에서 전화 키패드를 띄우고 브라우저의 전화번호 자동 완성을 받는다.
```ts
export interface PhoneNumberInputProps extends Omit<
  TextFieldProps,
  'value' | 'defaultValue' | 'onChange' | 'type' | 'inputMode'
> {
  /** 숫자만 있는 전화번호 (제어 모드). 예: "01012345678" */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값으로 호출된다 (하이픈 없음) */
  onValueChange?: (digits: string) => void;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### Popover

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Popover/Popover.tsx
PopoverClose: 팝오버 내용 안에서 누르면 팝오버를 닫는 요소.
@example <PopoverClose asChild><Button>확인</Button></PopoverClose>
```ts
export interface PopoverProps {
  /** 팝오버 내용 */
  content: ReactNode;
  /** 팝오버를 여는 요소. ref 를 받을 수 있는 요소 하나여야 한다 (보통 Button) */
  children: ReactElement;
  /** 제목. 팝오버(role="dialog")의 접근 가능한 이름이 된다 */
  title?: ReactNode;
  /** title 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 오른쪽 위에 닫기(X) 버튼을 표시한다 */
  showClose?: boolean;
  /** 트리거를 가리키는 화살표를 표시한다 */
  showArrow?: boolean;
  /** 표시 방향 */
  side?: 'top' | 'right' | 'bottom' | 'left';
  /** 정렬 */
  align?: 'start' | 'center' | 'end';
  /** 열림 상태 (제어 모드) */
  open?: boolean;
  /** 처음 열림 상태 (비제어 모드) */
  defaultOpen?: boolean;
  /** 열림 상태가 바뀔 때 호출된다 */
  onOpenChange?: (open: boolean) => void;
  /** true 이면 열려 있는 동안 바깥 요소와 상호작용할 수 없고 포커스가 팝오버 안에 갇힌다 */
  modal?: boolean;
  /** 팝오버 className */
  className?: string;
  /** 팝오버 style (너비 지정 등) */
  style?: CSSProperties;
  /** 열릴 때 포커스 처리. 기본은 내용의 첫 요소로 간다 — `event.preventDefault()` 후 원하는 요소에 focus() 할 수 있다 */
  onOpenAutoFocus?: (event: Event) => void;
}
```

### Progress

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Progress/Progress.tsx
```ts
export interface ProgressProps extends Omit<HTMLAttributes<HTMLDivElement>, 'color'> {
  /** 현재 값 (0 ~ max). 생략하거나 null 이면 진행률을 모르는 상태(indeterminate)로 움직이는 막대를 보여 준다 */
  value?: number | null;
  /** 최댓값 */
  max?: number;
  /** 막대 위에 보이는 레이블. progressbar 의 이름이 된다 */
  label?: ReactNode;
  /** 레이블이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 오른쪽에 값 텍스트(기본 "42%")를 보여 준다 */
  showValue?: boolean;
  /** 값 텍스트 형식. 화면 표시와 스크린리더(aria-valuetext)에 함께 쓴다 (예: (v, max) => `${v}/${max}개`) */
  formatValue?: (value: number, max: number) => string;
  /** 막대 두께 (sm 4px · md 8px · lg 12px) */
  size?: 'sm' | 'md' | 'lg';
  /** 의미 색상 */
  color?: 'primary' | 'neutral' | 'success' | 'warning' | 'danger';
}
```

### RadioGroup

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/RadioGroup/RadioGroup.tsx
RadioGroup: 여러 선택지 중 하나를 고르는 라디오 버튼 묶음.

네이티브 `<input type="radio">` 로 만든다 — 화살표 이동·선택, Tab 으로 들어오기, 비활성 건너뛰기, 폼 제출·`required` 검증을
브라우저가 처리한다. (1.1 까지는 Radix RadioGroup 이었는데, Radix 는 "포커스가 옮겨질 때 화살표 키가 아직 눌려 있는지" 로
선택을 정해서 키를 바로 떼는 입력(자동화·일부 보조기기)에서는 포커스만 옮겨지고 선택이 빠졌다 — E2E 에서 20회 중 19회.)
```ts
export interface RadioOption {
  value: string;
  label: ReactNode;
  /** 레이블 아래 보조 설명 */
  description?: ReactNode;
  disabled?: boolean;
}

export interface RadioGroupProps {
  /** 선택지 목록 */
  options: RadioOption[];
  /** 선택된 값 (제어 모드). undefined 를 넘기면 아무것도 선택하지 않은 상태 */
  value?: string;
  /** 처음 선택된 값 (비제어 모드) */
  defaultValue?: string;
  /** 값이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 그룹 위에 표시할 레이블 */
  label?: ReactNode;
  /** 그룹 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 배치 방향 */
  orientation?: 'vertical' | 'horizontal';
  /** 크기 */
  size?: 'sm' | 'md';
  disabled?: boolean;
  required?: boolean;
  /** form 제출 시 사용할 이름 */
  name?: string;
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 바깥 래퍼 className */
  className?: string;
}
```

### ResidentNumberInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/ResidentNumberInput/ResidentNumberInput.tsx
ResidentNumberInput: 주민·외국인등록번호 입력 — 앞 6자리와 뒷자리를 두 칸으로 받고 뒷자리는 가린다(password). 번호를 통째로 앞칸에 붙여 넣으면 두 칸에 나눠 넣는다.
앞칸을 다 채워도 포커스를 옮기지 않는다(예고 없는 포커스 이동은 WCAG 3.2.2). 뒷칸이 비었을 때 Backspace 는 앞칸으로 간다.

주민등록번호는 법령에 근거가 있을 때만 수집할 수 있다(개인정보 보호법 제24조의2). 나이·성별만 필요하면 `digits={7}`.
```ts
export interface ResidentNumberInputProps {
  /** 숫자만 있는 값 (제어 모드). 예: "9001011234567" (digits={7} 이면 "9001011") */
  value?: string;
  /** 처음 값 (비제어 모드) */
  defaultValue?: string;
  /** 숫자만 있는 값과, 다 채웠을 때 생년월일·뒷자리 첫 숫자가 맞는지로 호출된다 (다 채우기 전에는 valid 가 null) */
  onValueChange?: (digits: string, valid: boolean | null) => void;
  /**
   * 받을 자릿수. 13(기본)은 뒤 7자리를 가려서(password) 받고, 7 은 생년월일 + 뒷자리 첫 숫자만 받는다(나이·성별 확인 —
   * 주민번호 전체가 필요 없으면 7 을 쓴다).
   */
  digits?: 13 | 7;
  /**
   * 다 채웠는데 생년월일·뒷자리 첫 숫자가 맞지 않으면 자동으로 오류를 보여 준다 (기본 true). 마지막 검증 숫자는 보지 않는다
   * (2020년 10월 이후 번호는 임의 번호). 직접 error·helperText 를 주면 그 값이 우선한다.
   */
  validate?: boolean;
  /** 자동 검증 오류 문구 */
  invalidText?: string;
  /** 위에 표시할 레이블 (기본 "주민등록번호") */
  label?: ReactNode;
  /** 아래 도움말. error 일 때는 오류 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 오류 상태 */
  error?: boolean;
  /** 필수 입력 (레이블에 * 표시, required 속성) */
  required?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** form 제출 시 사용할 이름 — 숫자만 있는 값을 숨긴 input 으로 제출한다 */
  name?: string;
  /** 묶음 id — 앞칸은 `${id}-front`, 뒷칸은 `${id}-back` (ErrorSummary 링크·focusField 는 이 id 로 앞칸을 찾는다) */
  id?: string;
  /** 바깥 래퍼 className */
  className?: string;
  onBlur?: (event: FocusEvent<HTMLDivElement>) => void;
}
```

### SearchInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/SearchInput/SearchInput.tsx
SearchInput: 검색 입력. 앞에 돋보기, 글자가 있으면 끝에 지우기 버튼이 생긴다. Enter 는 onSearch, Escape 는 검색어를 지운다.
지우기 버튼은 Tab 순서에 넣지 않는다(키보드는 Escape) — Combobox 의 지우기와 같다.
```ts
export interface SearchInputProps extends Omit<TextFieldProps, 'value' | 'defaultValue' | 'type' | 'endAdornment'> {
  /** 검색어 (제어 모드) */
  value?: string;
  /** 처음 검색어 (비제어 모드) */
  defaultValue?: string;
  /** 검색어가 바뀔 때 (입력·지우기·form reset) */
  onValueChange?: (value: string) => void;
  /**
   * Enter 를 눌렀을 때 — 한글 조합 중 Enter 는 무시한다.
   * form 안에서는 Enter 가 form 도 제출하므로, form 이 있으면 form 의 onSubmit 하나만 쓰는 편이 낫다.
   */
  onSearch?: (value: string) => void;
  /** 지우기 버튼 이름 — 기본 "검색어 지우기" */
  clearLabel?: string;
  /** 앞의 돋보기 아이콘을 바꾼다. null 이면 없앤다 */
  startAdornment?: ReactNode;
  // ── 아래는 TextFieldProps 에서 물려받는 prop 중 자주 쓰는 것. 타입은 같고, Storybook 자동 문서(react-docgen 이
  //    Omit 으로 물려받은 prop 을 풀지 못함)에 보이도록 다시 적는다.
  /** 입력창 위에 표시할 레이블. 없으면 접근 가능한 이름으로 "검색" 을 쓴다(aria-label 로 바꿀 수 있음) */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  disabled?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  placeholder?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
}
```

### SegmentedControl

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/SegmentedControl/SegmentedControl.tsx
SegmentedControl: 여러 값 중 하나를 고르는 칸 묶음 (기간 일/주/월, 보기 방식 등).
의미는 라디오 그룹과 같다(WAI-ARIA radiogroup): Tab 으로 그룹에 들어가면 선택된 칸, 화살표로 옮기면 바로 선택된다.
선택에 따라 아래 내용이 바뀌는 "패널" 이 있으면 Tabs 를 쓴다.

Radix RadioGroup 을 쓰지 않고 직접 구현한다 — Radix 는 "포커스가 옮겨질 때 화살표 키가 아직 눌려 있는지" 로 선택을 정해서
키를 아주 빨리 떼는 입력(자동화·일부 보조기기)에서는 포커스만 옮겨지고 선택이 안 되는 경우가 있었다(E2E 에서 약 20%).
```ts
export interface SegmentedControlOption {
  value: string;
  /** 칸에 보이는 글자 (접근 가능한 이름이 된다) */
  label: ReactNode;
  /** 글자 앞 아이콘 (장식용) */
  icon?: ReactNode;
  disabled?: boolean;
}

export interface SegmentedControlProps {
  /** 선택지 (2~5개 권장 — 많으면 Select 를 쓴다) */
  options: SegmentedControlOption[];
  /** 선택된 값 (제어 모드) */
  value?: string;
  /** 처음 선택된 값 (비제어 모드) */
  defaultValue?: string;
  /** 값이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 위에 보이는 레이블. 없으면 aria-label 로 이름을 준다 */
  label?: ReactNode;
  /** label 이 없을 때 스크린리더용 이름 (예: "기간") */
  'aria-label'?: string;
  /** 크기 — 전체 높이가 Button·Input 과 같다 (sm 32 / md 40 / lg 48) */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채우고 칸을 같은 너비로 나눈다 */
  fullWidth?: boolean;
  disabled?: boolean;
  /** form 제출 시 사용할 이름 */
  name?: string;
  id?: string;
  className?: string;
}
```

### Select

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Select/Select.tsx
```ts
export interface SelectOption {
  value: string;
  label: ReactNode;
  disabled?: boolean;
}

export interface SelectProps {
  /** 선택지 목록 */
  options: SelectOption[];
  /** 선택된 값 (제어 모드). undefined 를 넘기면 선택 없음(placeholder)으로 표시한다 */
  value?: string;
  /** 처음 선택된 값 (비제어 모드) */
  defaultValue?: string;
  /** 값이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 선택 전 표시할 문구 */
  placeholder?: ReactNode;
  /** 위에 표시할 레이블 */
  label?: ReactNode;
  /** 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 크기 */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  disabled?: boolean;
  required?: boolean;
  /** form 제출 시 사용할 이름 */
  name?: string;
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 트리거 className */
  className?: string;
}
```

### Skeleton

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Skeleton/Skeleton.tsx
Skeleton: 콘텐츠를 불러오는 동안 자리를 표시한다. 장식용이라 스크린리더에서 숨긴다 —
로딩 중인 영역(감싸는 요소)에 `aria-busy="true"` 를 붙여 상태를 알린다.
```ts
export interface SkeletonProps extends HTMLAttributes<HTMLSpanElement> {
  /** 모양. text 는 글자 높이(1em), circle 은 width 를 지름으로 쓴다 */
  variant?: 'text' | 'rect' | 'circle';
  /** 너비. 숫자는 px (기본: text·rect 100%, circle 40px) */
  width?: number | string;
  /** 높이. 숫자는 px (기본: text 1em, rect 100px, circle 은 width 와 같음) */
  height?: number | string;
  /** text 에서 여러 줄을 그린다. 마지막 줄은 60% 너비 */
  lines?: number;
}
```

### SkipLink

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/SkipLink/SkipLink.tsx
SkipLink: 본문 바로가기 (KWCAG 2.2 6.4.1 반복 영역 건너뛰기 / WCAG 2.4.1).
페이지 맨 앞(머리글·메뉴보다 먼저)에 둔다. 평소에는 보이지 않고, 첫 Tab 에 왼쪽 위에 나타난다.
누르면 본문으로 포커스를 옮긴다 — 본문 요소가 원래 포커스를 받지 못하면 tabindex="-1" 을 붙여 옮긴다
(주소의 #만 바꾸면 일부 브라우저·SPA 라우터에서 포커스가 그대로 남는다).

@example
<SkipLink />            // "본문 바로가기" → #main
<Header />
<main id="main">…</main>
```ts
export interface SkipLinkProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
  /** 건너뛸 곳(본문)의 id 를 가리키는 주소. 기본 "#main" — 본문 요소에 id="main" 을 준다 */
  href?: string;
}
```

### Slider

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Slider/Slider.tsx
Slider: 범위 안에서 값을 고르는 슬라이더. 손잡이를 끌거나 키보드(←→↑↓, PageUp/Down, Home/End)로 조절한다.
Radix Slider 기반이라 손잡이마다 role="slider" 와 aria-valuemin/max/now 가 붙는다.
```ts
export interface SliderProps {
  /** 값 (제어 모드). 손잡이 하나면 `[50]`, 범위면 `[20, 80]` */
  value?: number[];
  /** 처음 값 (비제어 모드) */
  defaultValue?: number[];
  /** 값이 바뀌는 동안 계속 호출된다 */
  onValueChange?: (value: number[]) => void;
  /** 드래그·키 입력이 끝났을 때 한 번 호출된다 (서버 저장 등) */
  onValueCommit?: (value: number[]) => void;
  min?: number;
  max?: number;
  step?: number;
  /** 범위 슬라이더에서 두 손잡이 사이 최소 간격(step 개수) */
  minStepsBetweenThumbs?: number;
  /** 위에 표시하는 레이블. 손잡이(slider)의 이름이 된다 */
  label?: ReactNode;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 아래에 표시하는 보조 설명 (aria-describedby 로 연결) */
  helperText?: ReactNode;
  /** 오른쪽 위에 현재 값을 보여 준다 */
  showValue?: boolean;
  /** 값 텍스트 형식. 화면 표시와 스크린리더(aria-valuetext)에 함께 쓴다 (예: v => `${v.toLocaleString()}원`) */
  formatValue?: (value: number) => string;
  /**
   * 범위 슬라이더에서 손잡이마다 덧붙일 이름 (기본 ["최소", "최대"]).
   * 스크린리더는 "가격 최소", "가격 최대" 처럼 레이블과 함께 읽는다
   */
  thumbLabels?: string[];
  size?: 'sm' | 'md';
  disabled?: boolean;
  /** form 제출 시 사용할 이름 */
  name?: string;
  id?: string;
  className?: string;
}
```

### Spinner

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Spinner/Spinner.tsx
```ts
export interface SpinnerProps extends Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
  /** 크기 (sm 16px, md 20px, lg 28px) */
  size?: 'sm' | 'md' | 'lg';
  /** 색상. `inherit`(기본)는 부모 글자색을 그대로 쓴다 */
  color?: 'inherit' | 'primary' | 'neutral' | 'danger';
  /**
   * 스크린리더가 읽을 텍스트 (기본 "로딩 중").
   * 빈 문자열이면 장식용으로 보고 `aria-hidden` 처리한다 — 버튼처럼 바깥 요소가 이미 상태를 알릴 때 쓴다.
   */
  label?: string;
}
```

### Stack

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Stack/Stack.tsx
```ts
export interface StackProps extends HTMLAttributes<HTMLElement> {
  /** 렌더링할 요소 */
  as?: ElementType;
  /** 배치 방향 (기본 column). 구간별로: `{ base: 'column', md: 'row' }` */
  direction?: Responsive<Direction>;
  /** 자식 사이 간격 (space 토큰 키). 구간별로: `{ base: 3, lg: 6 }` */
  gap?: Responsive<SpaceKey>;
  /** 교차축 정렬 (align-items). 구간별 값도 받는다 */
  align?: Responsive<Align>;
  /** 주축 정렬 (justify-content). 구간별 값도 받는다 */
  justify?: Responsive<Justify>;
  /** 줄바꿈 허용 */
  wrap?: boolean;
}
```

### Stepper

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Stepper/Stepper.tsx
Stepper: 여러 단계로 나뉜 흐름(가입·결제·신청)에서 지금 어디쯤인지 보여 주는 표시용 목록.
`<ol>` 이라 스크린리더가 "n개 중 m번째" 를 읽고, 현재 단계는 aria-current="step", 완료한 단계는 "(완료)" 를 함께 읽는다.
단계를 눌러 이동하는 기능은 없다 — 이동은 "이전"·"다음" 버튼으로 둔다.
```ts
export interface StepperStep {
  /** 단계 이름 */
  label: ReactNode;
  /** 이름 아래 보조 설명 */
  description?: ReactNode;
}

export interface StepperProps extends Omit<OlHTMLAttributes<HTMLOListElement>, 'children' | 'type' | 'start'> {
  /** 단계 목록 */
  steps: StepperStep[];
  /** 현재 단계 (0부터). 앞 단계는 완료로 표시한다. steps.length 면 모두 완료 */
  current: number;
  /** horizontal(기본): 가로로 나란히, 이름은 원 아래. vertical: 세로로, 이름은 원 오른쪽(설명이 길 때) */
  orientation?: 'horizontal' | 'vertical';
  /**
   * 현재 단계가 진행 중이다(AI 응답·업로드 처리 등). 원 안에 스피너를 보여 주고 이름에 "(진행 중)" 을 함께 읽는다.
   * 단계가 바뀌는 순간을 스크린리더에 알리려면 `role="status"` 영역을 따로 둔다.
   */
  loading?: boolean;
  /** 목록 이름 (기본 "진행 단계") */
  'aria-label'?: string;
}
```

### Switch

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Switch/Switch.tsx
Switch: 켜고 끄는 스위치. `<button role="switch">` 로 그리고, form 안에서는 숨긴 checkbox 로 값 제출·required 검증·reset 을 처리한다
(1.5 까지 쓰던 Radix Switch 와 같은 동작 — 번들을 줄이려고 직접 구현).
```ts
export interface SwitchProps {
  /** 스위치 옆에 표시할 레이블 */
  label?: ReactNode;
  /** 크기 */
  size?: 'sm' | 'md';
  /** 켜짐 상태 (제어 모드) */
  checked?: boolean;
  /** 처음 켜짐 상태 (비제어 모드) */
  defaultChecked?: boolean;
  /** 켜짐 상태가 바뀔 때 호출된다 */
  onCheckedChange?: (checked: boolean) => void;
  disabled?: boolean;
  required?: boolean;
  /** form 제출 시 사용할 이름 */
  name?: string;
  /** form 제출 시 켜져 있을 때의 값 (기본 "on") */
  value?: string;
  id?: string;
  /** label 이 없을 때 스크린리더용 이름 */
  'aria-label'?: string;
  /** 바깥 래퍼 className */
  className?: string;
}
```

### Table

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Table/Table.tsx
Table: 데이터 표. 네이티브 `<table>` 에 스타일을 입힌다.
표가 넘치면 바깥 영역이 스크롤되고, 키보드로도 스크롤할 수 있도록 그 영역이 포커스를 받는다.
TableEmpty: 보여 줄 행이 없을 때(검색 결과 없음 등) TableBody 안에 두는 안내 행. 표 전체 폭 가운데에 글자·버튼을 놓는다.
안내를 갖춰 쓰려면 안에 `<EmptyState size="sm" titleAs="p" … />` 를 넣는다.
검색·필터로 결과가 바뀌면 개수를 role="status" 로 따로 알리는 것을 권장한다(파일럿 /orders 참고).
TableSkeleton: 불러오는 동안 TableBody 안에 두는 자리 표시 행. 보조기술에서는 숨긴다 — 표(Table)에 `aria-busy` 를 주고,
다 불러오면 결과 개수를 role="status" 로 알린다.
```ts
export type TableSize = 'sm' | 'md';

export interface TableProps extends HTMLAttributes<HTMLTableElement> {
  /** 셀 여백 */
  size?: TableSize;
  /** 짝수 행 배경을 칠한다 */
  striped?: boolean;
  /** 세로로 스크롤할 때 머리 행을 위에 고정한다 (containerStyle 등으로 높이를 제한해 쓴다) */
  stickyHeader?: boolean;
  /** 표 위에 보이는 제목. 표의 이름이 되고, 스크롤 영역의 이름으로도 쓰인다 */
  caption?: ReactNode;
  /** caption 이 없을 때 표의 이름 (스크린리더용) */
  'aria-label'?: string;
  /** 바깥 스크롤 영역의 className (높이 제한 등) */
  containerClassName?: string;
  /** 바깥 스크롤 영역의 style */
  containerStyle?: CSSProperties;
}

export interface TableRowProps extends HTMLAttributes<HTMLTableRowElement> {
  /** 선택된 행으로 강조한다 (`aria-selected` 는 grid 등 상호작용 표에서 직접 지정한다) */
  selected?: boolean;
}

export type TableAlign = 'left' | 'center' | 'right';

export interface TableHeadProps extends Omit<ThHTMLAttributes<HTMLTableCellElement>, 'align'> {
  /** 정렬 */
  align?: TableAlign;
  /**
   * 이 열의 정렬 상태. onSort 와 함께 주면 머리 셀이 정렬 버튼이 되고 `aria-sort` 를 붙인다.
   * 정렬되지 않은 열은 'none'.
   */
  sortDirection?: 'ascending' | 'descending' | 'none';
  /** 정렬 버튼을 눌렀을 때 호출된다. 다음 정렬 상태는 사용하는 쪽이 정한다 */
  onSort?: () => void;
}

export interface TableCellProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'align'> {
  /** 정렬 (숫자는 right 권장) */
  align?: TableAlign;
}

export interface TableEmptyProps extends Omit<TdHTMLAttributes<HTMLTableCellElement>, 'colSpan' | 'align'> {
  /** 표의 열 수 — 안내가 표 전체 폭을 차지하게 한다 */
  colSpan: number;
  children?: ReactNode;
}

export interface TableSkeletonProps {
  /** 자리 표시 행 수 (기본 5) */
  rows?: number;
  /** 열 수 */
  columns: number;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Table/useTableSelection.ts
useTableSelection: 표 행 선택 상태. 페이지를 넘겨도 선택은 유지되고, "이 페이지 모두 선택" 체크박스(혼합 상태 포함)와 행 체크박스에
바로 펼쳐 쓰는 prop 을 돌려준다.

```tsx
const selection = useTableSelection<string>();
<Checkbox aria-label="이 페이지 모두 선택" {...selection.selectAllProps(pageIds)} />
<Checkbox aria-label={`${row.id} 선택`} {...selection.rowProps(row.id)} />
<TableRow selected={selection.isSelected(row.id)}>
```

### Tabs

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Tabs/Tabs.tsx
```ts
export interface TabsProps extends ComponentPropsWithoutRef<typeof RadixTabs.Root> {
  /** 시각적 스타일. line 은 밑줄, soft 는 배경이 있는 세그먼트 */
  variant?: 'line' | 'soft';
  /** 크기 */
  size?: 'sm' | 'md';
  /** 선택된 탭 (제어 모드) */
  value?: string;
  /** 처음 선택된 탭 (비제어 모드) */
  defaultValue?: string;
  /** 선택된 탭이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /**
   * automatic(기본): 방향키로 포커스를 옮기면 바로 선택된다.
   * manual: 방향키로 포커스만 옮기고 Enter/Space 로 선택한다 (탭 전환 비용이 클 때).
   */
  activationMode?: 'automatic' | 'manual';
  /**
   * horizontal(기본): 탭 목록이 위, ←/→ 로 이동.
   * vertical: 탭 목록이 왼쪽(내용은 오른쪽), ↑/↓ 로 이동. 탭이 많거나 이름이 길 때(설정 화면 등).
   */
  orientation?: 'horizontal' | 'vertical';
}

export type TabsListProps = ComponentPropsWithoutRef<typeof RadixTabs.List>;

export interface TabsTriggerProps extends ComponentPropsWithoutRef<typeof RadixTabs.Trigger> {
  /** 이 탭의 값. 같은 값을 가진 TabsContent 와 연결된다 */
  value: string;
}

export interface TabsContentProps extends ComponentPropsWithoutRef<typeof RadixTabs.Content> {
  /** 연결할 TabsTrigger 의 값 */
  value: string;
}
```

### Tag

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Tag/Tag.tsx
Tag: 짧은 글자 하나를 담는 태그. 세 가지로 쓴다.
- 표시: 분류·키워드 (상태 라벨은 Badge).
- 삭제: `onRemove` — 고른 필터·입력한 키워드를 보여 주고 지운다. 삭제 버튼 위에서 Delete·Backspace 로도 지운다.
- 고르기: `selected`·`onSelectedChange` — 필터 칩. button 이고 켜짐을 aria-pressed 와 체크 아이콘으로 보인다.
```ts
/** TagGroup 이 안의 Tag 에 주는 것 — 삭제 직전에 불러 포커스 옮길 자리와 알림 글자를 맡긴다 */
export interface TagGroupContextValue {
  beforeRemove: (element: HTMLElement, label: string) => void;
}

export interface TagProps extends Omit<HTMLAttributes<HTMLElement>, 'color' | 'onSelect'> {
  /** 글자 */
  children: ReactNode;
  /** 시각적 스타일 (표시·삭제용) */
  variant?: 'soft' | 'outline';
  /** 의미 색상. 고르는 칩에서는 켜졌을 때의 색 */
  color?: 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
  /** 크기 — md 는 높이 32px(누르기 쉬움), sm 은 24px */
  size?: 'sm' | 'md';
  /** 글자 앞 아이콘 (장식용) */
  startIcon?: ReactNode;
  /**
   * 주면 끝에 삭제 버튼이 생긴다. 목록에서 실제로 지우는 것은 부르는 쪽이 한다.
   * 여러 개를 나열하면 TagGroup 으로 감싼다 — 지운 뒤 포커스를 다음 태그로 옮기고 "… 삭제됨" 을 알린다.
   */
  onRemove?: () => void;
  /** 삭제 버튼 이름 — 기본 "<글자> 삭제". 글자가 문자열이 아니면 직접 준다 */
  removeLabel?: string;
  /** 켜짐 (제어 모드) — selected·defaultSelected·onSelectedChange 중 하나를 주면 고르는 칩(button, aria-pressed)이 된다 */
  selected?: boolean;
  /** 처음 켜짐 (비제어 모드) */
  defaultSelected?: boolean;
  /** 고르는 칩을 눌렀을 때 */
  onSelectedChange?: (selected: boolean) => void;
  disabled?: boolean;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Tag/TagGroup.tsx
TagGroup: Tag 목록. 줄바꿈되는 가로 나열(ul)이고, 안의 Tag 를 지우면 포커스를 그 자리의 다음 태그(없으면 앞 태그) 삭제 버튼으로
옮긴 뒤 "… 삭제됨" 을 알린다. 마지막 태그까지 지우면 목록 자체(tabIndex -1)로 포커스를 둔다 — 포커스가 페이지 처음으로 사라지지 않게.
```ts
export interface TagGroupProps extends HTMLAttributes<HTMLUListElement> {
  /** Tag 들. 하나씩 목록 항목(li)으로 감싼다 */
  children?: ReactNode;
  /** 목록 이름 (스크린리더) — 예: "고른 필터". 화면에 제목이 있으면 aria-labelledby */
  'aria-label'?: string;
}
```

### Textarea

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Textarea/Textarea.tsx
```ts
export interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>, 'size'> {
  /** 입력창 위에 표시할 레이블 */
  label?: ReactNode;
  /** 입력창 아래에 표시할 도움말. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  /** 에러 상태 */
  error?: boolean;
  /** 크기 (안쪽 여백과 글자 크기) */
  size?: 'sm' | 'md' | 'lg';
  /** 부모 너비를 꽉 채운다 */
  fullWidth?: boolean;
  /** 사용자가 크기를 조절할 수 있는 방향. autoResize 이면 무시된다 */
  resize?: 'none' | 'vertical' | 'both';
  /** 내용에 맞춰 높이가 자동으로 늘어난다. 최대 높이는 style 의 maxHeight 로 제한한다 */
  autoResize?: boolean;
  /** 글자 수를 표시한다. maxLength 가 있으면 "12/200" 형태 */
  showCount?: boolean;
}
```

### Toast

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Toast/Toast.tsx
```ts
export type ToastColor = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';

export interface ToastOptions {
  /** 제목 */
  title: ReactNode;
  /** 설명 */
  description?: ReactNode;
  /** 의미 색상 (기본 neutral) — Alert·Badge 의 `color` 와 같은 이름 */
  color?: ToastColor;
  /** 자동으로 닫히기까지 시간(ms). Infinity 면 자동으로 닫히지 않는다 */
  duration?: number;
  /** 실행 버튼 */
  action?: {
    label: string;
    onClick: () => void;
    /** 스크린리더용 대체 설명 (예: "실행 취소하려면 Ctrl+Z") */
    altText?: string;
  };
}

export interface ToastContextValue {
  /** 토스트를 띄우고 id 를 반환한다 */
  toast: (options: ToastOptions) => number;
  /** id 의 토스트를 닫는다. id 가 없으면 모두 닫는다 */
  dismiss: (id?: number) => void;
}

export interface ToastProviderProps {
  children: ReactNode;
  /** 기본 표시 시간(ms) */
  duration?: number;
  /** 스크린리더가 토스트 영역을 읽을 때 쓰는 이름 */
  label?: string;
}
```

### Tooltip

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Tooltip/Tooltip.tsx
```ts
export interface TooltipProps {
  /** 툴팁 내용 */
  content: ReactNode;
  /** 툴팁을 띄울 요소. ref 를 받을 수 있는 요소 하나여야 한다 */
  children: ReactElement;
  /** 표시 방향 */
  side?: 'top' | 'right' | 'bottom' | 'left';
  /** 정렬 */
  align?: 'start' | 'center' | 'end';
  /** 마우스를 올린 뒤 표시까지 지연 시간(ms) */
  delay?: number;
  /** 열림 상태 (제어 모드) */
  open?: boolean;
  /** 처음 열림 상태 (비제어 모드) */
  defaultOpen?: boolean;
  /** 열림 상태가 바뀔 때 호출된다 */
  onOpenChange?: (open: boolean) => void;
  /** true 이면 툴팁을 띄우지 않고 children 만 렌더링한다 */
  disabled?: boolean;
  /** 툴팁 className */
  className?: string;
}
```

### Typography

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/Typography/Typography.tsx
```ts
export type TypographyVariant = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'body-lg' | 'body' | 'body-sm' | 'caption';

export interface TypographyProps extends Omit<HTMLAttributes<HTMLElement>, 'color'> {
  /** 텍스트 스타일 */
  variant?: TypographyVariant;
  /** 렌더링할 요소. 기본값은 variant 에 따라 결정된다 (h1, p, span 등) */
  as?: ElementType;
  /** 글자 색상 */
  color?: 'default' | 'muted' | 'subtle' | 'primary' | 'danger' | 'success' | 'warning' | 'inherit';
  /** variant 의 기본 굵기를 덮어쓴다 */
  weight?: 'regular' | 'medium' | 'semibold' | 'bold';
  /** 정렬 */
  align?: 'start' | 'center' | 'end';
  /** 한 줄로 자르고 말줄임표를 표시한다 */
  truncate?: boolean;
}
```

### VerificationCodeInput

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/VerificationCodeInput/VerificationCodeInput.tsx
VerificationCodeInput: 문자로 받은 인증번호 입력. 실제 입력창은 하나라서 문자 자동 채우기(`autocomplete="one-time-code"`)·붙여넣기가 그대로 되고,
스크린리더는 칸마다가 아니라 "인증번호" 하나로 읽는다. 칸 모양은 화면 표시용이다.
```ts
export interface VerificationCodeInputProps {
  /** 자릿수 */
  length?: number;
  /** 입력값 (제어 모드) */
  value?: string;
  /** 처음 입력값 (비제어 모드) */
  defaultValue?: string;
  /** 입력값이 바뀔 때 호출된다 */
  onValueChange?: (value: string) => void;
  /** 모든 자리를 채웠을 때 호출된다 (자동 제출 등) */
  onComplete?: (value: string) => void;
  /** 받을 문자. numeric 이면 숫자 키패드를 띄우고 숫자만 받는다 */
  type?: 'numeric' | 'alphanumeric';
  /** 레이블 (입력창의 이름) */
  label?: ReactNode;
  /** 아래 도움말. 생략하면 "6자리 숫자를 입력하세요" 처럼 자릿수를 안내한다. error 일 때는 에러 메시지로 표시된다 */
  helperText?: ReactNode;
  error?: boolean;
  disabled?: boolean;
  autoFocus?: boolean;
  /** 유효 시간(초). 주면 남은 시간을 보여 주고, 0 이 되면 onExpire 를 호출하고 만료 안내를 읽어 준다 */
  expiresIn?: number;
  onExpire?: () => void;
  /** 주면 재전송 버튼이 생긴다. 누르면 호출되고 입력값과 남은 시간을 처음으로 되돌린다 */
  onResend?: () => void;
  resendText?: string;
  /** 만료 안내 문구 */
  expiredText?: string;
  /** form 제출 시 사용할 이름 */
  name?: string;
  id?: string;
  className?: string;
}
```

### VisuallyHidden

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/components/VisuallyHidden/VisuallyHidden.tsx
VisuallyHidden: 화면에는 보이지 않고 스크린리더만 읽는 글자. 아이콘만 있는 열 머리글("작업"), 보이는 글자에 붙는 보충 설명 등에 쓴다.
`display: none`·`hidden` 과 달리 보조기술이 읽는다. hook 이 없어 서버 컴포넌트로도 렌더링된다.
```ts
export interface VisuallyHiddenProps extends HTMLAttributes<HTMLElement> {
  /** 렌더링할 요소 (기본 span) */
  as?: ElementType;
}
```

## 테마·문구 API

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/theme/createTheme.ts
createTheme: 브랜드 테마를 만든다. 여러 입력을 넘기면 순서대로 깊게 병합한다 (뒤가 우선).

@example
const brand = createTheme(
  createIntentColors('primary', '#7c3aed'),
  { common: { radius: { md: '6px' }, font: { family: { sans: 'Inter, sans-serif' } } } },
);
<ThemeProvider theme="dark" overrides={brand}>…</ThemeProvider>
```ts
export type DeepPartial<T> = { [K in keyof T]?: T[K] extends string ? string : DeepPartial<T[K]> };

export type ThemeOverrides = DeepPartial<ThemeTokens>;

/** createTheme 에 넘기는 입력. common 은 라이트·다크 공통, light/dark 는 모드별 값 (common 보다 우선). */
export interface ThemeInput {
  common?: ThemeOverrides;
  light?: ThemeOverrides;
  dark?: ThemeOverrides;
}

/** createTheme 의 결과. ThemeProvider 의 overrides 로 넘긴다. */
export interface BestowTheme {
  readonly light: ThemeOverrides;
  readonly dark: ThemeOverrides;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/theme/color.ts
createIntentColors: 대표색 하나로 intent(primary 등)의 라이트·다크 색 세트를 만든다. 결과는 createTheme 에 넘긴다.
- solid 는 넘긴 색을 그대로 쓴다 (다크모드에서 너무 어두우면 조금 밝힌다). 단 흰 글자·짙은 글자 모두
  대비 4.5:1 이 안 나오는 중간 밝기 색이면 4.5 가 나올 만큼만 밝기를 옮긴다.
- text 와 contrast(solid 위 글자색)는 WCAG AA 대비 4.5:1 을 만족하도록 계산한다.
- intent 가 'primary' 면 포커스 링 색(border.focus)도 함께 바꾼다.

@example createTheme(createIntentColors('primary', '#7c3aed'))
```ts
export type IntentName = 'primary' | 'neutral' | 'danger' | 'success' | 'warning' | 'info';
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/theme/ThemeProvider.tsx
useTheme: 현재 적용 중인 모드(light/dark)를 반환한다. `theme="system"` 이면 OS 설정에 따른 값이다 —
단, 서버 렌더링과 hydration 첫 렌더에서는 OS 설정을 몰라 'light' 이고, 그 직후 실제 값으로 다시 렌더링된다.
usePortalProps: Portal 로 ThemeProvider 바깥(body)에 렌더링되는 요소에 펼쳐 넣을 props.
현재 모드의 CSS 변수, 브랜드 오버라이드, 기본 글꼴을 다시 적용한다.

@example const portal = usePortalProps(); <Content className={cx(portal.className, styles.content)} style={portal.style} />
```ts
export interface ThemeProviderProps extends HTMLAttributes<HTMLDivElement> {
  /**
   * 라이트/다크 모드. `'system'` 은 OS 설정을 따르고 바뀌면 바로 반영한다 — 서버 렌더링에서도 CSS 미디어쿼리로 그려
   * 첫 화면이 깜빡이지 않는다. 생략하면 바깥 ThemeProvider 의 모드를 이어받는다 (최상위는 light).
   */
  theme?: ThemeMode;
  /**
   * createTheme 으로 만든 브랜드 테마. 모드를 바꿔도 유지되고, 중첩된 ThemeProvider 는 바깥 값을 이어받는다
   * (안쪽에서 준 값이 우선).
   */
  overrides?: BestowTheme;
}
```

소스: https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/src/i18n/LocaleProvider.tsx
LocaleProvider: 컴포넌트 기본 문구를 한곳에서 바꾼다 (다국어 대응 등). 중첩하면 바깥 값을 이어받고 안쪽이 우선한다.
@example <LocaleProvider messages={en}>…</LocaleProvider>
@example <LocaleProvider messages={{ close: '창 닫기' }}>…</LocaleProvider>
```ts
/**
 * 컴포넌트의 기본 문구. 모두 생략할 수 있고, 생략하면 각 컴포넌트의 한국어 기본값을 쓴다.
 * 우선순위: 컴포넌트에 직접 준 prop > LocaleProvider 의 messages > 한국어 기본값.
 *
 * 한국어 기본값을 하나의 객체로 모으지 않고 각 컴포넌트에 두는 이유: 그 객체를 import 하면 Button 하나만 써도
 * 모든 문구가 번들에 딸려 온다(Button → Spinner). 이 파일에는 타입과 Provider 만 둔다.
 */
export interface BestowMessages {
  /** 닫기 버튼 (Modal, Drawer, Popover, Toast, Alert) — "닫기" */
  close: string;
  /** Spinner — "로딩 중" */
  loading: string;
  /** Toast 영역 — "알림" */
  notifications: string;
  /** Breadcrumb — "이동 경로" */
  breadcrumb: string;
  /** Pagination — "페이지 탐색", "이전 페이지", "다음 페이지", "3 페이지" */
  pagination: string;
  paginationPrevious: string;
  paginationNext: string;
  paginationPage: (page: number) => string;
  /** Link external — "(새 창)" */
  newWindow: string;
  /** Combobox — "결과가 없어요", "목록 열기" */
  noResults: string;
  openList: string;
  /**
   * Combobox clearable — "선택 지우기".
   * 1.0 이후에 추가한 키는 선택(?)으로 둔다 — 직접 만든 BestowMessages 객체(다른 언어 묶음)가 타입 오류로 깨지지 않게.
   */
  clearSelection?: string;
  /** SkipLink — "본문 바로가기" (1.0 이후 추가, 선택 키) */
  skipToContent?: string;
  /** NumberInput −/+ 버튼 — "줄이기", "늘리기" (1.0 이후 추가, 선택 키) */
  decrement?: string;
  increment?: string;
  /** Stepper — 목록 이름 "진행 단계", 완료한 단계에 붙는 "완료" (1.0 이후 추가, 선택 키) */
  steps?: string;
  stepCompleted?: string;
  stepInProgress?: string;
  /**
   * FileUpload (1.0 이후 추가, 선택 키) — "파일 선택", "또는 여기로 끌어다 놓으세요", "선택한 파일", "○○ 삭제",
   * "파일 2개 선택됨", "○○ 삭제됨", 크기·형식·개수 초과 안내
   */
  fileSelect?: string;
  fileDropHint?: string;
  fileList?: string;
  fileRemove?: (name: string) => string;
  filesSelected?: (count: number) => string;
  fileRemoved?: (name: string) => string;
  fileTooLarge?: (name: string, maxSize: string) => string;
  fileTypeNotAllowed?: (name: string) => string;
  fileTooMany?: (maxFiles: number) => string;
  /** ErrorSummary 제목 — "입력한 내용에 고칠 곳이 3개 있어요" (1.0 이후 추가, 선택 키) */
  errorSummaryTitle?: (count: number) => string;
  /** DateRangePicker — "시작일", "종료일", 빠른 선택 묶음 이름 "빠른 선택" (1.0 이후 추가, 선택 키) */
  dateRangeStart?: string;
  dateRangeEnd?: string;
  dateRangePresets?: string;
  /** Slider 범위 손잡이 — "최소", "최대" */
  rangeStart: string;
  rangeEnd: string;
  /** AgreementGroup — "전체 동의", "필수", "선택", "보기", "접기" */
  agreeAll: string;
  required: string;
  optional: string;
  show: string;
  hide: string;
  /** VerificationCodeInput — "인증번호", "6자리 숫자를 입력하세요.", "재전송", "인증 시간이 지났어요. 재전송해 주세요." */
  verificationCode: string;
  verificationCodeHint: (length: number, type: 'numeric' | 'alphanumeric') => string;
  resend: string;
  verificationExpired: string;
  /** PhoneNumberInput — "휴대폰 번호" */
  phoneNumber: string;
  /** BusinessNumberInput — "사업자등록번호" 와 검증 문구 */
  businessNumber: string;
  businessNumberInvalid: string;
  businessNumberIncomplete: string;
  /** ResidentNumberInput — "주민등록번호", 두 칸의 이름, 검증 문구 (1.0 이후 추가, 선택 키) */
  residentNumber?: string;
  residentNumberFront?: string;
  residentNumberBack?: string;
  /** 앞 7자리만 받을 때 뒷칸 이름 — "뒷자리 첫 숫자" */
  residentNumberBackFirst?: string;
  residentNumberInvalid?: string;
  residentNumberIncomplete?: (digits: number) => string;
  /** PasswordInput — "비밀번호", 보기 버튼 "비밀번호 보기" (1.0 이후 추가, 선택 키) */
  password?: string;
  showPassword?: string;
  /** SearchInput — 레이블이 없을 때 이름 "검색", 지우기 버튼 "검색어 지우기" (1.0 이후 추가, 선택 키) */
  search?: string;
  clearSearch?: string;
  /** Tag 삭제 버튼 "사과 삭제", TagGroup 삭제 알림 "사과 삭제됨" (1.0 이후 추가, 선택 키). 글자가 문자열이 아니면 label 은 '' */
  removeTag?: (label: string) => string;
  tagRemoved?: (label: string) => string;
  /** MultiCombobox — 칩 목록 이름 "고른 항목", 다 골랐을 때 "최대 3개까지 고를 수 있어요" (1.0 이후 추가, 선택 키) */
  selectedOptions?: string;
  maxSelected?: (max: number) => string;
  /** CardNumberInput — "카드번호" 와 검증 문구 (1.0 이후 추가, 선택 키) */
  cardNumber?: string;
  cardNumberInvalid?: string;
  cardNumberIncomplete?: string;
  /** CorporateNumberInput — "법인등록번호" 와 검증 문구 (1.0 이후 추가, 선택 키) */
  corporateNumber?: string;
  corporateNumberInvalid?: string;
  corporateNumberIncomplete?: string;
  /** AccountNumberInput — "계좌번호", 10자리보다 짧을 때 문구 (1.0 이후 추가, 선택 키) */
  accountNumber?: string;
  accountNumberIncomplete?: string;
  /** AmountInput — "금액", "원" */
  amount: string;
  currencyUnit: string;
  /** AddressInput */
  address: string;
  addressSearch: string;
  addressSearchDescription: string;
  postalCode: string;
  baseAddress: string;
  baseAddressPlaceholder: string;
  detailAddress: string;
  detailAddressPlaceholder: string;
  addressLoading: string;
  addressLoadError: string;
  /** Calendar */
  previousMonth: string;
  nextMonth: string;
  /** 달 제목 — month 는 1~12 */
  monthTitle: (year: number, month: number) => string;
  /** 요일 머리글 (일요일부터 7개) */
  weekdaysShort: readonly string[];
  /** 요일 전체 이름 (일요일부터 7개) */
  weekdaysLong: readonly string[];
  /** 날짜 버튼 이름 — 화면에 보이는 날짜 숫자로 시작해야 한다 (WCAG 2.5.3) */
  dayLabel: (date: Date, weekdayLong: string) => string;
  holiday: string;
  today: string;
  /** DatePicker */
  date: string;
  openCalendar: string;
  calendar: string;
  dateInvalid: string;
  dateUnavailable: string;
  dateIncomplete: string;
}

export type Messages = Partial<BestowMessages>;

export interface LocaleProviderProps {
  /** 바꿀 문구. 일부만 넘기면 나머지는 바깥 LocaleProvider 또는 한국어 기본값을 쓴다 */
  messages: Messages;
  children?: ReactNode;
}
```