@conscience-technology/ctds 0.1.9 → 0.1.10

package/assets/components/Spinner/Spinner.tsx

@@ -0,0 +1,119 @@
+"use client";
+
+/**
+ * Spinner — Motion 축이 로더 성격을 결정.
+ *
+ * variant 생략 시 Motion 축의 `--loader-style`을 추종한다.
+ *   - bouncy  → dots-bounce
+ *   - standard → ring
+ *   - calm    → dots-fade
+ *   - none    → ring (접근성 예외: 로딩 신호는 유지)
+ *
+ * `lottie-<name>` variant는 번들된 Lottie 로티를 렌더 (colorBind=true면 currentColor 추종).
+ *
+ * 색은 currentColor로 묶여 부모 color를 그대로 승계 (Palette/Hue 축 호환).
+ */
+
+import { forwardRef, type HTMLAttributes } from "react";
+import styles from "./Spinner.module.css";
+import { LOTTIE_MANIFEST, type LottieName } from "./lottieManifest";
+import { LottiePlayer } from "./LottiePlayer";
+
+export type SpinnerSize = "xs" | "sm" | "md" | "lg";
+export type SpinnerBaseVariant = "ring" | "dots-bounce" | "dots-fade" | "pulse";
+export type SpinnerLottieVariant = `lottie-${LottieName}`;
+export type SpinnerVariant = SpinnerBaseVariant | SpinnerLottieVariant;
+
+export type SpinnerProps = HTMLAttributes<HTMLSpanElement> & {
+  size?: SpinnerSize;
+  /** 생략 시 현재 Motion 축의 `--loader-style`을 따름 */
+  variant?: SpinnerVariant;
+  /** 스크린리더 라벨 */
+  label?: string;
+};
+
+const sizeClass: Record<SpinnerSize, string> = {
+  xs: styles.xs,
+  sm: styles.sm,
+  md: styles.md,
+  lg: styles.lg,
+};
+
+const baseVariantClass: Record<SpinnerBaseVariant, string> = {
+  ring: styles["v-ring"],
+  "dots-bounce": `${styles["v-dots"]} ${styles["v-dots-bounce"]}`,
+  "dots-fade": `${styles["v-dots"]} ${styles["v-dots-fade"]}`,
+  pulse: styles["v-pulse"],
+};
+
+function isLottieVariant(v: SpinnerVariant): v is SpinnerLottieVariant {
+  return v.startsWith("lottie-");
+}
+
+const Spinner = forwardRef<HTMLSpanElement, SpinnerProps>(
+  ({ className, size = "sm", variant, label = "Loading", ...rest }, ref) => {
+    let variantPart = "";
+    let lottieName: LottieName | null = null;
+
+    if (variant) {
+      if (isLottieVariant(variant)) {
+        lottieName = variant.slice("lottie-".length) as LottieName;
+        const aspectClass =
+          LOTTIE_MANIFEST[lottieName].aspect === "wide" ? styles.wide : "";
+        variantPart = `${styles["v-lottie"]} ${aspectClass}`.trim();
+      } else {
+        variantPart = baseVariantClass[variant];
+      }
+    } else {
+      variantPart = styles["v-auto"];
+    }
+
+    const rootClass = [styles.root, sizeClass[size], variantPart, className ?? ""]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <span
+        ref={ref}
+        className={rootClass}
+        role="status"
+        aria-label={label}
+        {...rest}
+      >
+        {lottieName ? <LottiePlayer name={lottieName} /> : <SpinnerBody />}
+      </span>
+    );
+  },
+);
+
+Spinner.displayName = "Spinner";
+
+/* 비-로티 variant용 공통 바디. 활성 variant 클래스가 해당하는 자식만 display. */
+function SpinnerBody() {
+  return (
+    <>
+      <svg className={styles.ring} viewBox="0 0 24 24" fill="none" aria-hidden>
+        <circle
+          cx="12"
+          cy="12"
+          r="9"
+          stroke="currentColor"
+          strokeOpacity="0.2"
+          strokeWidth="3"
+        />
+        <path
+          d="M12 3a9 9 0 0 1 9 9"
+          stroke="currentColor"
+          strokeWidth="3"
+          strokeLinecap="round"
+        />
+      </svg>
+      <span className={styles.dot} aria-hidden />
+      <span className={styles.dot} aria-hidden />
+      <span className={styles.dot} aria-hidden />
+      <span className={styles.pulse} aria-hidden />
+    </>
+  );
+}
+
+export { Spinner };

