@conscience-technology/ctds 0.0.0-stage → 0.1.0

package/assets/prompts/axes/icon.md

@@ -0,0 +1,48 @@
+---
+axis: icon
+selector: '[data-icon-family]'
+values: [phosphor, solar, lucide]
+default: phosphor
+layer: 1
+---
+
+# Icon
+
+### 원칙
+Icon 축은 **Family** 하나만 담당. 한 페이지 = 한 Family.
+Weight는 축이 아니라 `<Icon weight="..." />` prop (컴포넌트별 자유 지정) — 상태 표시용.
+
+### Do
+- 아이콘은 항상 의미 기반 이름으로 참조: `<Icon name="check" />`.
+- 프로젝트 시작 시 Family 하나 결정. 리스킨 아닌 이상 안 바꾼다.
+- 활성/선택 상태 표시엔 `weight=fill`, 그 외에는 `weight=regular`.
+
+### Don't
+- 한 페이지에서 두 Family를 섞지 않는다.
+- 아이콘을 SVG로 하드코딩하지 않는다. 항상 `<Icon />` 경유.
+- Lucide에서 `weight=fill`을 요구하지 않는다 (원본이 fill 미제공).
+
+### Fallback
+Family는 `phosphor`, Weight는 `regular`.
+
+### 값
+
+**Family** (`data-icon-family`)
+- `phosphor` — regular/fill 매트릭 매칭. 가장 유연.
+- `solar` — 6-스타일 팩. Linear(regular)/Bold(fill) 매칭.
+- `lucide` — Feather 계승. 얇은 stroke. regular만.
+
+**Weight** (`<Icon weight="…" />` prop — 축 아님)
+- `regular` — 기본 outline.
+- `fill` — 채움. 활성/선택 상태.
+
+### 기본값
+`family=phosphor`, `weight=regular`
+
+### 페어링
+- `phosphor`·`solar` — regular/fill 모두 매칭. 활성 상태 표시 필요한 프로젝트 표준
+- `lucide` — regular만 지원. 활성 상태를 색·배경으로만 표현하는 프로젝트에 적합
+- 특정 [[axes/shape]] 값과의 강한 페어링은 없음. Family 선택은 브랜드 톤 기준
+
+### 관련
+N/A

package/assets/prompts/axes/mode.md

@@ -0,0 +1,50 @@
+# Mode
+
+### 원칙
+전체 배경·전경·그림자의 명도를 결정하는 축. OS 선호와 콘텐츠 성격 반영.
+
+### Do
+- 첫 진입 시 OS `prefers-color-scheme`을 존중한다.
+- 데이터 밀도가 높은 대시보드/관리도구는 `dark` 기본 검토 (장시간 응시 완화).
+- `mode`만 스왑해도 시각적 완성도가 유지되도록 semantic 토큰만 참조한다.
+
+### Don't
+- 특정 mode에만 존재하는 컴포넌트 만들지 않는다. 모든 컴포넌트가 두 mode 지원.
+- 순백(`#fff`)·순흑을 직접 지정하지 않는다. 항상 `--bg` 경유.
+
+### Fallback
+지정 없으면 `light`. OS 힌트 있으면 그 값.
+
+### 값
+- `light` — 밝은 배경, 어두운 텍스트. 일반 웹 UI 기본.
+- `dark` — 어두운 배경, 밝은 텍스트. 야간·장시간 응시·대시보드.
+- `high-contrast` — 접근성 강화 대비. KWCAG/WCAG AAA 대응. (미구현, 로드맵)
+
+### 기본값
+`light`
+
+### 국소 스코프 (라이트 페이지 안의 어두운 영역)
+라이트 모드 페이지 내에서 특정 영역만 다크로 뒤집고 싶을 때 (예: 이미지 위 오버레이, 어두운 카드/배너, 검정 툴바 위 IconButton) — 해당 컨테이너에 `data-mode="dark"`를 그대로 씌운다. `--bg`·`--fg`·`--border`·`--shadow` 등 시맨틱 토큰이 서브트리 안에서 다크 값으로 자동 반전되므로, 안쪽 컴포넌트는 별도 tone/inverse prop 없이 기존 토큰만 참조하면 된다.
+
+```tsx
+<div data-mode="dark" style={{ background: 'var(--bg)', padding: 'var(--space-4)' }}>
+  <IconButton icon="close" />   {/* --fg가 밝은 값으로 자동 반전 */}
+</div>
+```
+
+### Do (국소 스코프)
+- 어두운 표면 위에 컴포넌트를 얹을 때는 컨테이너를 `data-mode="dark"`로 감싸고, 배경은 반드시 `var(--bg)` 또는 `var(--bg-subtle/muted)`로 지정한다 (컨테이너 자체가 반전된 토큰을 사용해야 안쪽과 일관).
+- 국소 스코프는 palette·shape 등 다른 축은 상속받고 Mode만 바꾼다.
+
+### Don't (국소 스코프)
+- 컴포넌트에 `tone="inverse"`·`variant="onDark"` 같은 prop을 새로 만들지 않는다. 컨텍스트가 스타일을 결정한다.
+- 컨테이너 배경을 `#000`·`black`·하드코딩 hex로 지정하지 않는다. `var(--bg)` 경유.
+- 현재는 **다크 방향 반전만 지원**한다 (다크 페이지 안에 라이트 영역을 뚫는 `data-mode="light"` 국소 스코프는 미지원 — 필요해지면 별도 논의).
+
+### 페어링
+- `dark` + [[axes/density]] `compact` — 장시간 응시 대시보드 표준 조합
+- `high-contrast` — 다른 축과 무관하게 접근성 우선 ([[PRINCIPLES]] §5)
+- 특정 Mode + Palette 조합 제한 없음. 모든 Palette가 두 Mode 모두 지원해야 함
+
+### 관련
+- [[tokens/color]] — Mode가 스왑하는 semantic 컬러

