@conscience-technology/ctds 0.0.0-stage → 0.1.0

package/assets/prompts/components/sidebar.md

@@ -0,0 +1,107 @@
+# Sidebar
+
+### 원칙
+좌측 세로 nav. **라우팅 전용** — Tabs/필터는 쓸 곳이 아님. Brand(home 링크) + Section(그룹 라벨) + Item(라우트 링크) + Profile(사용자) + Footer가 compound 조합. `collapsed`로 icon-only 축소. Item은 [[components/menu-item]]을 그대로 어댑트 — 시각·상태 규칙 공유.
+
+### Do
+- 라우트 이동은 Item에 `asChild` + Next `<Link>`.
+- 현재 라우트는 `active`로 명시 (MenuItem의 active 시각 그대로).
+- Brand는 Home 링크 자리로. `symbol`(항상 노출) + `wordmark`(expanded만).
+- Section 묶음은 `title`로 그룹. collapsed일 땐 title 자동 숨김.
+- `collapsed` 상태에서는 `aria-label`과 `title`을 자동으로 걸어 접근성 유지.
+
+### Don't
+- 페이지 안 뷰 전환에 쓰지 않는다 — 그건 [[components/tabs]].
+- Item 안에 variant로 다른 톤을 쓰지 않는다. active 외의 강조 금지.
+- Sidebar 자체에 padding/width를 CSS로 덮지 않는다. `--sidebar-w*` 토큰 경유.
+- Brand symbol·wordmark 크기 override 금지. `--sidebar-brand-symbol-max`·`--sidebar-brand-wordmark-max` 상한 안에서만.
+
+### Fallback
+collapsed 결정 애매하면 `false`. Section title 애매하면 생략.
+
+### 관련
+- [[components/menu-item]] — Item 시각·상태 전부 재사용
+- [[components/avatar]] — Profile 왼쪽 아바타
+- [[components/app-frame]] — Sidebar를 담는 grid 쉘
+- [[axes/density]] — `--sidebar-w*` 토큰·control-h가 Density에 반응
+- [[tokens/color]] — `--fg`·`--primary`·active 상태 매핑
+
+### Props 시그니처
+```tsx
+<Sidebar collapsed={boolean}>                 // default: false
+  <Sidebar.Header>
+    <Sidebar.Brand symbol={<Icon />} wordmark={<Logo /> | "CTDS"} />
+  </Sidebar.Header>
+
+  <Sidebar.Section title="워크스페이스">
+    <Sidebar.Item
+      icon={<Icon name="house" />}
+      label="대시보드"
+      active={boolean}
+      trailing={ReactNode}                    // 배지·카운트
+      shortcut="⌘1"
+      hasSubmenu={boolean}
+      disabled={boolean}
+      asChild={boolean}
+      onClick={(e) => void}
+    />
+  </Sidebar.Section>
+
+  <Sidebar.Separator />
+
+  <Sidebar.Footer>
+    <Sidebar.Profile
+      name="희영"
+      sub="admin@ctds.dev"
+      avatar={{ src, status }}                // Avatar props 패스스루
+      trailing={<IconButton />}
+    />
+  </Sidebar.Footer>
+</Sidebar>
+```
+
+### 상태 매트릭스
+| 상태 | 시각 |
+|---|---|
+| expanded (기본) | 폭 `--sidebar-w`, 모든 자식 라벨·wordmark·trailing 노출 |
+| collapsed | 폭 `--sidebar-w-collapsed`, Item은 icon-only, wordmark·Section title·Profile 텍스트·trailing 숨김 |
+| Item active | MenuItem active 그대로 — `--bg-muted` 배경 + `fg-strong` + medium weight |
+
+### 조합 예시
+```tsx
+// 기본 — 섹션 2개 + Profile
+<Sidebar>
+  <Sidebar.Header>
+    <Sidebar.Brand symbol={<Icon name="rocket-launch" />} wordmark="CTDS" />
+  </Sidebar.Header>
+
+  <Sidebar.Section title="워크스페이스">
+    <Sidebar.Item asChild icon={<Icon name="house" />} label="대시보드" active>
+      <Link href="/">대시보드</Link>
+    </Sidebar.Item>
+    <Sidebar.Item asChild icon={<Icon name="chart-line" />} label="분석">
+      <Link href="/analytics">분석</Link>
+    </Sidebar.Item>
+  </Sidebar.Section>
+
+  <Sidebar.Separator />
+
+  <Sidebar.Section title="설정">
+    <Sidebar.Item icon={<Icon name="gear" />} label="환경설정" shortcut="⌘," />
+  </Sidebar.Section>
+
+  <Sidebar.Footer>
+    <Sidebar.Profile name="희영" sub="admin@ctds.dev" avatar={{ status: "online" }} />
+  </Sidebar.Footer>
+</Sidebar>
+
+// Collapsed — icon-only
+<Sidebar collapsed>
+  <Sidebar.Header>
+    <Sidebar.Brand symbol={<Icon name="rocket-launch" />} />
+  </Sidebar.Header>
+  <Sidebar.Section>
+    <Sidebar.Item icon={<Icon name="house" />} label="대시보드" active />
+  </Sidebar.Section>
+</Sidebar>
+```

