# 킨텍스 디자인 시스템 — Nifty × kx 토큰 (학습 문서)

> **목적:** 소유자 확정(2026-07-12) — 킨텍스 공통 UI의 디자인 기준 = **Nifty(themeon, Bootstrap 5 기반 관리자 테마)**. 이 문서는 Nifty 컴포넌트 패턴을 킨텍스 **kx 디자인 토큰**으로 번역하는 단일 규칙서다. 모든 UI 작업(에이전트·수동)은 착수 전 이 문서를 읽고 준수한다.
> 레퍼런스 인덱스: `docs/analysis/nifty-design-refs.md`. 토큰 정본: `src/frontend/src/styles/tokens.css`.

---

## 0. 대원칙 (불변)
1. **kx 토큰으로만 번역** — Nifty/Bootstrap의 hex·px를 그대로 쓰지 말고 아래 토큰에 매핑. 하드코딩 hex 금지.
2. **다크/라이트 양 테마** — 색은 `--color-*`(테마 remap) 사용. `--dk-*` 직접 참조 금지.
3. **이모지 금지** — 아이콘은 선(stroke) SVG(`components/ui/icons.tsx`)만.
4. **WISE 우선** — 셸·시스템관리·공통기능·캘린더는 WISE(UIWS) 구조가 정본. Nifty는 WISE에 없는 **공통 컴포넌트 스타일**(테이블·카드·버튼·드롭다운·리스트그룹·모달·뱃지·알럿·탭)의 레퍼런스.
5. **접근성** — focus-visible 링(`--focus-ring`)·role/aria·WCAG AA·`prefers-reduced-motion`.

## 1. 토큰 매핑표 (Nifty/Bootstrap → kx)