package/assets/prompts/axes/motion.md

@@ -0,0 +1,77 @@
+# Motion
+
+### 원칙
+애니메이션의 **성격**을 결정 — duration, easing, 이동 거리 3요소를 세트로 스왑.
+컴포넌트의 모든 애니는 모션 토큰 또는 프리미티브 경유. 하드코딩 금지.
+
+### Do
+- 프로젝트 성격에 맞춰 하나 선택. 화면마다 다르게 쓰지 않는다.
+- 컴포넌트의 모든 트랜지션/애니메이션은 `--duration-*` 토큰 또는 모션 프리미티브 경유.
+- 인터랙티브 컴포넌트(hover/press/focus)는 반드시 `--transition-colors` / `--transition-ring` / `--transition-press` 3종 시맨틱 프리셋 조합만 사용.
+- `prefers-reduced-motion: reduce`가 오면 축 값과 무관하게 즉시 정지.
+
+### Don't
+- `transition-duration`이나 `animation-duration`에 밀리초 하드코딩 금지.
+- 두 개 이상 프리미티브를 겹치지 않는다 (예외: 오버레이는 fade+scale 조합만 허용).
+- `motion=none`이라도 스피너·프로그레스는 예외적으로 동작 유지 (기능성 우선).
+
+### Fallback
+`standard`
+
+### 값
+- `bouncy` — 크고 오래(400ms 기본). Spring easing. 브랜드·마케팅·온보딩.
+- `standard` — 표준(200ms). Ease-out. 일반 웹 UI.
+- `calm` — 짧고 은은(100ms). Linear. 관리 도구·데이터 대시보드.
+- `none` — 즉시(0ms). 접근성 우선·저사양·정적 프리뷰.
+
+### 기본값
+`standard`
+
+### 페어링
+- `bouncy` + [[axes/shape]] `soft` — 부드러운 촉감 + 표현력 있는 모션
+- `calm` + [[axes/shape]] `crisp` — 신뢰·전문 인상 + 절제된 모션
+- `calm` + [[axes/density]] `compact` — 밀도 높은 화면에서 모션 이동 거리도 자동 축소
+- `none` — `prefers-reduced-motion: reduce` 사용자에게 강제 (다른 축 값과 무관, [[PRINCIPLES]] §5)
+
+### 인터랙션 트랜지션 시맨틱 프리셋
+모든 인터랙티브 컴포넌트(Button/IconButton/MenuItem/Input/Tabs 등)의 hover/press/focus는 아래 3종을 조합해서 사용. 컴포넌트가 `transition` 속성에 duration·easing을 직접 적지 않는다.
+
+- `--transition-colors` — background/color/border-color, `slow` + `ease-out`. hover가 스르륵 물듦 (소음 최소).
+- `--transition-ring` — box-shadow(focus ring), `fast` + `ease-out`. 키보드 사용자에게 즉각 피드백.
+- `--transition-press` — transform(press), `base` + `ease-out`. 진입·해제 대칭.
+
+```css
+.root {
+  transition: var(--transition-colors), var(--transition-ring), var(--transition-press);
+}
+```
+
+색이 안 변하면 `--transition-colors` 생략, press가 없으면 `--transition-press` 생략 — 필요한 프리셋만 조합. 값 튜닝은 globals.css의 토큰 정의에서만 (컴포넌트에서 override 금지).
+
+### 플로팅 서페이스 In/Out — `.m-float` 유틸 강제
+Tooltip · ContextMenu · DropdownMenu · Select · Popover · DatePicker · HoverCard 등 **떠오르는 표면(overlay/popover)은 예외 없이** globals.css의 전역 유틸 `.m-float`을 사용한다. 컴포넌트별로 자체 keyframe(`dp-emerge`, `menu-in` 등)이나 자체 `animation:` 규칙을 만들지 않는다.
+
+**적용법 (Radix 기반):**
+```tsx
+<Radix.Content
+  className={[styles.content, "m-float"].filter(Boolean).join(" ")}
+  {/* ... */}
+/>
+```
+
+**작동 원리:**
+- `data-state`(`open`|`closed`|`delayed-open`) × `data-side`(`top`|`bottom`|`left`|`right`) 조합으로 자동 매칭.
+- open은 앵커 반대편에서 자라남 (`--duration-base` + `--ease-emphasized`).
+- close는 앵커 쪽으로 되감김 (`--duration-fast` + `--ease-in`, 이동량 절반).
+- `prefers-reduced-motion: reduce`면 자동 정지.
+
+**왜 전역 유틸인가:**
+Turbopack CSS Modules는 컴포넌트 CSS 안의 `animation: <name>` shorthand에서 keyframe identifier를 hash로 rewrite한다 → globals.css의 전역 `@keyframes m-emerge-*`가 매칭 실패. `.m-float` 규칙 자체를 globals.css에 두어 스코핑을 회피하면 컴포넌트는 클래스 문자열만 붙이면 된다.
+
+**Don't:**
+- 컴포넌트 CSS에 `@keyframes` 새로 만들어 오버레이 등장 애니메이션 정의.
+- 오버레이 Content에 `animation:` 또는 `animation-*` 재정의.
+- `data-state="closed"` 애니메이션 생략 (인·아웃 대칭이 원칙).
+
+### 관련
+- [[primitives/fade]] · [[primitives/emerge]] · [[primitives/recede]] — Motion 축이 파라미터를 스왑, `.m-float`이 side별 매핑

