@conscience-technology/ctds 0.4.3 → 0.4.5

package/assets/prompts/components/callout.md

@@ -4,21 +4,24 @@
 사이드바·리스트 끝·설정 패널의 여백에 상주하는 소형 안내 카드. 페이지 흐름을 끊지 않고 새 기능·이동 경로를 제시한다. hover가 없는 [[components/tooltip]], 휘발되는 Toast, 페이지 폭 전체를 덮는 [[recipes/page-banner]]와 구분된다.
 
 ### Do
-- 표면 강도는 `variant`, 강조 색은 `tone`으로 독립 제어한다.
+- 표면은 `fill` 하나 — tone tint 배경 + 투명 border 로 신호를 담는다. 색 테두리 없음.
+- 강조 색은 `tone` 으로 제어한다.
 - `dismissible=true`면 `onDismiss`와 함께 부모가 숨김 상태를 저장한다.
 - `actions`는 [[components/button]] slot이다 — variant는 자유, size는 `xs`(기본) 또는 `sm`만.
 - 액션 Button의 색은 `tone`을 따라간다 — solid/soft 버튼이면 같은 tone(warning엔 warning 버튼, destructive엔 destructive 버튼), 아니면 `ghost`/`outline` 중립. tone과 다른 색 solid 버튼으로 신호를 깨지 않는다.
 - 좁은 컨테이너에선 `actionsPlacement="bottom"` 유지, `right`는 본문이 짧고 카드가 가로로 넓을 때만.
 - `warning`/`destructive` tone은 `icon` 미지정 시 각각 `warning-circle`(주의) / `warning`(위험)이 자동. 다른 의미 아이콘이 필요할 때만 override한다.
+- 톤을 "비권장" 수준으로 낮추고 싶으면 Callout 자체를 쓰지 않는다 — [[components/callout]] 대신 `fg-muted` 색 **인라인 텍스트 한 줄**로 처리.
 
 ### Don't
 - 페이지 폭 전역 경고에 쓰지 않는다 — [[recipes/page-banner]] 영역.
 - 임시 피드백에 쓰지 않는다 — Toast를 쓴다.
 - 본문을 4줄 넘게 채우지 않는다.
 - `tone`을 임의 색상으로 확장하지 않는다.
+- **[HARD] `variant="outline"` 금지** — 색 테두리 + 색 배경 조합(outlined Callout류) 영구 금지. "안 연한 배경 + 진한 스트로크" 는 UI 를 싸구려·시끄럽게 만듦 ([[PRINCIPLES]] §5b, [[feedback_no_outlined_callout]]). 과거 outline variant 는 폐기 — 쓰지 말 것. 비권장 메시지는 Callout 자체 대신 muted 인라인 텍스트로.
 
 ### Fallback
-`variant` 애매하면 `fill`. `tone` 애매하면 `brand`. `actionsPlacement` 애매하면 `bottom`.
+`variant` 는 `fill` 하나뿐. `tone` 애매하면 `brand`. `actionsPlacement` 애매하면 `bottom`.
 
 ### 관련
 - [[recipes/page-banner]] — 페이지 폭 전면 경고. Callout은 국소 카드.
@@ -31,7 +34,6 @@
 <Callout
   title={ReactNode}                                     // required
   icon={IconName}
-  variant="fill | outline"                              // default: fill
   tone="neutral | brand | success | warning | destructive"  // default: brand
   actions={ReactNode}
   actionsPlacement="bottom | right"                     // default: bottom
