@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/navigation-menu/AGENTS.md

@@ -0,0 +1,315 @@
+# NavigationMenu
+
+> 내비게이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+사이트 헤더의 메뉴(제품 · 보안 · 요금). 메뉴 이름에 마우스를 잠깐 올려 두면 열리고, 열린 동안 옆 이름으로 옮기면 바로 바뀌어요. 메뉴들은 패널 하나를 함께 쓰기 때문에 메뉴를 바꾸면 패널이 새로 뜨지 않고 새 크기로 늘거나 줄며, 내용은 옮겨 간 방향에서 미끄러져 들어와요. 메뉴 이름 뒤의 회색 채움도 따라 미끄러져요. 패널 안은 Grid로 자유롭게 짜고, NavigationMenuGroup(제목 + 링크 열) · NavigationMenuLink(이름 + 설명) · NavigationMenuFeature(소개 카드)를 끼워 넣어요. 링크는 as로 라우터 링크를 쓸 수 있어요. 키보드는 ←/→로 메뉴 사이 이동, ↓ · Enter로 열어 첫 링크로, 패널 안 ↑/↓, Esc로 메뉴 이름으로 돌아와요.
+
+```tsx
+import { NavigationMenu, NavigationMenuItem, NavigationMenuLink, NavigationMenuGroup, NavigationMenuFeature } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 사이트 헤더 메뉴(제품 · 보안 · 요금)는 `NavigationMenu`: 메뉴들이 **패널 하나를 함께** 쓰고, 메뉴를 바꾸면 패널이 새로 뜨지 않고 크기(· `panelAlign="trigger"`면 위치)를 바꾸며 내용은 옮긴 방향에서 미끄러져 들어온다. 처음 열기는 `TIMING.hoverIntent`, 열린 동안 옆 메뉴는 즉시, 벗어나면 `hoverGrace`. 패널 안은 Grid + `NavigationMenuGroup` · `NavigationMenuLink` · `NavigationMenuFeature`로 조립. 헤더 전체 폭은 `viewportAnchor`.
+
+## API
+
+### NavigationMenu
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `children` (필수) | `ReactNode` |  | NavigationMenuItem(패널을 여는 메뉴)과 NavigationMenuLink(바로 가는 링크), 순서대로. |
+| `value / onValueChange` | `string \| null / (value) => void` |  | 열린 메뉴의 value(null = 닫힘). 밖에서 제어할 때. |
+| `defaultValue` | `string \| null` | `null` | 처음 열린 메뉴(비제어). |
+| `openOn` | `'hover' \| 'click'` | `'hover'` | hover: 머물면 열리고 열린 동안 옆 메뉴로 바로 전환 · click: 눌러야 열림. |
+| `panelAlign` | `'stretch' \| 'trigger'` | `'stretch'` | stretch: viewportAnchor 폭 전체(메가 메뉴) · trigger: 내용 폭, 열린 메뉴 아래 가운데. |
+| `viewportAnchor` | `RefObject<HTMLElement>` |  | 패널이 폭과 아래 가장자리를 맞출 요소(보통 헤더 전체). 없으면 nav 자신. |
+| `tone` | `'default' \| 'inverse'` | `'default'` | inverse: 어두운 헤더용 밝은 메뉴 이름. |
+| `aria-label` | `string` | `'주 메뉴'` | nav의 접근성 이름. |
+
+### NavigationMenuItem
+
+메뉴 이름 버튼 + 패널에 보일 내용. 내용은 어떤 레이아웃이든 돼요(보통 Grid).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 메뉴 이름(예: 제품). |
+| `children` (필수) | `ReactNode` |  | 패널 내용. |
+| `value` | `string` |  | NavigationMenu value에서 이 메뉴를 가리키는 값. 없으면 내부 id. |
+| `icon` | `ReactNode` |  | 이름 앞 16px 아이콘. |
+| `disabled` | `boolean` |  | 비활성. 열리지 않고 키보드 이동에서 건너뛰어요. |
+| `width` | `number \| string` |  | panelAlign="trigger"일 때 내용 폭. 없으면 내용 자체 폭. |
+
+### NavigationMenuLink
+
+NavigationMenu 바로 아래면 막대 항목, 패널 안이면 이름 + 설명 행. 누르면 패널이 닫혀요(onClick에서 preventDefault 하는 라우터 링크도).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 링크 이름. |
+| `description` | `ReactNode` |  | 이름 아래 옅은 한 줄(패널 안). |
+| `icon` | `ReactNode` |  | 이름 앞 아이콘 · IconTile. |
+| `badge` | `ReactNode` |  | 이름 뒤 Badge 등. |
+| `active` | `boolean` |  | 현재 페이지. aria-current="page". |
+| `as` | `ElementType` | `'a'` | 라우터 링크 컴포넌트. 나머지 props(href, to …)는 그대로 전달. |
+
+### NavigationMenuGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` | `ReactNode` |  | 링크 열 위의 작은 제목(role="group" 이름). |
+| `children` (필수) | `ReactNode` |  | NavigationMenuLink들. |
+
+### NavigationMenuFeature
+
+패널 마지막 칸의 소개 카드. 칸 높이를 꽉 채워요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 카드 제목. |
+| `eyebrow / description` | `ReactNode` |  | 위 작은 줄 / 제목 아래 설명. |
+| `action` | `ReactNode` |  | 아래 버튼 · 링크. |
+| `media` | `ReactNode` |  | 글 뒤를 채우는 이미지 · 일러스트(cover). |
+| `background` | `string` |  | media가 없을 때 배경(CSS). 기본은 옅은 회색 판. |
+| `tone` | `'default' \| 'inverse'` | `'default'` | inverse: 어두운 배경 위 흰 글자. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 메가 메뉴 헤더
+
+viewportAnchor로 헤더 전체를 넘기면 패널이 헤더 폭에 맞춰 펼쳐져요. 제품을 연 채 보안으로 옮겨 보세요 — 패널 높이가 바뀌고 내용이 오른쪽에서 들어와요. 열린 패널로 가는 동안 잠깐 벗어나도 유예 시간 안이면 닫히지 않아요.
+
+```tsx
+import { useRef } from 'react'
+import { ChevronRight } from 'lucide-react'
+import { Button, Grid, Inline, Text, NavigationMenu, NavigationMenuFeature, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink } from '@iamfiro/design'
+
+export default function Example() {
+  // The panel spans the whole header, not just the menu triggers.
+  const headerRef = useRef<HTMLElement>(null)
+
+  return (
+    <Inline as="header" ref={headerRef} justify="between" wrap={false} style={{ width: '100%', padding: '8px 4px' }}>
+      <Text variant="heading-sm">Paged</Text>
+      <NavigationMenu viewportAnchor={headerRef}>
+        <NavigationMenuItem value="product" label="제품">
+          <Grid columns="1fr 1fr 300px" gap={4}>
+            <NavigationMenuGroup title="제품">
+              <NavigationMenuLink href="#hire" label="Hire" description="실제 장애 환경에서 보는 채용 실기" />
+              <NavigationMenuLink href="#train" label="Train" description="지난 포스트모템이 다음 온콜 훈련으로" />
+              <NavigationMenuLink href="#sandbox" label="시험 환경" description="BYOC 또는 설치 없는 Paged 샌드박스" />
+            </NavigationMenuGroup>
+            <NavigationMenuGroup title="활용">
+              <NavigationMenuLink href="#cohort" label="기수 채용" description="같은 기수를 같은 주에, 같은 난이도로" />
+              <NavigationMenuLink href="#career" label="경력 채용" description="면접 전에 실제 대응 과정을 확인" />
+              <NavigationMenuLink href="#open" label="공채" description="정해진 회차에, 1차는 읽기형으로" />
+              <NavigationMenuLink href="#oncall" label="온콜 조직" description="팀의 장애 대응을 정기적으로 훈련" />
+              <NavigationMenuLink href="#edu" label="교육기관" description="실무형 장애 대응 과제 운영" />
+            </NavigationMenuGroup>
+            <NavigationMenuFeature
+              eyebrow="제품 둘러보기"
+              title="Hire · Train이 같은 장애 하나로 이어져요"
+              tone="inverse"
+              background="linear-gradient(180deg, #141a4a 0%, #6b3f78 55%, #f08a4b 100%)"
+              action={
+                <Button size="sm" iconRight={<ChevronRight />}>
+                  흐름 보기
+                </Button>
+              }
+            />
+          </Grid>
+        </NavigationMenuItem>
+        <NavigationMenuItem value="security" label="보안">
+          <Grid columns="1fr 1fr 300px" gap={4}>
+            <NavigationMenuGroup title="보안">
+              <NavigationMenuLink href="#trust" label="보안 센터" description="인증 현황과 감사 보고서" />
+              <NavigationMenuLink href="#data" label="데이터 처리" description="후보자 데이터를 어디에, 얼마나 두는지" />
+            </NavigationMenuGroup>
+            <NavigationMenuGroup title="문서">
+              <NavigationMenuLink href="#dpa" label="데이터 처리 부속서" description="DPA 서명본 받기" />
+              <NavigationMenuLink href="#sub" label="하위 처리자" description="함께 일하는 처리자 목록" />
+            </NavigationMenuGroup>
+            <NavigationMenuFeature
+              eyebrow="ISMS-P"
+              title="2026년 10월 인증을 갱신했어요"
+              action={
+                <Button size="sm" iconRight={<ChevronRight />}>
+                  인증서 보기
+                </Button>
+              }
+            />
+          </Grid>
+        </NavigationMenuItem>
+        <NavigationMenuLink href="#pricing" label="요금" />
+      </NavigationMenu>
+      <Button size="sm" variant="primary">
+        데모 신청
+      </Button>
+    </Inline>
+  )
+}
+```
+
+### 어두운 헤더
+
+tone="inverse"면 메뉴 이름이 밝은 글자와 반투명 채움으로 바뀌어요. 패널은 그대로 흰색이에요.
+
+```tsx
+import { useRef } from 'react'
+import { ChevronRight } from 'lucide-react'
+import { Button, Grid, Inline, NavigationMenu, NavigationMenuFeature, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink } from '@iamfiro/design'
+
+export default function Example() {
+  const heroRef = useRef<HTMLDivElement>(null)
+
+  return (
+    <Inline
+      ref={heroRef}
+      justify="center"
+      style={{ width: '100%', padding: 12, borderRadius: 16, background: '#0b1033' }}
+    >
+      <NavigationMenu tone="inverse" viewportAnchor={heroRef}>
+        <NavigationMenuItem value="product" label="제품">
+          <Grid columns="1fr 1fr 280px" gap={4}>
+            <NavigationMenuGroup title="제품">
+              <NavigationMenuLink href="#hire" label="Hire" description="실제 장애 환경에서 보는 채용 실기" />
+              <NavigationMenuLink href="#train" label="Train" description="지난 포스트모템이 다음 온콜 훈련으로" />
+            </NavigationMenuGroup>
+            <NavigationMenuGroup title="활용">
+              <NavigationMenuLink href="#cohort" label="기수 채용" description="같은 기수를 같은 주에, 같은 난이도로" />
+              <NavigationMenuLink href="#oncall" label="온콜 조직" description="팀의 장애 대응을 정기적으로 훈련" />
+            </NavigationMenuGroup>
+            <NavigationMenuFeature
+              eyebrow="제품 둘러보기"
+              title="Hire · Train이 같은 장애 하나로 이어져요"
+              tone="inverse"
+              background="linear-gradient(180deg, #141a4a 0%, #6b3f78 55%, #f08a4b 100%)"
+              action={
+                <Button size="sm" iconRight={<ChevronRight />}>
+                  흐름 보기
+                </Button>
+              }
+            />
+          </Grid>
+        </NavigationMenuItem>
+        <NavigationMenuItem value="security" label="보안">
+          <Grid columns="1fr 1fr" gap={4}>
+            <NavigationMenuGroup title="보안">
+              <NavigationMenuLink href="#trust" label="보안 센터" description="인증 현황과 감사 보고서" />
+            </NavigationMenuGroup>
+            <NavigationMenuGroup title="문서">
+              <NavigationMenuLink href="#dpa" label="데이터 처리 부속서" description="DPA 서명본 받기" />
+            </NavigationMenuGroup>
+          </Grid>
+        </NavigationMenuItem>
+        <NavigationMenuLink href="#pricing" label="요금" />
+      </NavigationMenu>
+    </Inline>
+  )
+}
+```
+
+### 메뉴 아래 맞춤
+
+panelAlign="trigger"면 패널이 내용 폭만큼만 열린 메뉴 이름 아래 가운데에 놓여요. 메뉴마다 폭이 달라도 패널이 크기와 위치를 함께 옮기며 바뀌어요. 링크에 icon(IconTile 등)과 badge를 붙일 수 있어요.
+
+```tsx
+import { BookOpen, Code2, FileText, LifeBuoy, MessagesSquare, Newspaper, PlayCircle, Webhook } from 'lucide-react'
+import { Badge, IconTile, NavigationMenu, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <NavigationMenu panelAlign="trigger">
+      <NavigationMenuItem value="docs" label="개발자" width={340}>
+        <NavigationMenuLink
+          href="#quickstart"
+          icon={<IconTile size={32}><PlayCircle /></IconTile>}
+          label="빠른 시작"
+          description="5분 안에 첫 시나리오 실행하기"
+        />
+        <NavigationMenuLink
+          href="#api"
+          icon={<IconTile size={32}><Code2 /></IconTile>}
+          label="API 레퍼런스"
+          description="REST · GraphQL 엔드포인트 전체"
+        />
+        <NavigationMenuLink
+          href="#webhooks"
+          icon={<IconTile size={32}><Webhook /></IconTile>}
+          label="웹훅"
+          badge={<Badge size="sm" tone="accent">베타</Badge>}
+          description="결과가 나오면 바로 받아 보기"
+        />
+      </NavigationMenuItem>
+      <NavigationMenuItem value="resources" label="자료" width={520}>
+        <NavigationMenuGroup title="읽을거리">
+          <NavigationMenuLink href="#blog" icon={<Newspaper size={18} />} label="블로그" description="장애 대응 팀의 일하는 방식" />
+          <NavigationMenuLink href="#guides" icon={<BookOpen size={18} />} label="가이드" description="온콜 훈련을 설계하는 법" />
+          <NavigationMenuLink href="#reports" icon={<FileText size={18} />} label="리포트" description="2026 온콜 현황 보고서" />
+        </NavigationMenuGroup>
+      </NavigationMenuItem>
+      <NavigationMenuItem value="support" label="지원" width={280}>
+        <NavigationMenuLink href="#help" icon={<LifeBuoy size={18} />} label="도움말 센터" />
+        <NavigationMenuLink href="#community" icon={<MessagesSquare size={18} />} label="커뮤니티" />
+      </NavigationMenuItem>
+      <NavigationMenuLink href="#changelog" label="변경 기록" />
+    </NavigationMenu>
+  )
+}
+```
+
+### 클릭으로 열기 · 제어
+
+openOn="click"이면 눌러야만 열려요. value · onValueChange로 열린 메뉴를 밖에서 읽고 정해요(null = 닫힘). active 링크는 aria-current="page"로 표시돼요. 링크를 누르면 패널이 닫히고, disabled 메뉴는 ←/→ 이동에서 건너뛰어요.
+
+```tsx
+import { useState } from 'react'
+import { Badge, Inline, Stack, Text, NavigationMenu, NavigationMenuGroup, NavigationMenuItem, NavigationMenuLink } from '@iamfiro/design'
+
+const LABELS: Record<string, string> = { product: '제품', company: '회사' }
+
+export default function Example() {
+  const [open, setOpen] = useState<string | null>(null)
+  const [page, setPage] = useState('hire')
+
+  const go = (id: string) => (e: React.MouseEvent) => {
+    e.preventDefault()
+    setPage(id)
+  }
+
+  return (
+    <Stack gap={4} align="center" style={{ width: '100%' }}>
+      <NavigationMenu openOn="click" panelAlign="trigger" value={open} onValueChange={setOpen}>
+        <NavigationMenuItem value="product" label="제품" width={300}>
+          <NavigationMenuGroup title="제품">
+            <NavigationMenuLink href="#hire" label="Hire" active={page === 'hire'} onClick={go('hire')} />
+            <NavigationMenuLink href="#train" label="Train" active={page === 'train'} onClick={go('train')} />
+          </NavigationMenuGroup>
+        </NavigationMenuItem>
+        <NavigationMenuItem value="company" label="회사" width={300}>
+          <NavigationMenuGroup title="회사">
+            <NavigationMenuLink href="#about" label="소개" active={page === 'about'} onClick={go('about')} />
+            <NavigationMenuLink href="#careers" label="채용" active={page === 'careers'} onClick={go('careers')} />
+          </NavigationMenuGroup>
+        </NavigationMenuItem>
+        <NavigationMenuItem value="enterprise" label="엔터프라이즈" disabled>
+          {null}
+        </NavigationMenuItem>
+        <NavigationMenuLink href="#pricing" label="요금" active={page === 'pricing'} onClick={go('pricing')} />
+      </NavigationMenu>
+      <Inline gap={2}>
+        <Text variant="body-sm" tone="secondary">
+          열린 메뉴
+        </Text>
+        <Badge>{open ? LABELS[open] : '없음'}</Badge>
+        <Text variant="body-sm" tone="secondary">
+          현재 페이지
+        </Text>
+        <Badge tone="accent">{page}</Badge>
+      </Inline>
+    </Stack>
+  )
+}
+```