package/assets/prompts/axes/palette.md

@@ -0,0 +1,35 @@
+# Palette
+
+### 원칙
+브랜드 컬러의 **강도**를 결정. Hue가 "어떤 색"이라면 Palette는 "얼마나 강한 색".
+OKLCH의 chroma·lightness를 스왑.
+
+### Do
+- 프로젝트의 톤을 정하는 첫 축. Hue보다 Palette를 먼저 결정한다.
+- 정보 밀도가 높은 화면은 `calm` 또는 `standard`.
+- 마케팅·랜딩·온보딩은 `vivid` 또는 `pastel`.
+
+### Don't
+- Palette를 컴포넌트별로 다르게 쓰지 않는다. 프로젝트 전체가 한 Palette.
+- `pastel` 컬러 위에 흰 텍스트를 얹지 않는다 (대비 부족).
+
+### Fallback
+`standard`
+
+### 값
+- `vivid` — 채도 높음. 강한 인상, 브랜드 강조.
+- `standard` — 기본. 일반 웹 UI.
+- `calm` — 채도 낮음. 차분, 신뢰. 금융·의료·공공.
+- `pastel` — 매우 낮은 채도 + 밝은 명도. 부드러움. 교육·유아·라이프스타일.
+
+### 기본값
+`standard`
+
+### 페어링
+- `calm` + [[axes/hue]] `ocean`·`forest`·`slate` — 신뢰·안정 인상 (금융·의료·공공)
+- `vivid` + [[axes/hue]] `sunset`·`crimson` — 강한 브랜드 인상 (스타트업·프로모션)
+- `pastel` + [[axes/hue]] `lavender` — 부드러움 (교육·라이프스타일)
+- `pastel` + [[axes/mode]] `dark` — 비권장. 파스텔은 밝은 배경에서 최적화됨
+
+### 관련
+- [[axes/hue]] — Palette와 조합해 최종 브랜드 컬러 생성

package/assets/prompts/axes/shape.md

@@ -0,0 +1,33 @@
+# Shape
+
+### 원칙
+컴포넌트의 **촉감**(radius + shadow + border 두께). 세 요소를 세트로 스왑해 시각적 일관성 유지.
+
+### Do
+- 프로젝트 성격에 맞춰 하나 선택. 컴포넌트별로 다르게 쓰지 않는다.
+- 데이터 밀도 높은 화면은 `crisp` — 각진 경계가 정보 구분에 유리.
+- 콘텐츠·마케팅 화면은 `soft` — 친근함·여유.
+
+### Don't
+- radius/shadow/border를 개별 하드코딩하지 않는다. Shape 축으로만 조정.
+- 특정 컴포넌트만 다른 shape를 갖게 만들지 않는다 (예: Modal만 soft).
+
+### Fallback
+`standard`
+
+### 값
+- `soft` — 큰 radius, 부드러운 넓은 그림자, 얇은 border. 캐주얼·친근.
+- `standard` — soft와 crisp의 산술 중간. 무난한 표준.
+- `crisp` — 작은 radius, 짧고 예리한 그림자 + 아웃라인, 뚜렷한 border. 신뢰·전문.
+
+### 기본값
+`standard`
+
+### 페어링
+- `soft` + [[axes/motion]] `bouncy` — 부드러운 촉감과 표현력 있는 모션이 자연스러움
+- `crisp` + [[axes/motion]] `calm` — 신뢰·전문 인상에는 절제된 모션
+- `crisp` + [[axes/density]] `compact` — 데이터 밀도 화면의 표준 조합
+- `soft` + [[axes/density]] `compact` — 비권장. 부드러운 촉감과 밀도가 충돌
+
+### 관련
+- [[tokens/radius]] · [[tokens/shadow]] — Shape가 스왑하는 토큰들

