@conscience-technology/ctds 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,129 @@
-# Temporary Holding Version
+# ctds
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+CTDS — 하이브리드 디자인 시스템 설치/온보딩 CLI.
+
+## 요구사항
+
+- Node.js 18+
+- Next.js App Router 프로젝트 (`app/` 또는 `src/app/` 디렉토리)
+
+## 설치 (end user)
+
+```bash
+cd my-next-app
+npx ctds init
+```
+
+`init`이 하는 일:
+
+1. 프로젝트 감지 (`package.json` + `app/` 디렉토리 확인)
+2. 다음 자산 복사:
+   - `components/` → `components/ctds/` (또는 `src/components/ctds/`)
+     — 재사용 React 컴포넌트 + **`tokens.css`** (폰트 + 토큰 + 축 셀렉터 전체)
+   - `prompts/` → `prompts/`
+   - `.claude/skills/ctds/` → `.claude/skills/ctds/`
+3. `app/ctds/page.tsx` 생성 (온보딩 라우트)
+4. **수동으로 넣을 두 가지**를 콘솔에 출력:
+   - `app/globals.css` 최상단에 `@import "../components/ctds/tokens.css";`
+   - `app/layout.tsx`에 `<ThemeController>` wrapper
+
+설치 후:
+
+```bash
+npm run dev
+# http://localhost:3000/ctds 접속 → 온보딩 → "적용"
+```
+
+"적용"을 누르면 프로젝트 루트에 두 파일이 생성됩니다:
+
+- `ctds.config.json` — 축 값. AI 에이전트(Claude Code 등)와 `ThemeController`가 참조.
+- `DESIGN.md` — 테마·축 산문 요약. 사람·AI 모두 읽음.
+
+두 파일 모두 **커밋**하세요. 다른 개발자나 AI가 참조할 수 있어야 합니다.
+
+## 옵션
+
+```bash
+npx ctds init           # 기본
+npx ctds init --dry     # 아무것도 쓰지 않고 생성 예정 파일만 출력
+npx ctds init --force   # 기존 파일 있어도 덮어쓰기
+```
+
+디버그:
+```bash
+CTDS_DEBUG=1 npx ctds init
+```
+
+## 로컬 개발 (contributor)
+
+CTDS 레포에서 CLI를 수정·테스트할 때:
+
+```bash
+cd packages/ctds-cli
+npm link                     # 전역에 `ctds` 바이너리 심링크
+
+cd /tmp/test-next-app        # 테스트할 Next.js 플젝
+ctds init --dry              # 자산이 CTDS 레포에서 바로 긁힘 (bundle 없이)
+```
+
+`getAssetSources()`가 `assets/components`가 없으면 자동으로 레포 루트
+(`../../web/components`, `../../prompts`, `../../.claude/skills/ctds`)에서 긁어옴.
+
+## Publish
+
+```bash
+cd packages/ctds-cli
+npm run bundle-assets    # 레포 자산 → packages/ctds-cli/assets/ 로 복사
+npm publish --access public
+```
+
+## 알려진 미완성 (end-to-end 2단계 테스트 전)
+
+**지금 상태**: CTDS 레포 자체에서 `/ctds` 적용 플로우(1단계)는 작동. 다른 Next.js 플젝에서 `ctds init` 후 매끄럽게 쓰기(2단계)는 아래 간극들 때문에 터질 가능성이 큼. 다음 세션에서 하나씩 해결 예정.
+
+### ~~1. `tokens.css`가 분리돼 있지 않음~~ ✅ 해결 (2026-10-07)
+`web/app/globals.css`에서 토큰·축 셀렉터 블록(1~718줄)을 `web/components/tokens.css`로 떼냄. 폰트 로드까지 포함. CLI 복사 후 `app/globals.css` 상단에 `@import "../components/ctds/tokens.css";` 한 줄이면 CTDS 완전 작동.
+
+### ~~2. `ThemeController`가 `web/app/data.ts` 참조~~ ✅ 해결 (2026-10-07)
+`web/app/data.ts`를 `web/components/_data.ts`로 통째 이동. 축 타입 + preset 데이터 전부. 참조하던 파일(ThemeController, OnboardingAxisPanel, Icon 등) import 경로 전부 `@/components/_data` 또는 `../_data`로 교체. `components/` 복사 시 자동으로 따라감.
+
+### ~~3. 복사된 컴포넌트의 `@/components/*` alias~~ ✅ 해결 (2026-10-07)
+`components/` 내부의 모든 `@/components/<name>` → `../<name>` 상대경로로 재작성. `@/lib/cn`·`@/lib/color`가 쓰이던 유틸은 `components/_cn.ts`·`components/_color.ts`로 이동하고 참조를 상대경로로 교체. CLI 복사 후 사용자 플젝 tsconfig alias와 무관하게 작동.
+
+### ~~4. `OnboardingPage` export 형식~~ ✅ 해결 (2026-10-07)
+온보딩 UI 전체를 `web/app/onboarding/` → `web/components/Onboarding/`로 이동. OnboardingPage를 named export로 변경. CTDS 레포의 `/onboarding`은 default-export wrapper로 유지. ThemeController·axisOptions도 `web/components/` 아래로 이동. 복사된 사용자 플젝에서 `../../components/ctds/Onboarding`로 named import.
+
+### ~~5. 의존성 호환~~ ✅ 해결 (2026-10-07)
+CLI가 사용자 플젝 `package.json`의 deps를 체크해, 빠진 CTDS 런타임 패키지만 `npm install ...` 명령어로 안내. `src/utils/deps.js`의 `CTDS_RUNTIME_DEPS` 참조. Next 16, React 18.3에서 end-to-end 테스트 통과.
+
+### ~~6. Server action `process.cwd()` 가정~~ ✅ 해결 (2026-10-07)
+`actions.ts`의 `findProjectRoot()`가 cwd부터 상위로 올라가며 `package.json`이 있는 **가장 바깥 디렉토리**를 선택. CTDS 자기 레포 테스트 케이스(web/ vs 루트)와 end-to-end 테스트 플젝 모두 올바른 루트 찾음.
+
+---
+
+## 알려진 자잘한 간극 (end-to-end 테스트에서 발견, 치명적 아님)
+
+### 7. `.visually-hidden` 전역 유틸 ✅ 해결
+SelectableCard가 `className="visually-hidden"`을 참조하는데 기존엔 `globals.css`에만 있어서 복사 안 됨. `web/components/_utils.css` 신규 파일로 분리, `tokens.css`가 `@import "./_utils.css"`. 결과: 네이티브 라디오/체크박스가 올바르게 숨겨짐.
+
+### 8. `web/public/onboarding/*.png` 미복사 ✅ 해결
+온보딩 테마 호버 미리보기 이미지(pure.png/spare.png/expressive.png) 복사 플랜에 추가. 번들러(`bundle-assets.mjs`)와 repo fallback(`getAssetSources`) 둘 다 `public/onboarding` 포함.
+
+---
+
+## end-to-end 테스트 결과 (2026-10-07)
+
+Fresh Next.js 16 플젝에 `node bin/ctds.js init` 실행 → CLI 안내대로 수동 설정 → `/ctds` 접속 → 온보딩 완료 → "적용".
+
+- ✓ 자산 복사 (components/ctds/, prompts/, .claude/skills/ctds/, public/onboarding/)
+- ✓ `/ctds/page.tsx` 생성
+- ✓ 수동 설정 안내 출력 (globals.css import, layout.tsx wrapper, npm install deps)
+- ✓ dev 서버 렌더링 (라디오·타이틀·배경 정상)
+- ✓ 적용 → **test 플젝 루트에** `ctds.config.json` + `DESIGN.md` 생성
+- ✓ `findProjectRoot()`가 cwd(`/private/tmp/ctds-e2e`) 그대로 선택
+
+---
+
+## 라이선스
+
+MIT

