@conscience-technology/ctds 0.3.4 → 0.4.0

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

@@ -0,0 +1,103 @@
+# EventListItem
+
+### 원칙
+리스트에 쌓이는 **하나의 일정** 아이템. 좌측 날짜 블록(큰 숫자 + 요일) · 세로 hairline · 우측 제목 + status Badge + meta 라인의 고정 anatomy. 캘린더 셀 안 색 바는 [[components/event-chip]]의 몫이고, 이 컴포넌트는 "다가오는 일정 리스트" "결재/행사 리스트"처럼 시간을 축으로 수직 나열되는 자리의 1 레코드.
+
+날짜 숫자는 2자리 기준으로 트랙이 고정되어 리스트가 세로로 쌓여도 제목 시작점이 흔들리지 않는다. status는 enum 4종(upcoming/pending/completed/cancelled)으로 받아 [[components/badge]] soft + 상태색으로 자동 매핑 — 호출부가 Badge를 직접 조립하지 않는다.
+
+### Do
+- 한 아이템엔 **한 일정**. `date` 하나 + `title` 하나 + 선택적 `status` + `meta[]`.
+- status는 enum 4종으로 넘긴다 — 자유 색/텍스트 Badge 조립 금지. 라벨만 override 필요하면 `statusLabel`.
+- 메타 라인 아이템 사이는 **짧은 세로 hairline**으로 분리 (bullet·중점·|·하이픈 금지). `showMetaDivider={false}`로 끌 수 있지만 기본은 유지.
+- 행 전체를 라우팅으로 쓰려면 `href` — hover bg + focus ring 자동.
+- 리스트로 쌓을 때 세로 gap은 `--space-2` ~ `--space-3`. 아이템 자체가 chrome(border+radius+padding)을 들고 있어 부모는 수직 flex만. 단, `variant="line"`은 하단 hairline으로 분리되므로 부모 gap 없이 바로 쌓는다.
+- chrome 축은 `variant`로 바꾼다 — `card`(기본, 떠있는 카드) · `line`(radius 없이 하단 hairline만) · `fill`(기본은 중립 soft 회색, status 지정 시 색상 톤).
+
+### Don't
+- [HARD] 안에 다시 Card chrome(추가 border/shadow) 쌓지 않는다 — "리스트 안 카드 안 카드"가 되어 depth가 깨진다.
+- [HARD] status를 자유 색으로 덮어쓰지 않는다. "좋음=green" 같은 가치판단 반전 금지. 색은 **상태 enum**이 결정.
+- [HARD] 날짜 요일 라벨을 UPPERCASE로 강제하지 않는다 — 소문자 유지("fri", "sun"). [[feedback_no_uppercase]].
+- [HARD] 메타 사이 bullet/중점/`|`/em-dash 삽입 금지. 짧은 세로 hairline만 (또는 `showMetaDivider={false}`로 완전 제거).
+- 날짜 숫자 외의 자리에 큰 숫자(가격·카운트) 추가 금지 — 좌측 트랙은 "날짜" 자리 하나.
+- 2줄 이상 서술/본문을 title에 넣지 않는다 — 1줄 ellipsis. 본문이 길면 상세 뷰로.
+- 날짜 블록을 Avatar/Icon으로 대체하지 않는다 — 그러면 이건 [[components/list-item]].
+
+### Fallback
+`status` 애매하면 생략(Badge 안 뜸, fill variant면 중립 회색). `statusLabel`은 enum 기본 라벨(Upcoming/Pending/Completed/Cancelled) 사용. 라우팅 자리 아니면 `href` 생략.
+
+### 관련
+- [[components/event-chip]] — 혼동 금지. EventChip은 캘린더 셀 안 색 바, EventListItem은 리스트 아이템.
+- [[components/list-item]] — 날짜 자리에 Avatar/Icon이 오는 "누가 뭘 했다" 피드는 ListItem.
+- [[components/metric-card]] — 같은 Card chrome 규칙(그림자 금지, line 기본).
+- [[components/badge]] — status 매핑은 Badge soft + status.
+- [[components/icon]] — meta 아이콘.
+- [[tokens/color]] — `--bg` · `--bg-subtle` · `--border` · `--fg-strong` · `--fg-muted` · `--hover` · `--info-subtle` · `--warning-subtle` · `--success-subtle` · `--destructive-subtle`.
+- [[axes/density]] — compact에선 세로 padding 줄어 리스트가 조밀해짐.
+- [[feedback_no_bullet_separator]] — meta 사이 분리 규칙.
+- [[feedback_no_uppercase]] — 요일 소문자 유지.
+- [[feedback_font_weight_cap]] — title은 sm이라 medium, day는 2xl이라 semibold.
+
+### Props 시그니처
+```tsx
+<EventListItem
+  date={Date}                                               // required — 날짜 블록으로 자동 포맷
+  title={ReactNode}                                         // required — 1줄 ellipsis
+  variant="card | line | fill"                              // 기본 "card". chrome 스타일 축
+  size="md | sm"                                            // 기본 "md". padding/날짜/제목/meta가 한 단계씩
+  status="upcoming | pending | completed | cancelled"       // Badge soft + 상태색 자동 (fill에선 전면 색)
+  statusLabel={ReactNode}                                   // 기본 라벨 override (ex: 한국어 "예정")
+  meta={{ icon?: IconName; label: ReactNode }[]}            // 메타 라인. 사이는 세로 hairline으로 자동 분리
+  showDateDivider={boolean}                                 // 기본 true. 날짜 블록 오른쪽 세로 hairline
+  showMetaDivider={boolean}                                 // 기본 true. meta 사이 세로 hairline
+  href={string}                                             // 있으면 <a> + hover/focus ring 활성
+/>
+```
+
+### Variant 매트릭스
+
+| variant | chrome | 쓰임 |
+|---|---|---|
+| `card` (기본) | 1px border + radius-lg + bg | 단독 떠있는 아이템. 다른 섹션과 섞이는 리스트. |
+| `line` | radius 없음, 하단 hairline만 | 리스트가 가로 폭 꽉 채워 흐르는 자리. 아이템이 쭉 쌓임. |
+| `fill` | **기본 중립 soft 회색**. status 지정 시 info/warning/success/destructive 톤 | 상태가 아이템 전체의 시각 신호로 중요한 자리. |
+
+size (variant와 독립 축, 기본 `md`)
+
+| size | padding | day | weekday | title | meta | 쓰임 |
+|---|---|---|---|---|---|---|
+| `md` (기본) | space-4 / space-5 | text-2xl | text-2xs | text-sm | text-xs | 대시보드·상세 뷰 등 일반 자리 |
+| `sm` | space-3 / space-4 | text-xl | text-3xs | text-xs | text-2xs | 사이드바·밀집 리스트 등 세로 공간 아끼는 자리 |
+
+status enum (variant와 독립 축)
+
+| status | Badge status | 기본 라벨 | 쓰임 |
+|---|---|---|---|
+| `upcoming` | `info` | Upcoming | 다가올 일정 (기본 info 톤) |
+| `pending` | `warning` | Pending | 승인·확정 대기 |
+| `completed` | `success` | Completed | 종료·완료 |
+| `cancelled` | `destructive` | Cancelled | 취소·무산 |
+
+조합 결과
+
+- `card` / `line` + `status` → Badge soft 표기, chrome은 variant 그대로
+- `fill` + `status` 없음 → 중립 `--bg-subtle` 회색 bg (디폴트)
+- `fill` + `status` 지정 → 아이템 전체가 status soft 톤 bg. 중복 방지로 **Badge는 자동 숨김**(색이 이미 상태를 표현)
+
+### 조합 예시
+```tsx
+<div>
+  {events.map((e) => (
+    <EventListItem
+      key={e.id}
+      href={`/events/${e.id}`}
+      date={e.date}
+      title={e.title}
+      status={e.status}
+      meta={[
+        { icon: "calendar-dots", label: e.when },
+        { icon: "compass", label: e.where },
+      ]}
+    />
+  ))}
+</div>
+```