package/assets/components/Spinner/index.ts

@@ -0,0 +1,10 @@
+export { Spinner } from "./Spinner";
+export type {
+  SpinnerProps,
+  SpinnerSize,
+  SpinnerVariant,
+  SpinnerBaseVariant,
+  SpinnerLottieVariant,
+} from "./Spinner";
+export { LOTTIE_MANIFEST, LOTTIE_NAMES } from "./lottieManifest";
+export type { LottieName, LottieManifestEntry } from "./lottieManifest";

package/assets/components/Spinner/lottieColor.ts

@@ -0,0 +1,76 @@
+/**
+ * Lottie JSON 안의 모든 색 배열을 target 색으로 치환.
+ *
+ * Lottie 색 포맷: `[r, g, b]` 또는 `[r, g, b, a]` (0~1 정규화).
+ * 매니페스트에서 `colorBind: true`인 단색 로티에만 사용 — 다색 로티는 색 구조가
+ * 흐트러져서 적용 불가.
+ */
+
+export type Rgb = [number, number, number];
+
+/** CSS 색 문자열 → [r,g,b] 0~1 정규화. 서버에서는 null 반환.
+ *  oklch()/color()처럼 getComputedStyle이 색공간 문자열 그대로 뱉는 경우를 피하려고
+ *  canvas 2d에 그려 실제 sRGB 픽셀값을 읽어낸다. */
+export function parseCssColor(css: string): Rgb | null {
+  if (typeof document === "undefined") return null;
+  const canvas = document.createElement("canvas");
+  canvas.width = 1;
+  canvas.height = 1;
+  const ctx = canvas.getContext("2d");
+  if (!ctx) return null;
+  ctx.fillStyle = "#000";
+  ctx.fillStyle = css;
+  // 브라우저가 유효하지 않다고 판단한 색은 이전 fillStyle(#000)이 유지됨 → 바로 그리고 읽기
+  ctx.fillRect(0, 0, 1, 1);
+  const [r, g, b] = ctx.getImageData(0, 0, 1, 1).data;
+  return [r / 255, g / 255, b / 255];
+}
+
+/** 원본 색의 밝기(luminance)만 추출해 target 색조에 적용.
+ *  단색 로티: 모든 색이 비슷한 밝기 → target 색 그대로.
+ *  그라데이션/다색 로티: 밝기 계조는 유지, 색조만 target으로 → 그라데이션 보존.
+ *
+ *  Rec. 601 luma 가중치. 흰색(1,1,1)→target 밝게, 검정(0,0,0)→target 어둡게. */
+export function recolorLottie(data: unknown, target: Rgb): unknown {
+  const [tr, tg, tb] = target;
+  // target 자신의 luma — 원본이 target과 같은 밝기(=중간)일 때 target 그대로 나오도록 anchor.
+  const targetLuma = 0.299 * tr + 0.587 * tg + 0.114 * tb;
+
+  function recolorOne(src: Rgb): Rgb {
+    const [sr, sg, sb] = src;
+    const srcLuma = 0.299 * sr + 0.587 * sg + 0.114 * sb;
+    if (targetLuma === 0) {
+      // target이 완전 검정이면 비율 scale 불가 — 원본 luma만큼 어둡게.
+      return [srcLuma * tr, srcLuma * tg, srcLuma * tb];
+    }
+    // 비율 조정 — srcLuma=targetLuma면 target 그대로, 더 밝으면 target을 더 밝게.
+    const k = srcLuma / targetLuma;
+    const clamp = (v: number) => Math.max(0, Math.min(1, v));
+    return [clamp(tr * k), clamp(tg * k), clamp(tb * k)];
+  }
+
+  function walk(node: unknown): unknown {
+    if (Array.isArray(node)) {
+      if (
+        (node.length === 3 || node.length === 4) &&
+        node.every((v) => typeof v === "number" && v >= 0 && v <= 1)
+      ) {
+        const [r, g, b] = node as number[];
+        const [nr, ng, nb] = recolorOne([r, g, b]);
+        const alpha = node.length === 4 ? node[3] : undefined;
+        return alpha !== undefined ? [nr, ng, nb, alpha] : [nr, ng, nb];
+      }
+      return node.map(walk);
+    }
+    if (node && typeof node === "object") {
+      const out: Record<string, unknown> = {};
+      for (const [k, v] of Object.entries(node as Record<string, unknown>)) {
+        out[k] = walk(v);
+      }
+      return out;
+    }
+    return node;
+  }
+
+  return walk(data);
+}