package/agents/notice-stack/AGENTS.md

@@ -0,0 +1,101 @@
+# NoticeStack
+
+> 알림 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+닫을 수 있는 공지 카드 묶음(새 기능 소개, 팁, 점검 안내). 평소에는 맨 앞 카드 뒤로 나머지가 살짝 겹쳐 보이고, 마우스를 잠시 올리거나 포커스가 들어오면 펼쳐져요. ×로 닫으면 카드가 등장의 역방향으로 사라지고 다음 카드가 그 자리로 미끄러져 와요. 카드는 Card · CardHeader · CardFooter 조립이에요.
+
+```tsx
+import { NoticeStack, type NoticeItem } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 겹친 카드 묶음(`Toaster`, `NoticeStack`)은 같은 방식: 뒤 카드는 앞 카드 높이로 맞춰 가장자리만 보이고, hover(의도 지연·유예)·focus로 펼치며, 닫힌 카드는 제자리에서 등장 역방향으로 나가고 나머지가 그 자리로 이동.
+
+## API
+
+### NoticeStack
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` (필수) | `NoticeItem[]` |  | 카드 목록. 첫 번째가 맨 앞. |
+| `onDismiss` | `(id: string) => void` |  | 퇴장 애니메이션이 끝난 뒤 불려요. 여기서 items에서 빼 주세요(빼지 않아도 스스로 숨겨요). |
+| `visible` | `number` | `3` | 보이는 카드 수. |
+| `expanded` | `boolean` |  | hover · focus와 상관없이 항상 펼침. |
+| `direction` | `'up' \| 'down'` | `'up'` | up: 아래에 붙어 위로 겹치고 펼쳐져요 · down: 반대. |
+| `gap` | `number` | `8` | 펼쳤을 때 카드 사이(px). |
+| `dismissLabel` | `string` | `'닫기'` | × 버튼의 aria-label. |
+| `aria-label` | `string` | `'공지'` | 묶음(section)의 접근성 이름. |
+| `className / style` | `string / CSSProperties` |  | 바깥 요소에 전달. |
+
+### NoticeItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `id` (필수) | `string` |  | 고유 id. |
+| `title` (필수) | `ReactNode` |  | 굵은 제목. |
+| `eyebrow` | `ReactNode` |  | 제목 위 작은 파란 글자("새 기능"). |
+| `description` | `ReactNode` |  | 제목 아래 설명. |
+| `footer` | `ReactNode` |  | 아래 줄(예: "전체 변경 기록 ›" 버튼). |
+| `dismissible` | `boolean` | `true` | false면 ×가 없어요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 사이드바 아래 공지
+
+direction='up'(기본): 뒤 카드가 위로 삐져나오고 위로 펼쳐져요. hover는 잠깐(200ms) 머물러야 펼치고, 벗어나도 300ms 유예 뒤 접혀요. 닫은 카드는 onDismiss로 목록에서 빼요. 키보드로 닫으면 포커스가 다음 카드의 ×로 옮겨 가요.
+
+```tsx
+import { useState } from 'react'
+import { ChevronRight, RotateCcw } from 'lucide-react'
+import { Button, Stack, NoticeStack, type NoticeItem } from '@iamfiro/design'
+
+const NOTICES: NoticeItem[] = [
+  {
+    id: 'shared-folders',
+    eyebrow: '10월 새 기능',
+    title: '공유 폴더',
+    description: '폴더째로 팀원과 나눠 쓸 수 있어요.',
+    footer: (
+      <Button variant="ghost" size="sm" iconRight={<ChevronRight />}>
+        전체 변경 기록
+      </Button>
+    ),
+  },
+  { id: 'templates', eyebrow: '새 기능', title: '문서 템플릿', description: '자주 쓰는 형식을 템플릿으로 저장하세요.' },
+  { id: 'mobile', eyebrow: '안내', title: '모바일 앱 출시', description: 'iOS · Android에서 바로 받아 보세요.' },
+]
+
+export default function Example() {
+  const [items, setItems] = useState(NOTICES)
+  return (
+    // 사이드바 아래처럼 바닥에 붙여 두면 위로 펼쳐져요.
+    <Stack gap={4} justify="end" style={{ width: 260, height: 340 }}>
+      <NoticeStack items={items} onDismiss={(id) => setItems((prev) => prev.filter((n) => n.id !== id))} />
+      <Button size="sm" variant="ghost" icon={<RotateCcw />} onClick={() => setItems(NOTICES)} disabled={items.length === NOTICES.length}>
+        다시 보기
+      </Button>
+    </Stack>
+  )
+}
+```
+
+### 항상 펼침 · 아래로
+
+expanded면 늘 펼쳐 두고, direction='down'이면 아래로 쌓여요. dismissible: false인 카드는 × 없이 남아요.
+
+```tsx
+import { NoticeStack, type NoticeItem } from '@iamfiro/design'
+
+const NOTICES: NoticeItem[] = [
+  { id: 'maintenance', eyebrow: '점검 안내', title: '10월 28일 새벽 2시 점검', description: '약 30분 동안 저장이 잠시 멈춰요.', dismissible: false },
+  { id: 'export', eyebrow: '새 기능', title: 'PDF로 내보내기', description: '문서를 PDF로 바로 저장할 수 있어요.' },
+  { id: 'shortcut', eyebrow: '팁', title: '⌘K로 어디든 이동', description: '검색창에서 페이지 이름을 입력해 보세요.' },
+]
+
+export default function Example() {
+  return <NoticeStack items={NOTICES} expanded direction="down" style={{ width: 300 }} />
+}
+```