package/assets/prompts/components/generated-image.md

@@ -0,0 +1,80 @@
+# GeneratedImage
+
+### 원칙
+AI가 생성한 **이미지 결과물의 큰 표시 자리**. 세 상태(loading / placeholder / image)가 같은 프레임 안에서 바뀐다. `aspect` 축으로 비율만 바꾸고 폭은 상위 그리드가 담당 — 자체적으로 크기를 들고 다니지 않는다. loading 상태는 image-gen 전용 lottie(sparkle breathe)로 "생성 중"을 전달하고, 플레이스홀더 배경이 이미 들어가 있어 깜빡임 없이 전환된다.
+
+### Do
+- 폭은 상위 그리드/부모가 결정. GeneratedImage는 `aspect`로 비율만 선언.
+- 생성 중이면 `loading` prop, 결과가 없을 뿐이면 `loading` 생략(= placeholder만 노출).
+- 다운로드 버튼이 필요하면 `onDownload`를 넘긴다. hover·focus-visible일 때만 노출되고, loading·placeholder 상태에서는 자동으로 숨겨진다.
+- 결과물 레퍼런스는 세로 비율이 많아 기본값 `portrait`(3/4) 그대로 쓰기를 권장.
+
+### Don't
+- 폭을 CSS로 override 금지. 비율은 `aspect`가, 폭은 부모 레이아웃이 책임.
+- `loading=true`일 때 `src`에 결과물을 미리 넣어두는 식의 선행 로딩 금지 — 상태가 꼬인다.
+- 자체 border·bg 덮어쓰기 금지. `--bg-subtle`/`--bg-muted` 토큰이 상태를 신호한다.
+- 다운로드 버튼 자리에 다른 액션(공유·삭제 등) 추가 금지. 이 자리는 "저장" 전용. 액션이 더 필요하면 외부 Toolbar/MessageActions로 뺀다.
+- 결과물 위에 라벨·캡션 overlay 올리지 않는다. 캡션은 바깥 블록으로 분리.
+
+### Fallback
+비율 애매하면 `portrait`, 상태 애매하면 `loading` 생략(= placeholder). onDownload는 "저장이 UX의 핵심일 때만" 공급.
+
+### 관련
+- [[components/spinner]] — loading 상태에서 `variant="lottie-image-gen"` size `lg`로 내장.
+- [[components/tooltip]] — 다운로드 버튼의 "다운로드" 레이블.
+- [[components/ai-message]] — 어시스턴트 메시지 안 결과물 자리에서 자주 쌍으로 조립.
+- [[components/attachment-thumb]] — 사용자가 올린 참조 이미지 썸네일(작은 자리). 생성 결과 큰 자리는 GeneratedImage.
+- [[components/gallery-item]] — 여러 결과를 그리드로 늘어놓을 때 셀 안쪽 미디어 자리.
+
+### Props 시그니처
+```tsx
+<GeneratedImage
+  src={string}                                   // 결과 이미지 URL (없거나 loading이면 placeholder)
+  alt={string}                                   // 접근성 대체 텍스트
+  aspect="square | portrait | landscape"         // default: portrait (3/4)
+  loading={boolean}                              // 생성 중 — placeholder + sparkle breathe
+  onDownload={(e) => void}                       // 지정 시만 우상단 다운로드 버튼 노출
+/>
+```
+
+### Aspect 가이드
+| aspect | 비율 | 쓰임 |
+|---|---|---|
+| `portrait` | 3/4 | **기본**. 레퍼런스/캐릭터/인물 중심 결과물. |
+| `square` | 1/1 | 아이콘·썸네일·SNS 포맷 결과물. |
+| `landscape` | 4/3 | 배경·풍경·와이드 포스터 결과물. |
+
+### 상태 전환
+1. 초기: `src` 없음, `loading` 없음 → **placeholder** (배경 이미지 + 조용히 대기)
+2. 생성 시작: `loading=true` → **loading** (같은 배경 + image-gen lottie 중앙 중첩)
+3. 결과 수신: `loading=false`, `src=<url>` → **image** (cover로 가득 채움)
+4. 다운로드: `onDownload` 공급 시, image 상태에서만 우상단 버튼 hover 노출
+
+전환 사이에 레이아웃 shift가 없다 — 세 상태 모두 동일한 `aspect-ratio` 프레임 안에서 바뀌므로 상위 그리드가 흔들리지 않는다.
+
+### 조합 예시
+```tsx
+// 기본 — AI 메시지 안 결과물
+<GeneratedImage
+  src={result.url}
+  alt={result.prompt}
+  onDownload={() => downloadImage(result.url)}
+/>
+
+// 생성 중
+<GeneratedImage loading alt="생성 중" />
+
+// 와이드 포맷 결과
+<GeneratedImage
+  src={banner.url}
+  alt={banner.prompt}
+  aspect="landscape"
+  onDownload={() => downloadImage(banner.url)}
+/>
+
+// AIMessage 안쪽에서 쌍으로
+<AIMessage>
+  <AIMessage.Body>원하신 레퍼런스예요.</AIMessage.Body>
+  <GeneratedImage src={url} alt={prompt} onDownload={handleSave} />
+</AIMessage>
+```

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

