@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/list/AGENTS.md

@@ -0,0 +1,392 @@
+# List
+
+> 컨테이너 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+사람 · 파일 · 설정처럼 같은 모양의 행을 나열해요. 행 사이는 선 대신 여백으로 구분하고, 앞(leading) · 제목 · 설명 · 메타 · 뒤(trailing) 자리를 채워 조합해요. href나 onClick을 주면 행 전체가 눌리고, trailing 안의 컨트롤은 행과 따로 동작해요.
+
+```tsx
+import { List, ListItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 순위 목록(많이 본 페이지 · 유입 경로 · 국가)은 `BarList`: 이름 뒤로 옅은 막대(`tone` 또는 `color` 16% 섞기), 값은 오른쪽 tabular. 긴 목록은 `limit` + "더 보기"(0fr ↔ 1fr), 순위가 바뀌면 행이 새 자리로 미끄러진다. 행 진행률 하나면 `ListItem progress`.
+- 사람·파일·설정 같은 행은 `List` + `ListItem`. 행 사이는 선 대신 간격, 누를 수 있는 행은 hover 채움.
+- 파운데이션보다 **이미 있는 조합 컴포넌트를 먼저** 쓴다: 카드 제목줄은 `CardHeader`(오른쪽은 `actions`), 행 목록은 `List` + `ListItem`(`leading` · `trailing`). Stack/Inline으로 같은 것을 다시 짜지 않는다. List를 카드 안에 넣을 땐 `Card padding="sm"`(12px)이면 행 안쪽 여백(12px)과 왼쪽 끝이 맞는다.
+- 행 안의 진행률은 `ListItem progress`(행 뒤로 옅은 채움), 그룹으로 나눈 체크리스트는 `ProgressTracker groups`(Accordion `filled` + StatusIcon).
+- 목록–상세는 `SplitView`(칸마다 스크롤, 경계는 `role="separator"`). 회색 판 위의 선택 행은 `ListItem variant="raised"`.
+
+## API
+
+### List
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | ListItem들. |
+| `variant` | `'plain' \| 'inset'` | `'plain'` | plain: 페이지 위의 행 · inset: 흰 카드 위에 묶인 행. |
+| `density` | `'compact' \| 'default' \| 'comfortable'` | `'default'` | 행 높이와 여백. |
+| `label` | `ReactNode` |  | 행 위의 작은 제목(예: "멤버 6명"). |
+| `aria-label` | `string` |  | 목록(ul)의 접근성 이름. label이 없을 때 주세요. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+### ListItem
+
+List.Item으로도 쓸 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 첫 줄. |
+| `description` | `ReactNode` |  | 회색 둘째 줄. |
+| `leading` | `ReactNode` |  | 왼쪽 아바타 · 아이콘 · 썸네일. |
+| `meta` | `ReactNode` |  | 오른쪽 작은 회색 글자(시간, 크기, 개수). |
+| `trailing` | `ReactNode` |  | 오른쪽 컨트롤(버튼, 스위치, 배지, 메뉴). 행 클릭과 따로 동작해요. |
+| `href` | `string` |  | 행 전체를 링크로. |
+| `onClick` | `() => void` |  | 행 전체를 버튼으로(Enter / Space 지원). |
+| `chevron` | `boolean` |  | 끝에 › 표시. 다른 화면을 여는 행에. |
+| `selected` | `boolean` |  | 선택 상태. 링크면 aria-current="page", 버튼이면 aria-pressed. |
+| `disabled` | `boolean` |  | 비활성. 눌리지 않아요. |
+| `variant` | `'default' \| 'raised'` | `'default'` | raised: 선택된 행이 회색 채움 대신 그림자가 있는 흰 카드로 떠올라요. 옅은 회색 판(SplitView 목록) 위의 목록에. |
+| `progress` | `number` |  | 0–1. 행 내용 뒤로 옅은 채움이 왼쪽부터 자라요(행 안의 작업 진행률). 바뀌면 너비가 부드럽게 움직여요. 채움은 장식이라 진행률은 글자로도 보여 주세요. |
+| `progressTone` | `'accent' \| 'success' \| 'warning' \| 'danger' \| 'neutral'` | `'accent'` | progress 채움 색. 일시정지는 neutral, 완료는 success처럼. |
+| `className` | `string` |  | 행(li)에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 멤버
+
+leading에 Avatar, trailing에 Badge, meta에 최근 활동 시간.
+
+```tsx
+import { Avatar, Badge, type Tone, List, ListItem } from '@iamfiro/design'
+
+const MEMBERS: Array<{ name: string; email: string; role: string; tone: Tone; seen: string; online?: boolean }> = [
+  { name: '김민지', email: 'minji@lumen.app', role: '관리자', tone: 'accent', seen: '접속 중', online: true },
+  { name: '이도현', email: 'dohyun@lumen.app', role: '편집자', tone: 'neutral', seen: '2분 전', online: true },
+  { name: '박서연', email: 'seoyeon@lumen.app', role: '초대됨', tone: 'info', seen: '10월 24일' },
+  { name: '최준호', email: 'junho@lumen.app', role: '뷰어', tone: 'neutral', seen: '3일 전' },
+]
+
+export default function Example() {
+  return (
+    <List label={`멤버 ${MEMBERS.length}명`} style={{ width: 460 }}>
+      {MEMBERS.map((m) => (
+        <ListItem
+          key={m.email}
+          leading={<Avatar name={m.name} size={36} online={m.online} />}
+          title={m.name}
+          description={m.email}
+          meta={m.seen}
+          trailing={<Badge tone={m.tone}>{m.role}</Badge>}
+        />
+      ))}
+    </List>
+  )
+}
+```
+
+### 파일
+
+leading에 아이콘, meta에 크기 · 수정 시간, trailing에 DropdownMenu. 메뉴를 눌러도 행은 눌리지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Download, FileSpreadsheet, FileText, Image, MoreHorizontal, Pencil, Trash2 } from 'lucide-react'
+import { Button, DropdownMenu, DropdownMenuItem, DropdownMenuSeparator, List, ListItem } from '@iamfiro/design'
+
+const FILES = [
+  { id: 'f1', icon: <FileText />, name: '3분기 사업 계획서.pdf', size: '2.4MB', time: '2분 전' },
+  { id: 'f2', icon: <FileSpreadsheet />, name: '10월 매출 정리.xlsx', size: '860KB', time: '1시간 전' },
+  { id: 'f3', icon: <Image />, name: '랜딩 페이지 시안.png', size: '5.1MB', time: '10월 23일' },
+]
+
+export default function Example() {
+  const [opened, setOpened] = useState<string | null>(null)
+  return (
+    <List aria-label="최근 파일" style={{ width: 480 }}>
+      {FILES.map((f) => (
+        <ListItem
+          key={f.id}
+          leading={f.icon}
+          title={f.name}
+          description={opened === f.id ? '방금 열어 봤어요' : undefined}
+          meta={`${f.size} · ${f.time}`}
+          onClick={() => setOpened(f.id)}
+          selected={opened === f.id}
+          trailing={
+            <DropdownMenu align="end" aria-label={`${f.name} 메뉴`} trigger={<Button iconOnly variant="ghost" size="sm" icon={<MoreHorizontal />} aria-label="더보기" />}>
+              <DropdownMenuItem icon={<Download />}>다운로드</DropdownMenuItem>
+              <DropdownMenuItem icon={<Pencil />}>이름 바꾸기</DropdownMenuItem>
+              <DropdownMenuSeparator />
+              <DropdownMenuItem icon={<Trash2 />} danger>
+                삭제
+              </DropdownMenuItem>
+            </DropdownMenu>
+          }
+        />
+      ))}
+    </List>
+  )
+}
+```
+
+### 설정
+
+trailing에 Switch를 둔 행과, chevron으로 다음 화면을 여는 행. 실제 앱에선 href로 링크를, 여기선 onClick으로 버튼을 만들었어요. Enter / Space로도 눌러요.
+
+```tsx
+import { useState } from 'react'
+import { Bell, Globe, KeyRound, Moon, Smartphone } from 'lucide-react'
+import { Stack, Switch, List, ListItem } from '@iamfiro/design'
+
+export default function Example() {
+  const [push, setPush] = useState(true)
+  const [dark, setDark] = useState(false)
+  const [opened, setOpened] = useState<string | null>(null)
+
+  return (
+    <Stack gap={6} style={{ width: 440 }}>
+      <List variant="inset" label="일반">
+        <ListItem
+          leading={<Bell />}
+          title="푸시 알림"
+          description="멘션과 댓글을 바로 알려 드려요."
+          trailing={<Switch checked={push} onChange={(e) => setPush(e.target.checked)} aria-label="푸시 알림" />}
+        />
+        <ListItem
+          leading={<Moon />}
+          title="다크 모드"
+          trailing={<Switch checked={dark} onChange={(e) => setDark(e.target.checked)} aria-label="다크 모드" />}
+        />
+        <ListItem leading={<Globe />} title="언어" meta="한국어" onClick={() => setOpened('language')} selected={opened === 'language'} chevron />
+      </List>
+      <List variant="inset" label="보안">
+        <ListItem
+          leading={<KeyRound />}
+          title="비밀번호 변경"
+          description={opened === 'password' ? '변경 화면을 열었어요.' : '마지막 변경 3개월 전'}
+          onClick={() => setOpened('password')}
+          chevron
+        />
+        <ListItem
+          leading={<Smartphone />}
+          title="로그인된 기기"
+          meta="3대"
+          onClick={() => setOpened('devices')}
+          selected={opened === 'devices'}
+          chevron
+        />
+        <ListItem leading={<KeyRound />} title="보안 키" description="조직 관리자만 설정할 수 있어요." disabled chevron />
+      </List>
+    </Stack>
+  )
+}
+```
+
+### 카드로 묶은 목록
+
+Card padding="sm" 안에 List를 넣으면 왼쪽 끝이 맞아요. leading에 IconTile(아이콘 · 글자 타일), trailing에 Kbd 단축키, 제목 뒤엔 회색 도메인을 붙였어요. label이 그룹 제목이 돼요.
+
+```tsx
+import { Bookmark, FileSearch, History, Languages } from 'lucide-react'
+import { IconTile, Kbd, Stack, Text, Card, List, ListItem } from '@iamfiro/design'
+
+const TOOLS = [
+  { id: 'bookmark', label: '북마크', icon: <Bookmark />, keys: ['mod', 'shift', 'B'] },
+  { id: 'history', label: '방문 기록', icon: <History />, keys: ['mod', 'Y'] },
+  { id: 'find', label: '페이지에서 찾기', icon: <FileSearch />, keys: ['mod', 'F'] },
+  { id: 'translate', label: '번역', icon: <Languages /> },
+]
+
+const SUGGESTED = [
+  { id: 'wiki', title: '팀 위키', domain: 'wiki.lumen.app' },
+  { id: 'design', title: '디자인 가이드', domain: 'design.lumen.app' },
+  { id: 'news', title: '사내 소식', domain: 'news.lumen.app' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ width: 300 }}>
+      {/* Card padding="sm"(12px)이면 행 안쪽 여백(12px)과 왼쪽 끝이 맞아요. */}
+      <Card padding="sm">
+        <List label="도구" density="compact">
+          {TOOLS.map((t) => (
+            <ListItem
+              key={t.id}
+              leading={<IconTile>{t.icon}</IconTile>}
+              title={t.label}
+              onClick={() => {}}
+              trailing={t.keys && <Kbd keys={t.keys} size="sm" />}
+            />
+          ))}
+        </List>
+      </Card>
+      <Card padding="sm">
+        <List label="추천" density="compact">
+          {SUGGESTED.map((s) => (
+            <ListItem
+              key={s.id}
+              leading={<IconTile>{s.title.slice(0, 1)}</IconTile>}
+              title={
+                <>
+                  {s.title}{' '}
+                  <Text as="span" variant="body-sm" tone="tertiary">
+                    {s.domain}
+                  </Text>
+                </>
+              }
+              href="#"
+            />
+          ))}
+        </List>
+      </Card>
+    </Stack>
+  )
+}
+```
+
+### 행 안의 진행률 (progress)
+
+progress(0–1)를 주면 행 뒤로 옅은 채움이 자라요. 작업 대기열처럼 행마다 진행 상황이 다를 때. 일시정지하면 회색(neutral), 끝나면 초록(success)으로 바꿨어요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { FileSpreadsheet, FileText, Image, Pause, Play } from 'lucide-react'
+import { Button, IconTile, Text, Card, CardHeader, List, ListItem } from '@iamfiro/design'
+
+const JOBS = [
+  { id: 'j1', icon: <FileSpreadsheet />, title: '10월 정산 내보내기', worker: '김민지', speed: 0.07 },
+  { id: 'j2', icon: <Image />, title: '상품 사진 1,240장 압축', worker: '이도현', speed: 0.04 },
+  { id: 'j3', icon: <FileText />, title: '계약서 PDF 변환', worker: '김민지', speed: 0.11 },
+]
+
+export default function Example() {
+  const [paused, setPaused] = useState(false)
+  const [progress, setProgress] = useState<Record<string, number>>({ j1: 0.35, j2: 0.6, j3: 0.12 })
+
+  // 데모용 진행: 1초마다 조금씩 채워지고, 다 차면 처음부터 다시.
+  useEffect(() => {
+    if (paused) return
+    const id = window.setInterval(() => {
+      setProgress((prev) => Object.fromEntries(JOBS.map((j) => [j.id, prev[j.id] >= 1 ? 0 : Math.min(1, prev[j.id] + j.speed)])))
+    }, 1000)
+    return () => window.clearInterval(id)
+  }, [paused])
+
+  return (
+    <Card padding="sm" style={{ width: 440 }}>
+      <CardHeader
+        title="작업 대기열"
+        actions={
+          <Button variant="secondary" size="sm" icon={paused ? <Play /> : <Pause />} onClick={() => setPaused((v) => !v)}>
+            {paused ? '다시 시작' : '일시정지'}
+          </Button>
+        }
+      />
+      <List density="compact" aria-label="실행 중인 작업">
+        {JOBS.map((j) => {
+          const p = progress[j.id]
+          return (
+            <ListItem
+              key={j.id}
+              progress={p}
+              progressTone={p >= 1 ? 'success' : paused ? 'neutral' : 'accent'}
+              leading={<IconTile size={28}>{j.icon}</IconTile>}
+              title={j.title}
+              description={j.worker}
+              meta={
+                <Text as="span" variant="caption" tone="tertiary" numeric>
+                  {p >= 1 ? '완료' : paused ? '일시정지' : `${Math.round(p * 100)}%`}
+                </Text>
+              }
+            />
+          )
+        })}
+      </List>
+    </Card>
+  )
+}
+```
+
+### 떠오르는 선택 (variant="raised")
+
+회색 판 위의 목록에서 선택한 행이 흰 카드로 떠올라요. hover는 반투명이라 어떤 회색 위에서도 보여요. SplitView의 목록 쪽에 써요.
+
+```tsx
+import { useState } from 'react'
+import { FileSignature, Receipt, UserPlus } from 'lucide-react'
+import { Box, IconTile, List, ListItem } from '@iamfiro/design'
+
+const ITEMS = [
+  { id: 'a1', icon: <Receipt />, title: '10월 법인 카드 정산', meta: '경비', time: '방금' },
+  { id: 'a2', icon: <UserPlus />, title: '이도현 님 계정 권한 요청', meta: '권한', time: '14분' },
+  { id: 'a3', icon: <FileSignature />, title: '협력사 계약서 검토', meta: '계약', time: '1시간' },
+]
+
+export default function Example() {
+  const [selected, setSelected] = useState('a1')
+  return (
+    <Box background="subtle" radius="lg" padding={2} style={{ width: 360 }}>
+      <List aria-label="승인 대기">
+        {ITEMS.map((it) => (
+          <ListItem
+            key={it.id}
+            variant="raised"
+            selected={selected === it.id}
+            onClick={() => setSelected(it.id)}
+            leading={<IconTile tone="surface">{it.icon}</IconTile>}
+            title={it.title}
+            description={it.meta}
+            meta={it.time}
+          />
+        ))}
+      </List>
+    </Box>
+  )
+}
+```
+
+### 표면과 밀도
+
+plain은 페이지 위에 바로, inset은 흰 카드 위에 묶어요. density로 행 높이를 compact / default / comfortable 중에 골라요.
+
+```tsx
+import { useState } from 'react'
+import { Avatar, SegmentedControl, Stack, Grid, List, ListItem, type ListProps } from '@iamfiro/design'
+
+type Density = NonNullable<ListProps['density']>
+
+const PEOPLE = [
+  { name: '김민지', role: '프로덕트 디자이너' },
+  { name: '이도현', role: '프론트엔드 개발자' },
+  { name: '박서연', role: '리서처' },
+]
+
+export default function Example() {
+  const [density, setDensity] = useState<Density>('default')
+  return (
+    <Stack gap={5} align="start">
+      <SegmentedControl<Density>
+        ariaLabel="밀도"
+        value={density}
+        onChange={setDensity}
+        options={[
+          { value: 'compact', label: 'compact' },
+          { value: 'default', label: 'default' },
+          { value: 'comfortable', label: 'comfortable' },
+        ]}
+      />
+      <Grid columns={2} gap={6} style={{ width: 640 }}>
+        {(['plain', 'inset'] as const).map((variant) => (
+          <List key={variant} variant={variant} density={density} label={variant}>
+            {PEOPLE.map((p) => (
+              <ListItem key={p.name} leading={<Avatar name={p.name} />} title={p.name} description={p.role} />
+            ))}
+          </List>
+        ))}
+      </Grid>
+    </Stack>
+  )
+}
+```

package/agents/marker/AGENTS.md

@@ -0,0 +1,142 @@
+# Marker
+
+> 대화 & 활동 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+대화 · 활동 기록 사이에 끼는 이벤트 한 줄. 누가 말한 것이 아니라 일어난 일(멤버 초대, PR 병합, 메시지 고정)을 작은 아이콘 + 회색 글로 보여 줘요. 테두리나 배경 없이 글자 톤만으로 메시지와 구분되고, 참조(#482)는 Link variant="inherit"로 밑줄만 그어요. CommentThread 안에 넣으면 메시지 사이 간격이 자동으로 맞춰져요.
+
+```tsx
+import { Marker } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 대화 사이의 이벤트 줄(초대 · 병합 · 고정)은 `Marker`: 16px 아이콘 + 회색 한 줄, 배경 · 테두리 없음. 아이콘은 기본 회색, 결과에 상태가 담긴 이벤트만 `tone`(병합 = success). 스레드 안에선 `gutter={avatarSize}`로 아바타 열에 맞춘다. 글 속 참조(#482)는 `Link variant="inherit"`(주변 색 + 밑줄).
+
+## API
+
+### Marker
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | 일어난 일. 회색 body-md 한 줄(길면 줄바꿈). |
+| `icon` | `ReactNode` |  | 16px 아이콘(UserPlus, GitMerge, Pin…). |
+| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'neutral'` | 아이콘 색. 글자는 항상 회색이에요. |
+| `date` | `Date \| string \| number` |  | 일어난 시각. 글 끝에 "2분 전"처럼, 올리면 전체 날짜. |
+| `gutter` | `number` |  | 아이콘 열 폭(px). Comment의 avatarSize를 주면 아바타 · 본문 선에 맞춰져요. |
+| `appear` | `boolean` |  | 처음 나타날 때 아래에서 올라오며 등장(실시간으로 들어온 이벤트). |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+아이콘은 기본 회색(neutral). 병합처럼 결과에 상태가 담긴 이벤트만 tone으로 색을 줘요.
+
+```tsx
+import { GitMerge, Pin, UserPlus } from 'lucide-react'
+import { Link, Stack, Marker } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3}>
+      <Marker icon={<UserPlus />}>김민지 님이 이도현, 박솔 님을 초대했어요</Marker>
+      <Marker icon={<GitMerge />} tone="success">
+        박솔 님이 <Link variant="inherit" href="#">#482</Link>를 main에 병합했어요
+      </Marker>
+      <Marker icon={<Pin />}>박솔 님이 메시지를 고정했어요</Marker>
+    </Stack>
+  )
+}
+```
+
+### 아이콘 색 · 시간
+
+Badge와 같은 tone. date를 주면 글 끝에 RelativeTime이 붙고, 올리면 전체 날짜가 나와요. 긴 글은 줄이 바뀌어도 아이콘이 첫 줄 옆에 있어요.
+
+```tsx
+import { CircleAlert, GitPullRequestClosed, Rocket, Sparkles, TriangleAlert, UserMinus } from 'lucide-react'
+import { Link, Stack, Marker } from '@iamfiro/design'
+
+const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ maxWidth: 420 }}>
+      <Marker icon={<UserMinus />} date={minutesAgo(42)}>
+        이도현 님이 채널을 나갔어요
+      </Marker>
+      <Marker icon={<Sparkles />} tone="accent" date={minutesAgo(18)}>
+        AI가 대화를 요약했어요
+      </Marker>
+      <Marker icon={<Rocket />} tone="info" date={minutesAgo(9)}>
+        <Link variant="inherit" href="#">v2.14.0</Link>이 스테이징에 배포됐어요
+      </Marker>
+      <Marker icon={<TriangleAlert />} tone="warning" date={minutesAgo(5)}>
+        빌드 시간이 평소보다 오래 걸렸어요
+      </Marker>
+      <Marker icon={<GitPullRequestClosed />} tone="danger" date={minutesAgo(2)}>
+        김민지 님이 <Link variant="inherit" href="#">#479</Link>를 병합하지 않고 닫았어요
+      </Marker>
+      <Marker icon={<CircleAlert />} date={minutesAgo(1)}>
+        이 채널의 메시지는 90일이 지나면 자동으로 삭제돼요. 보관이 필요한 내용은 고정하거나 문서로 옮겨 주세요
+      </Marker>
+    </Stack>
+  )
+}
+```
+
+### 대화 안에서
+
+CommentThread에 Comment와 섞어 넣었어요. gutter에 Comment의 avatarSize(28)를 주면 아이콘이 아바타 열 가운데, 글은 메시지 본문 선에 맞춰져요. 버튼으로 이벤트를 추가하면 appear로 아래에서 올라와요.
+
+```tsx
+import { useState } from 'react'
+import { GitMerge, Pin, UserPlus } from 'lucide-react'
+import { Button, Link, Card, CardBody, CardHeader, Comment, CommentThread, Marker } from '@iamfiro/design'
+
+const minutesAgo = (m: number) => new Date(Date.now() - m * 60_000)
+const INVITED = minutesAgo(30)
+const ASKED = minutesAgo(24)
+const MERGED = minutesAgo(12)
+const ANSWERED = minutesAgo(10)
+
+export default function Example() {
+  const [pinned, setPinned] = useState<Date | null>(null)
+
+  return (
+    <Card padding="sm" style={{ width: 400 }}>
+      <CardHeader
+        title="# 디자인-시스템"
+        actions={
+          <Button size="sm" variant="ghost" icon={<Pin />} disabled={pinned != null} onClick={() => setPinned(new Date())}>
+            메시지 고정
+          </Button>
+        }
+      />
+      <CardBody>
+        <CommentThread aria-label="채널 메시지">
+          <Marker icon={<UserPlus />} gutter={28} date={INVITED}>
+            김민지 님이 이도현, 박솔 님을 초대했어요
+          </Marker>
+          <Comment author="이도현" date={ASKED}>
+            버튼 토큰 정리한 PR 올렸어요. 리뷰 부탁드려요.
+          </Comment>
+          <Marker icon={<GitMerge />} tone="success" gutter={28} date={MERGED}>
+            박솔 님이 <Link variant="inherit" href="#">#482</Link>를 main에 병합했어요
+          </Marker>
+          <Comment author="박솔" date={ANSWERED}>
+            확인하고 병합했어요. 다음 배포에 들어가요.
+          </Comment>
+          {pinned && (
+            <Marker icon={<Pin />} gutter={28} date={pinned} appear>
+              박솔 님이 메시지를 고정했어요
+            </Marker>
+          )}
+        </CommentThread>
+      </CardBody>
+    </Card>
+  )
+}
+```

package/agents/masked-text/AGENTS.md

@@ -0,0 +1,127 @@
+# MaskedText
+
+> 텍스트 & 코드 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+계좌번호 · IBAN · 키처럼 민감한 값을 양 끝만 보이고 가운데는 점 묶음으로 가려요("DE89 •••• 3000"). 숫자는 tabular(또는 고정폭)라 보기로 바꿔도 폭이 덜 흔들려요. 화면 읽기 프로그램은 점 대신 "가려진 값, 앞 DE89, 끝 3000"을 읽어요. 눈 버튼(툴팁 포함)으로 보기 · 가리기, CopyButton으로 전체 값 복사를 붙일 수 있어요.
+
+```tsx
+import { MaskedText, maskValue } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 민감한 값은 `MaskedText`(양 끝만, 점 한 묶음이라 길이를 드러내지 않음, 화면 읽기는 "가려진 값"), 글 속 강조 + 메모 말풍선은 `Highlight note`, 첨부 파일 링크는 `FileChip`(확장자는 줄이지 않음).
+
+## API
+
+### MaskedText
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 가릴 전체 값. |
+| `label` | `string` |  | 무슨 값인지("IBAN"). 화면 읽기 프로그램이 가려진 상태와 함께 읽어요. |
+| `visibleStart` | `number` | `4` | 앞에 보일 글자 수. |
+| `visibleEnd` | `number` | `4` | 끝에 보일 글자 수. |
+| `mask` | `string` | `'•'` | 가리는 문자. |
+| `groupSize` | `number` | `4` | 한 묶음의 점 개수. 묶음 사이는 공백. |
+| `maskLength` | `number` | `groupSize` | 그릴 점 개수. 기본은 한 묶음이라 실제 길이를 숨겨요. |
+| `revealable` | `boolean` |  | 보기 · 가리기 눈 버튼(툴팁, aria-pressed). |
+| `revealed / onRevealedChange` | `boolean / (revealed) => void` |  | 보기 상태를 밖에서 제어할 때. |
+| `defaultRevealed` | `boolean` | `false` | 처음 보기 상태(비제어). |
+| `copyable` | `boolean` |  | 뒤에 CopyButton. 언제나 전체 값을 복사해요. |
+| `copyValue` | `string` |  | 복사할 값(기본 value). 공백 없는 형태 등. |
+| `mono` | `boolean` |  | 고정폭 글꼴(--font-mono). 기본은 주변 글꼴의 tabular 숫자. |
+
+### maskValue(value, options)
+
+같은 규칙으로 가린 문자열을 돌려줘요. maskParts는 { start, hidden, end }로 나눠 줘요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `string` |  | 가릴 값. |
+| `options` | `MaskOptions` |  | visibleStart · visibleEnd · mask · groupSize · maskLength. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+기본은 앞 4 · 끝 4글자, 가운데 점 4개 한 묶음. 점 개수가 실제 길이를 드러내지 않아요. 값의 공백은 무시해요.
+
+```tsx
+import { MaskedText, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3}>
+      <Text variant="body-md">
+        IBAN <MaskedText label="IBAN" value="DE89 3704 0044 0532 0130 00" />
+      </Text>
+      <Text variant="body-md">
+        카드 <MaskedText label="카드 번호" value="5412 7512 3412 3456" visibleStart={0} />
+      </Text>
+      <Text variant="body-md" tone="secondary">
+        짧은 값은 모두 가려요: <MaskedText label="PIN" value="4821" />
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 보기 · 복사
+
+revealable은 눈 버튼(누르면 아이콘이 바뀌고 값이 아래에서 떠올라요), copyable은 CopyButton. 복사는 가려진 상태에서도 전체 값을 복사해요.
+
+```tsx
+import { useState } from 'react'
+import { MaskedText, Stack, Text, DescriptionList } from '@iamfiro/design'
+
+export default function Example() {
+  const [revealed, setRevealed] = useState(false)
+  return (
+    <Stack gap={4}>
+      <DescriptionList
+        labelStyle="muted"
+        size="sm"
+        columns={1}
+        aria-label="입금 계좌"
+        items={[
+          {
+            label: '입금 계좌 · 한빛은행',
+            value: <MaskedText label="입금 계좌" value="110-482-301193" copyValue="110482301193" visibleStart={3} revealable copyable />,
+          },
+          {
+            label: '배포 키',
+            value: <MaskedText label="배포 키" value="dk_prod_8f2a91c4e7b05d36" visibleStart={8} mono revealable revealed={revealed} onRevealedChange={setRevealed} />,
+          },
+        ]}
+      />
+      <Text variant="caption" tone="tertiary">
+        배포 키: {revealed ? '보이는 중' : '가려짐'}
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 자릿수 · 문자 · 고정폭
+
+visibleStart · visibleEnd · mask · groupSize · maskLength로 모양을, mono로 고정폭 글꼴을 골라요. 같은 규칙의 문자열이 필요하면 maskValue().
+
+```tsx
+import { MaskedText, Stack, Text, maskValue } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3}>
+      <MaskedText label="계좌" value="3333-01-5528419" visibleStart={0} visibleEnd={4} maskLength={8} />
+      <MaskedText label="주문 번호" value="ORD-20261025-7731" visibleStart={3} visibleEnd={2} mask="*" groupSize={3} maskLength={6} />
+      <MaskedText label="접속 키" value="dk_live_51Hc2k9Qe8Zx" visibleStart={7} mono />
+      <Text variant="caption" tone="tertiary">
+        maskValue: {maskValue('kim.minji@example.com', { visibleStart: 3, visibleEnd: 12 })}
+      </Text>
+    </Stack>
+  )
+}
+```