package/assets/components/AppFrame/AppFrame.module.css

@@ -0,0 +1,177 @@
+/* Root ─────────────────────────────────────────────────
+   3영역 grid. layout이 구조, variant가 표현을 담당.
+   app-scroll 패러다임: AppFrame이 뷰포트 높이(100dvh)를 꽉 채우고, 바깥 html/body는
+   스크롤하지 않는다. topbar/sidebar는 각자 grid cell로 자리만 잡으면 되고(sticky·
+   측정·오프셋 전부 불필요), 콘텐츠는 .contentSlot 자체에서 세로 스크롤. */
+.root {
+  display: grid;
+  height: 100dvh;
+  min-height: 0;
+  overflow: hidden;
+}
+
+/* sidebar-first — 사이드바가 세로 전체, 탑바는 오른쪽 영역 위.
+   Linear · Slack · Notion 패턴. */
+.root[data-layout="sidebar-first"] {
+  grid-template-columns: auto 1fr;
+  grid-template-rows: auto 1fr;
+  grid-template-areas:
+    "sidebar topbar"
+    "sidebar content";
+}
+
+.root[data-layout="sidebar-first"][data-has-tabs] {
+  grid-template-rows: auto auto 1fr;
+  grid-template-areas:
+    "sidebar topbar"
+    "sidebar tabs"
+    "sidebar content";
+}
+
+/* topbar-first — 탑바가 가로 전체, 사이드바는 아래 왼쪽.
+   Jira · Vercel · Figma 홈 패턴. */
+.root[data-layout="topbar-first"] {
+  grid-template-columns: auto 1fr;
+  grid-template-rows: auto 1fr;
+  grid-template-areas:
+    "topbar  topbar"
+    "sidebar content";
+}
+
+.root[data-layout="topbar-first"][data-has-tabs] {
+  grid-template-rows: auto auto 1fr;
+  grid-template-areas:
+    "topbar  topbar"
+    "tabs    tabs"
+    "sidebar content";
+}
+
+/* 슬롯 생략 분기 ───────────────────────────────────────
+   사이드바만 / 탑바만 / 콘텐츠만 — content가 남는 공간 전체를 먹도록. */
+
+/* 탑바만 */
+.root:not([data-has-sidebar]):not([data-has-topbar]) {
+  grid-template-columns: 1fr;
+  grid-template-rows: 1fr;
+  grid-template-areas: "content";
+}
+
+.root[data-has-topbar]:not([data-has-sidebar]) {
+  grid-template-columns: 1fr;
+  grid-template-rows: auto 1fr;
+  grid-template-areas:
+    "topbar"
+    "content";
+}
+
+.root[data-has-topbar][data-has-tabs]:not([data-has-sidebar]) {
+  grid-template-columns: 1fr;
+  grid-template-rows: auto auto 1fr;
+  grid-template-areas:
+    "topbar"
+    "tabs"
+    "content";
+}
+
+.root[data-has-sidebar]:not([data-has-topbar]) {
+  grid-template-columns: auto 1fr;
+  grid-template-rows: 1fr;
+  grid-template-areas: "sidebar content";
+}
+
+.sidebarSlot {
+  grid-area: sidebar;
+  display: flex;
+  min-height: 0;
+  /* 사이드바 영역은 자기 cell 높이 안에 자식(Sidebar)을 가둔다. 자식 콘텐츠가
+     길어지면 자식 내부 Body가 스크롤로 해결 — 영역 밖으로 삐져나오지 않도록. */
+  overflow: hidden;
+  background: var(--bg);
+}
+
+.topbarSlot {
+  grid-area: topbar;
+  display: flex;
+  min-width: 0;
+  background: var(--bg);
+}
+
+.tabsSlot {
+  grid-area: tabs;
+  display: flex;
+  min-width: 0;
+}
+
+/* 콘텐츠 cell이 유일한 세로 스크롤 컨테이너. topbar/sidebar는 그대로 자리에 있고
+   이 안쪽만 스크롤 — body-scroll + sticky 조합의 jank(측정 지연, 사이드바 흔들림)
+   가 발생하지 않는다. */
+.contentSlot {
+  grid-area: content;
+  min-width: 0;
+  min-height: 0;
+  overflow-y: auto;
+  overflow-x: hidden;
+}
+
+/* outlined ────────────────────────────────────────────
+   표현은 topbar 아래 hairline 한 줄만. 전체 테두리·radius·그림자 없음.
+   사이드바 좌측도 동일하게 hairline 한 줄만 — 바깥 카드 느낌이 생기지 않도록.
+   tabs가 있으면 topbar와 tabs 사이는 선 없이 붙고, tabs 아래에 hairline을 둠. */
+.root[data-variant="outlined"] .topbarSlot {
+  border-block-end: var(--hairline) solid var(--border);
+}
+
+.root[data-variant="outlined"][data-has-tabs] .topbarSlot {
+  border-block-end: none;
+}
+
+.root[data-variant="outlined"] .tabsSlot {
+  border-block-end: var(--hairline) solid var(--border);
+}
+
+.root[data-variant="outlined"] .sidebarSlot {
+  border-inline-end: var(--hairline) solid var(--border);
+}
+
+/* floating ────────────────────────────────────────────
+   sidebar/topbar/content가 각각 카드로 떠 있음. */
+.root[data-variant="floating"] {
+  gap: var(--space-3);
+  padding: var(--space-3);
+  background: var(--bg-subtle);
+}
+
+.root[data-variant="floating"] .sidebarSlot,
+.root[data-variant="floating"] .topbarSlot,
+.root[data-variant="floating"] .tabsSlot,
+.root[data-variant="floating"] .contentSlot {
+  background: var(--bg);
+  border-radius: var(--radius-lg);
+  box-shadow: var(--shadow-sm);
+}
+
+/* flat ────────────────────────────────────────────────
+   표현 없음. grid만. */
+
+/* 좁은 뷰포트 ─────────────────────────────────────────
+   900px 이하: 사이드바 영역 숨김. grid-template을 1열로 override해서
+   content가 전폭을 받도록. layout(sidebar-first/topbar-first) 양쪽 모두 커버. */
+@media (max-width: 900px) {
+  .root[data-has-sidebar] .sidebarSlot {
+    display: none;
+  }
+  .root[data-has-sidebar][data-layout="sidebar-first"],
+  .root[data-has-sidebar][data-layout="topbar-first"] {
+    grid-template-columns: 1fr;
+    grid-template-areas:
+      "topbar"
+      "content";
+  }
+  .root[data-has-sidebar][data-has-tabs][data-layout="sidebar-first"],
+  .root[data-has-sidebar][data-has-tabs][data-layout="topbar-first"] {
+    grid-template-areas:
+      "topbar"
+      "tabs"
+      "content";
+  }
+}