@@ -1,235 +1,213 @@
 # 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이 일괄 반응.
+리스트에 반복되는 **한 줄 단위**의 범용 anatomy. 피드·알림·활동 로그·작업 리스트·자원 목록이 전부 이 형태다. GitHub Timeline · Linear Inbox · Jira Issue history · Notion Updates · Figma Comments 모두 같은 뼈대 위에 서식과 톤만 바뀐다.
 
-| 훅 | 대상 | 폴백 |
-|---|---|---|
-| `--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` |
+**3구역 뼈대**: `[leading] [content] [trailing]`. 가로축은 이 셋이 전부고 세 구역 전부 `ReactNode`라 **자유 조립**. content 안쪽은 자주 쓰는 조립을 위한 편의 서브컴포넌트(`Title · Description · Meta · MetaDivider`)가 세로 리듬을 자동 공급하지만 강제는 아님 — 아바타 그룹·프로그레스·커스텀 차트 등 아무거나 넣을 수 있다.
 
-```css
-/* 예: 조용한 활동 로그 — 메타·본문 전부 한 단계 뒤로 */
-.quiet-activity {
-  --list-item-fg: var(--fg-muted);
-  --list-item-meta-fg: var(--fg-subtle);
-}
+**일정·이벤트처럼 날짜가 leading 아이덴티티인 자리는 [[components/event-list-item]] 사용** — ListItem은 범용 한 줄, EventListItem은 시간축 중심 전용.
 
-/* 예: 긴급 알림 리스트 — unread dot을 warning 톤으로 */
-.urgent-notifications {
-  --list-item-unread: var(--warning);
-}
+**chrome 없음** — bg·border·radius를 자체 공급하지 않는다. ListItem은 "리스트에 녹는 한 줄"이지, 블록이 아니다. 배경·테두리로 상태를 신호해야 하는 블록이 필요하면 [[components/callout]]로 승격한다.
+
+변주 축은 두 개: `size`(md/sm)가 세로 여백감을, `align`(center/top)이 leading 세로 정렬을 담당. 기본은 `md`(작업·자원 리스트 밀도), `sm`은 활동 로그·추출 완료처럼 분리선 없이 조밀하게 쌓이는 스트림 자리. row hover bg는 전 리스트 기본, href/onClick이 있으면 cursor pointer + focus ring 추가.
+
+---
+
+## 결정 가이드 — 뭘 만들려는 거지?
+
+### 1. 자원·문서 목록 (내가 열어볼 것들)
+문서·프로젝트·설정 항목처럼 **"열람 가능한 것들"의 목록**. 액션보다 네비게이션이 주.
+
+```tsx
+<ListItem
+  href="/docs/abc"
+  leading={<ListItemLeadingIcon size="md"><Icon name="file-text" /></ListItemLeadingIcon>}
+  trailing={<Icon name="caret-right" />}
+>
+  <ListItem.Title>채용 파이프라인 QBR</ListItem.Title>
+  <ListItem.Meta><time>2029년 7월 8일 작성</time></ListItem.Meta>
+</ListItem>
 ```
 
-### Props 시그니처
+- **leading**: `ListItemLeadingIcon`(배경색 아이콘) → 자원의 "타입 아이덴티티"
+- **content**: `Title` + `Meta`(생성/수정 날짜). Description은 생략 — 자원의 "본문 요약"이 필요한 자리면 그건 ListItem이 아니라 Card
+- **trailing**: `caret-right` → "클릭하면 열림" 신호
+- **size**: `md`, **align**: `center`
+
+### 2. 작업·할 일 리스트 (내가 처리해야 할 것들)
+요청·승인 대기·검토 필요처럼 **상태가 있는 작업 단위**.
+
 ```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> 등에 위임
