@conscience-technology/ctds 0.0.0-stage → 0.1.1

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

@@ -0,0 +1,235 @@
+# ListItem
+
+### 원칙
+피드·알림·인박스·활동 로그에 반복해서 등장하는 "누가 뭘 했다" 한 줄의 최소 단위. GitHub Timeline · Linear Activity · Jira Issue history · Slack Notification · Notion Updates가 모두 이 형태다. 시각 구조와 상태 신호(unread/urgent)만 담당하고, 그룹핑·필터·무한스크롤·mark-as-read 같은 흐름은 상위 컨테이너가 책임진다.
+
+같은 anatomy 안에서 **variant로 자리의 성격만 바꾼다** — `activity`(과거 서술), `notification`(처리 필요), `mention`(인용), `system`(사람 아님). variant를 늘리기 전에 slot(`leading`/`trailing`/`hoverActions`)으로 조립이 되는지 먼저 본다.
+
+컴포넌트 자신은 **단일 row**다. border/divider/카드 chrome을 자체적으로 지지 않는다 — 리스트로 묶는 건 부모 레이아웃이 결정한다. 운영 콘솔은 border로, pure 좌표는 hairline으로, 카드 안 리스트는 Callout이 담당. ([[components/metric-card]]의 `bare` variant와 같은 원리.)
+
+**단, "chrome 없음"은 완전한 공간 없음을 뜻하지 않는다** — ListItem은 `padding-block: var(--space-3) + margin-block: -var(--space-3)`의 **self-contained 상쇄 공식**을 가진다. 부모가 세로 padding을 안 걸어도 row hover hit area가 보장되게 하려는 안전장치다. 하지만 flex item 레이아웃에서는 음의 margin이 레이아웃 박스를 축소하지 못해 **ListItem이 "상쇄된 자리"를 실제로 차지한다** — 부모 li가 padding을 또 걸면 두 번 공간이 쌓여 과하게 보인다. 자세한 공식·완화법은 아래 "조립 — 부모 wrapper 공식" 섹션.
+
+### Do
+- **anatomy는 네 자리로 고정**: `[leading] [who] [body / verb+target] [meta/trailing]`. 어떤 variant든 이 뼈대를 깨지 않는다.
+- **layout은 두 형태**: `inline`(한 줄, 기본) · `stacked`(두 줄 — from이 1줄, body가 2줄). 서술 모드 둘 다에서 작동 — action 모드 stacked는 "from · verb · target" + body 2줄째, 서술 모드 stacked는 from + body 2줄째. 긴 서술/인용/멘션은 stacked.
+- **서술은 두 모드 중 하나로**: 자유 서술은 `from` + `body`("회계팀 — 외주비 결재 요청"), 액션 서술은 `from` + `verb` + `target`("박지훈 · 댓글 남김 · ERP 2.0 사이드바"). 둘 다 넘기지 않는다.
+- **unread는 텍스트 톤으로만 신호** (dot/badge 없음): `unread={true}`면 body/from이 가장 진하고 meta는 `--primary` 컬러로 "지금"을 강조. `unread={false}`면 전체 톤이 한두 단계 뒤로 물러나 "이미 처리됨"을 시사. `unread` 생략(undefined)이면 중립 — **리드/언리드 개념 자체가 없는 자리**(활동 로그·히스토리·타임라인)에서 자유롭게 사용.
+- **surface는 작은 inline 토큰**: `surface="GitHub"` 같은 서비스명은 target 뒤 작게 inline. [[components/badge]] variant="soft"로 렌더되지만 text-only로 유지.
+- **meta는 상대시간 한 토큰**: "방금", "12분", "어제". ISO 날짜는 Tooltip으로 보조.
+- **hover-only 액션은 명시적으로**: `hoverActions={[<IconButton name="archive"/>, ...]}` — Linear Inbox의 archive/snooze/mark-read 패턴. 평상시 숨김, row hover/focus/focus-within에서 등장. [[components/menu-item]]의 hoverOnly와 같은 메커니즘.
+- **row 전체 클릭은 `href`로**: 라우팅 아이템이면 asChild로 `<Link>`에 위임. target만 링크로 쓰고 row는 비활성인 자리도 OK.
+- **leading 정책은 리스트 단위로 통일**: 일부엔 Avatar, 일부엔 Icon처럼 섞으면 "누구"의 자리가 어긋난다. system 메시지가 섞이는 리스트면 전부 Avatar fallback(이니셜) + system은 서비스 로고 Avatar.
+- **leading 타입은 세 종류**: Avatar(사람·팀), Icon(단색 글리프), `ListItemLeadingIcon`(배경색 + 아이콘 마크). 세 번째는 "서비스/시스템이 상태를 색으로 신호"하는 자리 — tone 프리셋(`primary · success · warning · danger · info · neutral`)으로 bg/fg 쌍을 한 번에, 혹은 `--leading-icon-bg` · `--leading-icon-fg` 변수로 세밀 조절. Avatar와 같은 사이즈 트랙(xs/sm/md/lg)이라 섞여도 정렬 유지. 추가로 `size="auto"`는 `layout="stacked"`와 짝 — content 두 줄 전체 높이에 맞춰 정사각으로 stretch, 상태 마크를 크게 보여야 하는 알림/시스템 메시지 자리.
+- **density는 컨테이너에 맡긴다**: ListItem 자체는 size prop 없이, 부모 리스트의 density(또는 Density 축) 토큰을 상속한다.
+
+### Don't
+- `verb` + `body` 동시 사용 금지 — 서술 중복. 액션 모드와 서술 모드는 배타.
+- 채팅뷰처럼 긴 메시지 본문을 그대로 노출하지 않는다 — ListItem은 "누가 어디서 뭘 했다" 요약 라인이지, 메시지 내용의 복사본이 아니다. 멘션/댓글이어도 `verb` + `target`("어디/뭐에")로 축약하고 상세는 target 클릭 뒤 전체 뷰에서. 인용부호를 둘러친 긴 body도 금지.
+- `leading`을 생략하고 unread dot만 두지 않는다 — dot 혼자 떠서 "누구"의 자리가 사라진다. system 메시지는 서비스 로고/아이콘 Avatar를 세운다.
+- body를 두 줄 이상으로 늘리지 않는다 — 길면 `layout="stacked"`로 자동 승격해 target 라인과 서술 라인을 분리하거나, [[components/callout]] 영역으로 넘긴다.
+- `trailing` + `hoverActions`를 둘 다 넘기지 않는다 — 메타 자리 하나뿐. 상시 메타(카운트·시간)와 hover 액션이 공존해야 하면 `trailing`에 배열로.
+- unread/urgent를 색으로 중복 신호하지 않는다 — dot만. body 색을 fg-strong으로 올리거나 배경을 깔면 과잉.
+- 자체적으로 padding·border·bg는 두지 않지만 **hover bg는 예외** — row 레벨 상호작용 피드백은 "가두는 chrome"이 아니라 "지금 이 줄" 신호이므로 default로 켜져 있다. pure 좌표에서 끄려면 색상 훅 `--list-item-hover-bg: transparent`.
+- "댓글 남김" 같은 동사를 긴 서술로 늘이지 않는다. verb는 **동사 토큰** 하나. 긴 설명은 target 아래 2줄 body로 승격.
+
+### Fallback
+variant 애매하면 `activity`. layout 애매하면 `inline`. leading 애매하면 `from` 기반 Avatar(이니셜).
+
+### 색상 훅 (컨테이너 단위 톤 조절)
+MenuItem과 같은 패턴. 리스트 wrapper에 변수를 얹으면 안쪽 ListItem이 일괄 반응.
+
+| 훅 | 대상 | 폴백 |
+|---|---|---|
+| `--list-item-fg` | 본문 서술 색 | `--fg` |
+| `--list-item-from-fg` | from(누구) 색 | `--fg-strong` |
+| `--list-item-meta-fg` | meta/상대시간 색 | `--fg-muted` |
+| `--list-item-hover-bg` | row hover bg | `--hover` |
+
+```css
+/* 예: 조용한 활동 로그 — 메타·본문 전부 한 단계 뒤로 */
+.quiet-activity {
+  --list-item-fg: var(--fg-muted);
+  --list-item-meta-fg: var(--fg-subtle);
+}
+
+/* 예: 긴급 알림 리스트 — unread dot을 warning 톤으로 */
+.urgent-notifications {
+  --list-item-unread: var(--warning);
+}
+```
+
+### Props 시그니처
+```tsx
+<ListItem
+  // 왼쪽
+  leading={ReactNode}             // Avatar | Icon | 커스텀. 생략 가능 (system에서도 가능하면 Avatar fallback 권장)
+  unread={boolean}                // 명시해야 톤 신호. undefined=중립, true=강조, false=뒤로
+
+  // 본문 — 두 모드
+  from={ReactNode}                // "회계팀" / "박지훈" / "ERP"
+  body={ReactNode}                // 자유 서술 모드
+  verb={ReactNode}                // "댓글 남김" — 액션 모드
+  target={ReactNode}              // 대상. 링크 자리로 자주 쓰임
+  surface={ReactNode}             // "Figma" · "GitHub" — target 뒤 작게 inline
+
+  // 메타
+  meta={ReactNode}                // "방금" · "12분". 오른쪽 끝 default
+  trailing={ReactNode}            // meta 자리 커스텀 (ReactNode 또는 배열)
+  hoverActions={ReactNode[]}      // row hover 시 등장. archive/snooze/⋯
+
+  // 레이아웃·상호작용
+  variant="activity | notification | mention | system"  // default: activity
+  layout="inline | stacked"       // default: inline. stacked는 body 2줄.
+  href={string}                   // row 전체 링크. asChild로 Link 위임.
+  onClick={(e) => void}           // row 선택 핸들러
+  asChild={boolean}               // <Link> 등에 위임
+/>
+```
+
+### Variant 매트릭스
+같은 anatomy, 다른 **기본 성격**. slot으로 못 바꾸는 자리만 variant로 바꾼다.
+`unread`는 variant가 강제하지 않는다 — 명시해야 신호. 리드 개념이 없는 자리면 생략.
+
+| variant | leading 기본 | hoverActions 전제 | 서술 모드 선호 | 쓰임 |
+|---|---|---|---|---|
+| `activity` | Avatar(from) | 없음 | verb+target | 최근 활동·히스토리 로그. GitHub/Linear timeline. 보통 unread 생략 |
+| `notification` | Avatar(from) | archive/mark-read | from+body | 알림 센터·bell 드롭다운. unread 명시 권장 |
+| `mention` | Avatar(from) | reply/resolve | from+body(인용) | 멘션·댓글 피드. body에 인용부호 자연스러움 |
+| `system` | Icon(서비스 로고) | 없음 | from+body | ERP/CI/빌드 등 시스템 이벤트. 보통 unread 생략 |
+
+### 금지 조합
+- `verb` + `body` 동시 — 서술 중복
+- `leading=null` + `unread=true` — dot이 혼자 떠서 "누구" 자리가 사라짐
+- `trailing` + `hoverActions` — 메타 자리 충돌 (상시+hover면 trailing에 배열)
+- `layout="inline"` + body 2줄 이상 — stacked로 승격
+- `variant="system"` + Avatar(사람 이름) — system은 서비스 아이덴티티
+- 한 리스트 안에 variant 혼용 — 리스트 톤은 하나로. 섞어야 하면 섹션으로 분리
+
+### 조합 예시
+
+```tsx
+// 1) 최근 활동 피드 — verb+target 액션 서술
+<ListItem
+  leading={<Avatar name="박지훈" />}
+  from="박지훈"
+  verb="댓글 남김"
+  target="ERP 2.0 사이드바 구조 확정"
+  surface="Figma"
+  meta="방금"
+/>
+
+// 2) 알림 센터 — unread + hoverActions
+<ListItem
+  variant="notification"
+  leading={<Avatar name="회계팀" />}
+  from="회계팀"
+  body="외주비 세금계산서 결재 요청"
+  meta="방금"
+  unread
+  hoverActions={[
+    <IconButton name="archive" aria-label="보관" />,
+    <IconButton name="check" aria-label="읽음 처리" />,
+  ]}
+/>
+
+// 3) 멘션 — body에 인용 (stacked로 2줄)
+<ListItem
+  variant="mention"
+  layout="stacked"
+  leading={<Avatar name="장대표" />}
+  from="장대표"
+  body={<>&ldquo;@김희영 1:1 전에 자료 공유 부탁&rdquo;</>}
+  meta="오전 9:12"
+  unread
+/>
+
+// 4) 시스템 이벤트 — Icon leading, 사람 아님
+<ListItem
+  variant="system"
+  leading={<Icon name="chart-line" />}
+  from="ERP"
+  body="주간 리포트 생성 완료"
+  meta="3시간"
+/>
+
+// 4-b) 상태 색을 띤 아이콘 마크 leading — 성공/경고/실패 신호
+<ListItem
+  variant="system"
+  leading={
+    <ListItemLeadingIcon tone="success">
+      <Icon name="seal-check" />
+    </ListItemLeadingIcon>
+  }
+  from="CI"
+  body="main 브랜치 배포 성공"
+  meta="방금"
+/>
+
+// 5) pure 좌표 — 부모 리스트가 hairline으로 분리 (조립 공식 "패턴 C" 참고)
+// li에 세로 padding + ListItem self-space 중화 둘 다 필요하다.
+<ul className="pureFeed">
+  {feed.map((f) => (
+    <li key={f.id}>
+      <ListItem
+        leading={<Avatar name={f.from} />}
+        from={f.from}
+        body={f.body}
+        meta={f.ago}
+        unread={f.unread}
+      />
+    </li>
+  ))}
+</ul>
+```
+
+### 조립 — 부모 wrapper 공식
+ListItem은 **self-contained 상쇄 공식**(`padding-block: --space-3` + `margin-block: -(--space-3)`)을 들고 있다. 부모가 공간을 안 걸어도 보장되는 안전장치지만, 조립할 때 아래 세 패턴을 혼동하면 세로가 과하거나 콘텐츠가 선에 붙는다.
+
+**패턴 A — 부모가 간격 아예 안 걸음 (단독 사용):**
+그대로 둬도 ListItem이 자체 공간을 가진다. hover hit area는 보장되지만 **리스트처럼 세로로 쌓이면 아이템끼리 바로 붙는다** — 리스트 자리면 패턴 B/C로.
+
+**패턴 B — 부모 li에 padding만 걸고 ListItem self-space는 그대로:**
+flex item 레이아웃에서 ListItem의 음의 margin이 레이아웃 박스를 축소시키지 못해 **공간이 두 번 쌓인다** (li padding + ListItem self-padding). 겉보기엔 세로가 과하게 커진다 — hairline과 콘텐츠 사이 호흡은 보이지만 리스트가 전반적으로 숨 막혀 보이면 이 상태다.
+
+**패턴 C — li padding + ListItem self-space 중화 (권장, pure 좌표):**
+부모 wrapper가 세로 공식을 완전히 책임지는 자리에서는 자식 선택자로 ListItem self-padding·margin을 둘 다 0으로 눌러 공식을 **하나로 통일**한다. 이게 "콘텐츠가 hairline에 붙지 않으면서도 세로가 과하지 않은" 유일한 조립.
+
+```css
+/* pure 좌표 — hairline 리스트 */
+.activityList {
+  list-style: none;
+  margin: 0;
+  padding: 0;
+  display: flex;
+  flex-direction: column;
+  --list-item-hover-bg: transparent; /* 가두는 chrome 회피 */
+}
+.activityList > li {
+  padding-block: var(--space-3);     /* 세로 호흡은 li가 전담 */
+  border-top: 1px solid var(--border-subtle, var(--border));
+}
+.activityList > li:last-child {
+  border-bottom: 1px solid var(--border-subtle, var(--border));
+}
+/* ListItem self-space 중화 — 자식 선택자로 */
+.activityList > li > * {
+  padding-block: 0;
+  margin-block: 0;
+}
+```
+
+**조립 체크리스트 — 리스트에 쓰기 전 아래를 순서대로:**
+1. 리스트인가? (하나만이면 그대로 둬도 OK)
+2. 부모 wrapper가 세로 padding을 책임질 것인가? (hairline 리스트면 반드시 YES)
+3. YES면 자식 선택자로 ListItem self-padding·margin을 중화했는가?
+4. 완성 후 콘텐츠가 hairline/테두리에 **padding 없이 붙어 있지 않은가** 눈으로 확인.
+
+### 관련
+- [[components/avatar]] — leading의 default 렌더. system variant에서는 서비스 로고 Avatar.
+- [[components/menu-item]] — hoverOnly 패턴을 동일한 메커니즘으로 재사용.
+- [[components/badge]] — surface가 inline soft Badge로 렌더되는 경우.
+- [[components/callout]] — body가 2줄을 넘고 CTA가 필요하면 Callout 영역.
+- [[components/metric-card]] — 자신이 chrome을 지지 않고 부모가 분리를 담당하는 원칙(`bare` variant)과 같은 설계 철학.
+- [[axes/density]] — compact에선 수직 padding/gap이 줄어 timeline이 조밀해짐.
+- [[tokens/color]] — `--primary`(unread meta) · `--fg` · `--fg-strong` · `--fg-muted` · `--fg-subtle`만 사용.
+- [[feedback_no_uppercase]] — verb·surface·meta 어디에도 uppercase 금지.

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