package/assets/components/Spinner/lottieManifest.ts

@@ -0,0 +1,99 @@
+/**
+ * Lottie 로더 매니페스트.
+ *
+ * `name`: Spinner variant로 쓰는 식별자 (`lottie-<name>` 또는 매니페스트의 name 그대로)
+ * `path`: /public 밑 상대 경로
+ * `colorBind`:
+ *   true  — 단색 로티. 런타임에 모든 색을 currentColor로 치환해 Palette/Hue 축을 추종.
+ *   false — 다색 로티. 원본 색 유지 (브랜드 톤 또는 작가 의도).
+ * `aspect`: 'square' | 'wide' — 바깥 박스 크기 결정에 참조.
+ */
+
+export type LottieName =
+  | "rabbit"
+  | "infiniti"
+  | "dots"
+  | "spinner"
+  | "clock"
+  | "cosmos"
+  | "image-gen"
+  | "loading-square";
+
+export type LottieManifestEntry = {
+  name: LottieName;
+  path: string;
+  colorBind: boolean;
+  aspect: "square" | "wide";
+  /** 로티 원본이 캔버스를 덜 채워 체감 크기가 작을 때, 쇼케이스·사용처에서 쓸 보정 배율.
+   *  1 = 원본 그대로. 1보다 크면 bounds 안에서 scale-up (overflow 숨김 전제). */
+  visualScale?: number;
+  /** 한줄 설명 — showcase · 자동완성용 */
+  description: string;
+};
+
+export const LOTTIE_MANIFEST: Record<LottieName, LottieManifestEntry> = {
+  rabbit: {
+    name: "rabbit",
+    path: "/lottie/rabbit.json",
+    colorBind: true,
+    aspect: "square",
+    visualScale: 1.4,
+    description: "뛰어가는 토끼. 긴 작업·AI 생성 대기",
+  },
+  infiniti: {
+    name: "infiniti",
+    path: "/lottie/infiniti.json",
+    colorBind: true,
+    aspect: "wide",
+    visualScale: 1.3,
+    description: "무한 루프 선. 네트워크·동기화",
+  },
+  dots: {
+    name: "dots",
+    path: "/lottie/dots.json",
+    colorBind: false,
+    aspect: "square",
+    visualScale: 1.3,
+    description: "그라데이션 dot 흐름. 포인트 로더",
+  },
+  spinner: {
+    name: "spinner",
+    path: "/lottie/spinner.json",
+    colorBind: true,
+    aspect: "wide",
+    description: "표준 라인 스피너",
+  },
+  clock: {
+    name: "clock",
+    path: "/lottie/clock.json",
+    colorBind: true,
+    aspect: "wide",
+    visualScale: 1.8,
+    description: "회전 시계 바늘. 처리 대기·타임아웃",
+  },
+  cosmos: {
+    name: "cosmos",
+    path: "/lottie/cosmos.json",
+    colorBind: true,
+    aspect: "square",
+    description: "그라데이션 궤도. 몽환적·온보딩",
+  },
+  "image-gen": {
+    name: "image-gen",
+    path: "/lottie/image-gen.json",
+    colorBind: true,
+    aspect: "square",
+    visualScale: 1.1,
+    description: "이미지 생성 대기. AI 이미지",
+  },
+  "loading-square": {
+    name: "loading-square",
+    path: "/lottie/loading-square.json",
+    colorBind: true,
+    aspect: "square",
+    visualScale: 2.8,
+    description: "회전하는 사각형. 미니멀 처리 대기",
+  },
+};
+
+export const LOTTIE_NAMES = Object.keys(LOTTIE_MANIFEST) as LottieName[];

package/assets/components/Tabs/Tabs.module.css