-/>
+  align="top"
+  leading={<Icon name="list-dashes" />}
+  trailing={
+    <>
+      <Badge variant="soft" status="warning">검토 필요</Badge>
+      <IconButton size="sm" variant="ghost" icon={<Icon name="caret-right" />} aria-label="열기" />
+    </>
+  }
+>
+  <ListItem.Title>개발 대상과 문서 범위 확인</ListItem.Title>
+  <ListItem.Meta><time>22분 전 요청</time></ListItem.Meta>
+</ListItem>
 ```
 
-### Variant 매트릭스
-같은 anatomy, 다른 **기본 성격**. slot으로 못 바꾸는 자리만 variant로 바꾼다.
-`unread`는 variant가 강제하지 않는다 — 명시해야 신호. 리드 개념이 없는 자리면 생략.
+- **leading**: raw `<Icon>` → 체크리스트·태스크의 "종류"만 가볍게
+- **content**: `Title` + `Meta`(요청 시각·요청자). Description은 선택 — 제목이 짧으면 추가
+- **trailing**: 상태 `Badge` + chevron. Badge가 "지금 상태"를 shout, chevron이 "열어서 처리하라"
+- **size**: `md`, **align**: `top`
 
-| 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 생략 |
+### 3. 피드·활동 로그 (지나간 이벤트 스트림)
+알림·활동 기록·이력처럼 **읽을 뿐 처리는 거의 없는 흐름**.
 
-### 금지 조합
-- `verb` + `body` 동시 — 서술 중복
-- `leading=null` + `unread=true` — dot이 혼자 떠서 "누구" 자리가 사라짐
-- `trailing` + `hoverActions` — 메타 자리 충돌 (상시+hover면 trailing에 배열)
-- `layout="inline"` + body 2줄 이상 — stacked로 승격
-- `variant="system"` + Avatar(사람 이름) — system은 서비스 아이덴티티
-- 한 리스트 안에 variant 혼용 — 리스트 톤은 하나로. 섞어야 하면 섹션으로 분리
+```tsx
+<ListItem align="top" size="sm" leading={<Avatar size="sm" name="박지훈" />}>
+  <ListItem.Title>박지훈 — ERP 2.0 사이드바 티켓에 코멘트</ListItem.Title>
+  <ListItem.Meta><time>12분 전</time></ListItem.Meta>
+</ListItem>
+```
 
-### 조합 예시
+- **leading**: Avatar(사람 이벤트) 또는 raw `<Icon>`(시스템 이벤트)
+- **content**: `Title`에 "누가/뭘 했다"를 한 줄로. 긴 설명은 target 클릭 뒤 상세 뷰로
+- **trailing**: 보통 없음 (hover-only 액션은 archive/mark-read 패턴)
+- **size**: `sm` (스트림은 조밀하게), **align**: `top`
+
+### 4. 멘션·댓글 (내가 응답해야 할 메시지)
+멘션·@·댓글 리스트. 피드와 비슷하지만 **"응답 가능"이 핵심**.
 
 ```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>