package/assets/components/AppFrame/AppFrame.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+import {
+  Children,
+  forwardRef,
+  isValidElement,
+  type HTMLAttributes,
+  type ReactNode,
+} from "react";
+
+import { cn } from "../_cn";
+import styles from "./AppFrame.module.css";
+
+export type AppFrameVariant = "outlined" | "floating" | "flat";
+export type AppFrameLayout = "sidebar-first" | "topbar-first";
+
+export interface AppFrameProps extends HTMLAttributes<HTMLDivElement> {
+  /** 컨테이너 표현(bg/border/shadow). 기본 outlined. */
+  variant?: AppFrameVariant;
+  /**
+   * 레이아웃 구조.
+   * - sidebar-first: 사이드바가 세로 전체, 탑바는 오른쪽 영역 위에만. Linear/Slack.
+   * - topbar-first: 탑바가 가로 전체, 사이드바는 아래 왼쪽에만. Jira/Vercel.
+   * 기본 sidebar-first.
+   */
+  layout?: AppFrameLayout;
+}
+
+/* Slots ────────────────────────────────────────────────
+   grid-area 배정용 얇은 wrapper. */
+function AppFrameSidebar({ children }: { children: ReactNode }) {
+  return <div className={styles.sidebarSlot}>{children}</div>;
+}
+
+function AppFrameTopbar({ children }: { children: ReactNode }) {
+  return <div className={styles.topbarSlot}>{children}</div>;
+}
+
+function AppFrameTabs({ children }: { children: ReactNode }) {
+  return <div className={styles.tabsSlot}>{children}</div>;
+}
+
+function AppFrameContent({ children }: { children: ReactNode }) {
+  return <div className={styles.contentSlot}>{children}</div>;
+}
+
+/* Root ─────────────────────────────────────────────────
+   children을 훑어 어떤 슬롯이 들어왔는지 감지. 비어있는 슬롯이 있으면
+   data-has-* attribute로 CSS에게 알려 grid-template을 조정하게 한다. */
+const AppFrameRoot = forwardRef<HTMLDivElement, AppFrameProps>(function AppFrameRoot(
+  { variant = "outlined", layout = "sidebar-first", className, children, ...rest },
+  ref,
+) {
+  let hasSidebar = false;
+  let hasTopbar = false;
+  let hasTabs = false;
+  Children.forEach(children, (child) => {
+    if (!isValidElement(child)) return;
+    if (child.type === AppFrameSidebar) hasSidebar = true;
+    else if (child.type === AppFrameTopbar) hasTopbar = true;
+    else if (child.type === AppFrameTabs) hasTabs = true;
+  });
+
+  return (
+    <div
+      ref={ref}
+      className={cn(styles.root, className)}
+      data-variant={variant}
+      data-layout={layout}
+      data-has-sidebar={hasSidebar || undefined}
+      data-has-topbar={hasTopbar || undefined}
+      data-has-tabs={hasTabs || undefined}
+      {...rest}
+    >
+      {children}
+    </div>
+  );
+});
+
+type AppFrameComponent = typeof AppFrameRoot & {
+  Sidebar: typeof AppFrameSidebar;
+  Topbar: typeof AppFrameTopbar;
+  Tabs: typeof AppFrameTabs;
+  Content: typeof AppFrameContent;
+};
+
+const AppFrame = AppFrameRoot as AppFrameComponent;
+AppFrame.Sidebar = AppFrameSidebar;
+AppFrame.Topbar = AppFrameTopbar;
+AppFrame.Tabs = AppFrameTabs;
+AppFrame.Content = AppFrameContent;
+
+export { AppFrame };