@@ -41,16 +43,20 @@
 >{children}</Callout>
 ```
 
+> `variant` prop 은 폐기됨. 과거 코드는 자동으로 `fill` 로 동작하지만, 신규 작성 시 명시하지 않는다.
+
 ### Variant 매트릭스
-variant × tone 축이 독립 조합. 표는 tone 기준으로 정렬, 각 tone에 variant 두 종을 보여준다.
+`variant` 는 `fill` 하나로 고정. tone 별 표면 색만 바뀐다.
+
+| tone | fill (유일 variant) | 용도 |
+|---|---|---|
+| `neutral`     | 회색 표면(`bg-subtle`) + `fg-muted` 아이콘 | 톤 없는 기본 안내·중립 컨텍스트 |
+| `brand`       | tone 8% tint 표면 + brand 아이콘 | 신기능·프로모션·마이그레이션 유도 |
+| `success`     | success 8% tint + success 아이콘 | 완료·다음 스텝 제안 |
+| `warning`     | warning 8% tint + warning 아이콘 | 만료·용량 임박·설정 누락 |
+| `destructive` | destructive 8% tint + destructive 아이콘 | 삭제 예정·비가역 상태 |
 
-| tone | fill | outline | 용도 |
-|---|---|---|---|
-| `neutral`     | 회색 표면(`bg-subtle`) + `fg-muted` 아이콘 | 표면 투명 + `border` 경계 | 톤 없는 기본 안내·중립 컨텍스트 |
-| `brand`       | tone 8% tint 표면 + brand 아이콘·경계 | 표면 투명 + brand 경계 | 신기능·프로모션·마이그레이션 유도 |
-| `success`     | success 8% tint + success 아이콘·경계 | 표면 투명 + success 경계 | 완료·다음 스텝 제안 |
-| `warning`     | warning 8% tint + warning 아이콘·경계 | 표면 투명 + warning 경계 | 만료·용량 임박·설정 누락 |
-| `destructive` | destructive 8% tint + destructive 아이콘·경계 | 표면 투명 + destructive 경계 | 삭제 예정·비가역 상태 |
+모든 tone 에서 border 는 `transparent` — 색 테두리는 fill 표면과 신호가 겹쳐 소음만 더한다. 영역 분리가 필요하면 외부 레이아웃 gap 으로 해결, Callout 자체는 테두리를 그리지 않음.
 
 **금지 조합**
 tone이 톤 신호를 쥐고 있으므로, 그 안의 요소들(액션 버튼·아이콘)도 같은 신호를 유지해야 한다. 색이 어긋나면 사용자는 어느 쪽을 믿어야 할지 결정하지 못한다.

package/assets/prompts/components/chat-input.md

@@ -5,6 +5,7 @@ AI 채팅의 입력 영역. **첨부물 바 → 인용 바 → 입력 본문**(t
 
 ### Do
 - Shape은 두 가지 — `multi`(기본, 긴 입력·오버레이 UI), `single`(토픽바·검색봉 느낌).
+- Variant는 두 가지 — `framed`(기본, radius·border·shadow 가진 떠있는 블록), `flush`(radius·border·shadow 모두 제거, shell 바닥에 edge-to-edge).
 - 외곽 radius는 Shape 축 토큰이 직접 결정 — prop으로 받지 않음.
 - `models` + `selectedModel` + `onSelectModel` 셋이 다 있을 때만 모델 selector 노출.
 - 전송은 `Enter`로 — multi에선 `Shift+Enter`가 줄바꿈. 스트리밍 중엔 `Enter`나 send 클릭이 `onStop`을 호출.
@@ -15,10 +16,18 @@ AI 채팅의 입력 영역. **첨부물 바 → 인용 바 → 입력 본문**(t
 - 첨부·인용·메시지 상태를 ChatInput 안에서 관리하지 않는다 — controlled 전용.
 - 모델 선택 메뉴를 내부에서 열지 않는다 — 현재는 라벨 클릭 시 다음 모델로 토글만. 실제 ContextMenu는 소비처에서 조립 (ChatInput의 책임 과잉 방지).
 - SingleLine에서 모델 라벨을 끝까지 노출하지 않는다 — 10자 넘으면 자동 compact(아이콘만).
-- Send 버튼 색을 변경하지 않는다 — 비활성=`bg-subtle` / 활성·스트리밍=`primary`로 고정.
+- Send 버튼 색을 임의로 override하지 않는다 — 톤 조정은 `sendVariant` prop(`solid` | `ghost` | `soft`)으로만. 각 variant 안에서 비활성→활성 색 전환은 고정 규약.
+- `flush`를 떠있는 자리(페이지 중앙·오버레이)에 쓰지 않는다 — 외곽선 없이 공중에 뜨면 영역이 흐려짐. 반드시 shell 바닥·바텀바처럼 바깥 경계가 이미 존재하는 자리에만.
+
+### Send 버튼 variant
+- `sendVariant="solid"` *(기본)* — 비활성=`bg-subtle` / 활성·스트리밍=`primary` + 흰 아이콘. ChatGPT·Claude 류 떠있는 네모 버튼.
+- `sendVariant="ghost"` — 배경 투명, 아이콘만. 비활성=`fg-disabled` / 활성=`fg-strong`. hover에서만 `bg-subtle` 살짝. 흰 캔버스에 녹아드는 깔끔한 자리(가벼운 질문창·검색봉·툴 안쪽 작은 입력).
+- `sendVariant="soft"` — 늘 `bg-subtle` 배경, 활성이어도 색 강조 없이 fg만 진해짐. 조용한 자리(사이드바 바닥 flush, 패널 바텀바)에서 send 존재감을 낮추고 싶을 때.
+- `sendIcon="arrow-up"` *(기본)* — 전송 뉘앙스, 범용. `"return"`(↵) — 폼 submit·키보드 힌트. `"paper-plane"` — 메신저 느낌(iMessage/카톡 류). 스트리밍 중엔 아이콘 선택과 무관하게 자동으로 square로 교체.
+- 셋 다 활성 상태의 **아이콘 색 규약**은 고정 — ghost·soft는 fg-strong, solid만 흰색. 임의로 primary 색 아이콘 넣지 않는다.
 
 ### Fallback
-shape 애매하면 `multi`. maxRows 애매하면 `8`.
+shape 애매하면 `multi`. variant 애매하면 `framed`. sendVariant 애매하면 `solid`. sendIcon 애매하면 `arrow-up`. maxRows 애매하면 `8`.
 
 ### 관련
 - [[components/file-icon]] / [[components/attachment-thumb]] / [[components/attachment-item]] / [[components/quotation-bar]] — 조립 요소
@@ -30,6 +39,7 @@ shape 애매하면 `multi`. maxRows 애매하면 `8`.
 ```tsx
 <ChatInput
   shape="multi | single"               // default: multi
+  variant="framed | flush"             // default: framed
 
   value={string}
   onChange={(v) => void}
@@ -48,6 +58,9 @@ shape 애매하면 `multi`. maxRows 애매하면 `8`.
   selectedModel={string}
   onSelectModel={(id) => void}
 
+  sendVariant="solid | ghost | soft"   // default: solid
+  sendIcon="arrow-up | return | paper-plane"  // default: arrow-up
+
   placeholder="Ask me anything…"
   disabled={boolean}
   maxRows={number}                     // multi 전용, default 8
@@ -64,7 +77,8 @@ type ChatAttachment =
 - `kind: "file"`은 AttachmentItem이 filename 확장자로 FileIcon을 자동 결정.
 
 ### 레이아웃