@@ -107,7 +107,7 @@
   position: relative;
 }
 .size_sm .triggerUnderline { padding-inline: var(--space-1_5); }
-.size_lg .triggerUnderline { padding-inline: var(--space-3); }
+.size_lg .triggerUnderline { padding-inline: var(--space-1_5); }
 
 .listUnderline { position: relative; }
 
@@ -126,8 +126,8 @@
   transform: translateX(calc(var(--tab-indicator-x) + var(--space-1_5)));
 }
 .size_lg .underlineBar {
-  width: calc(var(--tab-indicator-w) - var(--space-3) * 2);
-  transform: translateX(calc(var(--tab-indicator-x) + var(--space-3)));
+  width: calc(var(--tab-indicator-w) - var(--space-1_5) * 2);
+  transform: translateX(calc(var(--tab-indicator-x) + var(--space-1_5)));
 }
 /* ready=true 이후에만 transition — 초기 배치는 순간이동. */
 .listUnderline[data-ready="true"] .underlineBar {

package/assets/components/UserMessage/UserMessage.module.css

@@ -0,0 +1,41 @@
+/* UserMessage — Bubble + MessageActions. 오른쪽 정렬. */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--space-1);
+  width: 100%;
+}
+
+/* 첨부·인용 등 bubble 위에 올리는 영역 */
+.before {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-end;
+  gap: var(--space-1);
+  max-width: 100%;
+}
+
+.actions {
+  display: flex;
+}
+
+/* actions-visibility=show: 상시 노출 */
+.root[data-actions-visibility="show"] .actions {
+  opacity: 1;
+}
+
+/* actions-visibility=hover: hover/focus-within에서만. 부드러운 fade + slight translate. */
+.root[data-actions-visibility="hover"] .actions {
+  opacity: 0;
+  transform: translateY(calc(var(--space-0_5) * -1));
+  transition:
+    opacity var(--duration-slow) var(--ease-out),
+    transform var(--duration-slow) var(--ease-out);
+}
+.root[data-actions-visibility="hover"]:hover .actions,
+.root[data-actions-visibility="hover"]:focus-within .actions {
+  opacity: 1;
+  transform: translateY(0);
+}

package/assets/components/UserMessage/UserMessage.tsx

@@ -0,0 +1,66 @@
+"use client";
+
+import type { HTMLAttributes, ReactNode } from "react";
+import { Bubble, type BubbleFill, type BubbleShape, type BubbleSize } from "@/components/ctds/Bubble";
+import {
+  MessageActions,
+  type MessageAction,
+} from "@/components/ctds/MessageActions";
+import styles from "./UserMessage.module.css";
+
+export type UserMessageActionsVisibility = "show" | "hover";
+
+export interface UserMessageProps extends HTMLAttributes<HTMLDivElement> {
+  /** 메시지 본문. string 또는 ReactNode. */
+  children: ReactNode;
+  /** 버블 모양. 기본 circular-drop. */
+  shape?: BubbleShape;
+  /** 버블 fill. 기본 translucent. */
+  fill?: BubbleFill;
+  /** 버블 size. 기본 md. */
+  size?: BubbleSize;
+  /** 액션 노출 — "show" 상시 / "hover" 호버 시만. 기본 hover. */
+  actionsVisibility?: UserMessageActionsVisibility;
+  /** 액션 커스터마이즈. 기본 [copy, edit]. 비우려면 []. */
+  actions?: MessageAction[];
+  /** 메시지 위에 올라올 첨부(이미지/파일) 등 — 상위에서 자유 조합. */
+  before?: ReactNode;
+}
+
+const DEFAULT_ACTIONS: MessageAction[] = [
+  { kind: "copy" },
+  { kind: "edit" },
+];
+
+export function UserMessage({
+  children,
+  shape = "circular-drop",
+  fill = "translucent",
+  size = "md",
+  actionsVisibility = "hover",
+  actions = DEFAULT_ACTIONS,
+  before,
+  className,
+  ...rest
+}: UserMessageProps) {
+  const cls = [styles.root, className].filter(Boolean).join(" ");
+  const hasActions = actions.length > 0;
+
+  return (
+    <div
+      className={cls}
+      data-actions-visibility={actionsVisibility}
+      {...rest}
+    >
+      {before ? <div className={styles.before}>{before}</div> : null}
+      <Bubble shape={shape} fill={fill} size={size} tail="end">
+        {children}
+      </Bubble>
+      {hasActions ? (
+        <div className={styles.actions}>
+          <MessageActions align="end" actions={actions} />
+        </div>
+      ) : null}
+    </div>
+  );
+}