package/assets/prompts/axes/voice.md

@@ -0,0 +1,54 @@
+---
+axis: voice
+selector: '[data-voice]'
+values: [formal, neutral, casual]
+default: neutral
+layer: 2
+css_tokens: none
+---
+
+# Voice
+
+### 원칙
+Voice는 **카피 톤만** 지배. 토큰·CSS 변수 없는 Layer 2 전용 축.
+Theme과 독립 — editorial이든 mechanical이든 어떤 Theme에도 어떤 Voice든 결합 가능.
+서비스 성격 기준으로 선택하며, 다른 축(색·간격·모션)에 전혀 연쇄하지 않는다.
+
+### Do
+- 카피를 생성할 때 현재 `data-voice` 또는 사용자 지시된 Voice를 **먼저 확인**하고 그 톤으로 작성.
+- 톤 전환은 종결어미만 바꾸지 말고 **어휘 선택까지** 바꾼다 (예: "오류" ↔ "앗").
+- Preset(`gov-formal` 등) 적용 후에도 Voice는 사용자가 별도로 선택한 값을 유지한다.
+
+### Don't
+- Voice를 색·간격·radius와 같은 기준으로 변경하지 않는다. 다른 축에 영향 없음.
+- 접근성 문구(에러 설명, 필수 필드 안내, 스크린리더 라벨)는 Voice와 무관하게 **명확성 우선**.
+  `casual`이어도 필수 정보를 희석하지 않는다 (예: "비밀번호는 필수입니다" 수준은 유지).
+- Voice에 CSS 변수나 토큰을 할당하지 않는다. 코드 레벨 영향은 `data-voice` 속성 노출뿐.
+- **제목·헤딩·버튼 라벨·메뉴명에 em dash(—), en dash(–), 하이픈(-)으로 부제를 잇지 않는다.**
+  모든 Voice 공통 하드 룰. 문서·UI 카피·AI 생성물 전부 해당.
+  나쁜 예: "온보딩 — 테마를 고릅니다", "설정 — 기본값", "저장 — 완료".
+  대신: 한 줄 제목으로 끝내거나(`"테마 고르기"`), 부제가 꼭 필요하면 별도 하위 텍스트로 분리.
+
+### Fallback
+`neutral`.
+
+### 값
+
+**Voice** (`data-voice`)
+- `formal` — 격식체. 종결어미 "···합니다". 공공·금융·법무·엔터프라이즈.
+  예: "저장되었습니다.", "요청을 처리할 수 없습니다."
+- `neutral` — 표준 존대. 종결어미 "···입니다 / ···해요" 혼용. 일반 웹 UI 기본.
+  예: "저장했어요.", "다시 시도해 주세요."
+- `casual` — 친근체. 말 놓기 톤 허용. 소셜·게임·내부 도구.
+  예: "저장 완료!", "앗, 뭔가 잘못됐어요."
+
+### 기본값
+`voice=neutral`
+
+### 페어링
+- 특정 Theme과의 강한 페어링 없음. Theme이 묶는 축 바깥에 있음.
+- 선택 기준은 **서비스 성격**: B2G/금융 → `formal`, 일반 B2C → `neutral`, 소셜·게임·사내툴 → `casual`.
+- 특정 [[axes/palette]]·[[axes/shape]]와의 강제 조합도 없음.
+
+### 관련
+- [[themes/_SCHEMA]] — Theme이 묶는 축에서 Voice는 제외됨 (Palette/Hue와 함께 Theme 바깥 3축).

package/assets/prompts/components/README.md