-- 외곽: hairline border, `var(--bg)`, radius=Shape 축 (`--radius-sm`)
+- 외곽(framed): hairline border, `var(--bg)`, radius=Shape 축, `--shadow-md`
+- 외곽(flush): border·radius·shadow 전부 0 — bg만 유지. 바깥 shell(사이드바 바닥·바텀바)이 경계를 책임지는 자리 전용
 - **스크롤 룰**: root `padding: 0; overflow: hidden`. textarea에 상·하·좌·우 padding 전부 → 긴 글 스크롤 시 글이 root border까지 흘러 자연스레 clip. (wrapper에 padding 두면 scroll 시 "빈 띠"가 남아 어색 — [[primitives/scroll]])
 - focus-within에서 ring
 - 내부 세로 gap: `--space-2`, padding: `--space-3`

package/assets/prompts/components/list-item.md

@@ -146,6 +146,7 @@
 - **leading에 inline `<svg>` 금지**: 반드시 `<Icon />`/Badge/Avatar 경유. [[feedback_no_inline_svg]].
 - **한 리스트 안 size 혼용 금지**: sm 리스트는 전부 sm.
 - **자리마다 세로 간격 손 조정 금지**: 균형 안 맞으면 `size` 또는 리듬 토큰(`--li-gap-title`·`--li-gap-body`)으로.
+- **[HARD] `border-bottom` 있는 li 에 세로 padding 생략 금지** ([[feedback_no_touching_edges]]) — 콘텐츠가 선에 붙으면 무조건 문제. 최소 `--space-3` 유지. border + padding 을 다른 레이어가 공급해도 결과적으로 접촉 금지는 소비처가 책임.
 
 ## Fallback
 leading 애매하면 Icon. size 애매하면 md. align 애매하면 center(한 줄)·top(2줄 이상).