package/assets/prompts/components/slider.md

@@ -0,0 +1,89 @@
+# Slider
+
+### 원칙
+연속·이산 수치를 **드래그로 조정**하는 최소 컨트롤. 트랙 + 채워진 부분 + 썸만 있는 미니멀 스펙 — 값 라벨·마크·range(양끝 두 개)는 이 컴포넌트가 다루지 않는다. 값을 텍스트로 보고 싶으면 옆에 별도 노드로 붙인다.
+
+native `<input type="range">` 위에 스타일만 얹어 접근성(키보드 ← → Home End, 드래그, 스크린리더)을 그대로 상속.
+
+### Do
+- **연속·근사 조정에만 씀** — 볼륨, 밝기, 오프셋, 확대율처럼 "대략 이 정도" 조작이 자연스러운 값.
+- **정확한 값 입력이 필요하면 [[components/input]]** (`type="number"`). 슬라이더는 근사, 입력은 정확 — 병행해도 좋다.
+- **현재 값을 어딘가엔 표시**. 슬라이더 오른쪽에 `<span>{value}px</span>` 같은 라벨을 붙여 지금 값이 얼마인지 읽히게.
+- **step은 의미 있는 최소 단위**. px 조정이면 1, 확대율이면 0.1, 볼륨이면 5 같은 식.
+
+### Don't
+- **불연속 3~5개 옵션 선택에 쓰지 않는다** — 그건 [[components/tabs]] `segmented` 또는 [[components/filter-button]].
+- **On/Off 두 값만 있는 자리에 쓰지 않는다** — [[components/switch]].
+- **range slider(양 끝 두 개)로 확장하지 않는다** — 이 컴포넌트는 단일 값만. 범위 선택은 별도 컴포넌트로.
+- 썸 크기·트랙 두께를 CSS로 덮어쓰지 않는다 — Density 축 (`--control-h-*`, `--space-*`)이 결정.
+
+### Fallback
+size 애매하면 `md`, step 애매하면 `1`.
+
+### 관련
+- [[axes/density]] — `--control-h-*`가 썸 크기·트랙 높이에 매핑
+- [[axes/shape]] — 트랙·썸 radius (`--radius-full` 고정, Shape 축 영향 없음)
+- [[axes/motion]] — hover·drag 상태 전환 duration
+- [[axes/palette]] — 채워진 트랙이 `--primary`
+- [[tokens/color]] — `--primary` (채운 부분), `--bg-muted` (트랙 배경), `--border-strong` (썸 경계)
+- [[components/input]] — 정확한 수치 입력 병행
+
+### Props 시그니처
+```tsx
+<Slider
+  size="sm | md | lg"          // default: md
+  min={number}                 // default: 0
+  max={number}                 // default: 100
+  step={number}                // default: 1
+  value={number}               // controlled
+  defaultValue={number}        // uncontrolled 초기값
+  onValueChange={(n) => void}  // 편의 콜백 (숫자로 바로 옴)
+  disabled
+  aria-label="…"               // 시각 라벨 없으면 필수
+/>
+```
+
+### 상태 매트릭스
+| 상태 | 트랙 | 썸 |
+|---|---|---|
+| default | `--bg-muted` 배경 + `--primary` fill | `--bg` + `--border-strong` 경계 + `shadow-xs` |
+| hover | 동일 | 경계 `--primary` |
+| focus-visible | 동일 | `--ring-shadow` + `--primary` 경계 |
+| active (드래그) | 동일 | scale 1.05, cursor grabbing |
+| disabled | opacity 0.5 | opacity 0.5, cursor not-allowed |
+
+### Size 가이드
+| size | 썸 (control-h) | 트랙 두께 | 언제 |
+|---|---|---|---|
+| `sm` | control-h-sm | space-0_5 | 툴바 · 인스펙터 · 조밀한 컨트롤 그룹 |
+| `md` | control-h-md | space-1 | **기본.** 폼 · 설정 페이지 |
+| `lg` | control-h-lg | space-1_5 | 터치 · 랜딩 · 큰 값 조정(볼륨·밝기 등) |
+
+### 접근성
+- 실제 `<input type="range">`라서 키보드 ← → (step), PageUp/PageDown (10*step), Home/End 가 자동 동작.
+- 스크린리더가 min·max·현재 값을 읽음.
+- 시각 라벨이 없으면 `aria-label` 필수. 옆에 값을 표시하는 노드가 있다면 `aria-describedby`로 연결하면 더 좋음.
+
+### 조합 예시
+```tsx
+// 툴바 안 오프셋 조정 — 값 라벨을 옆에 붙여 현재 값을 노출
+<div className="row">
+  <Slider
+    size="sm"
+    min={-40}
+    max={40}
+    step={1}
+    value={offset}
+    onValueChange={setOffset}
+    aria-label="Arrow offset"
+  />
+  <span className="value">{offset}px</span>
+</div>
+
+// 폼 안 볼륨 조정 — Input과 병행
+<label>
+  볼륨
+  <Slider min={0} max={100} step={5} value={vol} onValueChange={setVol} />
+  <Input type="number" min={0} max={100} value={vol} onChange={(e) => setVol(Number(e.target.value))} />
+</label>
+```