package/assets/components/AppFrame/index.ts

@@ -0,0 +1,6 @@
+export { AppFrame } from "./AppFrame";
+export type {
+  AppFrameProps,
+  AppFrameVariant,
+  AppFrameLayout,
+} from "./AppFrame";

package/assets/components/AttachmentChip/AttachmentChip.module.css

@@ -0,0 +1,71 @@
+/* AttachmentChip — [FileIcon] filename [X]
+   레퍼런스: ChatInput 안에서 쓰이는 둥근 사각 — radius-md, hairline border. */
+
+.root {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-width: 0;
+  background: var(--bg);
+  border: var(--hairline) solid var(--border);
+  border-radius: var(--radius-md);
+  color: var(--fg);
+  transition: var(--transition-colors);
+}
+
+/* 패딩만 size 차이. 오른쪽은 X 버튼 자리라 좁게. */
+.sizeSm {
+  padding: var(--space-1) var(--space-1) var(--space-1) var(--space-1);
+  font-size: var(--text-xs);
+}
+.sizeMd {
+  padding: var(--space-1_5) var(--space-1_5) var(--space-1_5) var(--space-1_5);
+  font-size: var(--text-sm);
+}
+
+/* 파일명 */
+.label {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  color: var(--fg-strong);
+  line-height: 1.2;
+  padding-right: var(--space-1);
+}
+
+/* X 버튼 — size에 따라 width/height가 변하도록 토큰 조합 */
+.removeBtn {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  background: transparent;
+  color: var(--fg-muted);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition: var(--transition-colors);
+  width: var(--space-5);
+  height: var(--space-5);
+  flex: 0 0 auto;
+}
+.sizeSm .removeBtn {
+  width: var(--space-4);
+  height: var(--space-4);
+}
+
+.removeBtn:hover {
+  background: var(--bg-subtle);
+  color: var(--fg);
+}
+.removeBtn:focus-visible {
+  outline: none;
+  box-shadow: var(--ring);
+}
+
+.removeIcon {
+  width: 70%;
+  height: 70%;
+}