package/assets/components/UserMessage/index.ts

@@ -0,0 +1,2 @@
+export { UserMessage } from "./UserMessage";
+export type { UserMessageProps, UserMessageActionsVisibility } from "./UserMessage";

package/assets/components/_data.ts

@@ -572,6 +572,7 @@ export const componentSlugs: Record<string, string> = {
   Sidebar: "nav/sidebar",
   "Sidebar Split": "nav/sidebar-split",
   Topbar: "nav/topbar",
+  "Identity Button": "nav/identity-button",
   Pagination: "nav/pagination",
   "App Frame": "layout/app-frame",
   Stepper: "nav/stepper",
@@ -584,22 +585,33 @@ export const componentSlugs: Record<string, string> = {
   "Table Row": "data/table-row",
   "Table Row Select": "data/table-row-select",
   "Table Row Edit": "data/table-row-edit",
+  Calendar: "data/calendar",
+  "Event Chip": "data/event-chip",
   "List Item": "data/list-item",
   "Metric Card": "data/metric-card",
   "Gallery Item": "data/gallery-item",
   "Empty State": "data/empty-state",
   "Progress Bar": "feedback/progress-bar",
+  Spinner: "feedback/spinner",
   "File Icon": "chat/file-icon",
   "Attachment Thumb": "chat/attachment-thumb",
   "Attachment Chip": "chat/attachment-chip",
   "Quotation Bar": "chat/quotation-bar",
   "Chat Input": "chat/chat-input",
+  "Bubble": "chat/bubble",
+  "Message Actions": "chat/message-actions",
+  "User Message": "chat/user-message",
+  "AI Message": "chat/ai-message",
+  "Code Block": "chat/code-block",
+  "Message Quote": "chat/message-quote",
+  "Message Sources": "chat/message-sources",
+  "Message Table": "chat/message-table",
 };
 
 /** 작업중 — 사이드바에서 접근은 가능하지만 "작업중" 뱃지로 표시해 사용 자제 유도. */
 export const componentsInProgress: Set<string> = new Set([
   "Drawer",
-  "Chat Input",
+  "Calendar",
 ]);
 
 export const components: { id: string; title: string; items: string[] }[] = [
@@ -626,7 +638,7 @@ export const components: { id: string; title: string; items: string[] }[] = [
     title: "Data Display",
     items: [
       "Table Header", "Table Row", "Table Row Select", "Table Row Edit",
-      "List Item", "Metric Card", "Gallery Item",
+      "List Item", "Metric Card", "Gallery Item", "Calendar", "Event Chip",
       "Empty State", "Description List", "Timeline",
     ],
   },
@@ -634,7 +646,7 @@ export const components: { id: string; title: string; items: string[] }[] = [
     id: "nav",
     title: "Navigation",
     items: [
-      "App Frame", "Tabs", "Breadcrumb", "Sidebar", "Sidebar Split", "Topbar", "Pagination",
+      "App Frame", "Tabs", "Breadcrumb", "Sidebar", "Sidebar Split", "Topbar", "Identity Button", "Pagination",
       "Stepper",
     ],
   },
@@ -659,7 +671,9 @@ export const components: { id: string; title: string; items: string[] }[] = [
     title: "AI Chat",
     items: [
       "File Icon", "Attachment Thumb", "Attachment Chip", "Quotation Bar", "Chat Input",
-      "Message Bubble", "Chat Sidebar",
+      "Bubble", "Message Actions", "User Message", "AI Message",
+      "Code Block", "Message Quote", "Message Sources", "Message Table",
+      "Chat Sidebar",
     ],
   },
 ];

package/assets/components/tokens.css

@@ -80,6 +80,17 @@
   --icon-size-md: calc(20px * var(--space-scale));
   --icon-size-lg: calc(24px * var(--space-scale));
 
+  /* Spinner · 로더 표준 크기 — IconButton 체계와 1:1 매칭 (xs=16, sm=20, md=24, lg=32).
+     로더는 캔버스를 다 채우지 않는 특성상 아이콘보다 한 단계 큰 bounds가 체감에 맞음. */
+  --loader-size-xs: calc(16px * var(--space-scale));
+  --loader-size-sm: calc(20px * var(--space-scale));
+  --loader-size-md: calc(24px * var(--space-scale));
+  --loader-size-lg: calc(32px * var(--space-scale));
+
+  /* Loader 성격 — Motion 축이 스왑 ([data-motion] 블록 참고).
+     기본값은 standard와 같은 ring. */
+  --loader-style: ring;
+
   /* 폼 컨트롤 권장 폭 — Input · Select 등 텍스트 필드 계열이 공유.
      기본 동작은 부모 폭 채움(fill)이지만, 카드/툴바 안에서 규격을 잡을 때 참조.
      md = 이메일 · 이름 · 짧은 문장 표준. lg = URL · 설명 · 긴 문장.
@@ -221,6 +232,11 @@
   --tone-hue: 260;
   --tone-chroma: 0.005;
 
+  /* 테마 중립 fixed 색 — 어두운 오버레이 위 로더·배지처럼
+     라이트/다크 공통으로 흰색이어야 하는 자리 전용 */
+  --fixed-white: #fff;
+  --fixed-black: #000;
+
   /* semantic — light mode */
   --bg:            oklch(1     var(--tone-chroma) var(--tone-hue));
   --bg-subtle:     oklch(0.978 var(--tone-chroma) var(--tone-hue));
@@ -520,20 +536,24 @@ html[data-focus-ring="off"] {
   --motion-scale: 1.2;                                           /* ~192ms · 오버슛 여운만큼 */
   --motion-distance-scale: 1.1;
   --ease-emphasized: cubic-bezier(0.34, 1.4, 0.64, 1);           /* 절제된 오버슛 spring */
+  --loader-style: dots-bounce;                                   /* 통통한 로더 — bouncy 성격 */
 }
 [data-motion="standard"] {
   --motion-scale: 1;                                             /* 160ms */
   --motion-distance-scale: 1;
   --ease-emphasized: cubic-bezier(0.32, 0.72, 0, 1);             /* Linear/Vercel ease-out */
+  --loader-style: ring;                                          /* 표준 회전 ring */
 }
 [data-motion="calm"] {
   --motion-scale: 0.9;                                           /* ~144ms · flat 곡선이라 짧아도 안전 */
   --motion-distance-scale: 0.9;
   --ease-emphasized: cubic-bezier(0.4, 0, 0.2, 1);               /* 표준 ease-out · 심심할수록 차분 */
+  --loader-style: dots-fade;                                     /* 위치 이동 없는 미니멀 dot fade */
 }
 [data-motion="none"] {
   --motion-scale: 0;
   --motion-distance-scale: 0;
+  --loader-style: ring;                                          /* 로더는 접근성 예외: 로딩 신호는 유지 */
 }
 [data-motion="none"] *,
 [data-motion="none"] *::before,

package/assets/prompts/components/ai-message.md

@@ -0,0 +1,43 @@
+# AI Message
+
+### 원칙
+AI가 보낸 응답 메시지. **왼쪽 정렬**, bubble 없이 본문 그대로 노출 — [[components/user-message]]의 bubble과 대비. 상단에 선택적 라벨, 본문(markdown 또는 콘텐츠 블록), 하단에 [[components/message-actions]].
+
+### Do
+- `label`로 메타 제목(예: “LongText”, “Code Block”)을 짧게 노출. 생략 가능.
+- `children`에 markdown HTML을 직접 넣거나, 콘텐츠 블록 컴포넌트(CodeBlock·Quote·Sources·Table)를 조합.
+- 기본 액션 `[copy, regenerate]`, `actionsVisibility`로 상시/호버 전환.
+- 생성 중엔 `isGenerating`로 액션 숨김. 로딩 UI는 [[components/message-state]] 조합.
+
+### Don't
+- bubble로 감싸지 않는다 — AI는 "본문"이 메시지 자체. bubble은 UserMessage 전용.
+- 아바타·모델명 넣지 않는다 — 상위 shell(ChatThread)에서 책임.
+- 오른쪽 정렬하지 않는다 — 왼쪽 고정.
+- edit 액션 넣지 않는다 — AI 응답은 수정 대상 아님 (regenerate가 대신).
+
+### Fallback
+visibility 애매하면 `hover`, actions 애매하면 기본 `[copy, regenerate]`.
+
+### 관련
+- [[components/user-message]] — 짝 컴포넌트
+- [[components/message-actions]] — 하단 액션 바
+- [[components/message-state]] — 로딩/상태 라인 (F5)
+- 콘텐츠 블록: `CodeBlock` / `Quote` / `Sources` / `Table` (F4)
+
+### Props 시그니처
+```tsx
+<AIMessage
+  label={ReactNode}                           // 상단 메타 라벨
+  actionsVisibility="show | hover"            // default: hover
+  actions={[{ kind: "copy" }, { kind: "regenerate" }]}  // 비우려면 []
+  isGenerating={boolean}                      // true면 액션 숨김
+>
+  본문 — markdown 또는 블록 조합
+</AIMessage>
+```
+
+### 레이아웃
+- root: `flex-direction: column; align-items: flex-start; gap: space-2`
+- label: `text-xs`, `fg-muted`
+- body: `text-base`, `line-height: 2` (평소의 ~2배, 가독성), 색 `--fg` (다크 그레이, strong보다 한 톤 연함), markdown 기본 톤
+- actions: `align=start`

package/assets/prompts/components/bubble.md

@@ -0,0 +1,56 @@
+# Bubble
+
+### 원칙
+메시지 말풍선 **primitive**. Shape 4종 × Fill 4종 조합. [[components/user-message]]·[[components/ai-message]]의 Quote 블록·AttachmentChip 등 "담는 그릇" 역할 전부에 재사용.
+
+### Do
+- UserMessage는 `shape=circular-drop fill=translucent tail=end` 조합이 기본.
+- AI Quote 블록은 `shape=rounded fill=outline` 또는 `fill=none`.
+- Shape 축 따라 radius 변화 — rounded는 `radius-xl` 토큰 사용.
+- circular-drop의 `tail` prop으로 꼬리 방향 지정 — user는 end, assistant/quote는 start.
+
+### Don't
+- Bubble을 "일반 Card" 용도로 쓰지 않는다 — 그건 [[components/metric-card]] / 커스텀.
+- fill=`solid`는 user "강조" 메시지(선택된/하이라이트)에만 — 기본은 translucent.
+- 꼬리를 양쪽 다 각지게 하지 않는다 — tail은 한 방향만.
+
+### Fallback
+shape 애매하면 `rounded`, fill 애매하면 `translucent`, size 애매하면 `md`.
+
+### 관련
+- [[components/user-message]] / [[components/ai-message]] — 상위 소비처
+- [[components/badge]] — 작은 라벨은 Badge
+- [[components/callout]] — 안내 상자는 Callout
+
+### Props 시그니처
+```tsx
+<Bubble
+  shape="rounded | circular-drop | circular | square"  // default: rounded
+  fill="none | solid | translucent | outline"          // default: translucent
+  size="md | lg"                                        // default: md
+  tail="start | end"                                    // circular-drop에서만
+>
+  Text
+</Bubble>
+```
+
+### 매트릭스
+| shape | radius |
+|---|---|
+| rounded | `--radius-md` (Shape 축 반응 명확: soft 14 / standard 10 / crisp 6) |
+| circular-drop | `--radius-md` 세 코너 + `0` tail 코너 하나 (각짐) |
+| circular | `--radius-full` (알약) |
+| square | `--radius-sm` |
+
+| fill | bg | fg | border |
+|---|---|---|---|
+| none | transparent | fg-strong | — |
+| solid | primary | bg | — |
+| translucent | primary-subtle (알파 8%) | fg-strong | — |
+| outline | bg | fg-strong | hairline border |
+
+### Size
+- `md` (기본): padding `space-2 space-3`, `text-base` — 일반 메시지 bubble.
+- `lg`: padding `space-3 space-4`, `text-base` — 히어로/강조 bubble. 패딩만 넉넉, 폰트는 md와 동일.
+
+소형 라벨이 필요하면 [[components/badge]] 사용.