package/assets/prompts/components/split-button.md

@@ -0,0 +1,71 @@
+# SplitButton
+
+### 원칙
+시각적으로 하나로 붙어있지만 클릭 영역이 두 개로 분리된 버튼 — `main`(기본 액션) + `menu`(부가 옵션 드롭다운). 사용자에게 "이 액션의 가장 흔한 형태 + 대안" 관계를 한 컨트롤로 압축한다. 예: [저장 | ▾] → 저장 / 다른 이름으로 저장 / 사본 저장.
+
+### Do
+- **main은 예측 가능한 기본값** — 90% 사용자가 원할 액션. menu는 그 외 변형.
+- `menuLabel` prop은 필수. 스크린리더가 caret 영역을 식별해야 함 ("옵션 더보기", "저장 옵션" 등).
+- variant는 [[components/button]]과 동일 규칙 — 한 화면에 `primary` 1개.
+- menu 열림 상태는 부모가 관리하고 `aria-expanded`는 caret button에 얹는다 (필요 시 `...rest`로 전달할 수 있게 컴포넌트 확장).
+
+### Don't
+- 두 액션이 **의미상 무관**하면 SplitButton 아님 → 그냥 Button 2개.
+- menu에 3개 이상 항목이 들어가면 검토. 너무 많으면 그냥 [[components/menu]] 트리거 Button 하나로.
+- 구분선 색·굵기 CSS로 덮어쓰지 않는다. currentColor × 알파로 variant 톤 자동 반응.
+- `ghost` / `destructive`는 지원하지 않는다. Ghost는 무게가 최소인데 옆에 caret이 붙는 순간 시각 위계가 튀고, destructive는 부가 옵션까지 감싸기엔 위험 신호가 과함. 삭제 계열은 [[components/button]] `destructive` / `destructive-ghost` 단독으로.
+
+### Fallback
+variant 애매하면 `secondary`, size 애매하면 `md`.
+
+### 관련
+- [[components/button]] — variant/size 규칙 공유
+- [[components/menu]] — menu 클릭 시 열리는 드롭다운
+- [[axes/density]] — `--control-h-*`가 두 영역 높이·정사각 폭에 매핑
+- [[axes/shape]] — root radius가 Shape 축에 반응
+
+### Props 시그니처
+```tsx
+<SplitButton
+  size="sm | md | lg"                            // default: md
+  variant="primary | inverse | secondary | outline"  // default: primary
+  leftIcon={ReactNode}                            // main 라벨 앞
+  menuIcon={ReactNode}                            // 기본 caret-down 대체
+  onMainClick={handler}
+  onMenuClick={openMenu}
+  menuLabel="옵션 더보기"                          // 필수, 접근성용
+  fullWidth loading disabled
+>
+  저장
+</SplitButton>
+```
+
+### 구조·동작
+- 내부적으로 `<button>` 2개 + 사이 `<span>` divider
+- 각 영역이 독립 `:hover` — main hover 시 menu는 그대로, 반대도 동일
+- Divider는 상하 여백(`--space-1_5`) 두고 세로 hairline, 색은 variant fg의 25% 알파
+- 포커스링은 각 button별로. 링이 옆 영역 위로 올라오게 z-index 처리
+
+### 조합 예시
+```tsx
+// 저장 + 다른 형식으로 저장 (드롭다운)
+<SplitButton
+  variant="primary"
+  leftIcon={<Icon name="check" />}
+  onMainClick={save}
+  onMenuClick={() => setMenuOpen(true)}
+  menuLabel="저장 옵션"
+>
+  저장
+</SplitButton>
+
+// 필터 적용 + 필터 편집
+<SplitButton
+  variant="outline"
+  onMainClick={applyLastFilter}
+  onMenuClick={openFilterMenu}
+  menuLabel="필터 편집"
+>
+  최근 필터
+</SplitButton>
+```