package/assets/components/AttachmentChip/AttachmentChip.tsx

@@ -0,0 +1,74 @@
+"use client";
+
+import type { HTMLAttributes, MouseEvent } from "react";
+import { X as PhX } from "@phosphor-icons/react";
+import { FileIcon, type FileIconSize } from "@/components/FileIcon";
+import styles from "./AttachmentChip.module.css";
+
+export type AttachmentChipSize = "sm" | "md";
+
+export interface AttachmentChipProps
+  extends Omit<HTMLAttributes<HTMLSpanElement>, "children" | "onError"> {
+  /** 파일명. 확장자가 FileIcon 색/라벨을 결정. */
+  filename: string;
+  /** 지정 시 우측에 X 노출, 클릭 시 호출. */
+  onRemove?: (e: MouseEvent<HTMLButtonElement>) => void;
+  /** sm=padding·icon 작게 / md=기본. */
+  size?: AttachmentChipSize;
+}
+
+const sizeClass: Record<AttachmentChipSize, string> = {
+  sm: styles.sizeSm,
+  md: styles.sizeMd,
+};
+
+const fileIconSize: Record<AttachmentChipSize, FileIconSize> = {
+  sm: "sm",
+  md: "md",
+};
+
+/** 긴 파일명을 중간 생략으로 자르되 확장자는 유지.
+ *  "very-long-report-name.pdf" → "very-long-rep…pdf" */
+function middleEllipsis(filename: string, max = 28): string {
+  if (filename.length <= max) return filename;
+  const dot = filename.lastIndexOf(".");
+  if (dot < 0 || dot < filename.length - 6) {
+    return filename.slice(0, max - 1) + "…";
+  }
+  const ext = filename.slice(dot); // ".pdf"
+  const head = filename.slice(0, Math.max(1, max - ext.length - 1));
+  return head + "…" + ext;
+}
+
+export function AttachmentChip({
+  filename,
+  onRemove,
+  size = "md",
+  className,
+  ...rest
+}: AttachmentChipProps) {
+  const cls = [styles.root, sizeClass[size], className]
+    .filter(Boolean)
+    .join(" ");
+
+  const label = middleEllipsis(filename);
+
+  return (
+    <span className={cls} {...rest}>
+      <FileIcon ext={filename} size={fileIconSize[size]} />
+      <span className={styles.label} title={filename}>
+        {label}
+      </span>
+      {onRemove ? (
+        <button
+          type="button"
+          className={styles.removeBtn}
+          onClick={onRemove}
+          aria-label="첨부 제거"
+        >
+          <PhX className={styles.removeIcon} weight="regular" />
+        </button>
+      ) : null}
+    </span>
+  );
+}