@@ -0,0 +1,84 @@
+# prompts/components/
+
+> **이 폴더는 CTDS 관리자용.**
+> CTDS를 사용하는 개발자는 [../../USAGE.md](../../USAGE.md)를 본다.
+
+CTDS 컴포넌트별 프롬프트 문서. Layer 2 (AI 프롬프트 컨텍스트).
+
+각 파일은 `web/components/<Name>/`의 코드 컴포넌트와 **쌍으로** 존재해야 한다.
+
+---
+
+## 파일 규칙
+
+- 파일 하나 = 컴포넌트 하나 (`button.md`, `input.md`, `select.md` ...)
+- 파일명은 kebab-case, 소문자
+- 문서 골격은 [../GUIDE.md](../GUIDE.md) §3.3 참고
+
+---
+
+## 최소 골격
+
+```markdown
+## <컴포넌트 이름>
+
+### 원칙
+<1~2줄. 이 컴포넌트가 왜 존재하고 언제 쓰는가.>
+
+### Do
+- <명령형 규칙>
+
+### Don't
+- <하드 리젝 사유>
+
+### Fallback
+<규칙이 애매할 때의 기본값.>
+
+### 관련
+- [[axes/density]] — <왜 관련되는지>
+- [[tokens/spacing]] — <왜 관련되는지>
+
+### Props 시그니처
+```tsx
+<Button variant="primary | secondary | ghost" size="sm | md | lg" />
+```
+
+### Variant 매트릭스
+| variant | 용도 | 금지 조합 |
+|---|---|---|
+| `primary` | 주요 액션 | 한 화면에 2개 이상 금지 |
+| `secondary` | 보조 액션 | — |
+
+### 조합 예시
+<규칙을 종합한 최소 예시 1개. 코드 블록.>
+```
+
+빈 헤딩은 `N/A` 한 줄로 표시. 헤딩 자체를 생략하지 않는다.
+
+---
+
+## 크로스 참조
+
+- 축 참조: `[[axes/density]]`
+- 토큰 참조: `[[tokens/spacing]]`
+- 다른 컴포넌트: `[[components/button]]`
+- 프리미티브: `[[primitives/fade]]`
+- 최상위 문서: `[[PRINCIPLES]]`, `[[GUIDE]]`
+
+상대 경로(`../axes/density.md`)나 URL 금지.
+
+---
+
+## 작성 우선순위
+
+[PROJECT_OVERVIEW.md](../../PROJECT_OVERVIEW.md) §핵심 컴포넌트 목록의 순서를 따른다.
+사용 빈도 높은 컴포넌트부터: Button → Input → Select → Table → Modal → Form ...
+
+---
+
+## 코드와의 연결
+
+- 코드: `web/components/<Name>/<Name>.tsx` + `.module.css`
+- 이 문서: `prompts/components/<name>.md`
+- 둘이 어긋나면 AI 에이전트가 사용자에게 알림 (기본 동작)
+- 새 컴포넌트 추가·수정 시 **코드와 문서를 함께 커밋** ([../../CONTRIBUTING.md](../../CONTRIBUTING.md))

package/assets/prompts/components/app-frame.md

