# doksam-ui

> doksam 프로젝트 공통 UI 표준 사이트. shadcn/ui 기반 디자인 토큰 + 전 컴포넌트 쇼케이스를 한곳에 모은 레퍼런스이며, 이 카탈로그의 항목은 self-host shadcn 커스텀 레지스트리로 직접 설치할 수 있습니다.

AI 에이전트/사람 모두를 위한 발견용 문서입니다. 아래 각 항목은 `npx shadcn add https://ui.dev.doksam.com/r/<name>.json` 명령으로 즉시 설치됩니다 — components.json이 없는 새 프로젝트라면 `npx shadcn@latest init`을 먼저 실행하세요.

전체 사용 규칙(코딩 컨벤션·시맨틱 토큰·접근성 규칙)은 [https://ui.dev.doksam.com/rules](https://ui.dev.doksam.com/rules) 를 참고하세요 — AI 프롬프트에 그대로 붙여넣을 수 있는 markdown 원문을 제공합니다.

## 컴포넌트

### Badge Extended (`badge-extended`)

shadcn Badge를 확장해 success/warning/danger 시맨틱 상태 variant를 추가한 컴포넌트. badge.tsx 원본은 건드리지 않고 badgeVariants만 재사용한다.

```
npx shadcn add https://ui.dev.doksam.com/r/badge-extended.json
```

registryDependencies: badge

npm dependencies: class-variance-authority

### Copy Button (`copy-button`)

navigator.clipboard로 텍스트를 복사하고 잠깐 "복사됨" 피드백을 보여주는 버튼.

```
npx shadcn add https://ui.dev.doksam.com/r/copy-button.json
```

registryDependencies: button

npm dependencies: @phosphor-icons/react

### Tooltip Icon Button (`tooltip-icon-button`)

아이콘 전용 버튼 — Tooltip 래핑과 aria-label을 tip 하나로 강제해서 접근성 실수를 구조적으로 막는다. app/layout.tsx 최상단에 TooltipProvider가 이미 있어야 한다.

```
npx shadcn add https://ui.dev.doksam.com/r/tooltip-icon-button.json
```

registryDependencies: button, tooltip

### Table Sortable (`table-sortable`)

고정 헤더 + 스크롤 바디를 가진 제네릭 데이터 그리드. 컬럼 헤더 클릭 정렬(@tanstack/react-table), 행 드래그 순서 변경(@dnd-kit), 컬럼 표시/숨김 토글을 지원한다.

```
npx shadcn add https://ui.dev.doksam.com/r/table-sortable.json
```

registryDependencies: button, dropdown-menu, table

npm dependencies: @tanstack/react-table, @dnd-kit/core, @dnd-kit/sortable, @dnd-kit/utilities, @phosphor-icons/react

### Screen Help Dialog (`screen-help-dialog`)

화면 제목 옆 (?) 버튼을 누르면 뜨는 화면 매뉴얼 다이얼로그. shadcn Dialog + Button(asChild) 조합 커스텀 패턴.

```
npx shadcn add https://ui.dev.doksam.com/r/screen-help-dialog.json
```

registryDependencies: button, dialog

npm dependencies: @phosphor-icons/react

### JSON Tree (`json-tree`)

재귀 JSON 트리 뷰어 — 접기/펼치기, 타입별 색(chart-1~3 시맨틱 토큰), 대용량 배열은 20개씩 "더 보기"로 분할 렌더링한다. 관측성(observability) 패턴 코어.

```
npx shadcn add https://ui.dev.doksam.com/r/json-tree.json
```

npm dependencies: @phosphor-icons/react

### Log Viewer (`log-viewer`)

레벨별 색+배경(info/debug/warn/error), 반복 카운트 배지, 그룹 들여쓰기를 갖춘 로그 뷰어. 관측성 패턴 코어.

```
npx shadcn add https://ui.dev.doksam.com/r/log-viewer.json
```

### Request Inspector (`request-inspector`)

요청 목록 + 클릭 시 Accordion으로 펼치는 Headers/Query/Payload/Response 상세 인스펙터. 4xx/5xx 상태는 색으로 강조하고 cURL 명령을 바로 복사할 수 있다. 관측성 패턴 코어.

```
npx shadcn add https://ui.dev.doksam.com/r/request-inspector.json
```

registryDependencies: accordion, badge, https://ui.dev.doksam.com/r/copy-button.json

## 라이브러리/유틸

### Finance: Rate (`finance-rate`)

등락률/등락액 표시 유틸. 한국식 시세 관례로 상승은 gain(빨강), 하락은 loss(파랑) 시맨틱 토큰을 사용한다. themes/*.ts에 gain/loss 토큰이 정의돼 있어야 한다.

```
npx shadcn add https://ui.dev.doksam.com/r/finance-rate.json
```

### Finance: Format Won (`finance-format-won`)

원화 금액을 억/조 단위로 축약하는 유틸. 1억 미만은 천단위 콤마, 반올림 경계값(9,999.6억 등)을 조 단위로 안전하게 전환한다.

```
npx shadcn add https://ui.dev.doksam.com/r/finance-format-won.json
```

### Finance: Normalize Color (`finance-normalize-color`)

oklch() 등 CSS 색상값을 hex로 정규화하는 유틸. lightweight-charts 등 CSS를 직접 파싱하지 못하는 캔버스/서드파티 렌더러에 시맨틱 토큰 색을 넘길 때 쓴다. 테마 전환 감지용 observeColorScheme도 포함한다.

```
npx shadcn add https://ui.dev.doksam.com/r/finance-normalize-color.json
```

### Format Biz No (`format-biz-no`)

사업자등록번호를 000-00-00000 형태로 포맷하는 화면 표시 전용 유틸. 저장/전송용 원본 값은 이 함수를 거치지 않는다.

```
npx shadcn add https://ui.dev.doksam.com/r/format-biz-no.json
```

## 프로필(테마+폰트+radius)

### Profile: Admin (`profile-admin`)

내부 관리자 도구·백오피스 화면 프로필. theme=slate(무채색 뉴트럴) + font=Geist + defaultMode=light. 폰트는 자동 설치되지 않는다 — assets/fonts/geist/의 woff2를 복사하고 next/font/local로 layout.tsx에 연결해야 한다(폐쇄망 대응, next/font/google 미사용). 자세한 절차는 https://ui.dev.doksam.com/rules 참고.

```
npx shadcn add https://ui.dev.doksam.com/r/profile-admin.json
```

### Profile: Service (`profile-service`)

대외 서비스·고객 대면 화면 프로필. theme=ocean(신뢰감 있는 블루) + font=Noto Sans KR + defaultMode=light. 폰트는 자동 설치되지 않는다 — assets/fonts/noto-sans-kr/의 woff2를 복사하고 next/font/local로 layout.tsx에 연결해야 한다(폐쇄망 대응). 자세한 절차는 https://ui.dev.doksam.com/rules 참고.

```
npx shadcn add https://ui.dev.doksam.com/r/profile-service.json
```

### Profile: Data (`profile-data`)

데이터 대시보드·시세/뉴스류 화면 프로필. theme=violet(대비 뚜렷한 퍼플) + font=Space Grotesk + defaultMode=dark. 폰트는 자동 설치되지 않는다 — assets/fonts/space-grotesk/의 woff2를 복사하고 next/font/local로 layout.tsx에 연결해야 한다(폐쇄망 대응, 라틴 전용이라 한글은 시스템 폰트로 폴백). 자세한 절차는 https://ui.dev.doksam.com/rules 참고.

```
npx shadcn add https://ui.dev.doksam.com/r/profile-data.json
```

## 블록

### Trading Dashboard 템플릿 (`template-trading`)

data 프로필(Violet 다크·Space Grotesk) 트레이딩 대시보드 풀 템플릿 — 포트폴리오·시세·수급. finance 토큰·dataviz·table-sortable 조합.

```
npx shadcn add https://ui.dev.doksam.com/r/template-trading.json
```

registryDependencies: https://ui.dev.doksam.com/r/table-sortable.json, https://ui.dev.doksam.com/r/finance-rate.json, https://ui.dev.doksam.com/r/finance-format-won.json

npm dependencies: @tanstack/react-table, @dnd-kit/core, @dnd-kit/sortable, @phosphor-icons/react

### Admin/Backoffice Pro 템플릿 (`template-admin`)

admin 프로필(Slate·Geist) 관리자 대시보드 — 사이드바 셸·정렬 테이블·관측성 뷰어·설정 폼.

```
npx shadcn add https://ui.dev.doksam.com/r/template-admin.json
```

registryDependencies: https://ui.dev.doksam.com/r/table-sortable.json, https://ui.dev.doksam.com/r/json-tree.json, https://ui.dev.doksam.com/r/log-viewer.json, https://ui.dev.doksam.com/r/request-inspector.json

npm dependencies: @tanstack/react-table, @dnd-kit/core, @dnd-kit/sortable, @phosphor-icons/react

### SaaS Landing + Dashboard 템플릿 (`template-saas`)

service 프로필(Ocean·Noto Sans KR) 랜딩+대시보드+피드 — 히어로·가격·콘텐츠 피드.

```
npx shadcn add https://ui.dev.doksam.com/r/template-saas.json
```

registryDependencies: https://ui.dev.doksam.com/r/screen-help-dialog.json

npm dependencies: @phosphor-icons/react

### Chat / AI Assistant 템플릿 (`template-chat`)

data 프로필(Violet 다크·Space Grotesk) AI 어시스턴트 대화 템플릿 — 말풍선·메시지 스크롤러·첨부 입력창·설정 폼.

```
npx shadcn add https://ui.dev.doksam.com/r/template-chat.json
```

registryDependencies: https://ui.dev.doksam.com/r/screen-help-dialog.json

npm dependencies: @phosphor-icons/react

### E-commerce Storefront 템플릿 (`template-shop`)

service 프로필(Ocean·Noto Sans KR) 커머스 템플릿 — 스토어프론트·상품상세(캐러셀)·장바구니.

```
npx shadcn add https://ui.dev.doksam.com/r/template-shop.json
```

npm dependencies: @phosphor-icons/react

## 링크

- 전체 컴포넌트 쇼케이스: https://ui.dev.doksam.com/components
- 패턴(관측성/데이터뷰/폼 등 복합 조합): https://ui.dev.doksam.com/patterns
- 브랜드 프로필: https://ui.dev.doksam.com/profiles
- 디자인 토큰: https://ui.dev.doksam.com/tokens
- AI 프롬프트용 사용 규칙: https://ui.dev.doksam.com/rules
- 레지스트리 인덱스(JSON): https://ui.dev.doksam.com/r/registry.json