@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/aspect-ratio/AGENTS.md

@@ -0,0 +1,143 @@
+# AspectRatio
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+폭은 부모를 따르고 높이는 비율로 정해지는 틀. 이미지·동영상·지도·미리보기가 불러오기 전에도 자리를 차지해 레이아웃이 밀리지 않아요. 바로 아래 자식은 틀을 꽉 채우고, 이미지는 잘라 채우거나(cover) 여백을 두고 맞춰요(contain).
+
+```tsx
+import { AspectRatio } from '@iamfiro/design'
+```
+
+## API
+
+### AspectRatio
+
+div의 나머지 속성(aria-*, onClick 등)을 그대로 받아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `ratio` | `number \| string` | `1` | 폭 ÷ 높이. 16 / 9, '16/9', '16:9'. |
+| `fit` | `'cover' \| 'contain'` | `'cover'` | 바로 아래 img · video가 틀을 채우는 방식. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl'` | `'none'` | 모서리 둥글기(토큰). |
+| `background` | `'none' \| 'subtle'` | `'none'` | subtle은 작은 회색 채움(#f4f4f4). 자리 표시와 contain 여백에 써요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+ratio에 폭 ÷ 높이를 넘겨요. 16 / 9 같은 숫자나 '16/9' · '16:9' 문자열 모두 돼요.
+
+```tsx
+import { AspectRatio, Stack, Text } from '@iamfiro/design'
+import { Play } from 'lucide-react'
+
+export default function Example() {
+  return (
+    <div style={{ width: 420 }}>
+      <AspectRatio ratio={16 / 9} radius="lg" background="subtle">
+        <Stack align="center" justify="center" gap={2}>
+          <Play size={28} />
+          <Text variant="caption" tone="secondary">
+            제품 소개 영상 · 2:14
+          </Text>
+        </Stack>
+      </AspectRatio>
+    </div>
+  )
+}
+```
+
+### 자주 쓰는 비율
+
+정사각 썸네일, 4:3 사진, 16:9 동영상, 21:9 배너. background="subtle"은 불러오기 전 자리 표시예요.
+
+```tsx
+import { AspectRatio, Grid, Stack, Text } from '@iamfiro/design'
+
+const RATIOS = [
+  { ratio: '1/1', label: '1:1', use: '프로필 · 썸네일' },
+  { ratio: '4/3', label: '4:3', use: '사진' },
+  { ratio: '16/9', label: '16:9', use: '동영상' },
+  { ratio: '21/9', label: '21:9', use: '배너' },
+]
+
+export default function Example() {
+  return (
+    <Grid columns={4} gap={4} align="end" style={{ width: '100%', maxWidth: 640 }}>
+      {RATIOS.map((r) => (
+        <Stack key={r.ratio} gap={2}>
+          <AspectRatio ratio={r.ratio} radius="md" background="subtle">
+            <Stack align="center" justify="center">
+              <Text variant="label-md">{r.label}</Text>
+            </Stack>
+          </AspectRatio>
+          <Text variant="caption" tone="secondary">
+            {r.use}
+          </Text>
+        </Stack>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### 채우기 방식 (fit)
+
+cover는 틀에 맞게 잘라 채우고, contain은 전체가 보이도록 회색 여백을 남겨요.
+
+```tsx
+import { AspectRatio, Grid, Stack, Text } from '@iamfiro/design'
+import hero from '@/assets/hero.png'
+
+export default function Example() {
+  return (
+    <Grid columns={2} gap={4} style={{ width: '100%', maxWidth: 480 }}>
+      {(['cover', 'contain'] as const).map((fit) => (
+        <Stack key={fit} gap={2}>
+          <AspectRatio ratio={16 / 9} fit={fit} radius="md" background="subtle">
+            <img src={hero} alt="쌓인 레이어 그림" />
+          </AspectRatio>
+          <Text variant="caption" tone="secondary">
+            {fit}
+          </Text>
+        </Stack>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### 카드 미디어
+
+CardMedia에 ratio를 주면 안에서 AspectRatio를 써요. 카드 목록의 이미지 높이가 모두 같아져요.
+
+```tsx
+import { Card, CardHeader, CardMedia, Grid, Stack, Text } from '@iamfiro/design'
+
+const POSTS = [
+  { title: '10월 디자인 리뷰 정리', author: '김민지', minutes: 4 },
+  { title: '새 온보딩 흐름 실험 결과', author: '이도현', minutes: 7 },
+  { title: '접근성 점검 체크리스트', author: '박서연', minutes: 3 },
+]
+
+export default function Example() {
+  return (
+    <Grid columns={3} gap={4} style={{ width: '100%', maxWidth: 640 }}>
+      {POSTS.map((p) => (
+        <Card key={p.title} padding="sm" interactive>
+          <CardMedia ratio="4/3">
+            <Stack align="center" justify="center">
+              <Text variant="caption" tone="tertiary">
+                이미지
+              </Text>
+            </Stack>
+          </CardMedia>
+          <CardHeader title={p.title} description={`${p.author} · ${p.minutes}분 분량`} />
+        </Card>
+      ))}
+    </Grid>
+  )
+}
+```

package/agents/avatar/AGENTS.md

@@ -0,0 +1,130 @@
+# Avatar
+
+> 아이콘 & 아바타 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+사람이나 팀을 나타내는 이름 배지. 한국어 이름(3–4글자)은 성을 빼고 이름만(김민지 → 민지), 그 밖의 이름은 이니셜로 보여요. 배경색은 이름에 따라 정해져 같은 사람은 늘 같은 색이에요.
+
+```tsx
+import { Avatar, AvatarGroup } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 행 앞 타일: 사람은 `Avatar`, 도구·사이트·문서는 `IconTile`(회색 채움 + 아이콘/글자). 선택된 것을 보여 주고 메뉴로 바꾸는 버튼(워크스페이스·계정 전환, 드롭다운 제목)은 `SelectorButton`을 `DropdownMenu` trigger에.
+
+## API
+
+### Avatar
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `name` (필수) | `string` |  | 이름. 보이는 글자, 배경색, 툴팁, 화면 읽기 이름이 모두 여기서 나와요. |
+| `size` | `number` | `28` | 지름(px). |
+| `square` | `boolean` |  | 둥근 사각형. |
+| `online` | `boolean` |  | 오른쪽 아래 접속 중 점. |
+| `color` | `string` |  | 배경색. 생략하면 이름으로 정해요. |
+| `tooltip` | `boolean \| ReactNode` | `true` | hover 시 이름 툴팁. 내용을 주면 그 내용, false면 툴팁 없음(이미 이름이 옆에 보이는 행 등). |
+
+### AvatarGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `names` (필수) | `string[]` |  | 이름 목록. |
+| `size` | `number` | `24` | 각 아바타 지름(px). |
+| `max` | `number` | `4` | 보여 줄 최대 인원. 나머지는 +N. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+한국어 이름, 영문 이름, 접속 중 표시(online), 팀 · 서비스용 각진 모양(square).
+
+```tsx
+import { Avatar } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+      <Avatar name="김민지" size={36} />
+      <Avatar name="이도현" size={36} online />
+      <Avatar name="남궁민수" size={36} />
+      <Avatar name="Sarah Kim" size={36} />
+      <Avatar name="Lumen" size={36} square />
+    </div>
+  )
+}
+```
+
+### 크기 · 색
+
+size는 px 숫자예요. color로 배경색을 직접 정할 수 있어요.
+
+```tsx
+import { Avatar } from '@iamfiro/design'
+
+const SIZES = [20, 24, 28, 36, 48]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 16 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        {SIZES.map((size) => (
+          <Avatar key={size} name="최서연" size={size} online={size >= 28} />
+        ))}
+      </div>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <Avatar name="Acme Corp" size={36} square color="var(--accent)" />
+        <Avatar name="Lumen Labs" size={36} square color="var(--success)" />
+        <Avatar name="Northwind" size={36} square color="var(--n8)" />
+      </div>
+    </div>
+  )
+}
+```
+
+### 이름 툴팁
+
+마우스를 올리면 Tooltip으로 전체 이름이 떠요(첫 툴팁은 잠깐 기다렸다가). tooltip에 내용을 주면 그걸, false면 끄고요. AvatarGroup의 +N은 가려진 사람들 이름을 보여 줘요.
+
+```tsx
+import { Avatar, AvatarGroup, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={6}>
+      <Inline gap={3}>
+        <Avatar name="김민지" size={36} />
+        <Avatar name="Sarah Kim" size={36} tooltip="Sarah Kim · 디자인팀" />
+        <Avatar name="이도현" size={36} tooltip={false} />
+      </Inline>
+      <AvatarGroup names={['김민지', '이도현', '박서준', '최유진', '정하늘', '한지우']} size={32} />
+    </Inline>
+  )
+}
+```
+
+### AvatarGroup
+
+겹쳐서 보여 주고, max를 넘는 인원은 +N으로 묶어요.
+
+```tsx
+import { AvatarGroup, Text } from '@iamfiro/design'
+
+const MEMBERS = ['김민지', '이도현', '최서연', '정우진', '한지수', '오세훈', '박미나']
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 16, justifyItems: 'start' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 10 }}>
+        <AvatarGroup names={MEMBERS} />
+        <Text variant="body-sm" tone="secondary" as="span">
+          {MEMBERS.length}명이 보고 있어요
+        </Text>
+      </div>
+      <AvatarGroup names={MEMBERS} size={32} max={3} />
+    </div>
+  )
+}
+```

package/agents/badge/AGENTS.md

@@ -0,0 +1,217 @@
+# Badge
+
+> 라벨 & 배지 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+상태 · 분류 · 개수를 짧게 알려 주는 작은 라벨. 테두리 없이 연한 채움과 색 글자로 구분해요. 기본은 누를 수 없는 라벨이고, 눌러서 무언가를 여는 상태 배지만 as="button"으로 만들어요. 필터나 선택에는 FilterChip을 쓰세요.
+
+```tsx
+import { Badge } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 진행 중 배지는 `Badge spinner`, 실시간은 `Badge pulse`, 눌러서 여는 상태 배지는 `Badge as="button" chevron`, 아주 작은 대문자 태그는 `Badge overline`.
+- 제목 · 아이콘 옆 개수 원은 `CountBadge`(tone · `max` "99+" · 바뀌면 튀기). 글자가 있는 상태 라벨은 `Badge`.
+
+## API
+
+### Badge
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `tone` | `'neutral' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'info'` | `'neutral'` | 색. |
+| `dot` | `boolean` |  | 글자 앞 상태 점. |
+| `pulse` | `boolean` |  | 점이 퍼지며 깜박여요(실시간 · 진행 중). dot을 포함해요. |
+| `spinner` | `boolean` |  | 글자 앞 작은 Spinner. dot · icon 대신 보여요. |
+| `square` | `boolean` |  | 덜 둥근 모서리. |
+| `icon` | `ReactNode` |  | 글자 앞 아이콘. |
+| `iconRight` | `ReactNode` |  | 글자 뒤 아이콘. |
+| `chevron` | `boolean` |  | 맨 뒤 오른쪽 화살표. 보통 as="button"과 함께. |
+| `size` | `'sm' \| 'md'` | `'md'` | md 22px · sm 18px. |
+| `overline` | `boolean` |  | 대문자 오버라인 글자의 작은 태그. |
+| `as` | `'span' \| 'button'` | `'span'` | 'button'이면 누를 수 있어요(onClick, disabled). |
+| `disabled` | `boolean` |  | as="button"일 때 비활성. |
+| `children` | `ReactNode` |  | 내용. |
+| `...rest` | `HTMLAttributes` |  | className · style · onClick · aria-* 등은 루트 요소로 전달돼요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 색
+
+neutral은 회색, 나머지는 상태색의 연한 배경 + 진한 글자예요.
+
+```tsx
+import { Badge } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 8 }}>
+      <Badge>초안</Badge>
+      <Badge tone="accent">신규</Badge>
+      <Badge tone="success">완료</Badge>
+      <Badge tone="warning">대기 중</Badge>
+      <Badge tone="danger">실패</Badge>
+      <Badge tone="info">베타</Badge>
+    </div>
+  )
+}
+```
+
+### 상태 점
+
+dot은 글자 앞에 작은 점을 붙여요. 목록에서 상태를 한눈에 훑을 때 좋아요.
+
+```tsx
+import { Badge, Text, type Tone } from '@iamfiro/design'
+
+const DEPLOYS: Array<{ branch: string; status: string; tone: Tone }> = [
+  { branch: 'main', status: '운영 중', tone: 'success' },
+  { branch: 'feat/checkout', status: '빌드 중', tone: 'info' },
+  { branch: 'fix/login-redirect', status: '검토 대기', tone: 'warning' },
+  { branch: 'chore/deps', status: '실패', tone: 'danger' },
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'auto auto', gap: '12px 24px', alignItems: 'center', justifyContent: 'start' }}>
+      {DEPLOYS.map((d) => (
+        <div key={d.branch} style={{ display: 'contents' }}>
+          <Text variant="code">{d.branch}</Text>
+          <Badge tone={d.tone} dot>
+            {d.status}
+          </Badge>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 진행 표시
+
+spinner는 아직 돌아가는 일, pulse는 지금 살아 있는 것(점이 퍼지며 깜박여요), icon은 끝난 · 기다리는 상태에 써요.
+
+```tsx
+import { Check, Clock } from 'lucide-react'
+import { Badge, Inline } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Inline gap={2}>
+      <Badge tone="info" spinner>
+        배포 중
+      </Badge>
+      <Badge tone="info" pulse>
+        실시간
+      </Badge>
+      <Badge tone="success" icon={<Check />}>
+        완료
+      </Badge>
+      <Badge tone="warning" icon={<Clock />}>
+        승인 대기
+      </Badge>
+      <Badge tone="danger" dot>
+        실패
+      </Badge>
+    </Inline>
+  )
+}
+```
+
+### 누를 수 있는 배지
+
+as="button"이면 hover 채움 · 누름 · 포커스 링이 생겨요. chevron은 눌러서 무언가 열린다는 힌트예요.
+
+```tsx
+import { useState } from 'react'
+import { Clock } from 'lucide-react'
+import { Badge, Inline, Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [opened, setOpened] = useState(0)
+  return (
+    <Inline gap={3}>
+      <Badge as="button" tone="warning" icon={<Clock />} chevron onClick={() => setOpened((n) => n + 1)}>
+        검토 필요 2건
+      </Badge>
+      <Badge as="button" tone="info" spinner chevron onClick={() => setOpened((n) => n + 1)}>
+        빌드 중
+      </Badge>
+      <Badge as="button" chevron disabled>
+        권한 없음
+      </Badge>
+      <Text variant="caption" tone="tertiary" numeric>
+        {opened > 0 ? `${opened}번 열었어요` : '배지를 눌러 보세요'}
+      </Text>
+    </Inline>
+  )
+}
+```
+
+### 크기 · 오버라인
+
+size="sm"은 18px로 촘촘한 행 · 제목 옆에, overline은 대문자 오버라인 역할의 아주 작은 태그예요.
+
+```tsx
+import { Badge, Heading, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Inline gap={2}>
+        <Badge tone="success">기본 22px</Badge>
+        <Badge tone="success" size="sm">
+          작게 18px
+        </Badge>
+        <Badge tone="info" size="sm" pulse>
+          실시간
+        </Badge>
+      </Inline>
+      <Inline gap={2}>
+        <Heading level={4}>결제 단계</Heading>
+        <Badge tone="warning" overline>
+          Slowest
+        </Badge>
+        <Badge tone="accent" overline>
+          Beta
+        </Badge>
+      </Inline>
+      <Inline gap={2}>
+        <Text variant="label-sm">응답 시간 1.8초</Text>
+        <Badge overline>p95</Badge>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 각진 모양 · 아이콘
+
+square는 모서리를 줄여 버전 · 코드 같은 값에 어울려요. icon은 글자 앞에 붙어요.
+
+```tsx
+import { Lock, Sparkles, Star } from 'lucide-react'
+import { Badge } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: 8 }}>
+      <Badge square>v2.4.0</Badge>
+      <Badge tone="info" square>
+        API
+      </Badge>
+      <Badge tone="accent" icon={<Sparkles />}>
+        AI 추천
+      </Badge>
+      <Badge tone="warning" icon={<Star />}>
+        즐겨찾기
+      </Badge>
+      <Badge icon={<Lock />} square>
+        비공개
+      </Badge>
+    </div>
+  )
+}
+```