@@ -160,6 +161,27 @@ leading 애매하면 Icon. size 애매하면 md. align 애매하면 center(한
 | `--li-gap-body` | 큰 블록 간 간격 | `var(--space-2)` |
 | `--li-gap-meta` | Meta 라인 아이템 간 가로 gap | `var(--space-2)` |
 
+### MetaDivider 스펙
+
+가운뎃점·bullet·파이프 대신 쓰는 짧고 연한 세로 hairline. 가운뎃점·`|`·`•` 전부 금지 ([[feedback_no_bullet_separator]]).
+
+```css
+.metaDivider {
+  display: inline-block;
+  width: 1px;
+  height: calc(var(--text-xs) * 0.8);   /* Meta 텍스트 높이 대비 약간 짧게 */
+  background: var(--fg);
+  opacity: 0.2;                          /* hairline 톤 */
+  margin-inline: var(--space-1);        /* 좌우 작게 — Meta 토큰 간격은 --li-gap-meta 가 담당 */
+  vertical-align: baseline;
+}
+```
+
+핵심 원칙:
+- 색은 `--fg` × 낮은 알파 (fg 톤 유지, bg 와 섞이지 않음) — 다크/라이트 모드 전환 자동 반응.
+- 높이는 Meta 폰트 크기(`--text-xs`) 기준 상대값 — Density 축 스왑에 자동 반응.
+- 좌우 margin 은 `--space-1` 로 고정, Meta 토큰 간 가로 gap 은 상위 Meta wrapper 의 `gap` (`--li-gap-meta`)이 담당.
+
 ## Props 시그니처
 ```tsx
 <ListItem

package/assets/prompts/components/tab-strip.md

@@ -0,0 +1,144 @@
+# TabStrip
+
+### 원칙
+브라우저·에디터·디자인툴 상단에 늘어선 **"열려있는 문서/파일 탭"** 전용 컴포넌트. 각 탭은 **독립 문서·독립 라우트**를 가리킨다 — Chrome의 창 탭, Figma의 파일 탭, VSCode의 에디터 탭이 전부 같은 자리. 이름은 Chromium/VSCode/Telerik이 공통으로 쓰는 업계 표준어 `TabStrip`.
+
+[[components/tabs]]와 역할이 **완전히 다르다**. Tabs는 "같은 화면 안 섹션 전환"(URL `?tab=activity`), TabStrip은 "열린 N개 중 하나 선택"(각 탭 = 라우트). 섞어 쓰지 말 것 — 한 화면에 TabStrip이 있고 그 아래 Tabs가 있는 건 OK (브라우저 탭 밑에 설정 섹션 탭 있는 꼴).
+
+활성 표시는 **pill·underline이 아니라 bg-muted 배경 상시 유지** — hover 색(bg-muted)이 활성 탭에서 lock된 꼴. "hover되는 자리가 현재 자리"라는 직관.
+
+### Do
+- **각 탭 = 독립 문서/라우트**. 라우팅이나 외부 상태 저장소에 반영 (`?doc=portfolio` 또는 workspace store).
+- **leadingIcon에 자유롭게** — [[components/icon]], `<img>`(파일 썸네일), `<svg>`(브랜드 로고) 전부 ReactNode로 받는다. Figma 파일 탭의 작은 썸네일, VSCode 파일 아이콘 패턴.
+- **닫기는 `closable` prop으로**. x 버튼은 `absolute`로 오른쪽에 띄워 **왼쪽에서 bg-muted 그라데이션으로 라벨 위를 덮으며 등장** — Chrome 긴 탭 패턴. **hover 시에만** fade-in (활성 탭도 hover 아니면 숨김) — 평상시 시각 노이즈 최소화.
+- **긴 라벨은 hover 시 marquee loop** — 라벨이 overflow되면 짧은 지연 후 왼쪽으로 **전광판처럼 끊김 없이** 흐른다 (텍스트 복제본이 뒤를 이어받음). ResizeObserver로 overflow 감지, 짧은 라벨은 자동으로 안 움직임. `prefers-reduced-motion`에선 비활성.
+- **trailing slot은 자유 조립**. `trailing` prop에 ReactNode를 넣으면 탭 묶음 오른쪽에 자리잡음 — `<IconButton icon={<Icon name="plus" />} />` (새 탭), `<IconButton icon={<Icon name="dots-three" />} />` (더보기), 또는 아무것도 안 넣기. TabStrip hover·focus-within 시에만 fade-in.
+- **자리 중립** — Topbar 바로 아래 2번째 줄에 flush로 두거나, Topbar의 center slot에 넣는다. 소비처가 자리를 결정.
+- **키보드**: ← → Home End 지원. Enter/Space로 선택. 활성 탭만 `tabIndex=0` (roving).
+- **라벨은 1줄 cap** — `max-width: 20ch`(md), `16ch`(sm)에서 ellipsis. 문서명이 길면 Tooltip으로 보완.
+
+### Don't
+- **섹션 전환**에 TabStrip 쓰지 말 것 — 그건 [[components/tabs]] underline/segmented/text. 역할 뒤집으면 "탭 안에 탭" 혼동.
+- **활성 색을 `--primary`로 덮지 않는다** — 활성은 `--fg-strong` + `--bg-muted` 무채. 브랜드 컬러는 CTA와 위계가 충돌 ([[components/tabs]]와 동일 원칙).
+- **라벨 가로 폭을 숫자(px)로 고정 금지** — 폰트 축이 바뀌면 깨짐. `ch` 단위 사용.
+- **x 아이콘을 상시 노출하지 말 것** — 시각 노이즈. hover·active에만, 활성 탭은 늘 보이는 게 맞다.
+- **`<svg>` 인라인 금지** — leadingIcon은 Icon·이미지·브랜드 svg는 OK지만 "아이콘용 raw svg"는 [[feedback_no_inline_svg]].
+- **trailing에 생짜 `<button>` 넣지 말 것** — Button·IconButton·DropdownMenu 트리거 등 CTDS 컴포넌트 경유. 자리별 간격·디바이더는 wrapper가 담당하니 소비처는 버튼만 넘김.
+- **탭 사이에 가운뎃점·대시 구분자 금지** — [[feedback_no_bullet_separator]]. 탭 자체가 구분된 블록.
+
+### Fallback
+자리 애매하면 **Topbar 아래 2번째 줄**(shell 2단), size 애매하면 **md** (shell chrome에서도 sm보다 md가 안정적 — Topbar와 같은 리듬).
+
+### 관련
+- [[components/tabs]] — 역할 분리. Tabs=섹션 전환, TabStrip=문서 전환
+- [[components/topbar]] — TabStrip이 가장 자주 조립되는 shell. 아래 줄 또는 center slot
+- [[components/icon]] · [[components/file-icon]] — leadingIcon 자리 (파일 타입 썸네일로 FileIcon 자주 조합)
+- [[components/tooltip]] — 라벨이 ellipsis될 때 전체 문서명 노출
+- [[axes/density]] — `--control-h-*`가 탭 높이에 매핑
+- [[axes/shape]] — 탭 radius가 Shape 축에 반응
+- [[axes/motion]] — hover·active 전환 duration
+- [[tokens/color]] — `--bg-muted`(활성·hover 배경), `--fg-muted` → `--fg-strong` 대비
+
+### Props 시그니처
+```tsx
+<TabStrip
+  variant="ghost | soft | segmented"  // default: ghost
+  size="sm | md"                      // default: md
+  value={string}                      // controlled
+  defaultValue={string}               // uncontrolled 초기값
+  onValueChange={(v) => void}
+  trailing={<ReactNode>}              // 오른쪽 slot. IconButton·DropdownMenu 등 자유 조립
+>
+  <TabStrip.Tab
+    value="revana"
+    leadingIcon={<Icon name="file-text" />}
+    closable
+    onClose={() => removeTab("revana")}
+    closeLabel="탭 닫기"
+  >
+    Revana (copy 2)
+  </TabStrip.Tab>
+  <TabStrip.Tab
+    value="portfolio"
+    leadingIcon={<img src="/figma.svg" alt="" />}
+    closable
+    onClose={() => removeTab("portfolio")}
+  >
+    Portfolio
+  </TabStrip.Tab>
+</TabStrip>
+```
+
+### 상태 매트릭스
+| 상태 | 배경 | 라벨 색 | leading opacity | x + fade | 라벨 marquee |
+|---|---|---|---|---|---|
+| default (inactive) | transparent | `--fg-muted` | 0.75 | opacity 0 | 정지 |
+| hover (inactive) | `--bg-muted` | `--fg` | 1 | fade-in | 지연 후 loop (오버플로우 시) |
+| active (no hover) | `--bg-muted` 상시 | `--fg-strong` | 1 | opacity 0 | 정지 |
+| active + hover | `--bg-muted` | `--fg-strong` | 1 | fade-in | 지연 후 loop (오버플로우 시) |
+| disabled | transparent | opacity 0.5 | 0.5 | opacity 0 | 정지 |
+| focus-visible | — | — | — | `--ring-shadow` | — |
+
+### Variant 가이드
+| variant | 결 | 언제 |
+|---|---|---|
+| `ghost` (default) | 투명 + hover/active bg | shell chrome 기본. 가장 가벼움. 주변 UI와 조용히 어울림. |
+| `soft` | 모든 탭에 연한 bg 상시, 활성이 조금 더 진함 | 탭이 **독립 블록**으로 보여야 할 때. 선택 자리가 또렷. Button 그룹과 리듬 맞음. |
+| `segmented` | 탭 사이 세로 hairline으로 칸 구분 | 브라우저·에디터의 **문서 탭** 표준. 탭 경계가 또렷하고 전통적. |
+
+### Size 가이드
+| size | 언제 |
+|---|---|
+| `sm` | 밀도 승부처 (사이드바 내부 docked, 좁은 패널) |
+| `md` | 기본. Topbar 아래 shell 2번째 줄 |
+
+### 조합 예시
+
+```tsx
+// Topbar 아래 줄 (Figma·Chrome 패턴)
+<Topbar>
+  <Topbar.Leading><IdentityButton …/></Topbar.Leading>
+  <Topbar.Trailing>…</Topbar.Trailing>
+</Topbar>
+<div className="shell-row-2">
+  <TabStrip
+    value={active}
+    onValueChange={setActive}
+    trailing={
+      <IconButton
+        variant="ghost"
+        icon={<Icon name="plus" />}
+        aria-label="새 문서"
+        onClick={handleNewDoc}
+      />
+    }
+  >
+    {docs.map((d) => (
+      <TabStrip.Tab
+        key={d.id}
+        value={d.id}
+        leadingIcon={<FileIcon ext={d.ext} />}
+        closable
+        onClose={() => closeDoc(d.id)}
+      >
+        {d.title}
+      </TabStrip.Tab>
+    ))}
+  </TabStrip>
+</div>
+```
+
+```tsx
+// Topbar center slot (탭 2~4개로 적을 때)
+<Topbar>
+  <Topbar.Leading><IdentityButton …/></Topbar.Leading>
+  <Topbar.Center>
+    <TabStrip value={view} onValueChange={setView} size="sm">
+      <TabStrip.Tab value="design">Design</TabStrip.Tab>
+      <TabStrip.Tab value="code">Code</TabStrip.Tab>
+      <TabStrip.Tab value="specs">Specs</TabStrip.Tab>
+    </TabStrip>
+  </Topbar.Center>
+  <Topbar.Trailing>…</Topbar.Trailing>
+</Topbar>
+```

package/assets/prompts/components/toolbar.md

@@ -1,14 +1,16 @@
 # Toolbar
 
 ### 원칙
-IconButton 중심의 action 줄. 에디터·캔버스·갤러리 상단, 또는 "뜨 있는" 알약으로 콘텐츠 위에 떠서 액션을 모으는 자리. 단일 size — toolbar 안의 버튼은 전부 같은 사이즈여야 한다.
+IconButton 중심의 action 줄. 에디터·캔버스·갤러리 상단, 또는 "뜨 있는" 알약으로 콘텐츠 위에 떠서 액션을 모으는 자리. toolbar 안의 버튼은 전부 같은 사이즈 — Toolbar의 `size` prop이 안쪽 IconButton 히트박스·아이콘을 한 번에 결정.
 
 ### Do
 - `variant="floating"` 기본 — bg-elevated + shadow-md + radius-xl, 콘텐츠 위에 떠있는 알약. 캔버스·에디터·이미지 뷰어의 상단 중앙.
 - `variant="attached"`는 콘텐츠에 붙은 bar — transparent + 하단 hairline. 페이지 상단에 "탭 아래 액션 바"로 쓸 때.
 - 관련 액션은 `<Toolbar.Group>`으로 묶는다 — 내부는 좁은 gap, 그룹 간은 `<Toolbar.Divider>`.
 - 좌·우 정렬이 필요하면 `<Toolbar.Spacer>`로 공간 밀기 — flex:1.
-- toolbar 안엔 IconButton size="sm"이 기본. floating variant는 size="md"까지도 OK.
+- `size="md"`(기본) — 히트박스 32·아이콘 20. 캔버스·에디터 상단 표준 자리.
+- `size="sm"` — 히트박스 24·아이콘 16. 사이드바 바닥·인라인 bar처럼 밀도 승부처.
+- 안쪽 IconButton은 size prop을 넘기지 않는다 — Toolbar가 CSS 변수로 자동 매칭.
 
 ### Don't
 - toolbar 안에 label 긴 Button을 섞지 않는다 — IconButton + Tooltip이 toolbar 패턴. 긴 label이 필요하면 그 자리는 toolbar가 아니라 액션 영역.
@@ -20,6 +22,7 @@ IconButton 중심의 action 줄. 에디터·캔버스·갤러리 상단, 또는
 ```tsx
 <Toolbar
   variant?="floating | attached"              // default: floating
+  size?="sm | md"                              // default: md (히트박스 32·아이콘 20)
   stretch?={boolean}                           // default: variant로 자동 (attached=true, floating=false)
   role?={string}                               // default: "toolbar"
 >

package/assets/prompts/components/topbar.md

@@ -17,6 +17,7 @@
 - zone 밖에 **자식을 바로 넣지 않는다**. `<Topbar><Breadcrumb/>...</Topbar>` 같은 구조 금지 — 반드시 Leading/Center/Trailing 중 하나로 감싼다.
 - `h1`·큰 hero head·환영 메시지("good morning, …")·페이지 섹션 타이틀을 Topbar 안에 넣지 않는다 — Topbar는 **얇은 축**이고 큰 타이포가 들어가는 순간 `align-items` 전쟁이 벌어진다. 이걸 로컬 CSS로 때우는 순간(`align-items: flex-start`, `padding-bottom` override 등) Topbar의 "축" 약속이 깨지고, 아래 body와의 수직 리듬도 어긋난다. hero는 body의 첫 섹션으로 꺼낸다.
 - 수직 스택(eyebrow + title 세로 두 줄 같은 조합)을 Topbar 안에 넣지 않는다. 수직 리듬은 body의 섹션 head에서.
+- **[HARD] Topbar 안 IdentityButton 에 `sub` prop 금지** ([[feedback_topbar_single_line_identity]]) — 2줄 모드가 Topbar "얇은 축" 리듬을 깬다. 2줄이 필요하다 느껴지면 자리 자체가 틀림: 콘텐츠 소속감이 필요한 자리면 PageHeader(body 안), 네비게이션 소속감이면 Sidebar.Footer 로 옮긴다.
 - 알림·검색·Breadcrumb 외의 **콘텐츠**(KPI·요약·공지 문구)를 Topbar에 끼우지 않는다. 그건 body hero 섹션 또는 Callout의 자리.
 - Topbar에 로컬 `padding`·`align-items`를 override해서 "큰 요소 끼운 걸 수습"하지 않는다 — 수습이 필요한 순간 그 요소가 Topbar의 자리가 아니라는 신호.
 - 자체 bg/border/shadow 추가 금지 — AppFrame variant가 쥐고 있는 자리.

package/assets/prompts/primitives/scroll.md

@@ -38,12 +38,19 @@
 
 ### 스크롤바 시각 정책 (전역, globals.css)
 
+핵심은 **overlay 방식 전용** — 스크롤바는 콘텐츠 위에 뜨기만 하고 **공간을 먹지 않는다**. 공간을 먹는 "고정 스크롤바" 는 다크 모드에서 OS·브라우저 조합이 트랙·코너를 흰색으로 강제 렌더해 그 자리가 하얗게 뜨는 함정이 있어 영구 금지 ([[feedback_scrollbar_no_fixed_track]]).
+
 - 평상시: thumb 투명 → 스크롤바 자리는 있지만 안 보임 (overlay)
 - 부모 `:hover` 또는 `:focus-within`: thumb에 `--border-strong` 페이드 인
 - thumb `:hover`: `--fg-muted`로 진해짐
-- 두께: `--scrollbar-size` 토큰 (Density 축 영향 없음, 고정)
+- 두께: `--scrollbar-size` 토큰 — overlay 두께이지 공간 할당 아님. 커지면 overlay 가 더 두껍게 뜰 뿐, 콘텐츠는 안 밀림.
 - macOS 방식(사용 중일 때만 얇게 노출) — Notion/Linear/Figma 스타일
 
+#### Don't (스크롤바)
+- `scrollbar-gutter: stable` 로 트랙 공간 미리 확보하기 — 그게 "고정 스크롤바" 다.
+- 컴포넌트/페이지에서 `::-webkit-scrollbar-*` 또는 `scrollbar-*` 를 재선언해 트랙 폭을 만들기.
+- 평상시에도 트랙·thumb 이 보이는 "always visible" 스타일. 특히 다크 모드에서 흰 띠가 뜸.
+
 ### 스크롤 페이드 (edge fade mask)
 
 스크롤로 잘려나가는 콘텐츠 경계를 부드럽게 처리. 사용자에게 "더 있음"을 암시하면서 카드 벽에 텍스트가 딱 붙는 느낌을 없앤다.

package/assets/prompts/recipes/page-header.md

@@ -14,7 +14,7 @@
 
 - eyebrow와 title 사이: `space-1`
 - title과 description 사이: `space-2`
-- 블록 전체 아래 (다음 섹션까지): `space-6` (앱 리듬) / `space-10` (랜딩 리듬)
+- **블록 전체 아래 (다음 섹션까지)의 간격은 상위 wrapper 의 `gap` 이 담당**. `space-6` (앱 리듬) / `space-10` (랜딩 리듬). PageHeader 자체는 `margin-bottom` 을 걸지 않는다 ([[feedback_page_header_no_bottom_margin]]).
 - actions는 title과 같은 row — `align-items: center`, `flex: 1 1 auto` title / `flex: 0 0 auto` actions
 
 ### Do
@@ -34,29 +34,43 @@
 서브텍스트가 애매하면 생략. 설명이 1줄 미만이면 쓰지 않는다. actions도 없으면 h1 단독으로.
 
 ### 조립 예시
+
+PageHeader → 다음 섹션 사이 간격은 **외부 wrapper 가 담당**. PageHeader 자체는 `margin-bottom` 을 걸지 않음.
+
 ```tsx
-<header className="page-header">
-  {/* eyebrow 옵션 */}
-  <div className="eyebrow">프로젝트</div>
-  <div className="title-row">
-    <h1>개발 계획·실행</h1>
-    <div className="actions">
-      <Button variant="outline" size="md">가져오기</Button>
-      <Button variant="primary" size="md">새 계획</Button>
+<div className="page-shell">
+  <header className="page-header">
+    {/* eyebrow 옵션 */}
+    <div className="eyebrow">프로젝트</div>
+    <div className="title-row">
+      <h1>개발 계획·실행</h1>
+      <div className="actions">
+        <Button variant="outline" size="md">가져오기</Button>
+        <Button variant="primary" size="md">새 계획</Button>
+      </div>
     </div>
-  </div>
-  <p className="description">
-    확정본을 선택해 개발 계획을 요청하고, 계획과 작업 범위를 승인한 뒤 실행하세요.
-  </p>
-</header>
+    <p className="description">
+      확정본을 선택해 개발 계획을 요청하고, 계획과 작업 범위를 승인한 뒤 실행하세요.
+    </p>
+  </header>
+
+  {/* 다음 섹션 — gap 이 PageHeader 와 섹션 사이 간격을 공급 */}
+  <section>...</section>
+</div>
 ```
 
 ```css
+.page-shell {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-6);   /* 앱 리듬. 랜딩이면 --space-10 */
+}
+
 .page-header {
   display: flex;
   flex-direction: column;
   gap: var(--space-1); /* eyebrow→title */
-  margin-bottom: var(--space-6);
+  /* margin-bottom 금지 — 상위 .page-shell 의 gap 이 담당 */
 }
 .page-header .title-row {
   display: flex;

package/assets/skills/ctds-wireframe/SKILL.md

@@ -99,6 +99,11 @@ description: 와이어프레임·목업·기존 페이지를 CTDS로 번역·교
 - **그룹핑 재편**: 역할이 같은 것은 하나의 Section/Card에, 다른 것은 분리.
 - **원본에 없던 CTDS 패턴 추가**: EmptyState·Toolbar·Breadcrumb 등 원본엔 없지만 CTDS 페이지에 필요한 요소는 **추가하는 게 기본**.
 - **벤더에 없는 자리는 레시피 참조**: 페이지 헤더·섹션 헤더·카드 row·메타 라인·폼 푸터·안내 배너 등 자주 등장하는 자리는 `prompts/recipes/<자리>.md`를 **반드시 열어** 토큰·구조 조합을 확인. 수제 조립로 가지 않는다 ([[ASSEMBLY]]).
+- **Sidebar 패딩 공급 계획 — 조립 코드 작성 전에** ⭐ ([[feedback_wireframe_sidebar_padding_check]]) 번역 결과에 Sidebar 가 포함되면 글로 적어서 확정하고 넘어간다:
+  - `Sidebar.Header` 안쪽 패딩은 누가 공급하는가? (벤더는 공급 안 함)
+  - `Sidebar.Body` 안 섹션 패딩은 누가 공급하는가? preset slot(`data-sidebar-slot`) vs 콘텐츠 래퍼 vs 바깥 flex 조립 중 하나로 결정.
+  - `Sidebar.Footer` 가 있으면 안쪽 패딩은 누가 공급하는가?
+  - 결정 없이 바로 조립 들어가면 메뉴·검색이 가장자리에 붙음.
 
 ## 체크리스트 — 번역 완료 전 전부 통과
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@conscience-technology/ctds",
-  "version": "0.4.3",
+  "version": "0.4.5",
   "description": "CTDS — 하이브리드 디자인 시스템 설치 · 온보딩 CLI (shadcn식 코드 생성기)",
   "type": "module",
   "sideEffects": [
@@ -48,9 +48,9 @@
     "directory": "packages/ctds-cli"
   },
   "peerDependencies": {
-    "react": ">=18.2.0",
-    "react-dom": ">=18.2.0",
-    "next": ">=14.0.0",
+    "react": ">=18.2.0 <20.0.0",
+    "react-dom": ">=18.2.0 <20.0.0",
+    "next": ">=14.0.0 <17.0.0",
     "@phosphor-icons/react": "^2.1.10",
     "solar-icon-set": "^2.0.1",
     "lucide-react": "^1.47.0",

package/src/commands/init.js

@@ -23,7 +23,13 @@ import { checkMissingDeps, renderInstallCmd } from "../utils/deps.js";
 import { c, step, success, warn, info, kv } from "../utils/log.js";
 import { computeFilesMap, writeMeta } from "../utils/meta.js";
 import { hasDevScript, startDevAndOpen } from "../utils/launch.js";
-import { patchGlobalsCss, patchLayoutTsx, inspectNextConfig } from "../utils/patch.js";
+import {
+  patchGlobalsCss,
+  patchLayoutTsx,
+  patchNextConfig,
+  patchPostCssConfig,
+  hasPkgDep,
+} from "../utils/patch.js";
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 const CLI_PKG_PATH = join(__dirname, "..", "..", "package.json");
@@ -58,9 +64,20 @@ export async function run(args) {
   kv("경로", cwd);
   kv("app router", project.appDir);
   kv("src/ 사용", project.useSrcDir ? "yes" : "no");
+  if (project.nextVersion) kv("next", project.nextVersion);
   if (dry) kv("모드", c.yellow("dry run (쓰기 없음)"));
   console.log("");
 
+  // Next 16+는 create-next-app이 `@tailwindcss/turbopack` + `turbopack.rules["*.css"]`를
+  // 자동 생성하는데, 그 룰이 built-in Lightning CSS CSS Modules 경로를 bypass해버려
+  // `.module.css`의 class export가 전부 undefined로 깨짐. 아래 자동 패치로 Tailwind를
+  // PostCSS 경로로 옮기면 Next 15/16 모두 안전하게 작동. (아래 patchNextConfig/
+  // patchPostCssConfig가 그 역할.)
+  if (project.nextMajor != null && project.nextMajor >= 16) {
+    info(`Next.js ${project.nextMajor} 감지 — Tailwind를 PostCSS 경로로 자동 전환합니다.`);
+    console.log("");
+  }
+
   const assets = getAssetSources();
   info(`자산 소스: ${assets.mode === "bundled" ? "번들" : "로컬 레포"}`);
   console.log("");
@@ -175,15 +192,53 @@ export async function run(args) {
     });
   }
 
-  // 3-3) next.config의 Turbopack *.css 전역 룰 감지
-  // (Tailwind create-next-app 등으로 생성된 설정에서 .module.css가 undefined로 깨지는 함정)
-  const nextCheck = inspectNextConfig(cwd);
-  if (nextCheck.status === "risk") {
+  // 3-3) next.config의 turbopack.rules["*.css"] 삭제 + Tailwind를 PostCSS로 전환.
+  // Next 15 사용자는 next.config가 영향 없고 (룰이 없음), Next 16은 자동 복구.
+  const nextResult = patchNextConfig(cwd, { dry });
+  if (nextResult.status === "applied") {
+    const name = (nextResult.filePath ?? "next.config").split("/").pop();
+    step(dry ? `[dry] 패치` : `패치`, `${name} — turbopack.rules의 *.css 삭제`);
+  } else if (nextResult.status === "failed") {
+    warn(`next.config 자동 패치 실패: ${nextResult.reason}`);
     manualFallbacks.push({
-      title: `${c.cyan(nextCheck.name)}의 turbopack.rules가 *.css를 전역 처리하고 있어요. CSS Modules가 깨질 수 있으니 *.module.css 제외 룰을 추가:`,
+      title: `${c.cyan("next.config.ts")}에서 ${c.bold(`turbopack.rules["*.css"]`)} 블록을 통째로 삭제하세요.`,
       lang: "ts",
-      body: `turbopack: {\n  rules: {\n    "*.css": { loaders: [/* 기존 설정 */], as: "*.css" },\n    "*.module.css": {}, // ← CSS Modules는 Next 기본 처리로 넘김\n  },\n},`,
-      note: "증상: styles.foo가 undefined로 import됨 → 레이아웃 전부 깨짐.",
+      body: `// 삭제 전\nturbopack: {\n  rules: {\n    "*.css": { loaders: ["@tailwindcss/turbopack"], as: "*.css" },\n  },\n},\n\n// 삭제 후 — turbopack 블록 자체 제거`,
+      note: "이 룰이 Lightning CSS CSS Modules 경로를 bypass해 .module.css class를 global로 처리하게 만듦.",
+    });
+  }
+
+  // 3-4) PostCSS 설정 — Tailwind 사용 플젝에만. postcss.config이 없으면 신규 생성해
+  // Next 16 native PostCSS 처리로 Tailwind를 돌리게. @tailwindcss/turbopack 대체.
+  const hasTailwind = hasPkgDep(cwd, "tailwindcss");
+  const postCssResult = patchPostCssConfig(cwd, { dry, hasTailwind });
+  if (postCssResult.status === "applied") {
+    step(dry ? `[dry] 생성` : `생성`, `postcss.config.mjs — @tailwindcss/postcss plugin`);
+  } else if (postCssResult.status === "failed") {
+    warn(`postcss.config 자동 패치 실패: ${postCssResult.reason}`);
+    manualFallbacks.push({
+      title: `${c.cyan(postCssResult.filePath?.split("/").pop() ?? "postcss.config.mjs")}에 ${c.bold("@tailwindcss/postcss")} 플러그인을 추가:`,
+      lang: "js",
+      body: `export default {\n  plugins: { "@tailwindcss/postcss": {} },\n};`,
+    });
+  }
+
+  // 3-5) @tailwindcss/postcss 미설치 안내 (Tailwind 쓰는데 플러그인 없는 경우)
+  if (hasTailwind && !hasPkgDep(cwd, "@tailwindcss/postcss")) {
+    manualFallbacks.push({
+      title: `${c.bold("@tailwindcss/postcss")}를 설치하세요 (Tailwind가 PostCSS 경로로 작동):`,
+      lang: "bash",
+      body: `npm install -D @tailwindcss/postcss`,
+    });
+  }
+
+  // 3-6) @tailwindcss/turbopack이 설치돼 있으면 제거 안내 (자동 삭제는 npm 호출이 리스크)
+  if (hasTailwind && hasPkgDep(cwd, "@tailwindcss/turbopack")) {
+    manualFallbacks.push({
+      title: `${c.bold("@tailwindcss/turbopack")}은 더이상 필요 없어요. 제거하세요:`,
+      lang: "bash",
+      body: `npm uninstall @tailwindcss/turbopack`,
+      note: "@tailwindcss/postcss가 Turbopack native PostCSS 경로로 Tailwind를 처리합니다.",
     });
   }
 

