@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/kbd/AGENTS.md

@@ -0,0 +1,160 @@
+# Kbd
+
+> 라벨 & 배지 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+단축키를 보여주는 키캡. 흰 키캡 + 아래 진한 가장자리로 살짝 떠 보여요. 키 이름으로 넘기면 OS에 맞춰 표시돼요 — mod는 Mac에서 ⌘, Windows에서 Ctrl. 툴팁 안처럼 어두운 배경에서는 배경색에 맞춰 바뀌어요.
+
+```tsx
+import { Kbd, formatKey, isMac } from '@iamfiro/design'
+```
+
+## API
+
+### Kbd
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `keys` | `string[]` |  | 키 이름 목록. 예: ['mod', 'K'], ['shift', 'enter']. formatKey로 OS에 맞게 표시. |
+| `children` | `ReactNode` |  | keys 대신 그대로 보여줄 내용. 예: <Kbd>⌘K</Kbd>. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 키캡 높이 18 / 20 / 24px. |
+| `combined` | `boolean` |  | 조합 전체를 한 칸에 표시("⌘K", "Ctrl+K"). |
+| `separator` | `ReactNode` |  | 키 사이에 넣을 글자. 예: '+', '다음'. |
+| `className` | `string` |  | 바깥 kbd에 붙일 클래스. |
+
+### formatKey
+
+(key: string) => string. 함께 내보내는 isMac(boolean 상수)은 navigator.platform이 Mac · iPhone · iPad일 때 true예요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `key` (필수) | `string` |  | mod · cmd · meta · ctrl · alt · option · shift는 OS별 글자(⌘ ⌃ ⌥ ⇧ / Ctrl Win Alt Shift), enter · esc · tab · space · backspace · delete · 방향키는 기호로, 한 글자는 대문자로 바꿔요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 단일 키
+
+enter → ↵, esc → Esc, 방향키 → 화살표. 한 글자는 대문자로 바꿔요.
+
+```tsx
+import { Kbd } from '@iamfiro/design'
+
+const KEYS = ['esc', 'enter', 'tab', 'space', 'backspace', 'up', 'down', 'left', 'right', 'k']
+
+export default function Example() {
+  return (
+    <div style={{ display: 'flex', flexWrap: 'wrap', gap: 12 }}>
+      {KEYS.map((key) => (
+        <Kbd key={key} keys={[key]} />
+      ))}
+    </div>
+  )
+}
+```
+
+### 조합 키
+
+기본은 키마다 한 칸, combined는 한 칸에 묶어요(Windows에서는 Ctrl+K처럼 + 로 이어요).
+
+```tsx
+import { Kbd, Text } from '@iamfiro/design'
+
+const SHORTCUTS = [
+  { label: '검색', keys: ['mod', 'K'] },
+  { label: '명령 팔레트', keys: ['mod', 'shift', 'P'] },
+  { label: '줄바꿈 없이 보내기', keys: ['alt', 'enter'] },
+]
+
+const ROW = { display: 'grid', gridTemplateColumns: '160px 120px 120px', alignItems: 'center', gap: 24 }
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 14 }}>
+      <div style={ROW}>
+        <span />
+        <Text variant="caption" tone="tertiary">
+          기본
+        </Text>
+        <Text variant="caption" tone="tertiary">
+          combined
+        </Text>
+      </div>
+      {SHORTCUTS.map((s) => (
+        <div key={s.label} style={ROW}>
+          <Text variant="label-md">{s.label}</Text>
+          <Kbd keys={s.keys} />
+          <Kbd keys={s.keys} combined />
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 순서 키
+
+separator로 키 사이에 글자를 넣어요. G 다음 I처럼 차례로 누르는 단축키에 써요.
+
+```tsx
+import { Kbd, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: '140px auto', alignItems: 'center', gap: '14px 24px' }}>
+      <Text variant="label-md">받은편지함으로 이동</Text>
+      <Kbd keys={['G', 'I']} separator="다음" />
+      <Text variant="label-md">복사</Text>
+      <Kbd keys={['mod', 'C']} separator="+" />
+      <Text variant="label-md">이전 · 다음 항목</Text>
+      <Kbd keys={['up', 'down']} separator="/" />
+    </div>
+  )
+}
+```
+
+### 크기
+
+sm 18 · md 20 · lg 24px. 문장 속에서는 sm이 글줄과 잘 맞아요. 글자와 키캡 사이는 6px.
+
+```tsx
+import { Kbd, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 28, justifyItems: 'center' }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 16 }}>
+        <Kbd keys={['mod', 'K']} size="sm" />
+        <Kbd keys={['mod', 'K']} />
+        <Kbd keys={['mod', 'K']} size="lg" />
+      </div>
+      <Text tone="secondary">
+        <Kbd keys={['mod', 'K']} size="sm" /> 를 눌러 어디서든 검색하고, <Kbd keys={['esc']} size="sm" /> 로 닫아요.
+      </Text>
+    </div>
+  )
+}
+```
+
+### formatKey · isMac
+
+키캡이 아닌 곳(placeholder, aria-label, 문자열)에 단축키를 쓸 때. 같은 규칙으로 OS에 맞는 글자를 돌려줘요.
+
+```tsx
+import { Search } from 'lucide-react'
+import { Input, Text, formatKey, isMac } from '@iamfiro/design'
+
+// 키캡을 쓸 수 없는 문자열에서도 OS에 맞는 단축키 글자를 써요.
+const searchShortcut = [formatKey('mod'), formatKey('k')].join(isMac ? '' : '+')
+
+export default function Example() {
+  return (
+    <div style={{ width: 320, display: 'grid', gap: 10 }}>
+      <Input leading={<Search />} placeholder={`문서 검색 (${searchShortcut})`} aria-label="문서 검색" aria-keyshortcuts={isMac ? 'Meta+K' : 'Control+K'} />
+      <Text variant="caption" tone="tertiary">
+        {isMac ? 'Mac에서는 ⌘ 기호로' : 'Windows에서는 Ctrl+ 형식으로'} 표시하고 있어요.
+      </Text>
+    </div>
+  )
+}
+```

package/agents/layout/AGENTS.md

@@ -0,0 +1,351 @@
+# Layout
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+여백을 손으로 맞추지 않도록 돕는 레이아웃 기본 요소. Stack은 세로, Inline은 가로, Grid는 열로 배치하고 간격은 모두 4px 단위 토큰(--s1 … --s10)을 써요. 구분은 여백이 먼저이고, 그걸로 부족할 때만 Separator를 써요.
+
+```tsx
+import { Box, Grid, Inline, Separator, Stack } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 차트: 시리즈 색은 `--chart-1…6`을 순서대로, 그리드는 `--chart-grid`로 아주 옅게(세로선·축선 없음). 범례·툴팁의 색 표시는 `ColorDot`, 툴팁은 `Card raised` + `Separator`로 조립. 축·툴팁·범례·호버/키보드는 `components/Chart/`의 공용 조각(`ChartTooltip`, `ChartLegend`, `useChartInteraction`)을 쓴다. → `LineChart` · `BarChart` · `PieChart` · `Sparkbar`
+- 배치는 `Stack`(세로) · `Inline`(가로) · `Grid` · `Box`로. 간격은 4px 단위 `Space`(1=4 … 10=40)만. 즉석 flex div 금지.
+- 구분선(`Separator`)은 간격만으로 부족할 때만.
+- 루트 클래스 이름이 다른 요소와 겹치지 않는지 먼저 검색한다(DataGrid가 `.ds-grid`를 써서 Layout `Grid`가 flex로 깨졌던 버그 → `.ds-datagrid`).
+- 라벨 + 숫자는 `Stat`(한 줄 "시간 1:52 / 2:55" 또는 오버라인 라벨 위 큰 숫자), 지표 띠는 `StatGroup`(칸 사이 `Separator`, 줄이 바뀌어도 줄 첫 칸 앞엔 선 없음).
+- 실제 컴포넌트를 작게 줄여 보여 주는 썸네일(갤러리 카드 · 템플릿 고르기)은 `ScaledPreview`(고정 높이 무대, 맞춰 줄이기, inert, `label` 흰 칩 · `meta` 회색 칩, 타이머가 도는 내용은 `lazy`로 보일 때만). 필터로 바뀌는 카드 격자는 `Grid stagger` + 필터 값을 `key`로.
+
+## API
+
+### Stack
+
+세로 flex. as로 다른 요소(form, ul, section…)로 렌더할 수 있어요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `gap` | `Space` | `3` | 자식 사이 간격. 0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 8 \| 10 → --s1 … --s10 (4px 단위). |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'stretch'` | 가로 정렬(align-items). |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` |  | 세로 분배(justify-content). |
+| `wrap` | `boolean` | `false` | 줄바꿈 허용. |
+| `as` | `ElementType` | `'div'` | 렌더할 요소. |
+
+### Inline
+
+가로 flex. 버튼 묶음, 칩, 메타 정보 줄에.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `gap` | `Space` | `2` | 자식 사이 간격(4px 단위 토큰). |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch' \| 'baseline'` | `'center'` | 세로 정렬(align-items). |
+| `justify` | `'start' \| 'center' \| 'end' \| 'between' \| 'around'` |  | 가로 분배(justify-content). |
+| `wrap` | `boolean` | `true` | 공간이 부족하면 다음 줄로. |
+| `as` | `ElementType` | `'div'` | 렌더할 요소. |
+
+### Grid
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `columns` | `number \| string` | `2` | 같은 폭 열의 수, 또는 grid-template-columns 문자열 그대로. |
+| `minItemWidth` | `number` |  | 반응형: 각 열이 이 폭(px) 이상이 되도록 들어가는 만큼 열을 만들어요. columns보다 우선해요. |
+| `gap` | `Space` | `4` | 열 간격. rowGap을 안 주면 행 간격도 같아요. |
+| `rowGap` | `Space` |  | 행 간격을 따로 줄 때. |
+| `align` | `'start' \| 'center' \| 'end' \| 'stretch'` |  | 셀 안 세로 정렬(align-items). |
+| `stagger` | `boolean` | `false` | 붙을 때 칸이 아래에서 하나씩(약 70ms 간격) 올라와요. 필터를 바꿀 때 key를 바꾸면 다시 재생돼요. |
+| `as` | `ElementType` | `'div'` | 렌더할 요소. |
+
+### Separator
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | 선 방향. 세로선은 부모 높이만큼 늘어나요. |
+| `label` | `ReactNode` |  | 가운데 글자(예: "또는"). |
+| `spacing` | `Space` | `0` | 선 양쪽 여백. |
+| `decorative` | `boolean` | `true` | false면 보조 기술에 separator로 알려요. |
+
+### Box
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `padding` | `Space` |  | 네 방향 안쪽 여백. |
+| `paddingX / paddingY` | `Space` |  | 좌우 / 위아래 안쪽 여백. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'xl' \| 'full'` | `'none'` | 모서리 둥글기(토큰). |
+| `background` | `'none' \| 'surface' \| 'subtle'` | `'none'` | surface는 흰색, subtle은 옅은 회색 채움(#f4f4f4). |
+| `elevated` | `boolean` |  | 테두리 대신 옅은 그림자로 띄워요(흰 배경 포함). |
+| `as` | `ElementType` | `'div'` | 렌더할 요소. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### Stack과 Inline
+
+Stack은 위에서 아래로, Inline은 왼쪽에서 오른쪽으로 놓아요. Inline은 기본으로 줄바꿈되고 세로 가운데 정렬이에요.
+
+```tsx
+import { Avatar, Badge, Button, Grid, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Grid columns={2} gap={10} style={{ width: 600 }}>
+      <Stack gap={3} align="start">
+        <Text variant="overline" tone="tertiary">
+          Stack
+        </Text>
+        <Stack gap={1}>
+          <Text variant="heading-sm">주간 리포트</Text>
+          <Text variant="body-sm" tone="secondary">
+            매주 월요일 오전 9시에 자동으로 보내요.
+          </Text>
+        </Stack>
+        <Button size="sm">미리 보기</Button>
+      </Stack>
+      <Stack gap={3} align="start">
+        <Text variant="overline" tone="tertiary">
+          Inline
+        </Text>
+        <Inline gap={2}>
+          <Avatar name="김민지" />
+          <Text variant="label-md">김민지</Text>
+          <Badge tone="success" dot>
+            온라인
+          </Badge>
+        </Inline>
+        <Inline gap={2}>
+          <Button variant="primary" size="sm">
+            초대
+          </Button>
+          <Button variant="ghost" size="sm">
+            나중에
+          </Button>
+        </Inline>
+      </Stack>
+    </Grid>
+  )
+}
+```
+
+### 설정 폼
+
+Stack으로 필드를 쌓고 Inline으로 나란한 필드와 버튼 줄을 만들어요. justify="end"로 버튼을 오른쪽에 붙여요.
+
+```tsx
+import { Button, Field, Grid, Inline, Input, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack as="form" gap={6} style={{ width: 460 }} onSubmit={(e) => e.preventDefault()}>
+      <Stack gap={1}>
+        <Text variant="heading-sm">프로필</Text>
+        <Text variant="body-sm" tone="secondary">
+          팀원들에게 보이는 이름과 연락처예요.
+        </Text>
+      </Stack>
+      <Stack gap={4}>
+        <Grid columns={2} gap={3}>
+          <Field label="성" htmlFor="profile-last">
+            <Input id="profile-last" defaultValue="김" />
+          </Field>
+          <Field label="이름" htmlFor="profile-first">
+            <Input id="profile-first" defaultValue="민지" />
+          </Field>
+        </Grid>
+        <Field label="이메일" hint="로그인과 알림에 쓰여요." htmlFor="profile-email">
+          <Input id="profile-email" type="email" defaultValue="minji@lumen.app" />
+        </Field>
+        <Field label="전화번호" htmlFor="profile-phone">
+          <Inline gap={2} wrap={false}>
+            <Input id="profile-phone" type="tel" defaultValue="010-1234-5678" wrapperStyle={{ flex: 1 }} />
+            <Button>인증하기</Button>
+          </Inline>
+        </Field>
+      </Stack>
+      <Inline gap={2} justify="end">
+        <Button variant="ghost">취소</Button>
+        <Button variant="primary" type="submit">
+          저장
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### Grid
+
+columns로 열 수를 고정하거나, minItemWidth로 폭에 들어가는 만큼 열을 만들어요(반응형).
+
+```tsx
+import { BarChart3, Bell, CreditCard, FolderOpen, Shield, Users } from 'lucide-react'
+import { Grid, Stack, Text, Card, CardHeader } from '@iamfiro/design'
+
+const STATS = [
+  { label: '이번 달 방문자', value: '12,480' },
+  { label: '신규 가입', value: '326' },
+  { label: '전환율', value: '4.2%' },
+]
+
+const SECTIONS = [
+  { icon: <Users />, title: '멤버', description: '초대와 역할 관리' },
+  { icon: <CreditCard />, title: '결제', description: '플랜과 결제 수단' },
+  { icon: <Bell />, title: '알림', description: '이메일 · 푸시 설정' },
+  { icon: <Shield />, title: '보안', description: '2단계 인증, 세션' },
+  { icon: <FolderOpen />, title: '프로젝트', description: '보관과 이전' },
+  { icon: <BarChart3 />, title: '사용량', description: '이번 달 사용 내역' },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={8} style={{ width: '100%', maxWidth: 720 }}>
+      <Grid columns={3} gap={3}>
+        {STATS.map((s) => (
+          <Card key={s.label} padding="sm">
+            <Stack gap={1}>
+              <Text variant="caption" tone="tertiary">
+                {s.label}
+              </Text>
+              <Text variant="number-lg">{s.value}</Text>
+            </Stack>
+          </Card>
+        ))}
+      </Grid>
+      <Grid minItemWidth={200} gap={3}>
+        {SECTIONS.map((s) => (
+          <Card key={s.title} as="button" type="button" interactive padding="sm">
+            <CardHeader icon={s.icon} title={s.title} description={s.description} />
+          </Card>
+        ))}
+      </Grid>
+    </Stack>
+  )
+}
+```
+
+### Grid stagger
+
+필터를 바꾸면 칸이 줄 단위로 아래에서 차례로 올라와요. Grid의 key를 필터 값으로 바꿔 다시 재생해요.
+
+```tsx
+import { useState } from 'react'
+import { Grid, Stack, Card, CardHeader, FilterChip, FilterChipGroup } from '@iamfiro/design'
+
+type Team = 'all' | 'design' | 'dev'
+
+const PEOPLE: { name: string; role: string; team: Exclude<Team, 'all'> }[] = [
+  { name: '김민지', role: '프로덕트 디자이너', team: 'design' },
+  { name: '이도현', role: '프론트엔드 개발자', team: 'dev' },
+  { name: '박서연', role: 'UX 리서처', team: 'design' },
+  { name: '최준호', role: '백엔드 개발자', team: 'dev' },
+  { name: '정하은', role: '브랜드 디자이너', team: 'design' },
+  { name: '한지우', role: '모바일 개발자', team: 'dev' },
+]
+
+export default function Example() {
+  const [team, setTeam] = useState<Team>('all')
+  const shown = team === 'all' ? PEOPLE : PEOPLE.filter((p) => p.team === team)
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 620 }}>
+      <FilterChipGroup type="single" required value={team} onValueChange={(v) => setTeam((v as Team | null) ?? 'all')} aria-label="팀">
+        <FilterChip value="all">전체</FilterChip>
+        <FilterChip value="design">디자인</FilterChip>
+        <FilterChip value="dev">개발</FilterChip>
+      </FilterChipGroup>
+      <Grid key={team} stagger minItemWidth={180} gap={3}>
+        {shown.map((p) => (
+          <Card key={p.name} padding="sm">
+            <CardHeader title={p.name} description={p.role} />
+          </Card>
+        ))}
+      </Grid>
+    </Stack>
+  )
+}
+```
+
+### Separator
+
+가로선, Inline 안의 세로선, 가운데 글자가 있는 구분선. spacing으로 선 양쪽 여백을 줘요.
+
+```tsx
+import { Mail } from 'lucide-react'
+import { Button, Field, Inline, Input, Separator, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={10} style={{ width: 380 }}>
+      <Stack gap={0}>
+        <Text variant="label-md">알림 요약</Text>
+        <Separator spacing={3} />
+        <Inline gap={3}>
+          <Text variant="body-sm" tone="secondary">
+            읽지 않음 12
+          </Text>
+          <Separator orientation="vertical" />
+          <Text variant="body-sm" tone="secondary">
+            멘션 3
+          </Text>
+          <Separator orientation="vertical" />
+          <Text variant="body-sm" tone="secondary">
+            2분 전 업데이트
+          </Text>
+        </Inline>
+      </Stack>
+      <Stack gap={4}>
+        <Button block>Google로 계속하기</Button>
+        <Separator label="또는" />
+        <Field label="이메일" htmlFor="sep-email">
+          <Input id="sep-email" type="email" placeholder="name@company.com" />
+        </Field>
+        <Button variant="primary" block icon={<Mail />}>
+          이메일로 계속하기
+        </Button>
+      </Stack>
+    </Stack>
+  )
+}
+```
+
+### Box
+
+여백 · 모서리 · 배경만 주는 래퍼. 실제 콘텐츠 묶음이라면 Card를 쓰세요.
+
+```tsx
+import { Box, Grid, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={6} style={{ width: 600 }}>
+      <Grid columns={2} gap={4}>
+        <Box padding={4} radius="lg" background="subtle">
+          <Stack gap={1}>
+            <Text variant="label-md">background="subtle"</Text>
+            <Text variant="body-sm" tone="secondary">
+              옅은 회색 채움. 보조 정보나 빈 자리 표시에.
+            </Text>
+          </Stack>
+        </Box>
+        <Box padding={4} radius="lg" elevated>
+          <Stack gap={1}>
+            <Text variant="label-md">elevated</Text>
+            <Text variant="body-sm" tone="secondary">
+              테두리 대신 옅은 그림자로 띄워요.
+            </Text>
+          </Stack>
+        </Box>
+      </Grid>
+      <Inline gap={2}>
+        <Box paddingX={3} paddingY={1} radius="full" background="subtle">
+          <Text variant="label-sm">디자인</Text>
+        </Box>
+        <Box paddingX={3} paddingY={1} radius="full" background="subtle">
+          <Text variant="label-sm">프론트엔드</Text>
+        </Box>
+        <Box paddingX={3} paddingY={1} radius="full" background="subtle">
+          <Text variant="label-sm">리서치</Text>
+        </Box>
+      </Inline>
+    </Stack>
+  )
+}
+```