@@ -0,0 +1,234 @@
+# MenuItem
+
+### 원칙
+메뉴/리스트 안 개별 행의 최소 단위. Dropdown Menu · Context Menu · Sidebar · Command Palette · 일반 List 아이템이 모두 이 컴포넌트를 공유한다. 시각 구조와 상태만 담당하고, 열림/닫힘·포커스 트랩·화살표 네비게이션은 상위 컨테이너(Radix DropdownMenu/ContextMenu, Sidebar `<nav>` 등)가 책임진다.
+
+root는 `<div role="menuitem">`이다 — `leadingActions`/`trailingActions`에 `IconButton` 같은 인터랙션 요소를 자유롭게 넣기 위해 nested `<button>` 스펙 위반을 피했다. Enter/Space 키 처리는 컴포넌트가 직접 한다.
+
+### Do
+- **슬롯은 배열로**: `leadingActions` / `trailingActions`에 아이콘·IconButton·배지·카운트 등 뭐든 넣는다. 각 슬롯 아이템은 `flex-gap: --space-1.5`로 나열됨.
+- **hover-only 액션은 명시적으로**: `{ node: <IconButton .../>, hoverOnly: true }` — 평상시 숨김, MenuItem hover/focus/focus-within에서 드러남. Notion 페이지 리스트 `+`/`⋯`, Linear 이슈 `⋯`, VSCode Explorer `+`/`✏️`/`↻`, Slack 채널 `⋯` 표준 패턴.
+- **항상 보이는 메타 + hover 액션 공존**: `trailingActions={[unreadCount, { node: menuBtn, hoverOnly: true }]}` — Slack 채널 언리드 카운트 + hover ⋯가 이 형태.
+- **내부 액션 클릭은 반드시 `e.stopPropagation()`**: 아니면 root의 `onClick`(=아이템 자체 선택)도 함께 발화한다. IconButton `onClick` 안에서 처리.
+- **checked=true**면 `leadingActions` 맨 앞에 자동으로 checkmark. 기존 leading 아이콘과 공존 가능(체크된 파일 옆에 파일 타입 아이콘도 함께).
+- **한 메뉴 안 leading 정책은 통일**: 어느 아이템에 leadingActions이 있으면 나머지도 유지 — 아니면 라벨 시작점이 어긋난다.
+- **size는 컨텍스트에 맞춘다**: Dropdown/Context Menu · Sidebar = `md`(기본), Command Palette · 밀도 높은 관리 UI = `sm`, 터치·모바일 시트 = `lg`.
+- **단축키는 실제 심볼**: `⌘K`, `⇧⌘P`. uppercase(`CTRL+K`) 금지 — [[feedback_no_uppercase]].
+- **destructive는 hover-only 빨강**: 평상시 fg, hover/focus에서만 빨강. 위계상 "약한" 위험 표시. 최종 확인은 [[components/alert-dialog]].
+
+### Don't
+- MenuItem 안에 두 개 이상의 &ldquo;주된 액션&rdquo;을 두지 않는다 — 아이템 전체가 하나의 selection. 부가 액션(즐겨찾기 토글·⋯메뉴)만 slot에 얹는다.
+- 라벨을 두 줄 이상 넣지 않는다. 설명이 필요하면 [[components/command-palette]] description 슬롯이나 [[components/tooltip]].
+- 페이지 이동에 root click 시맨틱 금지. 라우팅 아이템이면 `asChild`로 `<Link>`/`<a>`에 위임.
+- height를 CSS로 덮어쓰지 않는다. `size` prop 경유 (Density 축이 스왑).
+- hover-only 액션을 &ldquo;시각적으로 숨김&rdquo;으로만 처리하지 않는다 — `opacity: 0` + `pointer-events: none`이 짝. 안 그러면 안 보이는 버튼이 클릭됨.
+
+### Fallback
+size 애매하면 `md`, variant 애매하면 `default`.
+
+### 색상 훅 (컨테이너 단위 톤 조절)
+MenuItem은 세 개의 CSS 변수로 색을 열어둔다. **부모 컨테이너에 값을 얹으면 그 안의 모든 MenuItem이 일괄 반응**한다 — variant를 늘리지 말고 이 훅을 쓰는 게 원칙.
+
+| 훅 | 대상 | 폴백 |
+|---|---|---|
+| `--menu-fg` | 기본 라벨 색 | `--fg` |
+| `--menu-active-bg` | active 배경 (fill 스타일) | `--bg-muted` |
+| `--menu-active-fg` | active 라벨·아이콘·accent-bar 바 | fill=`--fg-strong` / accent-bar=`--primary` |
+
+```css
+/* 예: 사이드바 라벨을 연하게 + active는 브랜드 컬러로 */
+.brand-nav {
+  --menu-fg: var(--fg-muted);
+  --menu-active-bg: var(--primary);
+  --menu-active-fg: var(--bg);
+}
+
+/* 예: 조용한 리스트 — 평소 아주 연하게, active는 기본 강조만 */
+.quiet-list {
+  --menu-fg: var(--fg-subtle);
+}
+```
+
+Do
+- 훅은 **컨테이너 단위**로 지정한다 — 개별 아이템마다 다른 톤을 쓰면 시각 리듬이 깨진다.
+- primary·secondary·destructive 같은 **시맨틱 토큰만** 훅에 넣는다. hex/oklch 직접 금지 ([[PRINCIPLES]] §1).
+
+Don't
+- 이 훅으로 hover/focus 색을 바꾸려 하지 않는다 — hover는 `--hover`로 별도 관리되며 원칙적으로 통일 유지.
+- disabled/destructive 색은 훅으로 열려 있지 않다 — 접근성·위계 규칙이 붙어 있어 컴포넌트가 통제한다.
+
+### 관련
+- [[components/button]] · [[components/icon-button]] — trailing/leading에 흔히 들어감. hover 표면·destructive 위계 원리 공유.
+- [[components/dropdown-menu]] · [[components/context-menu]] — 이 컴포넌트를 감싸는 상위 컨테이너
+- [[components/sidebar]] · [[components/command-palette]] — 같은 MenuItem을 다른 컨텍스트에서 사용
+- [[axes/density]] — `--control-h-*`가 size에 매핑
+- [[axes/shape]] — radius가 Shape 축에 반응 (Button과 동일)
+- [[tokens/color]] — `--hover`/`--bg-muted`/`--destructive` 매핑
+
+### Props 시그니처
+```tsx
+type MenuItemAction =
+  | ReactNode
+  | { node: ReactNode; hoverOnly?: boolean; key?: string };
+
+<MenuItem
+  size="sm | md | lg"                    // default: md
+  variant="default | destructive"        // default: default
+  leadingActions={MenuItemAction[]}       // 왼쪽 슬롯 (아이콘, IconButton, 배지, ...)
+  trailingActions={MenuItemAction[]}      // 오른쪽 슬롯 (카운트, ⋯, hover-only 액션, ...)
+  shortcut="⌘K"                          // trailingActions 맨 앞에 자동 삽입
+  hasSubmenu={boolean}                   // trailingActions 맨 뒤에 caret 자동 삽입
+  checked={boolean}                      // leadingActions 맨 앞에 checkmark 자동 삽입
+  active={boolean}                       // 현재 페이지/선택 아이템 강조
+  disabled={boolean}
+  asChild={boolean}                      // Radix Slot — <Link>/<a>/DropdownMenu.Item 등에 위임
+  onClick={(e) => void}
+/>
+```
+
+### 상태 매트릭스
+| 상태 | 시각 |
+|---|---|
+| default | fg 텍스트, 투명 배경 |
+| hover · focus (`:focus-visible` / Radix `[data-highlighted]`) | `--hover` 배경, `fg-strong` 텍스트 |
+| active(눌림) | `--bg-muted` 배경 |
+| active(현재 페이지/선택) | `--bg-muted` 배경, `fg-strong` + medium weight |
+| checked | leading 맨 앞에 checkmark, 색 `fg-strong` |
+| disabled | `fg-disabled` 텍스트, cursor not-allowed, tabIndex=-1 |
+| destructive · hover | destructive 8% 배경, destructive 텍스트/아이콘 |
+| hoverOnly 액션 | 기본 opacity 0 → hover/focus/focus-within 시 opacity 1 (터치는 항상 노출) |
+
+### Size 가이드
+| size | height | icon | 언제 |
+|---|---|---|---|
+| `sm` | 32 | 14 | 밀도 높은 관리 UI, Command Palette |
+| `md` | 36 | 16 | **기본.** Dropdown / Context Menu / Sidebar |
+| `lg` | 40 | 18 | 터치·모바일 시트, 랜딩용 큰 메뉴 |
+
+### 조합 예시
+```tsx
+// 가장 단순 — 아이콘 + 라벨 + 단축키
+<MenuItem
+  leadingActions={[<Icon name="user" />]}
+  shortcut="⌘,"
+>계정 설정</MenuItem>
+
+// 서브메뉴 트리거
+<MenuItem
+  leadingActions={[<Icon name="star" />]}
+  hasSubmenu
+>즐겨찾기로 이동</MenuItem>
+
+// 체크박스 메뉴 (Radix CheckboxItem + [[components/checkbox]])
+// 표준: leading 슬롯에 <Checkbox> 컴포넌트를 그대로 얹는다.
+// - MenuItem의 checked prop(✓ 자동 삽입)에 의존하지 않는다 — 시각 톤을 폼과 통일하기 위함.
+// - Checkbox는 pointer-events:none + tabIndex=-1로 시각 마커화하고, 실제 토글은
+//   Radix가 관리한다(onCheckedChange). raw MenuItem이면 onClick에서.
+<DropdownMenu.CheckboxItem asChild checked={showGrid} onCheckedChange={setShowGrid}>
+  <MenuItem
+    leadingActions={[
+      <Checkbox size="sm" checked={showGrid} readOnly tabIndex={-1} className="menu-form-marker" />,
+    ]}
+    shortcut="⌘G"
+  >그리드 표시</MenuItem>
+</DropdownMenu.CheckboxItem>
+
+// 라디오 메뉴 (Radix RadioGroup + RadioItem + [[components/radio]])
+// 표준: leading 슬롯에 <Radio> 컴포넌트를 그대로 얹는다.
+// - 미선택도 "빈 원(○)" 자리를 유지 → 라벨 좌측 시작점 흔들림 없음.
+// - Radio도 마커화(pointer-events:none, tabIndex=-1). 같은 name으로 native 그룹 보장.
+<DropdownMenu.RadioGroup value={density} onValueChange={setDensity}>
+  {["compact", "cozy", "comfortable"].map((value) => (
+    <DropdownMenu.RadioItem asChild key={value} value={value}>
+      <MenuItem
+        leadingActions={[
+          <Radio
+            size="sm"
+            name="density"
+            value={value}
+            checked={density === value}
+            readOnly
+            tabIndex={-1}
+            className="menu-form-marker"
+          />,
+        ]}
+        active={density === value}
+      >{value}</MenuItem>
+    </DropdownMenu.RadioItem>
+  ))}
+</DropdownMenu.RadioGroup>
+
+// 참고: ContextMenu/DropdownMenu의 <CheckboxItem>/<RadioItem> 래퍼는
+// 내부에서 이미 dot/check placeholder를 leading에 얹고 CSS로 그린다.
+// 그 래퍼를 쓰면 위처럼 leadingActions를 직접 넘길 필요 없음.
+// 여기 예시는 raw MenuItem 위에 폼 컴포넌트로 직접 조합하는 방식.
+
+// Notion 페이지 리스트: leading 페이지 아이콘, 항상 보이는 카운트, hover 시 +/⋯
+<MenuItem
+  leadingActions={[<Icon name="star" />]}
+  trailingActions={[
+    <span className="badge">12</span>,
+    {
+      node: (
+        <IconButton
+          variant="ghost"
+          size="sm"
+          icon={<Icon name="arrow-right" />}
+          aria-label="새 하위 페이지"
+          onClick={(e) => { e.stopPropagation(); addChild(); }}
+        />
+      ),
+      hoverOnly: true,
+    },
+    {
+      node: (
+        <IconButton
+          variant="ghost"
+          size="sm"
+          icon={<Icon name="gear" />}
+          aria-label="더 보기"
+          onClick={(e) => { e.stopPropagation(); openMenu(); }}
+        />
+      ),
+      hoverOnly: true,
+    },
+  ]}
+  onClick={() => openPage()}
+>디자인 시스템</MenuItem>
+
+// Figma 파일 리스트: 항상 보이는 별표(즐겨찾기 토글), hover ⋯
+<MenuItem
+  leadingActions={[
+    <IconButton
+      variant="ghost"
+      size="sm"
+      icon={<Icon name="star" weight={starred ? "fill" : "regular"} />}
+      aria-label={starred ? "즐겨찾기 해제" : "즐겨찾기"}
+      onClick={(e) => { e.stopPropagation(); toggleStar(); }}
+    />,
+  ]}
+  trailingActions={[
+    <span className="date">2일 전</span>,
+    {
+      node: (
+        <IconButton size="sm" variant="ghost" aria-label="더 보기" icon={<Icon name="gear" />}
+          onClick={(e) => { e.stopPropagation(); openMenu(); }} />
+      ),
+      hoverOnly: true,
+    },
+  ]}
+  onClick={() => openFile()}
+>Untitled</MenuItem>
+
+// Sidebar 라우팅: asChild로 <Link>에 위임 + active
+<MenuItem asChild active={pathname === "/tokens/color"} leadingActions={[<Icon name="star" />]}>
+  <Link href="/tokens/color">Color</Link>
+</MenuItem>
+
+// 위험 액션
+<MenuItem
+  leadingActions={[<Icon name="trash" />]}
+  variant="destructive"
+  onClick={() => confirmDelete()}
+>삭제</MenuItem>
+```