package/src/utils/detect.js

@@ -19,10 +19,10 @@ export function detectProject(cwd) {
     return { ok: false, reason: `package.json 파싱 실패: ${e.message}` };
   }
 
-  const hasNext =
+  const nextRange =
     (pkg.dependencies && pkg.dependencies.next) ||
     (pkg.devDependencies && pkg.devDependencies.next);
-  if (!hasNext) {
+  if (!nextRange) {
     return {
       ok: false,
       reason: "package.json에 next 의존성이 없습니다. Next.js 플젝이 아닙니다.",
@@ -38,10 +38,22 @@ export function detectProject(cwd) {
     };
   }
 
+  // Next major 버전 감지. "^16.4.1" / "16.0.0" / ">=15.0.0 <17.0.0" 등 느슨히 커버.
+  // 못 뽑으면 null — 경고 없이 통과.
+  const nextMajor = parseMajor(nextRange);
+
   return {
     ok: true,
     name: pkg.name ?? "(unnamed)",
     useSrcDir,
     appDir: useSrcDir ? "src/app" : "app",
+    nextVersion: nextRange,
+    nextMajor,
   };
 }
+
+/** semver range 문자열에서 유의미한 major 숫자 하나 추출. 범위면 하한 기준. */
+function parseMajor(range) {
+  const m = String(range).match(/\d+/);
+  return m ? Number(m[0]) : null;
+}