### 색상 (Bootstrap contextual → kx)
| Nifty/BS | 의미 | kx 토큰 |
|---|---|---|
| primary | 주 액션 | `--color-primary-600`(#0066b3) / hover `--color-primary-700`(#004c86) |
| success | 성공·승인 | `--color-success`(#0e8a5f) / bg `--color-success-bg` |
| warning | 경고·임박 | `--color-warning`(#b45309) / bg `--color-warning-bg` |
| danger  | 위험·오류 | `--color-error`(#d92d20) / bg `--color-error-bg` |
| info    | 보조 정보 | `--color-primary-050/100` + `--color-primary-700` 텍스트 |
| default/light | 중립 | `--color-neutral-100` bg / `--color-neutral-700` 텍스트 / `--border-card` |
| dark    | 강조 텍스트 | `--color-neutral-900`(#101828) |
| (AI 전용) | AI 기능 | `--color-ai-accent`(#6d4aff) / surface `--color-ai-surface` |

### 타이포 (Nifty 위계 → kx `--fs-*`)
| 용도 | kx 토큰 |
|---|---|
| 페이지 타이틀(h1) | `--fs-h1` 24/32 |
| 섹션(h2) | `--fs-h2` 20/28 |
| 카드 제목(h3) | `--fs-h3` 16/24 |
| 본문 | `--fs-body` 14/22 |
| 캡션·헤더셀·메타 | `--fs-caption` 12/18 |
| 숫자열 | `--fs-body` + `font-variant-numeric: tabular-nums`(`.tnum`) |
| 코드/모노 | `--fs-mono` 13 / `--font-mono` |

### 간격·모양
| Nifty | kx |
|---|---|
| 컴포넌트 내부 패딩 | `--space-2`(8) ~ `--space-4`(16) |
| 카드 패딩 | `--space-4`(16) ~ `--space-5`(24) |
| 요소 간 gap | `--space-1~3` |
| 섹션 간 | `--space-5`(24, 상한 `--space-6` 32) |
| 버튼·인풋 radius | `--radius-sm`(4) |
| 카드·패널 radius | `--radius-lg`(8) |
| 배지·필·토글 | `--radius-pill` |

## 2. 컴포넌트 규격 (Nifty 패턴 → kx 구현)

### 2.1 버튼 (`Button` / `.kx-btn`)
- **변형**: primary(채움) · secondary(아웃라인) · ghost(투명) · danger. Nifty의 8색 전부를 만들지 말고 **의미 단위**(주/보조/위험/AI)로 수렴.
- **크기**: `sm`(높이 28·`--fs-caption`) · `md`(기본 36·`--fs-body`) · `lg`(44). Nifty xs~lg를 3단으로.
- **상태**: hover(명도 1단계)·active·disabled(opacity .5·cursor not-allowed)·loading(스피너). focus-visible 링 필수.
- **아이콘**: leadingIcon(선 SVG)·icon-only(정사각·aria-label). 버튼 그룹은 인접 radius 접합.
- **블록**: `block`=100% 폭.

### 2.2 카드 (`.kx-card`)
- 구조: `kx-card`(테두리 `--border-card`·radius-lg·bg `--color-white`) > `kx-card__head`(제목 h3·우측 액션) · body · `kx-card__foot`(선택).
- Nifty 변형: **컬러 좌측 액센트 바**(상태 카드), **KPI 타일**(수치 강조 `--fs-display`), **미디어 카드**(포스터). 그림자는 과하지 않게(hover만 약한 elevation).

### 2.3 테이블 (`.kx-table` — Nifty "Advanced table headers")
- thead th: bg `--color-neutral-050`·`--fs-caption`·중간색(`--color-neutral-500`)·좌정렬·`border-bottom: 2px --color-neutral-200`·sticky top.
- tbody td: `--fs-body`·`--color-neutral-700`·패딩 10px 12px·`border-bottom 1px`.
- zebra(`--zebra`)·행 hover(`--color-primary-050`)·선택행(`--color-primary-100`)·숫자열 `.kx-num` 우정렬 tnum.
- 인터랙티브(정렬·필터·페이지·CSV)는 **Tabulator**로 별도(§3).

### 2.4 드롭다운 / 셀렉트
- 트리거(버튼) + 메뉴(카드형·radius-sm·그림자 약)·항목 hover(`--color-primary-050`)·구분선·아이콘·위험 항목(danger 색). 키보드(↑↓·Esc·Enter)·aria-expanded.

### 2.5 리스트 그룹 (`.kx-list-group`)
- 목록형(공지·활동·검색결과): 행 = 아이콘/점 + 제목 + 메타 + 우측 배지/시간. hover·active·구분선. 링크형은 전체 행 클릭.

### 2.6 뱃지·필·알럿·탭·프로그레스·페이지네이션·모달·툴팁·offcanvas
- **뱃지/필**: `--radius-pill`·`--fs-caption`·상태색 bg+text(위 색표).
- **알럿**: 상태색 배경(연)+좌측 액센트+아이콘+닫기. info/success/warn/danger.
- **탭/세그**: `.kx-seg`(현존) — 활성 밑줄 또는 채움. role=tablist.
- **모달/메시지박스**: 백드롭(반투명)+카드(radius-lg)+헤더/바디/푸터(액션 버튼 우측). 확인/경고 메시지박스는 아이콘+제목+본문+2버튼. focus trap·Esc.
- **offcanvas**: 우/좌 슬라이드 패널(모바일 드로어·상세 슬라이드). 백드롭·Esc·트랜지션(reduced-motion 존중).
- **프로그레스/페이지네이션**: 상태색·`--radius-pill`(bar)·현재 페이지 강조.

## 3. Tabulator (인터랙티브 데이터 그리드)
- 도입 시: 테마 CSS를 kx 토큰으로 오버라이드(헤더=§2.3 스타일 정합)·다크 대응·한글 로케일·CSV export. 관리자/대용량 목록에 파일럿 후 확산. 정적 표는 `.kx-table` 유지.

## 4. 적용 절차 (에이전트 지침)
1. 이 문서 + `nifty-design-refs.md` 읽기 → 대상 요소의 Nifty 패턴 파악.
2. 해당 URL을 WebFetch로 확인(구조·변형·상태) → §1 토큰으로 번역.
3. 공통 컴포넌트(`components/ui/*`·`shared.css`)에 표준 확립 → 화면별 산재 스타일 수렴(중복 제거).
4. 검증: `tsc -b --force`·`vite build` EXIT 0 + 다크/라이트 스팟 + 헤드리스 렌더 대조.

## 변경 이력
| 일자 | 내용 |
|---|---|
| 2026-07-12 | 최초 작성 — Nifty(BS5) → kx 토큰 매핑·컴포넌트 규격·적용 절차. 소유자 "Nifty 스타일 학습" 지시 |