package/assets/prompts/components/metric-card.md

@@ -0,0 +1,132 @@
+# MetricCard
+
+### 원칙
+대시보드 상단에 조밀하게 늘어서는 KPI/Stat 카드. 라벨 → 큰 숫자 → delta Badge 로 "지금 숫자 하나" 를 전달한다. 숫자 뒤에 추세 신호를 색으로 겹치지만, 숫자 자체는 중립 톤으로 유지해 여러 장이 나란히 서도 색이 튀지 않는다. 긴 설명이 필요하거나 액션이 있으면 [[components/callout]] 영역이고, 리스트/표의 반복 레코드는 [[components/table-row]] 영역이다.
+
+### Do
+- 한 카드엔 숫자 하나. `value`는 **짧게** — "72%", "4건", "₩1.2M" 처럼 단위 포함 한 토큰.
+- 추세는 `trend`로 넘기고 숫자는 `deltaLabel`에만. Badge는 자동으로 생성(상승=success+▲ / 하락=destructive+▼ / 유지=info+–).
+- 그리드로 늘어세울 때는 4~5열, 모든 카드 `variant` 동일. 섞으면 집중도가 깨진다.
+- 숨은 drill-down 링크로 쓰고 싶으면 `href` 넘긴다 — hover 배경 + focus ring이 자동 활성.
+- `description`은 "vs 지난주" 같은 비교 축만. 두 줄 이상이면 Callout 영역.
+
+### Don't
+- `value`에 두 줄 텍스트, 긴 서술, 통화·단위를 라벨로 분리해 큰 숫자만 외롭게 두지 않는다.
+- `trend`와 `delta`를 둘 다 넘기지 않는다 — `delta`를 넘기면 자동 매핑이 무시된다.
+- `trend="down"`인데 숫자상 "좋은" 하락(예: 미결 결재 ↓)일 때도 색을 success로 뒤집지 않는다. 추세 색은 **방향**만 신호한다. 좋음/나쁨 해석은 `description`이나 라벨에서 한다.
+- 그림자로 depth 쌓지 않는다. Shape 축이 shadow를 쥐었다면 간접 반영만.
+- 아이콘을 숫자 옆에 두지 않는다. 아이콘은 라벨 왼쪽 보조 신호.
+
+### Fallback
+`variant` 애매하면 `line`. `trend` 애매하면 생략(delta Badge 숨김). `href`/`onClick` 없이도 완결된다.
+
+`bare`는 "부모가 분리를 담당하는" 자리에서만 — 혼자 쓰면 안 됨. pure 좌표에서 상단 hairline + 수직 hairline으로 strip을 만든 자리, 또는 섹션 안 한 줄 수평 나열에서 사용.
+
+### 관련
+- [[components/callout]] — 긴 설명·CTA가 있는 공지. MetricCard는 단일 수치, Callout은 서술.
+- [[components/badge]] — Badge pill로는 delta를 쓰지 않지만, 수동 `delta` slot에 Badge를 넣을 수 있음.
+- [[components/table-row]] — 숫자 반복 레코드. 4개 이상이고 비교·정렬이 필요하면 테이블.
+- [[axes/shape]] — radius 성향을 흡수. 자체 리터럴 없음.
+- [[axes/density]] — compact에선 그리드 열 수 ↑, comfortable에선 ↓.
+- [[tokens/color]] — `--bg` · `--bg-subtle` · `--border` · `--fg` · `--fg-muted` 만 사용.
+
+### Props 시그니처
+```tsx
+<MetricCard
+  label={ReactNode}                              // required — 캡션
+  value={ReactNode}                              // required — 큰 숫자
+  icon={IconName}                                // 선택 — 라벨 왼쪽
+  trend="up | down | flat"                       // 추세 방향. 색 자동 매핑
+  deltaLabel={ReactNode}                         // trend와 짝. "+8%p"
+  delta={ReactNode}                              // 수동 override. trend/deltaLabel 무시
+  description={ReactNode}                        // 선택 — value 아래 보조 설명
+  variant="line | soft | bare"                   // default: line
+  href={string}                                  // 있으면 <a>로 렌더. hover/focus 활성
+/>
+```
+
+### Variant 매트릭스
+
+| variant | 표면 | 경계 | padding | 용도 |
+|---|---|---|---|---|
+| `line` | `--bg` | `1px solid --border` | 있음 | 운영 콘솔·조밀 그리드. hairline만. 기본값 |
+| `soft` | `--bg-subtle` | 투명 | 있음 | 서술형 대시보드·분위기 있는 레이아웃. 경계 대신 표면 톤으로 depth |
+| `bare` | 투명 | 없음 | 없음 | pure 좌표 전용. 부모가 hairline/톤으로 분리를 담당하는 strip 안에서만. 혼자 쓰지 않는다 |
+
+**trend × 색 매핑 (자동)**
+
+delta는 Badge pill이 아니라 **inline 텍스트 + 아이콘** 조합. 색은 토큰 그대로 입힌다 — 배경 없음.
+
+| trend | Color | Icon |
+|---|---|---|
+| `up` | `--success` | `trend-up` |
+| `down` | `--destructive` | `trend-down` |
+| `flat` | `--fg-muted` | `minus` |
+
+**금지 조합**
+- `variant=soft` + 그림자 추가 — 표면 톤이 depth를 쥐고 있는데 그림자까지 쌓이면 Shape 축 신호가 깨진다.
+- `trend` 매핑을 "좋음=green/나쁨=red" 가치판단으로 뒤집기 — 색은 **방향**만. 의미 반전은 라벨/설명에서.
+- 한 그리드 안에 `line` + `soft` + `bare` 혼용 — depth 레일이 깨진다. 그리드 단위로 variant 통일.
+- `value`에 Badge나 Chip 삽입 — 숫자 토큰은 하나여야 한다.
+- `bare`를 분리 장치 없는 자리에 혼자 사용 — 부모 strip(상단 hairline + 수직 hairline, 또는 bg 톤 교대)이 없으면 카드가 서로 뭉쳐 "덜 가둠"이 아니라 "덜 담음"으로 보인다.
+- `bare` + 부모 셀에 padding 생략 — bare는 자체 padding을 비웠으므로 **부모 셀(strip 안의 각 cell)이 좌우 padding을 반드시 책임져야** 숫자가 hairline에 붙지 않는다. [[components/list-item]] "조립 — 부모 wrapper 공식"과 같은 원리로, chrome 없는 variant는 부모가 공간 공식을 전담.
+
+### 조합 예시
+
+```tsx
+// 운영 콘솔 — 조밀한 KPI 4카드
+<section className="grid grid-cols-4 gap-3">
+  {metrics.map((m) => (
+    <MetricCard
+      key={m.id}
+      variant="line"
+      label={m.label}
+      value={m.value}
+      trend={m.trend}
+      deltaLabel={m.delta}
+    />
+  ))}
+</section>
+
+// 아이콘 + 설명이 붙은 "분위기" 대시보드
+<MetricCard
+  variant="soft"
+  icon="chart-line"
+  label="이번 주 완료율"
+  value="72%"
+  trend="up"
+  deltaLabel="+8%p"
+  description="vs 지난주 평균"
+/>
+
+// 수동 delta (Badge 자체를 커스텀) — trend 자동 매핑 off
+<MetricCard
+  label="대기 중 결재"
+  value="4건"
+  delta={<Badge variant="soft" status="warning">주의</Badge>}
+/>
+
+// drill-down 링크 카드
+<MetricCard
+  href="/approvals"
+  label="대기 중 결재"
+  value="4건"
+  trend="down"
+  deltaLabel="-2건"
+/>
+
+// pure 좌표 — bare variant를 hairline strip 안에서.
+// 부모가 상단 border-top + 자식 간 수직 border-right으로 분리를 담당.
+<section className="metricsStrip">  {/* border-top: 1px solid border-subtle */}
+  {metrics.map((m) => (
+    <MetricCard
+      key={m.id}
+      variant="bare"
+      label={m.label}
+      value={m.value}
+      trend={m.trend}
+      deltaLabel={m.delta}
+    />
+  ))}
+</section>
+```