package/agents/number-stepper/AGENTS.md

@@ -0,0 +1,96 @@
+# NumberStepper
+
+> 텍스트 입력 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+− 숫자 + 로 작은 수(작업자 수, 좌석, 재시도 횟수)를 바꿔요. 입력 칸이 아니라 테두리 없이 흰 칩 + 옅은 그림자예요. 짧게 누르면 한 칸(놓는 순간), 길게 누르면 잠깐 뒤부터 연속으로 바뀌고, 숫자는 움직인 방향에서 미끄러져 들어와요. 숫자는 ARIA spinbutton이라 키보드로도 바꿔요.
+
+```tsx
+import { NumberStepper } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 작은 수 조절은 `NumberStepper`: 클릭은 놓을 때 한 칸, 길게 누르면 `TIMING.repeatDelay` 뒤 `repeatInterval`마다 반복.
+
+## API
+
+### NumberStepper
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `number` |  | 현재 값(제어). |
+| `defaultValue` | `number` |  | 처음 값(비제어). 없으면 0을 min~max 안으로. |
+| `onValueChange` | `(value: number) => void` |  | 값이 바뀔 때(길게 누르는 동안 매번). |
+| `min / max` | `number` | `-Infinity / Infinity` | 범위. 닿으면 그쪽 버튼이 비활성. |
+| `step` | `number` | `1` | 한 번에 바뀌는 양. 소수면 그 자릿수로 반올림. |
+| `largeStep` | `number` | `step × 10` | PageUp / PageDown으로 바뀌는 양. |
+| `size` | `'sm' \| 'md'` | `'md'` | 높이 28 / 34px. |
+| `disabled` | `boolean` |  | 비활성. |
+| `formatValue` | `(value: number) => ReactNode` |  | 보이는 글자(예: "4명"). 글자면 aria-valuetext에도 쓰여요. |
+| `aria-label / aria-labelledby` | `string` |  | spinbutton의 이름. |
+| `decrementLabel / incrementLabel` | `string` | `'줄이기' / '늘리기'` | − / + 버튼의 aria-label. |
+| `name` | `string` |  | 폼 제출용 숨은 input 이름. |
+| `id / className / style` | `string / string / CSSProperties` |  | id는 spinbutton에, 나머지는 바깥 요소에. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 크기 · 범위 · 비활성
+
+md · sm 크기. min / max에 닿으면 그쪽 버튼이 비활성이 돼요. 비활성은 회색 채움.
+
+```tsx
+import { Inline, Stack, Text, NumberStepper } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4} align="start">
+      <Inline gap={4}>
+        <NumberStepper defaultValue={4} min={1} max={8} aria-label="동시 작업 수" />
+        <NumberStepper size="sm" defaultValue={2} min={0} max={10} aria-label="재시도 횟수" />
+        <NumberStepper defaultValue={3} disabled aria-label="좌석 수" />
+      </Inline>
+      <Text variant="caption" tone="tertiary">
+        버튼을 길게 누르면 잠깐 뒤 연속으로 바뀌어요. 숫자에 포커스하고 ↑ ↓ · PageUp/PageDown · Home/End로도 바꿔요.
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### 카드 머리글에서 제어
+
+작업 대기열 카드의 일시정지 버튼 옆에 둔 예. value / onValueChange로 제어하고 formatValue로 "4명"처럼 보여요.
+
+```tsx
+import { useState } from 'react'
+import { Pause, Play } from 'lucide-react'
+import { Button, Inline, Text, Card, CardBody, CardHeader, NumberStepper } from '@iamfiro/design'
+
+export default function Example() {
+  const [workers, setWorkers] = useState(4)
+  const [paused, setPaused] = useState(false)
+  return (
+    <Card padding="sm" style={{ width: 420 }}>
+      <CardHeader
+        title="작업 대기열"
+        description={paused ? '일시정지됨' : `작업자 ${workers}명이 처리 중이에요`}
+        actions={
+          <Inline gap={2} wrap={false}>
+            <Button size="sm" icon={paused ? <Play /> : <Pause />} onClick={() => setPaused((v) => !v)}>
+              {paused ? '다시 시작' : '일시정지'}
+            </Button>
+            <NumberStepper size="sm" value={workers} onValueChange={setWorkers} min={1} max={12} aria-label="작업자 수" formatValue={(v) => `${v}명`} />
+          </Inline>
+        }
+      />
+      <CardBody>
+        <Text as="p" variant="caption" tone="tertiary">
+          value / onValueChange로 제어해요. formatValue는 화면 글자와 aria-valuetext에 함께 쓰여요.
+        </Text>
+      </CardBody>
+    </Card>
+  )
+}
+```