+  href="/thread/123"
+  align="top"
+  leading={<Avatar size="sm" name="장대표" />}
+>
+  <ListItem.Title>장대표</ListItem.Title>
+  <ListItem.Description>@희영 1:1 전에 자료 공유 부탁</ListItem.Description>
+  <ListItem.Meta><time>오전 9:12</time></ListItem.Meta>
+</ListItem>
 ```
 
-### 조립 — 부모 wrapper 공식
-ListItem은 **self-contained 상쇄 공식**(`padding-block: --space-3` + `margin-block: -(--space-3)`)을 들고 있다. 부모가 공간을 안 걸어도 보장되는 안전장치지만, 조립할 때 아래 세 패턴을 혼동하면 세로가 과하거나 콘텐츠가 선에 붙는다.
+- **content**: `Title`에 이름, `Description`에 **인용 한 줄**(전체 메시지 복사 금지), `Meta`에 시각
+- **href**: row 전체가 thread 열기
+- **align**: `top`
+
+### 5. 데이터 레코드 (내가 보고 비교할 숫자)
+가격·수량·기간이 핵심인 리스트. 숫자가 Title보다 중요한 자리.
+
+→ **ListItem이 아니라 [[components/table]]의 자리**. ListItem은 "자원·텍스트 중심 한 줄", 숫자 비교·정렬·집계는 Table.
+
+### 6. 상태 공지·보류 블록 (지금 당장 봐야 하는 알림)
+"작업 보류", "다운타임 예정", "결제 실패"처럼 **배경 톤으로 shouts** 해야 하는 블록.
+
+→ **ListItem이 아니라 [[components/callout]]의 자리**. ListItem은 chrome 없이 흐름에 녹는 한 줄이지, 상태 블록이 아니다.
+
+### 7. 선택 가능한 목록 (여러 개 체크·drag)
+멀티 셀렉션·drag reorder·bulk 작업 리스트.
 
-**패턴 A — 부모가 간격 아예 안 걸음 (단독 사용):**
-그대로 둬도 ListItem이 자체 공간을 가진다. hover hit area는 보장되지만 **리스트처럼 세로로 쌓이면 아이템끼리 바로 붙는다** — 리스트 자리면 패턴 B/C로.
+→ **ListItem leading에 `<Checkbox />`** 꽂아서 시작. drag handle은 leading 왼쪽에 추가 자리로. 복잡해지면 Table로 승격.
 
-**패턴 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에 붙지 않으면서도 세로가 과하지 않은" 유일한 조립.
+## 서브컴포넌트 역할
+
+| 서브컴포넌트 | 뭘 담나 | 언제 쓰나 |
+|---|---|---|
+| `ListItem.Title` | 메인 제목·행위 요약 | 항상. Title 없는 ListItem은 거의 없음. Badge를 inline으로 Title 앞에 섞어도 OK |
+| `ListItem.Description` | 제목으로 안 담기는 **인용·부제** | 멘션/댓글 본문, 설명이 1줄 더 필요한 자리. 생성일 같은 메타는 절대 Description 아님 |
+| `ListItem.Meta` | **메타데이터** (시각·작성자·버전·상태 텍스트) | 작성일·수정일·요청자·"n개 참여" 같은 보조 수치 전부 여기 |
+| `ListItem.MetaDivider` | Meta 안 토큰 사이 hairline 구분자 | `<span>작성 10일 전</span><Divider /><span>박지훈</span>` 같을 때 |
+
+### Description vs Meta
+가장 자주 실수하는 자리. 구분 공식:
+- **Description** = "제목으로 안 들어간 **본문 성격의 한 줄**" (댓글 본문, 부제, 요약)
+- **Meta** = "**누가/언제/몇 개** 같은 메타데이터" (날짜·사람·수치·상태 텍스트)
+
+"2029년 7월 8일 작성"은 **Meta**. "@희영 1:1 전에 자료 공유 부탁"은 **Description**.
+
+---
+
+## Do
+- **anatomy는 3구역 고정**: leading / children(content) / trailing.
+- **세 구역은 전부 ReactNode — 완전 자유**: 전용 서브컴포넌트는 리듬 토큰을 자동 공급하는 **편의 레이어**지 강제가 아님.
+- **leading 타입은 리스트 단위로 통일**: 자원 리스트는 전부 IconMark, 피드는 전부 Avatar 식.
+- **2줄 이상 본문이면 `align="top"`**: leading이 Title 라인에 top-align.
+- **스트림 자리는 `size="sm"`**: 활동 로그·알림 스트림은 조밀하게.
+- **row 전체 클릭은 `href`/`onClick`**: cursor pointer + focus ring 자동.
+- **Meta 안 토큰 사이는 MetaDivider**: 가운뎃점·bullet·파이프 금지. [[feedback_no_bullet_separator]].
+- **날짜는 [[feedback_date_writing]] 규칙 준수**: "10월 13일" 또는 "12분 전", 숫자 패턴(10. 13) 금지.
+
+## Don't
+- **Description에 메타데이터 쓰기 금지**: "2029년 7월 8일 작성" 같은 날짜·사람·수치는 전부 `Meta`로.
+- **Title에 전체 메시지/긴 서술 넣기 금지**: ListItem은 요약 라인, 메시지 뷰어가 아님.
+- **content에 여러 Title 금지**: 메인 제목은 하나.
+- **Description은 2줄 안쪽**: 3줄 이상이면 외부 Callout·Card로.
+- **bg·border·radius 자체 공급 금지**: 블록 외형이 필요하면 [[components/callout]].
+- **leading에 inline `<svg>` 금지**: 반드시 `<Icon />`/Badge/Avatar 경유. [[feedback_no_inline_svg]].
+- **한 리스트 안 size 혼용 금지**: sm 리스트는 전부 sm.
+- **자리마다 세로 간격 손 조정 금지**: 균형 안 맞으면 `size` 또는 리듬 토큰(`--li-gap-title`·`--li-gap-body`)으로.
+
+## Fallback
+leading 애매하면 Icon. size 애매하면 md. align 애매하면 center(한 줄)·top(2줄 이상).
+
+## 축 (CSS 변수)
+
+| 훅 | 대상 | 폴백 |
+|---|---|---|
+| `--li-pad-y` | 세로 padding (hit area) | `var(--space-3)` |
+| `--li-gap-x` | leading↔content↔trailing | `var(--space-3)` |
+| `--li-gap-title` | Title↔Description·Meta ("제목+부제" 유닛감) | `var(--space-0_5)` |
+| `--li-gap-body` | 큰 블록 간 간격 | `var(--space-2)` |
+| `--li-gap-meta` | Meta 라인 아이템 간 가로 gap | `var(--space-2)` |
+
+## Props 시그니처
+```tsx
+<ListItem
+  leading={ReactNode}             // Icon | Avatar | Badge | ListItemLeadingIcon | 자유
+  trailing={ReactNode}            // Badge | Button | IconButton | 조합 | 자유
+  size="md | sm"                  // default: md (sm은 스트림 자리)
+  align="center | top"            // default: center. 2줄 이상이면 top.
+  href={string}                   // row 전체 링크 (클릭 가능)
+  onClick={(e) => void}           // row 선택 핸들러 (클릭 가능)
+>
+  <ListItem.Title>...</ListItem.Title>
+  <ListItem.Description>...</ListItem.Description>
+  <ListItem.Meta>
+    <time>...</time>
+    <ListItem.MetaDivider />
+    <span>...</span>
+  </ListItem.Meta>
+</ListItem>
+
+```
+
+## 조립 — 부모 wrapper
+리스트로 묶을 때는 부모 ul에 hairline border만 공급.
 
 ```css