@@ -0,0 +1,94 @@
+# AppFrame
+
+### 원칙
+앱 전체 쉘의 grid 레이아웃. Sidebar + Topbar + Tabs(선택) + Content의 자리를 **CSS Grid**로 배정. compound 슬롯 패턴 — 자식 slot을 넣은 만큼 grid-template이 자동 조정. `variant`로 컨테이너 표현(outlined/floating/flat), `layout`으로 Sidebar/Topbar 배치 축을 결정.
+
+### Do
+- 모든 페이지 쉘의 **진입점** — layout.tsx 또는 섹션 쉘의 최상위에 둔다.
+- `AppFrame.Sidebar` / `AppFrame.Topbar` / `AppFrame.Tabs` / `AppFrame.Content` 슬롯을 쓴다. 자식 순서는 자유 (grid-area가 배정).
+- 비어있는 슬롯은 아예 **생략**. `data-has-*`가 자동 감지해 grid-template 축소.
+- `variant`로 컨테이너 톤을 결정: outlined(기본, 테두리) / floating(그림자, 떠있는) / flat(배경만, 쉘 티 안 남).
+- `layout`은 서비스 성격 기준: sidebar-first(Linear·Slack·Figma 패턴) / topbar-first(Jira·Vercel 패턴).
+
+### Don't
+- Content 안쪽에서 다시 AppFrame을 중첩하지 않는다 — grid 규칙 깨짐.
+- Sidebar·Topbar 안에서 flex/grid를 override로 조립하지 않는다. 각자 자신의 레이아웃 컴포넌트([[components/sidebar]], [[components/topbar]])에 위임.
+- 슬롯을 custom DOM으로 대체하지 않는다 — `data-has-*` 감지가 깨짐. 반드시 `AppFrame.X` 사용.
+- padding/gap을 override 금지. `--control-h-*`, `--sidebar-w*`, `--topbar-h*` 토큰이 전담.
+
+### Fallback
+variant 애매하면 `outlined`. layout 애매하면 `sidebar-first`.
+
+### 관련
+- [[components/sidebar]] — Sidebar 슬롯 안에 담김
+- [[components/topbar]] — Topbar 슬롯 안
+- [[components/tabs]] — Tabs 슬롯 (optional, Topbar 아래 contextual nav)
+- [[axes/density]] — sidebar/topbar 폭·높이 토큰이 Density에 반응
+- [[axes/shape]] — outlined/floating의 radius·shadow가 Shape 축에 반응
+
+### Props 시그니처
+```tsx
+<AppFrame
+  variant="outlined | floating | flat"       // default: outlined
+  layout="sidebar-first | topbar-first"      // default: sidebar-first
+>
+  <AppFrame.Sidebar>
+    <Sidebar>...</Sidebar>
+  </AppFrame.Sidebar>
+
+  <AppFrame.Topbar>
+    <Topbar>...</Topbar>
+  </AppFrame.Topbar>
+
+  <AppFrame.Tabs>                            {/* optional */}
+    <Tabs>...</Tabs>
+  </AppFrame.Tabs>
+
+  <AppFrame.Content>
+    {page}
+  </AppFrame.Content>
+</AppFrame>
+```
+
+### Variant × Layout 매트릭스
+| variant | 시각 | 자리 |
+|---|---|---|
+| `outlined` | 전체 bg + hairline border | 기본 — 관리·대시보드 |
+| `floating` | 쉘이 떠있는 느낌, shadow | 랜딩·마케팅·모던 SaaS |
+| `flat` | 쉘 티 안 남, 콘텐츠가 바탕에 직접 | 미니멀·docs·에디터 |
+
+| layout | 구조 | 레퍼런스 |
+|---|---|---|
+| `sidebar-first` | 사이드바가 세로 전체, 탑바는 오른쪽만 | Linear · Slack · Figma |
+| `topbar-first` | 탑바가 가로 전체, 사이드바는 아래 왼쪽만 | Jira · Vercel · Confluence |
+
+### 조합 예시
+```tsx
+// 가장 흔한 쉘 — Sidebar + Topbar + Content
+<AppFrame variant="outlined" layout="sidebar-first">
+  <AppFrame.Sidebar><Sidebar>…</Sidebar></AppFrame.Sidebar>
+  <AppFrame.Topbar><Topbar>…</Topbar></AppFrame.Topbar>
+  <AppFrame.Content>{children}</AppFrame.Content>
+</AppFrame>
+
+// Topbar 아래 Tabs가 있는 상세 페이지
+<AppFrame>
+  <AppFrame.Sidebar><Sidebar>…</Sidebar></AppFrame.Sidebar>
+  <AppFrame.Topbar><Topbar title="프로젝트" />.</AppFrame.Topbar>
+  <AppFrame.Tabs>
+    <Tabs value={tab} onValueChange={setTab}>
+      <Tabs.List>
+        <Tabs.Trigger value="overview">Overview</Tabs.Trigger>
+        <Tabs.Trigger value="activity">Activity</Tabs.Trigger>
+      </Tabs.List>
+    </Tabs>
+  </AppFrame.Tabs>
+  <AppFrame.Content>{tab === "overview" ? <Overview /> : <Activity />}</AppFrame.Content>
+</AppFrame>
+
+// 랜딩 — Topbar만, Sidebar 없음
+<AppFrame variant="flat" layout="topbar-first">
+  <AppFrame.Topbar><Topbar variant="landing" /></AppFrame.Topbar>
+  <AppFrame.Content><Hero /></AppFrame.Content>
+</AppFrame>
+```

package/assets/prompts/components/attachment-chip.md