package/assets/prompts/components/stepper.md

@@ -0,0 +1,93 @@
+# Stepper
+
+### 원칙
+다단계 프로세스의 진행 위치를 시각적으로 보여주는 컴포넌트. 각 스텝은 `upcoming | active | done` 세 상태를 가지며, 상태 대비로 사용자가 "지금 어디에 있고 얼마나 남았는지"를 즉시 파악하게 한다. Rail·툴바 같은 껍데기(브랜드 슬롯·푸터)는 이 컴포넌트가 담지 않는다 — Stepper는 **스텝 리스트만** 담당.
+
+### Do
+- **기본은 `orientation="vertical"`**. 온보딩·설정·긴 폼처럼 화면 좌측 사이드에 붙는 표준 케이스.
+- **좁은 헤더·상단 배너에는 `orientation="horizontal"`**. 세로 공간이 부족하고 스텝 개수가 3~5개일 때.
+- **스텝이 6개를 넘으면 hint를 지운다** — title만 남기고 밀도를 확보.
+- **활성 스텝은 한 번에 하나**. `activeIndex`로만 제어. 자식 Item에 `state`를 직접 넣는 건 예외 케이스(비선형 진행)에서만.
+- **미도달 스텝 클릭은 막는다** — 상위에서 `disabled` prop 또는 `onStepClick`에서 조건 처리. 스텝 스킵을 허용하면 진행률의 의미가 무너진다.
+- **marker는 `dot` 기본**. `number`는 순서가 정보 그 자체일 때만 (예: "3단계 결제 프로세스"처럼 숫자가 사용자 언어에 이미 있는 경우).
+- **색은 로컬 CSS 변수로 오버라이드**. 특수 팔레트(온보딩 다크 rail 등)에서는 `--stepper-fg` · `--stepper-fg-muted` · `--stepper-fg-subtle` · `--stepper-line` · `--stepper-dot-idle` · `--stepper-marker-fg`를 부모에서 재정의.
+
+### Don't
+- Stepper 안에 브랜드 로고·푸터·CTA 버튼을 넣지 않는다 — 상위 shell(Rail)의 책임.
+- marker 안에 이모지·아바타·커스텀 배지 삽입 금지. dot / number / check만 허용.
+- 활성 스텝을 진하게, 미도달을 진하게 동시에 강조하지 않는다. 위계는 하나(active만 `--stepper-fg`).
+- 스텝 사이 dashed line을 solid로 바꾸지 않는다 — dashed는 "진행 여지"의 시각 신호.
+- Motion 축과 무관하게 marker에 커스텀 애니메이션(bounce, spin 등) 붙이지 않는다. 상태 전환은 `--transition-colors`로 통일.
+- `data-state="active"` 위에 hover가 border/bg를 덮어쓰지 않는다. [[feedback/hover-over-active]] 원칙.
+
+### Fallback
+orientation 애매하면 `vertical`, marker 애매하면 `dot`. 스텝 6개 초과에 orientation·marker 판단 안 서면 사용자에게 확인.
+
+### 관련
+- [[components/progress-bar]] — 연속형 진행률. 스텝이 discrete 하지 않으면 이쪽.
+- [[components/tabs]] — 순서·진행 개념 없이 병렬 전환이면 Tabs.
+- [[axes/density]] — `--space-scale`이 스텝 간격 · marker 크기에 반영
+- [[axes/motion]] — 상태 전환 duration/easing
+- [[tokens/color]] — `--fg` · `--fg-muted` · `--fg-subtle` · `--border` 매핑
+- [[tokens/spacing]] — `--space-5`(marker), `--space-6`(item-gap) 참고
+
+### Props 시그니처
+```tsx
+<Stepper
+  activeIndex={number}
+  orientation="vertical | horizontal"       // default: vertical
+  marker="dot | number"                     // default: dot
+  onStepClick={(index: number) => void}
+>
+  <Stepper.Item title="..." hint="..." disabled={boolean} state="upcoming | active | done" />
+</Stepper>
+```
+
+### Variant 매트릭스
+| orientation | marker | 용도 | 금지 조합 |
+|---|---|---|---|
+| `vertical` | `dot` | **기본.** 온보딩·설정·긴 폼의 좌측 rail | — |
+| `vertical` | `number` | 순서가 사용자 언어에 이미 있는 세로 rail (드묾) | 스텝 6개 초과 시 hint까지 붙이면 답답 |
+| `horizontal` | `dot` | 좁은 헤더·상단 배너, 스텝 3~5개 | 스텝 6개 초과 금지 (dashed line이 짧아짐) |
+| `horizontal` | `number` | 결제·체크아웃 같은 "명시적 순서" 헤더 프로세스 | 스텝 6개 초과 금지 |
+
+### 색 오버라이드 예 (특수 팔레트)
+```css
+/* 예: 온보딩 다크 rail에서 Stepper를 밝은 톤으로 뒤집기 */
+.myDarkRail {
+  --stepper-fg: var(--onb-rail-fg);
+  --stepper-fg-muted: var(--onb-rail-fg-muted);
+  --stepper-fg-subtle: var(--onb-rail-fg-subtle);
+  --stepper-line: var(--onb-rail-line);
+  --stepper-dot-idle: var(--onb-rail-dot-idle);
+  --stepper-marker-fg: var(--onb-rail);
+}
+```
+
+### 조합 예시
+```tsx
+// 온보딩 세로 rail — 기본 dot
+<Stepper
+  activeIndex={stepIdx}
+  onStepClick={(i) => {
+    if (i <= stepIdx || isReachable(i)) setStepIdx(i);
+  }}
+>
+  {STEPS.map((s, i) => (
+    <Stepper.Item
+      key={s.key}
+      title={s.title}
+      hint={s.hint}
+      disabled={i > stepIdx && !isReachable(i)}
+    />
+  ))}
+</Stepper>
+
+// 체크아웃 상단 헤더 — horizontal + number
+<Stepper activeIndex={1} orientation="horizontal" marker="number">
+  <Stepper.Item title="장바구니" />
+  <Stepper.Item title="배송 정보" />
+  <Stepper.Item title="결제" />
+  <Stepper.Item title="완료" />
+</Stepper>
+```

