# BestOW UI

> 한국 서비스를 만들 때 바로 쓰는, 접근성이 검증된 React 디자인 시스템(npm `@bestow-ui/react`). 대표색 하나로 라이트·다크 브랜드 테마를 만들고
> (글자 대비 4.5:1 보장), 약관 동의·인증번호·전화번호·사업자등록번호·주민등록번호·금액·주소·날짜 입력 같은 한국 서비스 부품을 기본으로 제공한다.
> 모든 스토리를 라이트·다크에서 axe 로 검사하고, 주요 컴포넌트는 스크린리더(VoiceOver·NVDA)로 수동 점검했으며, KWCAG 2.2 항목별 대응 근거를 문서로 둔다. 문서는 한국어.

- 설치: `npm install @bestow-ui/react` → 앱 진입점에서 `import '@bestow-ui/react/styles.css'`, 스타일은 CSS 레이어 `bestow` 안이라 레이어 밖 CSS(className)가 항상 이긴다 — 리셋 CSS 는 `@layer base` 에, Tailwind v4 는 `@layer theme, base, bestow, components, utilities;` 를 전역 CSS 맨 위에(v3 는 preflight 끄기). shadcn/ui 프로젝트에 섞어 쓸 때는 `createTheme({ common: { color: { primary: { solid: 'var(--primary)', contrast: 'var(--primary-foreground)' }, bg: { default: 'var(--background)' }, fg: { default: 'var(--foreground)' } }, font: { family: { sans: 'var(--font-sans)' } } } })` 를 ThemeProvider `overrides` 로(portal 까지 적용, `.dark` 를 따라감) — 입력 칸 테두리(`--input`)·포커스(`--ring`)·보조 글자(`--muted-foreground`)는 대비가 모자라 BestOW 값을 둔다. 예제 `examples/shadcn-starter`. 가입·본인 확인·정산 정보·로그인 Next.js 템플릿: `npx create-next-app@latest my-app --example "https://github.com/Dev-BestOW/BestOW-UI/tree/main/examples/next-starter"`(react-hook-form + zod, 스키마를 클라이언트·서버 액션이 함께 씀, 단계마다 폼 하나). 최상위를 `<ThemeProvider theme="light">` 로 감싼다(OS 설정을 따르려면 `theme="system"` — 서버 렌더링도 CSS 미디어쿼리로 그려 깜빡임 없음).
- React 18·19, Next.js App Router(서버 컴포넌트) 지원. 스타일은 vanilla-extract 로 빌드된 CSS 파일 하나(런타임 CSS 0). 오버레이는 Radix UI 기반.
- 한국 서비스 서식·검증 함수만 필요하면(React 없이도) `@bestow-ui/korean-utils`.

## 문서

- [전체 문서 (LLM 용, 한 파일)](https://bestow-ui.com/llms-full.txt): README + 모든 컴포넌트의 props 정의(소스 그대로) + 언제 무엇을 쓰나 + 키보드·스크린리더 동작
- [@bestow-ui/react README](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/README.md): 설치, Next.js 설정, 다크 모드, 브랜드 테마, 문구 바꾸기, 컴포넌트 목록
- [@bestow-ui/korean-utils README](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/korean-utils/README.md): 전화번호·사업자등록번호·주민등록번호·금액 한글 읽기·한국어 날짜·마스킹(이름·전화·주민번호·카드) 함수
- [@bestow-ui/korean-utils 함수별 문서](https://bestow-ui.com/korean-utils/): 함수마다 푸는 문제·코드 예시·알아 둘 점·같은 동작의 React 입력 컴포넌트, 은행 코드 목록
- [저장소 README](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/README.md): Next.js App Router 에서 5분 만에 시작하기, 다른 라이브러리와 비교

## 예제

- [AI 코딩 도구 규칙 파일](https://bestow-ui.com/ai/bestow-ui.md): 프로젝트에 넣어 두는 짧은 사용 규칙(한국 입력 컴포넌트·값 형태·폼·서버 컴포넌트·테마). Cursor 용은 같은 내용의 `ai/bestow-ui.mdc`

- [Vite 시작 예제](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/examples/vite-starter/src/App.tsx): 전화번호·인증번호·금액·약관 동의 폼, 다크 모드, 대표색 테마
- [react-hook-form 회원가입](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/apps/playground/app/signup/page.tsx): register·Controller·ErrorSummary
- [주문 관리 화면](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/apps/playground/app/orders/page.tsx): Table·검색·필터·기간 선택·선택 처리

## Optional

- [지원 범위·버전 정책](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/SUPPORT.md)
- [변경 내역](https://raw.githubusercontent.com/Dev-BestOW/BestOW-UI/main/packages/react/CHANGELOG.md)
- [홈페이지 (사람용 소개·데모)](https://bestow-ui.com/)
- [Storybook (사람용 문서, JS 필요)](https://bestow-ui.com/storybook/)