@@ -0,0 +1,46 @@
+# Attachment Chip
+
+### 원칙
+파일 첨부 1건 pill — `[FileIcon] filename [X]`. 파일명에서 확장자를 뽑아 [[components/file-icon]] 색/라벨을 자동 결정. 긴 파일명은 **중간 ellipsis** + 끝 확장자 유지. ChatInput·Message 양쪽 공용.
+
+### Do
+- 파일명 통째로 넘기면 끝 — `filename="report.pdf"` 하나로 아이콘·라벨·식별까지 다 해결.
+- 삭제 가능한 자리엔 `onRemove` 지정 — X 상시 노출 (hover 틴트).
+- Thumb(이미지)·Chip(파일) 섞여 흐를 자리는 `flex-wrap: wrap` + `gap: space-2`로 조립.
+- 긴 파일명은 middle ellipsis가 알아서 자름 — maxLen 초과면 `name… + ext` 형태.
+
+### Don't
+- 파일명과 확장자를 **따로** 받는 props 추가하지 않는다 — 소비처에서 자르면 FileIcon 매핑이 어긋남.
+- X를 호버 전용으로 숨기지 않는다 — ChatInput 안에선 상시 노출이 원칙 (이미지 썸네일과 다름).
+- Chip 안에 메뉴/추가 액션 넣지 않는다 — 삭제 외엔 상위 ChatInput이 책임.
+- 배경을 과한 톤으로 덮지 않는다 — bg는 `var(--bg)`, 테두리는 hairline. ChatInput 안에서 두드러지지 않게.
+
+### Fallback
+size 애매하면 `md`. 모르는 확장자는 FileIcon이 `others`로 폴백하니 그대로 넘겨도 됨.
+
+### 관련
+- [[components/file-icon]] — 좌측 뱃지
+- [[components/attachment-thumb]] — 이미지 첨부
+- [[components/chat-input]] — 상위 소비처
+- [[components/message-bubble]] — 메시지 내 파일 인용에서도 재사용
+
+### Props 시그니처
+```tsx
+<AttachmentChip
+  filename={string}                // 필수. 확장자 자동 추출
+  size="sm | md"                   // default: md
+  onRemove={(e) => void}           // 지정 시 우측 X 노출
+/>
+```
+
+### 비율·레이아웃
+- 외곽 `--radius-full` (pill)
+- `--hairline` 1px border, `var(--border)` 색
+- 내부 gap: `--space-2`
+- padding: md = `space-1_5 space-3 space-1_5 space-1_5` (왼쪽은 FileIcon 바싹 붙게 좁게)
+- X: `--space-5` (md) / `--space-4` (sm) 정사각, radius full
+
+### Middle ellipsis 규칙
+`filename.length > 28`이면 `name… + ext`로 치환.
+- `"super-long-project-pitch.pptx"` → `"super-long-pr… .pptx"` 식.
+- 확장자 없거나 너무 짧으면 일반 ellipsis.

package/assets/prompts/components/attachment-thumb.md

@@ -0,0 +1,49 @@
+# Attachment Thumb
+
+### 원칙
+Chat Input·Message의 **이미지 첨부 썸네일**. 정사각 radius ~22%(size × 0.22) 고정, 세 가지 상태 — `src` 있음(이미지)/없음(블루톤 image glyph)/`loading`(pulse). 전부 inner hairline으로 edge definition. hover 시 코너에 X 삭제 버튼 노출(`onRemove` 지정 시).
+
+### Do
+- 이미지 첨부(png/jpg/gif/webp)엔 썸네일, 그 외 포맷은 [[components/file-icon]] 또는 [[components/attachment-chip]].
+- 업로드 처리 중/디코딩 전엔 `loading` → pulse. 끝나면 `src` 세팅.
+- 메타만 받고 썸네일 URL이 늦게 오면 `src` 비워두면 image glyph placeholder — 로딩이 길어 답답한 자리를 메움.
+- 삭제 UI가 필요하면 `onRemove`를 넘김 — hover/focus-visible에서 코너 X 활성.
+
+### Don't
+- 썸네일 안에 캡션·메뉴 넣지 않는다 — 레퍼런스는 "순수한 미리보기".
+- `object-fit: contain` 금지 — 비율은 crop(`cover`).
+- radius를 Shape 축에 반응시키지 않는다 — 소형 치수라 [[components/file-icon]]과 같은 이유로 고정.
+- placeholder 그라데이션 등 "꾸미기" 금지 — mp3 음악 노트와 같은 패턴, 단일 톤 glyph만.
+
+### Fallback
+size 애매하면 `md`(40). `src`·`loading` 둘 다 없으면 자동 placeholder.
+
+### 관련
+- [[components/attachment-chip]] — 파일형 첨부
+- [[components/file-icon]] — 브랜드 사각 뱃지
+- [[components/chat-input]] — 상위 소비처
+
+### Props 시그니처
+```tsx
+<AttachmentThumb
+  src={string}                     // 이미지 URL. 없으면 image glyph placeholder
+  alt={string}
+  size="sm | md | lg"              // default: md (32 / 40 / 56)
+  loading={boolean}                // true면 pulse (src 무시)
+  onRemove={(e) => void}           // 지정 시 hover에서 X 노출
+/>
+```
+
+### 비율 (고정 — FileIcon과 통일)
+- `radius / size` = 0.25 → sm=8, md=10, lg=14
+- `glyph / size` = 0.60
+- Remove 버튼: `size × 0.42`, 코너에 `-12%` offset으로 overlap
+- 가로세로 1:1 crop
+
+### Placeholder 색 (Mode 축 자동 전환)
+| 모드 | bg | fg |
+|---|---|---|
+| Light | `#D5E8FD` | `#2D7FD3` |
+| Dark | `#1E3A5F` | `#C5DFF8` |
+
+브랜드 자산 범주 — [[components/file-icon]]과 같은 하드코딩 예외. 토큰으로 추상화 X.