package/assets/prompts/components/switch.md

@@ -0,0 +1,86 @@
+# Switch
+
+### 원칙
+**즉시 적용되는 on/off** 컨트롤. 토글하는 순간 상태가 변한다 — 저장 버튼이 따로 없는 자리에 쓴다.
+시맨틱은 `role="switch"`가 붙은 native checkbox. 시각은 알약 트랙 + 원형 썸 — 켜지면 트랙이 `--primary`로 채워지고 썸이 우측으로 이동.
+
+### Do
+- **즉시 반영에만**: 다크모드, 알림 on/off, 자동 저장, 필터 옵션. 토글 → 부작용까지 즉시.
+- **"선택 여부"가 아니라 "상태 전환"에만**: 폼 제출 후 반영되는 옵션은 [[components/checkbox]].
+- **라벨은 별도 컴포넌트로**: Switch 자체는 컨트롤만. 라벨은 `<label>` wrap이나 옆 텍스트 노드로 배치. 컴팩트한 툴바에서는 라벨을 아예 생략(그룹 자체가 라벨 역할)해도 됨.
+- **폼 안이면 `name` 필수**: native checkbox 위에 얹은 거라 폼 제출에 자연스럽게 포함됨.
+
+### Don't
+- **다중 선택에 쓰지 않는다** — [[components/checkbox]].
+- **저장이 필요한 자리에 쓰지 않는다** — Switch를 켜자마자 부작용이 없다면 사용자는 "정말 켜졌나?" 헷갈린다.
+- 트랙 색을 status(성공/경고/삭제)로 바꾸지 않는다 — 켜짐은 항상 `--primary`. 상태 표현은 다른 컴포넌트가 담당.
+- 썸·트랙 크기를 CSS로 덮어쓰지 않는다. `size` prop · Density 축이 결정.
+
+### Fallback
+size 애매하면 `md`.
+
+### 관련
+- [[components/checkbox]] — 선택 여부(폼 제출 후 반영)
+- [[components/tabs]] `segmented` — 세 개 이상 배타 옵션
+- [[axes/density]] — `--space-*` 스케일이 트랙·썸 크기에 매핑
+- [[axes/motion]] — 썸 이동 duration
+- [[tokens/color]] — `--primary` (켜짐), `--bg-muted` (꺼짐), `--fg-disabled` (disabled 썸)
+
+### Props 시그니처
+```tsx
+<Switch
+  size="sm | md | lg"                    // default: md
+  checked / defaultChecked                // native input props
+  onCheckedChange={(on) => void}          // 편의 콜백 (boolean 바로 옴)
+  disabled
+  name
+  aria-label="…"                         // 시각 라벨 없으면 필수
+/>
+```
+
+### 상태 매트릭스
+| 상태 | 트랙 | 썸 |
+|---|---|---|
+| off · default | `--bg-muted` + `--border` hairline | `--bg` 원 + `shadow-xs` |
+| off · hover | 경계 `--border-strong` | 동일 |
+| on · default | `--primary` fill, 보더도 `--primary` | 우측 이동 |
+| on · hover | `--primary`를 fg 12% 섞어 살짝 진하게 | 동일 |
+| focus-visible | 트랙에 `--ring-shadow` | 동일 |
+| disabled | `--bg-muted`, 투명 보더 | `--fg-disabled`, shadow none |
+
+### Size 가이드
+| size | 트랙 (w × h) | 언제 |
+|---|---|---|
+| `sm` | space-6 × space-3 | 툴바, 인스펙터, 밀집 폼 |
+| `md` | space-8 × space-4 | **기본.** 설정 페이지, 일반 폼 |
+| `lg` | space-10 × space-5 | 터치, 온보딩, 큰 옵션 그룹 |
+
+### 접근성
+- `role="switch"` + native `input type="checkbox"` → 스크린리더가 "스위치, 켜짐/꺼짐"으로 읽음.
+- 시각 라벨이 없으면 `aria-label` 필수.
+- `<label>` 래퍼가 있어서 트랙·썸 어디 클릭해도 토글.
+- 키보드: Space로 토글, Tab으로 포커스.
+
+### 조합 예시
+```tsx
+// 툴바 안 옵션 토글 — 그룹이 라벨 역할, aria-label로만 시맨틱 라벨
+<div className="toolbar-group">
+  <span>Time</span>
+  <Switch size="sm" checked={withTime} onCheckedChange={setWithTime} aria-label="Time" />
+</div>
+
+// 폼 안 옵션 — 텍스트 라벨과 세트
+<label className="row">
+  <Switch checked={notify} onCheckedChange={setNotify} name="notify" />
+  <span>이메일 알림 받기</span>
+</label>
+
+// 설정 페이지 — 라벨 왼쪽, Switch 오른쪽 (justify-between)
+<div className="setting-row">
+  <div>
+    <div>다크 모드</div>
+    <div className="hint">시스템 설정을 따르지 않고 강제 적용</div>
+  </div>
+  <Switch checked={dark} onCheckedChange={setDark} aria-label="다크 모드" />
+</div>
+```