package/assets/components/AttachmentChip/index.ts

@@ -0,0 +1,2 @@
+export { AttachmentChip } from "./AttachmentChip";
+export type { AttachmentChipProps, AttachmentChipSize } from "./AttachmentChip";

package/assets/components/AttachmentThumb/AttachmentThumb.module.css

@@ -0,0 +1,107 @@
+/* AttachmentThumb — 정사각 썸네일.
+   비율은 FileIcon과 동일 (radius 0.25, glyph 0.60). 사이즈 리터럴은 라인별 ignore. */
+
+.root {
+  --at-size: 40px; /* lint-hardcoded: ignore */
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: var(--at-size);
+  height: var(--at-size);
+  border-radius: calc(var(--at-size) * 0.25);
+  flex: 0 0 auto;
+  user-select: none;
+  transition: var(--transition-colors);
+  /* overflow:hidden X — bg clip과 img radius는 각자 처리.
+     Remove 버튼이 바깥으로 overlap되도록. */
+}
+
+.sizeSm { --at-size: 32px; /* lint-hardcoded: ignore */ }
+.sizeMd { --at-size: 40px; /* lint-hardcoded: ignore */ }
+.sizeLg { --at-size: 56px; /* lint-hardcoded: ignore */ }
+
+/* 이미지 */
+.hasImage {
+  background: var(--bg-subtle);
+}
+
+/* Image glyph placeholder — src 없을 때. 색은 TSX의 CSS 변수로 주입. */
+.placeholder {
+  background: var(--at-ph-bg-light);
+  color: var(--at-ph-fg-light);
+}
+:global([data-mode="dark"]) .placeholder {
+  background: var(--at-ph-bg-dark);
+  color: var(--at-ph-fg-dark);
+}
+.img {
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  display: block;
+  border-radius: inherit;
+}
+
+/* image-square glyph — FileIcon의 generic과 동일 size × 0.60 */
+.glyph {
+  width: calc(var(--at-size) * 0.60);
+  height: calc(var(--at-size) * 0.60);
+}
+
+/* Loading pulse — 토큰 조합 */
+.loading {
+  background: var(--bg-subtle);
+  animation: at-pulse calc(var(--duration-slower) * 5) var(--ease-in-out) infinite;
+}
+@keyframes at-pulse {
+  0%, 100% { opacity: 1; }
+  50% { opacity: 0.55; }
+}
+
+/* Remove 버튼 — hover 시만 노출. 코너 overlap. */
+.removeBtn {
+  position: absolute;
+  top: calc(var(--at-size) * -0.12);
+  right: calc(var(--at-size) * -0.12);
+  width: calc(var(--at-size) * 0.42);
+  height: calc(var(--at-size) * 0.42);
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  border: 0;
+  border-radius: var(--radius-full);
+  background: var(--bg);
+  color: var(--fg);
+  box-shadow:
+    inset 0 0 0 1px color-mix(in oklch, var(--fg) 15%, transparent),
+    var(--shadow-xs);
+  cursor: pointer;
+  opacity: 0;
+  transform: scale(0.9);
+  transition:
+    var(--transition-colors),
+    opacity var(--duration-fast) var(--ease-out),
+    transform var(--duration-fast) var(--ease-out);
+  z-index: var(--z-raise);
+}
+.root[data-removable]:hover .removeBtn,
+.removeBtn:focus-visible {
+  opacity: 1;
+  transform: scale(1);
+}
+.removeBtn:hover {
+  background: var(--bg-subtle);
+}
+.removeBtn:focus-visible {
+  outline: none;
+  box-shadow:
+    inset 0 0 0 1px color-mix(in oklch, var(--fg) 15%, transparent),
+    var(--ring);
+}
+.removeIcon {
+  width: 62%;
+  height: 62%;
+}