@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/skeleton/AGENTS.md

@@ -0,0 +1,166 @@
+# Skeleton
+
+> 진행 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+내용이 들어올 자리를 미리 보여 주는 회색 자리 표시. 실제 레이아웃과 같은 크기로 그려 두면 내용이 들어올 때 화면이 덜컹거리지 않아요. SkeletonGroup으로 감싸면 로딩이 끝날 때 실제 내용으로 부드럽게 바뀌어요.
+
+```tsx
+import { Skeleton, SkeletonText, SkeletonCircle, SkeletonGroup } from '@iamfiro/design'
+```
+
+## API
+
+### Skeleton
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `width` | `number \| string` | `'100%'` | 너비. 숫자는 px. |
+| `height` | `number \| string` | `16` | 높이. 숫자는 px. |
+| `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full' \| number` | `'sm'` | 모서리(0 / 6 / 10 / 16px / 원형). |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+| `className / style` | `string / CSSProperties` |  | 블록에 적용돼요. |
+
+### SkeletonText
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `lines` | `number` | `3` | 줄 수. |
+| `lastLineWidth` | `string` | `'62%'` | 마지막 줄 너비(2줄 이상일 때). 문단처럼 보이게 해요. |
+| `variant` | `TextVariant` | `'body-md'` | 맞출 글자 역할. 줄 높이가 실제 Text와 같아져요. |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+### SkeletonCircle
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `number` | `36` | 지름(px). |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | 움직임. shimmer는 빛이 지나가고, pulse는 깜빡여요. |
+
+### SkeletonGroup
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `loading` (필수) | `boolean` |  | true면 fallback, false면 children을 보여 줘요. |
+| `fallback` (필수) | `ReactNode` |  | 로딩 중에 보여 줄 스켈레톤. |
+| `children` (필수) | `ReactNode` |  | 실제 내용. |
+| `label` | `string` | `'불러오는 중'` | 로딩 중 스크린 리더가 읽는 이름. |
+| `className` | `string` |  | 루트에 붙일 클래스. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본 모양
+
+Skeleton은 크기와 모서리를 정하는 블록, SkeletonCircle은 아바타 자리, SkeletonText는 글자 역할(variant)의 줄 높이에 맞춘 문단이에요.
+
+```tsx
+import { Skeleton, SkeletonCircle, SkeletonText } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20, width: 360 }}>
+      <div style={{ display: 'flex', alignItems: 'center', gap: 12 }}>
+        <SkeletonCircle size={40} />
+        <div style={{ display: 'grid', gap: 8, flex: 1 }}>
+          <Skeleton width="40%" height={14} />
+          <Skeleton width="65%" height={12} />
+        </div>
+      </div>
+      <Skeleton height={180} radius="lg" />
+      <div style={{ display: 'grid', gap: 6 }}>
+        <div style={{ width: '70%' }}>
+          <SkeletonText variant="heading-sm" lines={1} />
+        </div>
+        <SkeletonText lines={3} lastLineWidth="45%" />
+      </div>
+    </div>
+  )
+}
+```
+
+### 애니메이션
+
+여러 줄이면 줄마다 조금씩 늦게 시작해서 물결처럼 보여요.
+
+```tsx
+import { Text, SkeletonCircle, SkeletonText, type SkeletonAnimation } from '@iamfiro/design'
+
+const ANIMATIONS: Array<[SkeletonAnimation, string]> = [
+  ['shimmer', '빛이 지나가요 (기본)'],
+  ['pulse', '천천히 깜빡여요'],
+  ['none', '움직이지 않아요'],
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(auto-fit, minmax(180px, 1fr))', gap: 28, width: '100%', maxWidth: 640 }}>
+      {ANIMATIONS.map(([animation, label]) => (
+        <div key={animation} style={{ display: 'grid', gap: 12 }}>
+          <SkeletonCircle size={32} animation={animation} />
+          <SkeletonText lines={3} animation={animation} />
+          <Text variant="caption" tone="tertiary">
+            {animation} · {label}
+          </Text>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 실제 내용으로 바꾸기
+
+SkeletonGroup은 loading 동안 fallback을 보여 주고, 끝나면 children을 서서히 나타내요. 로딩 중에는 aria-busy가 붙어요.
+
+```tsx
+import { useState } from 'react'
+import { FolderKanban } from 'lucide-react'
+import { AvatarGroup, Switch, Card, CardBody, CardFooter, CardHeader, Skeleton, SkeletonGroup, SkeletonText } from '@iamfiro/design'
+
+function ProjectCardSkeleton() {
+  return (
+    <Card style={{ width: 360 }}>
+      <CardHeader
+        icon={<Skeleton width={40} height={40} radius="md" />}
+        title={
+          <div style={{ width: '55%' }}>
+            <SkeletonText variant="heading-sm" lines={1} />
+          </div>
+        }
+        description={
+          <div style={{ width: '80%' }}>
+            <SkeletonText variant="body-sm" lines={1} />
+          </div>
+        }
+      />
+      <CardBody>
+        <SkeletonText lines={2} />
+      </CardBody>
+      <CardFooter align="start">
+        <Skeleton width={84} height={24} radius="full" />
+      </CardFooter>
+    </Card>
+  )
+}
+
+export default function Example() {
+  const [loading, setLoading] = useState(true)
+
+  return (
+    <div style={{ display: 'grid', justifyItems: 'center', gap: 20 }}>
+      <Switch label="불러오는 중" checked={loading} onChange={(e) => setLoading(e.target.checked)} />
+      <SkeletonGroup loading={loading} fallback={<ProjectCardSkeleton />}>
+        <Card style={{ width: 360 }}>
+          <CardHeader icon={<FolderKanban />} title="웹사이트 리뉴얼" description="김민지 외 3명 · 2분 전 수정" />
+          <CardBody>새 랜딩 페이지 시안을 검토하고 있어요. 금요일까지 피드백을 남겨 주세요.</CardBody>
+          <CardFooter align="start">
+            <AvatarGroup names={['김민지', '이도현', '박서연', '최준호']} />
+          </CardFooter>
+        </Card>
+      </SkeletonGroup>
+    </div>
+  )
+}
+```

package/agents/slider/AGENTS.md

@@ -0,0 +1,181 @@
+# Slider
+
+> 선택 컨트롤 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+끌어서 값을 고르는 슬라이더. 숫자 하나를 주면 단일 값, [시작, 끝]을 주면 범위가 돼요. 끄는 동안은 미리보기(onValueChange), 손을 놓을 때 확정(onValueCommit)하고, 끄는 중에 Esc를 누르면 원래 값으로 돌아가요.
+
+```tsx
+import { Slider } from '@iamfiro/design'
+```
+
+## API
+
+### Slider
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` | `number \| [number, number]` |  | 값(제어). 튜플이면 범위 슬라이더. |
+| `defaultValue` | `number \| [number, number]` | `min` | 처음 값(비제어). 범위는 반드시 튜플로 주세요. |
+| `onValueChange` | `(value) => void` |  | 끄는 동안·키 입력마다 호출(미리보기). |
+| `onValueCommit` | `(value) => void` |  | 손을 놓을 때 / 키를 누를 때 한 번 호출(확정). Esc로 취소하면 호출되지 않아요. |
+| `min` | `number` | `0` | 최솟값. |
+| `max` | `number` | `100` | 최댓값. |
+| `step` | `number` | `1` | 단위. 소수(0.1 등)도 돼요. |
+| `minDistance` | `number` | `0` | 범위 전용. 두 손잡이 사이 최소 간격. |
+| `marks` | `Array<number \| { value: number; label?: ReactNode }>` |  | 트랙 아래 눈금. label이 있으면 글자도 표시. |
+| `formatValue` | `(value: number) => string` | `String` | 말풍선과 스크린 리더(aria-valuetext)에 쓰는 표시 형식. |
+| `showValue` | `'auto' \| 'always' \| 'never'` | `'auto'` | 값 말풍선: 조작할 때만 / 항상 / 안 보임. |
+| `size` | `'sm' \| 'md'` | `'md'` | 손잡이 18 / 14px. |
+| `disabled` | `boolean` |  | 비활성. |
+| `name` | `string` |  | 폼 제출용 hidden input 이름. 범위는 name[0], name[1]. |
+| `aria-label` | `string` |  | 손잡이 이름. |
+| `getThumbLabel` | `(index: number) => string` |  | 범위에서 손잡이별 이름. 예: (i) => (i === 0 ? '최소 가격' : '최대 가격'). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 기본
+
+트랙 어디를 눌러도 그 위치로 옮겨가요. 끄는 동안 위에 값 말풍선이 뜨고, formatValue로 단위를 붙여요. ←→ 한 칸, PageUp/PageDown 크게, Home/End 끝으로.
+
+```tsx
+import { useState } from 'react'
+import { Volume1, Volume2 } from 'lucide-react'
+import { Slider } from '@iamfiro/design'
+
+export default function Example() {
+  const [volume, setVolume] = useState(60)
+  return (
+    <div style={{ display: 'flex', alignItems: 'center', gap: 12, width: 340 }}>
+      <Volume1 size={18} color="var(--text-3)" />
+      <div style={{ flex: 1 }}>
+        <Slider value={volume} onValueChange={setVolume} formatValue={(v) => `${v}%`} aria-label="볼륨" />
+      </div>
+      <Volume2 size={18} color="var(--text-3)" />
+    </div>
+  )
+}
+```
+
+### 범위
+
+눌린 위치에서 가까운 손잡이가 움직여요. minDistance로 두 손잡이 사이 최소 간격을, getThumbLabel로 손잡이별 이름을 정해요.
+
+```tsx
+import { useState } from 'react'
+import { Text, Slider } from '@iamfiro/design'
+
+const won = (v: number) => (v >= 10000 ? `${(v / 10000).toLocaleString('ko-KR')}만원` : `${v.toLocaleString('ko-KR')}원`)
+
+export default function Example() {
+  const [price, setPrice] = useState<[number, number]>([100000, 350000])
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 360 }}>
+      <Text variant="label-md" numeric>
+        가격 {won(price[0])} – {won(price[1])}
+      </Text>
+      <Slider
+        value={price}
+        onValueChange={setPrice}
+        min={0}
+        max={500000}
+        step={10000}
+        minDistance={50000}
+        formatValue={won}
+        getThumbLabel={(i) => (i === 0 ? '최소 가격' : '최대 가격')}
+      />
+    </div>
+  )
+}
+```
+
+### 눈금
+
+marks에 label을 넣으면 트랙 아래에 글자가 찍혀요. 숫자만 넣으면 눈금만 그려요. showValue로 말풍선을 항상 / 끄기 할 수 있어요.
+
+```tsx
+import { useState } from 'react'
+import { Slider } from '@iamfiro/design'
+
+const QUALITY = ['낮음', '보통', '높음', '최고']
+
+export default function Example() {
+  const [quality, setQuality] = useState(2)
+  return (
+    <div style={{ display: 'grid', gap: 32, width: 360 }}>
+      <Slider
+        value={quality}
+        onValueChange={setQuality}
+        min={0}
+        max={3}
+        marks={QUALITY.map((label, value) => ({ value, label }))}
+        formatValue={(v) => QUALITY[v]}
+        showValue="never"
+        aria-label="화질"
+      />
+      <Slider defaultValue={40} step={20} marks={[0, 20, 40, 60, 80, 100]} formatValue={(v) => `${v}%`} showValue="always" aria-label="투명도" />
+    </div>
+  )
+}
+```
+
+### 미리보기와 확정
+
+저장이나 서버 요청은 onValueCommit에서 하세요. 끄는 중 Esc를 누르면 미리보기가 취소되고 아무것도 확정되지 않아요.
+
+```tsx
+import { useState } from 'react'
+import { Text, Slider } from '@iamfiro/design'
+
+export default function Example() {
+  const [preview, setPreview] = useState(120)
+  const [saved, setSaved] = useState(120)
+  return (
+    <div style={{ display: 'grid', gap: 12, width: 360 }}>
+      <Slider
+        value={preview}
+        onValueChange={setPreview}
+        onValueCommit={setSaved}
+        min={30}
+        max={300}
+        step={10}
+        formatValue={(v) => `${v}분`}
+        aria-label="자동 잠금 시간"
+      />
+      <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+        <Text variant="body-sm" tone="secondary" numeric>
+          미리보기 {preview}분
+        </Text>
+        <Text variant="body-sm" weight="semibold" numeric>
+          저장됨 {saved}분
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 크기와 비활성
+
+size sm / md, disabled.
+
+```tsx
+import { Field, Slider } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gap: 20, width: 340 }}>
+      <Field label="작게 (sm)">
+        <Slider size="sm" defaultValue={40} aria-label="밝기" />
+      </Field>
+      <Field label="작게 (sm) · 범위">
+        <Slider size="sm" defaultValue={[20, 70]} getThumbLabel={(i) => (i === 0 ? '최소 온도' : '최대 온도')} />
+      </Field>
+      <Field label="비활성">
+        <Slider defaultValue={30} disabled aria-label="비활성 슬라이더" />
+      </Field>
+    </div>
+  )
+}
+```

package/agents/spark-chart/AGENTS.md

@@ -0,0 +1,257 @@
+# SparkChart
+
+> 차트 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+축 없이 흐름만 보여 주는 아주 작은 차트. 표의 칸이나 KPI 카드에 넣어요. SparkLine(선) · SparkArea(선 + 옅은 그라데이션) · Sparkbar(막대)가 같은 props를 쓰고, SparkChart type으로 하나를 골라요. 24–40px 높이에서도 또렷하게 실제 픽셀 크기로 그리며, 마우스·터치·←/→로 십자선 점과 값 카드를 띄워요. tone="trend"는 처음 값 대비 마지막 값의 방향으로 색을 정해요(Delta처럼 higherIs로 좋고 나쁨).
+
+```tsx
+import { SparkArea, SparkChart, SparkLine } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 표 칸 · KPI 카드의 작은 추이는 `SparkLine` · `SparkArea` · `Sparkbar`(같은 props, 하나로 고르면 `SparkChart type`). 축 없음, 실제 픽셀 크기로 그려 24–40px에서도 또렷하게, 값 범위는 0이 아니라 최솟값–최댓값. 색은 `tone="trend"` + `higherIs`(Delta와 같은 규칙), 마지막 값은 `endDot`. 긴 표에선 `tooltip={false}`로 이벤트 없는 정적 그림(`role="img"`). KPI 카드는 Card 안 `Stat` + `Delta` + `SparkArea`.
+
+## API
+
+### SparkLine · SparkArea
+
+SparkArea는 SparkLine props + fill.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `data` (필수) | `(number \| null)[]` |  | 한 칸에 값 하나(오래된 것부터). null이면 선이 끊겨요. |
+| `height` | `number` | `32` | 높이(px). 24–40을 권장해요. |
+| `width` | `number \| string` | `'100%'` | 너비. 표 칸에선 숫자로 고정해요. |
+| `curve` | `'linear' \| 'smooth'` | `'smooth'` | 직선 또는 튀어 오르지 않는 단조 곡선. |
+| `tone` | `'accent' \| 'neutral' \| 'trend'` | `'accent'` | trend는 방향(마지막 값 − 처음 값)에 따라 초록 / 주황. |
+| `higherIs` | `'better' \| 'worse' \| 'neutral'` | `'better'` | trend에서 오르는 게 좋은지. 시간 · 비용 · 오류는 worse. |
+| `worseTone` | `'warning' \| 'danger'` | `'warning'` | 나빠졌을 때 색. |
+| `color` | `string` |  | 직접 정한 색(CSS 변수 '--chart-2' 또는 색). tone보다 우선. |
+| `min / max` | `number` |  | 값 범위. 기본은 데이터의 최솟값 · 최댓값(모양을 보여 주는 차트라 0부터가 아니에요). |
+| `endDot` | `boolean` |  | 마지막 값에 점. |
+| `fill` | `'gradient' \| 'solid'` | `'gradient'` | SparkArea 채움. |
+| `tooltip` | `boolean` | `true` | 십자선 점 + 값 카드. false면 이벤트 · 포커스 없는 정적 그림. |
+| `formatLabel` | `(index) => string` | `'3일'` | 툴팁 제목. |
+| `valueLabel` | `string` | `'값'` | 툴팁 행 이름. |
+| `formatValue` | `(value) => string` | `'1,234'` | 툴팁 값 형식. |
+| `activeIndex / defaultActiveIndex / onActiveIndexChange` | `number \| null` |  | 고른 칸(제어/비제어). |
+| `aria-label` | `string` | `'추이'` | 이름. 고른 값은 aria-live로 읽어요. |
+
+### SparkChart
+
+위 props 전부 + type. bar는 Sparkbar로 그려요(Sparkbar도 tone · higherIs · worseTone을 받아요).
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `type` | `'line' \| 'area' \| 'bar'` | `'line'` | 그릴 모양. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### KPI 카드
+
+Card 안에 Stat + Delta + SparkArea. 응답 시간처럼 낮을수록 좋은 지표는 higherIs="worse"로 내려가는 선이 초록이 돼요. endDot은 마지막 값에 점을 찍어요.
+
+```tsx
+import { Delta, Grid, Stack, Card, CardBody, SparkArea, Stat } from '@iamfiro/design'
+
+const DAYS = ['10월 12일', '10월 13일', '10월 14일', '10월 15일', '10월 16일', '10월 17일', '10월 18일', '10월 19일', '10월 20일', '10월 21일', '10월 22일', '10월 23일', '10월 24일', '10월 25일']
+
+const KPIS = [
+  {
+    label: '매출',
+    value: '₩4,820만',
+    delta: 12.4,
+    higherIs: 'better' as const,
+    unit: '만 원',
+    data: [312, 298, 330, 341, 325, 352, 368, 344, 371, 389, 402, 396, 418, 432],
+  },
+  {
+    label: '활성 사용자',
+    value: '18,240',
+    delta: -3.1,
+    higherIs: 'better' as const,
+    unit: '명',
+    data: [19400, 19120, 19310, 18980, 18760, 18900, 18640, 18520, 18710, 18450, 18390, 18300, 18260, 18240],
+  },
+  {
+    label: '평균 응답 시간',
+    value: '182ms',
+    delta: -8.6,
+    higherIs: 'worse' as const,
+    unit: 'ms',
+    data: [214, 220, 205, 211, 198, 201, 195, 190, 193, 188, 186, 191, 184, 182],
+  },
+]
+
+export default function Example() {
+  return (
+    <Grid minItemWidth={200} gap={3} style={{ width: '100%' }}>
+      {KPIS.map((k) => (
+        <Card key={k.label}>
+          <CardBody>
+            <Stack gap={3}>
+              <Stat label={k.label} value={k.value} delta={<Delta value={k.delta} format={(n) => `${n}%`} higherIs={k.higherIs} size="sm" />} />
+              <SparkArea
+                data={k.data}
+                height={40}
+                tone="trend"
+                higherIs={k.higherIs}
+                endDot
+                formatLabel={(i) => DAYS[i]}
+                valueLabel={k.label}
+                formatValue={(v) => `${v.toLocaleString('ko-KR')}${k.unit}`}
+                aria-label={`${k.label} 최근 14일`}
+              />
+            </Stack>
+          </CardBody>
+        </Card>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### 표 안의 추이
+
+Table 칸에 width를 정한 SparkLine. null은 선이 끊긴 칸이에요. 칸 위에서 마우스를 움직이면 그날 값이 떠요.
+
+```tsx
+import { Delta, Text, SparkLine, Table, type TableColumn } from '@iamfiro/design'
+
+interface Page {
+  id: string
+  path: string
+  views: number
+  change: number
+  /** 최근 14일 조회수 */
+  trend: Array<number | null>
+}
+
+const PAGES: Page[] = [
+  { id: 'p1', path: '/요금제', views: 12840, change: 18.2, trend: [620, 640, 610, 700, 760, 720, 810, 840, 860, 900, 950, 930, 1010, 1080] },
+  { id: 'p2', path: '/시작하기', views: 9310, change: 4.1, trend: [640, 660, 650, 630, 670, 690, 660, 680, 700, 690, 710, 700, 720, 730] },
+  { id: 'p3', path: '/블로그/출시-노트', views: 6120, change: -22.5, trend: [880, 820, 760, 640, 600, 520, 480, 430, 410, 380, 350, 330, 310, 290] },
+  { id: 'p4', path: '/고객-사례', views: 3470, change: 0, trend: [240, 260, 230, 250, 270, 240, 250, 260, 240, 250, 255, 245, 250, 248] },
+  { id: 'p5', path: '/문의', views: 1980, change: 9.7, trend: [110, 120, null, null, 130, 135, 140, 128, 150, 145, 155, 160, 158, 170] },
+]
+
+const COLUMNS: TableColumn<Page>[] = [
+  { key: 'path', header: '페이지', render: (p) => <Text variant="label-md">{p.path}</Text> },
+  { key: 'views', header: '조회수', numeric: true, render: (p) => p.views.toLocaleString('ko-KR') },
+  {
+    key: 'trend',
+    header: '최근 14일',
+    width: 120,
+    render: (p) => (
+      <SparkLine
+        data={p.trend}
+        width={112}
+        height={28}
+        tone="trend"
+        formatLabel={(i) => `10월 ${12 + i}일`}
+        valueLabel="조회수"
+        formatValue={(v) => `${v.toLocaleString('ko-KR')}회`}
+        aria-label={`${p.path} 최근 14일 조회수`}
+      />
+    ),
+  },
+  { key: 'change', header: '변화', align: 'end', render: (p) => <Delta value={p.change} format={(n) => `${n}%`} size="sm" /> },
+]
+
+export default function Example() {
+  return <Table caption="많이 본 페이지" columns={COLUMNS} rows={PAGES} rowKey={(p) => p.id} style={{ width: '100%', maxWidth: 640 }} />
+}
+```
+
+### 세 가지 type
+
+SparkChart type="line" | "area" | "bar". 데이터를 바꾸면 선은 새 모양으로, 막대는 새 높이로 미끄러져요.
+
+```tsx
+import { useState } from 'react'
+import { Button, Grid, Inline, Stack, Text, SparkChart } from '@iamfiro/design'
+
+const THIS_WEEK = [32, 41, 38, 52, 47, 61, 58, 66, 72, 69, 80, 84]
+const LAST_WEEK = [28, 30, 35, 31, 40, 38, 44, 41, 39, 46, 43, 50]
+
+const TYPES = [
+  { type: 'line', label: '선 (line)' },
+  { type: 'area', label: '영역 (area)' },
+  { type: 'bar', label: '막대 (bar)' },
+] as const
+
+export default function Example() {
+  const [week, setWeek] = useState<'this' | 'last'>('this')
+  const data = week === 'this' ? THIS_WEEK : LAST_WEEK
+  return (
+    <Stack gap={5} style={{ width: '100%', maxWidth: 560 }}>
+      <Grid columns={3} gap={6}>
+        {TYPES.map((t) => (
+          <Stack key={t.type} gap={2}>
+            <Text variant="caption" tone="tertiary">
+              {t.label}
+            </Text>
+            <SparkChart
+              type={t.type}
+              data={data}
+              height={36}
+              tone="accent"
+              formatLabel={(i) => `${i * 2}시`}
+              valueLabel="주문"
+              formatValue={(v) => `${v}건`}
+              aria-label={`시간대별 주문 · ${t.label}`}
+            />
+          </Stack>
+        ))}
+      </Grid>
+      <Inline gap={2}>
+        <Button size="sm" variant={week === 'last' ? 'primary' : 'secondary'} onClick={() => setWeek('last')}>
+          지난주
+        </Button>
+        <Button size="sm" variant={week === 'this' ? 'primary' : 'secondary'} onClick={() => setWeek('this')}>
+          이번 주
+        </Button>
+      </Inline>
+    </Stack>
+  )
+}
+```
+
+### 추세 색 · 정적
+
+tone="trend" + higherIs · worseTone. tooltip={false}면 이벤트 없이 그림만 그려서(role="img") 긴 표에서도 가벼워요. fill="solid"는 한 겹의 옅은 색.
+
+```tsx
+import { Inline, Stack, Text, SparkArea, SparkLine } from '@iamfiro/design'
+
+const UP = [12, 14, 13, 17, 16, 19, 22, 21, 25, 27]
+const DOWN = [27, 25, 26, 22, 21, 19, 18, 15, 14, 12]
+
+const ROWS = [
+  { label: '가입 · 늘수록 좋음', data: UP, higherIs: 'better' as const },
+  { label: '이탈 · 줄수록 좋음', data: DOWN, higherIs: 'worse' as const },
+  { label: '오류 · 늘면 위험', data: UP, higherIs: 'worse' as const, worseTone: 'danger' as const },
+  { label: '방문 · 줄었음', data: DOWN, higherIs: 'better' as const },
+]
+
+export default function Example() {
+  return (
+    <Stack gap={4} style={{ width: '100%', maxWidth: 420 }}>
+      {ROWS.map((r) => (
+        <Inline key={r.label} justify="between" gap={4} wrap={false}>
+          <Text variant="body-sm" tone="secondary">
+            {r.label}
+          </Text>
+          <Inline gap={4} wrap={false}>
+            <SparkLine data={r.data} width={96} height={24} tone="trend" higherIs={r.higherIs} worseTone={r.worseTone} endDot tooltip={false} aria-label={r.label} />
+            <SparkArea data={r.data} width={96} height={24} tone="trend" higherIs={r.higherIs} worseTone={r.worseTone} curve="linear" fill="solid" tooltip={false} aria-label={r.label} />
+          </Inline>
+        </Inline>
+      ))}
+    </Stack>
+  )
+}
+```