package/assets/prompts/components/table-cell.md

@@ -0,0 +1,87 @@
+# TableCell
+
+### 원칙
+[[components/table-row]]·[[components/table-row-edit]]의 셀 자리에 넣는 **의미별 서브 컴포넌트 세트**. 하나의 TableCell이 아니라 **9종** — Text·Number·Image·Tag·Badge·Icon·Avatar·Link·Meter. 셀 안 콘텐츠 종류마다 톤·정렬·간격이 다른데 그 결정을 셀 레벨에서 끊어내 Row는 레이아웃만 담당하게 한다.
+
+### Do
+- 콘텐츠 성격에 맞는 서브 컴포넌트를 고른다. 성격 혼재 금지.
+- Number는 `tabular-nums`가 자동. 숫자 셀은 반드시 Number 사용.
+- Avatar 셀은 `label` + `sublabel`(이메일·역할) 2행 구조. 이름만이면 label만.
+- Tag는 **다중값**(기술 스택·태그 모음), Badge는 **단일 상태**.
+- 색은 톤(`tone`) prop으로만. hex·custom color 금지.
+
+### Don't
+- 숫자를 Text로 렌더하지 않는다 — tabular 정렬 깨짐.
+- 숫자 셀 **우측정렬 금지** ([[feedback_no_right_align_numbers]]). 좌측정렬 유지.
+- 셀 안에 두 종류 섞지 않는다(Avatar + Badge 등). 그러려면 상위 Row 커스텀 셀로.
+- Tag·Badge를 Icon 셀에 섞어 쓰지 않는다. 아이콘은 상태 시그널 전용.
+- 셀 자체에 padding override 금지. Row의 셀 간격 토큰이 전담.
+
+### Fallback
+tone 애매하면 Text=`default`, Icon=`default`, Meter=`default`.
+
+### 관련
+- [[components/table-row]] · [[components/table-row-edit]] · [[components/table-row-select]] — 담는 Row
+- [[components/table-header]] — 컬럼 정의
+- [[components/avatar]] — Avatar 셀 안쪽
+- [[components/badge]] · [[components/tag]] — 각 셀의 소스
+- [[tokens/color]] — tone 매핑
+
+### Props 시그니처
+```tsx
+// 공통: 모든 TableCell*은 <span>으로 렌더. HTML attributes 통과.
+<TableCellText tone="default | strong | muted | subtle">{string | ReactNode}</TableCellText>
+<TableCellNumber value={number} format?={Intl.NumberFormatOptions} />
+<TableCellImage src={string} alt={string} size={number} shape="circle | rounded | square" />
+<TableCellBadge status="success | warning | destructive | info" variant="soft | solid">
+  {string}
+</TableCellBadge>
+<TableCellIcon icon={<Icon />} tone="default | success | warning | destructive | info" />
+<TableCellAvatar
+  src?={string} name?={string} initials?={string}
+  shape="circle | rounded"                     // default: circle
+  status?="online | offline | busy | away"
+  label?={ReactNode}                           // 미지정 시 name 재사용
+  sublabel?={ReactNode}                        // 이메일·역할
+/>
+<TableCellLink href={string} external?={boolean}>{ReactNode}</TableCellLink>
+<TableCellMeter value={0..100} tone="default | success | warning | destructive" label?={string} />
+```
+
+### 서브 컴포넌트 선택 가이드
+| 셀 콘텐츠 | 사용 |
+|---|---|
+| 일반 텍스트 | `TableCellText` (tone 조절) |
+| 금액·개수·비율 | `TableCellNumber` (tabular-nums) |
+| 썸네일·프로덕트 사진 | `TableCellImage` |
+| 다중 메타 라벨 (기술·분류·속성) | `TableCellBadge` 여러 개를 `inline-flex` + `space-1` gap으로 나열 |
+| 단일 상태 라벨 | `TableCellBadge` |
+| 상태 아이콘만 | `TableCellIcon` |
+| 사람·팀 식별 | `TableCellAvatar` |
+| 외부 링크·상세 라우팅 | `TableCellLink` |
+| 진행률·사용량 바 | `TableCellMeter` |
+
+### 조합 예시
+```tsx
+// 사용자 리스트 — Avatar + 숫자 + Badge
+<TableRow
+  cells={[
+    <TableCellAvatar src={u.avatar} name={u.name} sublabel={u.email} />,
+    <TableCellText tone="muted">{u.role}</TableCellText>,
+    <TableCellNumber value={u.projects} />,
+    <TableCellBadge status={u.active ? "success" : "warning"}>
+      {u.active ? "활성" : "휴면"}
+    </TableCellBadge>,
+  ]}
+/>
+
+// 분석 테이블 — 숫자 + Meter + Link
+<TableRow
+  cells={[
+    <TableCellText tone="strong">{row.name}</TableCellText>,
+    <TableCellNumber value={row.visits} />,
+    <TableCellMeter value={row.conversion} tone="success" label={`${row.conversion}%`} />,
+    <TableCellLink href={`/reports/${row.id}`}>자세히</TableCellLink>,
+  ]}
+/>
+```