package/assets/prompts/components/avatar.md

@@ -0,0 +1,86 @@
+# Avatar
+
+### 원칙
+사람·팀의 **식별 마커**. 이미지 → 이니셜 → 아이콘 순서로 자동 폴백. 10색 tint 팔레트에서 이름 해시 기반 안정 매핑 — 같은 사람은 항상 같은 색. shape으로 **사람/조직** 구분(circle/rounded), status로 **접속 상태** 뱃지. 축 영향 안 받는 고정 팔레트 (사용자 식별은 흔들리면 안 됨).
+
+### Do
+- 가능하면 `name` 전달 — 이니셜 폴백 + tint seed + aria 라벨 공용.
+- `shape="circle"`은 사람·개인, `shape="rounded"`는 팀·조직·봇.
+- `src` 로드 실패 시 자동으로 이니셜 폴백. `onError` 수동 처리 불필요.
+- 접속 상태는 `status` prop. online/offline 두 값만.
+- Sidebar.Profile·TableCell.Avatar에 쓰는 패스스루 패턴 활용.
+
+### Don't
+- hex·custom 색으로 tint 덮지 않는다. 10색 팔레트가 자동.
+- status에 커스텀 값 금지 (busy/away 아직 미지원).
+- aria-label 생략 금지 (`alt` 또는 `name` 중 하나는 필수).
+- Avatar 안에 그라데이션·이모지·텍스트 2글자 넘김 금지 — 식별 신호 혼탁.
+- 크기를 CSS로 override 금지. `size` prop만.
+
+### Fallback
+size 애매하면 `md`, shape 애매하면 `circle` (사람).
+
+### 관련
+- [[components/sidebar]] — Sidebar.Profile 안쪽
+- [[components/table-cell]] — TableCellAvatar 안쪽
+- [[components/badge]] — status 뱃지 시각 쌍
+- [[components/avatar-upload]] — 업로드 가능한 Avatar wrapper (별도)
+- [[tokens/color]] — `--avatar-tint-N-bg`·`--avatar-tint-N-fg` 10색
+
+### Props 시그니처
+```tsx
+<Avatar
+  size="xs | sm | md | lg | xl"               // default: md
+  shape="circle | rounded"                    // default: circle
+  src={string}                                // 이미지 URL (실패 시 자동 폴백)
+  alt={string}                                // 접근성 대체 텍스트
+  name={string}                               // 이니셜 추출 + tint seed + aria
+  initials={string}                           // 이니셜 직접 지정 (name보다 우선)
+  icon={ReactNode}                            // 이미지·이니셜 대신 아이콘
+  status="online | offline"                   // 접속 뱃지 (미지정 시 뱃지 없음)
+/>
+```
+
+### Size 가이드
+| size | 쓰임 |
+|---|---|
+| `xs` | 10 — Chip leftIcon, 밀도 극한 리스트 |
+| `sm` | 14 — TableCell.Avatar, 리스트 아이템 |
+| `md` | 18 — **기본**, Sidebar.Profile |
+| `lg` | 24 — 프로필 카드 |
+| `xl` | 40 — 설정 페이지의 큰 아바타 |
+
+### 폴백 체인
+1. `src`가 있고 로드 성공 → 이미지
+2. `initials` 또는 `name`에서 추출된 이니셜 → 색 배경 + 이니셜 2글자
+3. `icon` → 아이콘 (`--fg-muted`)
+4. 전부 없으면 → "?" 이니셜
+
+**이니셜 추출 규칙**:
+- 한글: 첫 글자 1개 (`"김희영"` → `"김"`)
+- 영문: 첫 단어 앞 2글자 (`"Kim Heeyoung"` → `"Ki"`, `"AB"` → `"Ab"`)
+
+**Tint 매핑**: `name` 또는 `initials` 해시 → 10색 중 하나. 같은 입력 = 같은 색 (사용자 식별 안정).
+
+### 조합 예시
+```tsx
+// 가장 흔한 — 이름 + 이미지 + 상태
+<Avatar size="md" name="희영" src="/avatars/hy.jpg" status="online" />
+
+// 조직·팀 — rounded
+<Avatar size="lg" name="디자인팀" shape="rounded" />
+
+// 이미지 없고 이니셜만
+<Avatar size="sm" name="Alex Johnson" />
+
+// 커스텀 아이콘 (봇·시스템)
+<Avatar size="md" shape="rounded" icon={<Icon name="robot" />} alt="시스템 봇" />
+
+// TableCell.Avatar 안 — label·sublabel
+<TableCellAvatar
+  src={user.avatar}
+  name={user.name}
+  sublabel={user.email}
+  status={user.online ? "online" : "offline"}
+/>
+```