-/* pure 좌표 — hairline 리스트 */
-.activityList {
+.feed {
   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));
+  margin: 0;
 }
-/* ListItem self-space 중화 — 자식 선택자로 */
-.activityList > li > * {
-  padding-block: 0;
-  margin-block: 0;
+.feed > li {
+  border-bottom: var(--hairline) solid var(--border);
 }
+.feed > li:last-child { border-bottom: none; }
 ```
 
-**조립 체크리스트 — 리스트에 쓰기 전 아래를 순서대로:**
-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 금지.
+**interactive ListItem**(`href`/`onClick`)은 cursor pointer + focus ring 자동, hit area는 좌우 `space-2`만큼 자동 확장(negative margin으로 정렬 유지).
+
+## 관련
+- [[components/avatar]] — leading의 "사람" 자리.
+- [[components/badge]] — Title 앞 inline 상태, leading 상태, trailing 상태 전부.
+- [[components/button]] — trailing CTA.
+- [[components/icon-button]] — trailing chevron/dots.
+- [[components/callout]] — 배경·테두리로 상태 신호가 필요한 블록은 Callout.
+- [[components/event-list-item]] — 날짜가 leading 아이덴티티인 일정·이벤트 리스트는 EventListItem.
+- [[components/table]] — 숫자 비교·정렬이 핵심이면 Table.
+- [[components/metric-card]] — chrome 없이 부모가 분리 담당하는 설계 철학 공유.
+- [[axes/density]] — 전역 Density 축은 테마 레벨, ListItem의 size는 리스트 자리별 조절.
+- [[feedback_no_bullet_separator]] — Meta 라인 구분자는 MetaDivider.
+- [[feedback_no_inline_svg]] — leading 아이콘은 Icon 컴포넌트.
+- [[feedback_date_writing]] — Meta 안 날짜는 "10월 13일" / "12분 전" 형식.

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

@@ -14,7 +14,7 @@
 - `value`에 두 줄 텍스트, 긴 서술, 통화·단위를 라벨로 분리해 큰 숫자만 외롭게 두지 않는다.
 - `trend`와 `delta`를 둘 다 넘기지 않는다 — `delta`를 넘기면 자동 매핑이 무시된다.
 - `trend="down"`인데 숫자상 "좋은" 하락(예: 미결 결재 ↓)일 때도 색을 success로 뒤집지 않는다. 추세 색은 **방향**만 신호한다. 좋음/나쁨 해석은 `description`이나 라벨에서 한다.
-- 그림자로 depth 쌓지 않는다. Shape 축이 shadow를 쥐었다면 간접 반영만.
+- 그림자로 depth 쌓지 않는다. `line`만 아주 은은한 `--shadow-sm`을 깐다(hairline 보조). `soft`·`bare`는 그림자 금지.
 - 아이콘을 숫자 옆에 두지 않는다. 아이콘은 라벨 왼쪽 보조 신호.
 
 ### Fallback
@@ -49,7 +49,7 @@
 
 | variant | 표면 | 경계 | padding | 용도 |
 |---|---|---|---|---|
-| `line` | `--bg` | `1px solid --border` | 있음 | 운영 콘솔·조밀 그리드. hairline만. 기본값 |
+| `line` | `--bg` | `1px solid --border` + `--shadow-sm` | 있음 | 운영 콘솔·조밀 그리드. hairline + 아주 은은한 lift. 기본값 |
 | `soft` | `--bg-subtle` | 투명 | 있음 | 서술형 대시보드·분위기 있는 레이아웃. 경계 대신 표면 톤으로 depth |
 | `bare` | 투명 | 없음 | 없음 | pure 좌표 전용. 부모가 hairline/톤으로 분리를 담당하는 strip 안에서만. 혼자 쓰지 않는다 |