@iamfiro/design 0.0.0-stage → 0.3.0

package/agents/delta/AGENTS.md

@@ -0,0 +1,114 @@
+# Delta
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+이전 · 목표와 비교한 증감을 부호와 함께 보여 줘요. 더 큰 값이 좋은지 나쁜지(higherIs)에 따라 초록 · 주황이 정해지고, 0은 회색이에요. 빼기는 하이픈이 아닌 진짜 마이너스(−)를 쓰고 숫자는 tabular라 세로로 줄이 맞아요.
+
+```tsx
+import { Delta } 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`.
+- 증감은 `Delta`: 진짜 마이너스(−), tabular 숫자, 좋고 나쁨은 부호가 아니라 `higherIs`로 정한다(시간 · 비용 · 오류는 `worse`). 0은 회색.
+
+## API
+
+### Delta
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `value` (필수) | `number` |  | 부호가 있는 증감 값. 0은 중립(회색, 부호 없음). |
+| `format` | `(absolute: number) => ReactNode` | `ko-KR 숫자` | 절댓값을 보여 줄 형식. 부호는 자동으로 붙어요. |
+| `suffix` | `ReactNode` |  | 숫자 뒤 글자("늦음", "지난주 대비"). |
+| `higherIs` | `'better' \| 'worse' \| 'neutral'` | `'better'` | 값이 커지는 것의 의미. neutral이면 늘 회색. |
+| `worseTone` | `'warning' \| 'danger'` | `'warning'` | 나빠졌을 때 색. 위험한 지표는 danger. |
+| `arrow` | `boolean` |  | 숫자 앞 위/아래 화살표. |
+| `variant` | `'soft' \| 'text'` | `'soft'` | soft: 연한 배지 · text: 색 글자만. |
+| `size` | `'sm' \| 'md'` | `'md'` | 크기. |
+| `aria-label` | `string` |  | 보이는 글자 대신 읽을 문장. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 좋아짐 · 나빠짐
+
+매출처럼 클수록 좋은 값은 higherIs="better"(기본), 소요 시간 · 비용처럼 작을수록 좋은 값은 "worse".
+
+```tsx
+import { Fragment } from 'react'
+import { Delta, Grid, Text } from '@iamfiro/design'
+
+const ROWS = [
+  { label: '주간 가입자', value: 128, higherIs: 'better' as const },
+  { label: '주간 가입자', value: -36, higherIs: 'better' as const },
+  { label: '평균 빌드 시간', value: 12, higherIs: 'worse' as const },
+  { label: '평균 빌드 시간', value: -4, higherIs: 'worse' as const },
+  { label: '열린 이슈', value: 0, higherIs: 'worse' as const },
+]
+
+export default function Example() {
+  return (
+    <Grid columns="auto auto auto" gap={6} rowGap={3} align="center" style={{ justifyContent: 'start' }}>
+      {ROWS.map((r, i) => (
+        <Fragment key={i}>
+          <Text variant="label-sm" tone="secondary">
+            {r.label}
+          </Text>
+          <Text variant="code">{`higherIs="${r.higherIs}"`}</Text>
+          <Delta value={r.value} higherIs={r.higherIs} />
+        </Fragment>
+      ))}
+    </Grid>
+  )
+}
+```
+
+### 형식 · 화살표
+
+format은 부호를 뺀 절댓값을 받아요. 단위 · 소수점 · 통화는 여기서, 부호는 Delta가 붙여요.
+
+```tsx
+import { Delta, Inline } from '@iamfiro/design'
+
+const won = new Intl.NumberFormat('ko-KR', { style: 'currency', currency: 'KRW' })
+
+export default function Example() {
+  return (
+    <Inline gap={3}>
+      <Delta value={12} higherIs="worse" format={(n) => `${n}초`} />
+      <Delta value={-4} higherIs="worse" format={(n) => `${n}초`} />
+      <Delta value={0.042} format={(n) => `${(n * 100).toFixed(1)}%`} arrow />
+      <Delta value={-0.018} format={(n) => `${(n * 100).toFixed(1)}%`} arrow />
+      <Delta value={2300} higherIs="worse" format={(n) => won.format(n)} worseTone="danger" arrow />
+      <Delta value={3} higherIs="worse" format={(n) => `${n}건`} size="sm" />
+    </Inline>
+  )
+}
+```
+
+### 글자형
+
+variant="text"는 배경 없이 색 글자만. 제목줄 · 문장 안에 넣을 때 써요.
+
+```tsx
+import { Delta, Heading, Inline, Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={4}>
+      <Inline gap={3} align="baseline">
+        <Heading level={3}>10월 정기 배포</Heading>
+        <Delta variant="text" value={23} higherIs="worse" format={(n) => `${n}초`} suffix="늦음" />
+      </Inline>
+      <Text variant="body-sm" tone="secondary">
+        이번 주 응답 시간은 평균 182ms로{' '}
+        <Delta variant="text" value={-14} higherIs="worse" format={(n) => `${n}ms`} arrow /> 줄었고, 오류율은{' '}
+        <Delta variant="text" value={0} format={(n) => `${n}%p`} /> 그대로예요.
+      </Text>
+    </Stack>
+  )
+}
+```

package/agents/description-list/AGENTS.md

@@ -0,0 +1,251 @@
+# DescriptionList
+
+> 데이터 표시 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+라벨 · 값 쌍을 진짜 <dl>로 보여 줘요. 라벨(오버라인 또는 옅은 캡션) 아래 값을 columns 칸 격자로 놓거나, 한 줄에 라벨 왼쪽 · 값 오른쪽으로 놓아요. soft는 상세 팝오버 안의 옅은 회색 패널(모서리 12, 촘촘한 여백)이에요. DescriptionSection은 격자 아래 "입력 / 결과" 같은 오버라인 제목 + 본문 블록이에요. 모두 Box · Grid · Stack · Text 조립이고, 값 크기는 Stat과 같은 숫자 역할을 써요.
+
+```tsx
+import { DescriptionItem, DescriptionList, DescriptionSection } from '@iamfiro/design'
+```
+
+## 디자인 규칙
+
+- 라벨 · 값 쌍(상세 팝오버, 결제 정보)은 `DescriptionList`(`<dl>`, `columns` 격자 또는 `layout="inline"` 행, `variant="soft"` 회색 패널, `labelStyle="overline" | "muted"`). "입력 / 결과" 같은 제목 + 본문은 `DescriptionSection`.
+
+## API
+
+### DescriptionList
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `items` | `DescriptionListItem[]` |  | { id?, label, value, icon?, tone?, span? } 목록. 또는 children. |
+| `children` | `ReactNode` |  | <DescriptionItem>들. |
+| `layout` | `'stacked' \| 'inline'` | `'stacked'` | 라벨 위 값 격자 / 한 줄 행(라벨 왼쪽, 값 오른쪽). |
+| `columns` | `number \| string` | `stacked 3 · inline 1` | 칸 수 또는 grid-template-columns 문자열. |
+| `minItemWidth` | `number` |  | 반응형: 이 폭(px) 이상인 칸을 들어가는 만큼. columns보다 우선. |
+| `variant` | `'plain' \| 'soft'` | `'plain'` | soft: 회색 패널(--surface-active, 모서리 12, 여백 12). |
+| `labelStyle` | `'overline' \| 'muted'` | `'overline'` | 오버라인 라벨 / 옅은 캡션 라벨. |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 값 크기. stacked는 number-sm · md · lg, inline은 label-sm · md · lg. |
+| `align` | `'end' \| 'start'` | `'end'` | inline 행만. end: 값을 행 오른쪽 끝에 · start: 값을 가장 긴 라벨 뒤 한 열에 맞춰 왼쪽 정렬(받는 사람 / 제목 / 첨부). |
+| `gap` | `Space` | `stacked 4 · inline 6` | 칸 사이 간격. |
+| `rowGap` | `Space` | `stacked 4 · inline 2` | 줄 사이 간격. |
+| `aria-label` | `string` |  | 목록 이름("배포 정보"). |
+
+### DescriptionItem
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `label` (필수) | `ReactNode` |  | 라벨(<dt>). |
+| `icon` | `ReactNode` |  | 라벨 앞 아이콘. 라벨과 같은 옅은 색, inline 16px · stacked 14px. |
+| `children` (필수) | `ReactNode` |  | 값(<dd>). |
+| `tone` | `TextTone` | `'default'` | 값 색. 오류는 danger. |
+| `span` | `number` |  | 차지할 칸 수. |
+
+### DescriptionSection
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `title` (필수) | `ReactNode` |  | 오버라인 제목("입력"). |
+| `children` (필수) | `ReactNode` |  | 본문(body-sm, secondary). |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 배포 상세 (soft + 섹션)
+
+variant="soft"는 회색 패널 안의 3칸 격자. 아래 DescriptionSection으로 입력 · 결과를 붙여요. tone="danger"로 "1 오류"처럼 값 색을 바꿔요.
+
+```tsx
+import { Badge, Stack, Card, CardBody, CardHeader, DescriptionList, DescriptionSection } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card variant="raised" style={{ width: '100%', maxWidth: 400 }}>
+      <CardHeader title="결제 페이지 배포" description="프로덕션 · 이도현" actions={<Badge tone="success">완료</Badge>} />
+      <CardBody>
+        <Stack gap={4}>
+          <DescriptionList
+            variant="soft"
+            columns={3}
+            aria-label="배포 지표"
+            items={[
+              { label: '소요 시간', value: '37초' },
+              { label: '시작', value: '+11초' },
+              { label: '비용', value: '₩1,200' },
+              { label: '변경 줄', value: '9.8k' },
+              { label: '테스트', value: '412' },
+              { label: '오류', value: '1', tone: 'danger' },
+            ]}
+          />
+          <DescriptionSection title="입력">요금제 세 가지의 결제 문구를 새로 반영</DescriptionSection>
+          <DescriptionSection title="결과">무료 · 프로 · 팀 문구 반영, 쿠폰 처리 테스트 1건 재시도</DescriptionSection>
+        </Stack>
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 결제 정보 (옅은 라벨)
+
+labelStyle="muted"는 대문자 느낌 없이 조용한 캡션 라벨, size="sm"은 14px 값이에요. 값 자리에는 MaskedText · Highlight 같은 어떤 요소든 넣을 수 있어요.
+
+```tsx
+import { MaskedText, DescriptionList } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <DescriptionList
+      labelStyle="muted"
+      size="sm"
+      columns="repeat(3, max-content)"
+      gap={8}
+      aria-label="송금 정보"
+      items={[
+        { label: '금액', value: '₩12,480,000' },
+        { label: '지급일', value: '10월 24일' },
+        { label: '계좌', value: <MaskedText label="계좌" value="110-482-301193" visibleEnd={4} visibleStart={3} /> },
+      ]}
+    />
+  )
+}
+```
+
+### 상세 정보 (앞 아이콘)
+
+item마다 icon을 주면 라벨 앞에 옅은 16px 아이콘이 붙어요(라벨과 같은 색, 라벨이 길어져도 찌그러지지 않음). 값은 행 오른쪽 끝에 맞춰요.
+
+```tsx
+import { Banknote, Hash, User, Users } from 'lucide-react'
+import { Avatar, Inline, Card, CardBody, CardHeader, DescriptionList } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card padding="sm" style={{ width: '100%', maxWidth: 340 }}>
+      <CardHeader title="상세 정보" />
+      <CardBody>
+        <DescriptionList
+          layout="inline"
+          labelStyle="muted"
+          aria-label="상세 정보"
+          items={[
+            {
+              label: '요청자',
+              icon: <User />,
+              value: (
+                <Inline gap={2} justify="end" wrap={false}>
+                  <Avatar name="김민지" size={20} />
+                  김민지
+                </Inline>
+              ),
+            },
+            { label: '담당 팀', icon: <Users />, value: '재무기획팀' },
+            { label: '처리 건수', icon: <Hash />, value: '12건' },
+            { label: '비용', icon: <Banknote />, value: '₩42,000' },
+          ]}
+        />
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### 승인 카드 (회색 패널 + 왼쪽 정렬)
+
+align="start"면 값이 가장 긴 라벨 바로 뒤 한 열에 줄지어 서요. variant="soft"와 함께 카드 안의 옅은 회색 패널로 받는 사람 · 제목 · 첨부를 보여 줘요.
+
+```tsx
+import { Mail } from 'lucide-react'
+import { Button, IconTile, Card, CardBody, CardFooter, CardHeader, DescriptionItem, DescriptionList, FileChip, toast } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card padding="sm" style={{ width: '100%', maxWidth: 400 }}>
+      <CardHeader
+        icon={
+          <IconTile>
+            <Mail />
+          </IconTile>
+        }
+        title="메일 발송 승인"
+        description="계약 변경 안내를 보내기 전에 확인해 주세요."
+      />
+      <CardBody>
+        <DescriptionList layout="inline" align="start" variant="soft" labelStyle="muted" size="sm" aria-label="보낼 메일">
+          <DescriptionItem label="받는 사람">박서준 (한빛물류)</DescriptionItem>
+          <DescriptionItem label="제목">공급 계약 제3조 변경 안내</DescriptionItem>
+          <DescriptionItem label="첨부">
+            <FileChip name="공급계약_변경안_v2.pdf" size={182_000} icon="clip" variant="ghost" onClick={() => toast('공급계약_변경안_v2.pdf 미리보기를 열었어요')} />
+          </DescriptionItem>
+        </DescriptionList>
+      </CardBody>
+      <CardFooter>
+        <Button size="sm" variant="secondary" onClick={() => toast('발송을 거절했어요')}>
+          거절
+        </Button>
+        <Button size="sm" variant="primary" onClick={() => toast.success('메일을 보냈어요')}>
+          보내기
+        </Button>
+      </CardFooter>
+    </Card>
+  )
+}
+```
+
+### 한 줄 행
+
+layout="inline": 라벨 왼쪽 · 값 오른쪽. 영수증 · 요약 카드처럼 좁은 곳에 써요. 행 사이는 선 없이 간격이에요.
+
+```tsx
+import { Card, CardBody, DescriptionList } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Card style={{ width: '100%', maxWidth: 320 }}>
+      <CardBody>
+        <DescriptionList
+          layout="inline"
+          labelStyle="muted"
+          aria-label="청구서 INV-2207"
+          items={[
+            { label: '청구서', value: 'INV-2207' },
+            { label: '거래처', value: '한빛물류' },
+            { label: '공급가액', value: '₩11,345,455' },
+            { label: '부가세', value: '₩1,134,545' },
+            { label: '미납', value: '1건', tone: 'danger' },
+          ]}
+        />
+      </CardBody>
+    </Card>
+  )
+}
+```
+
+### children으로
+
+items 대신 <DescriptionItem>을 직접 넣어요. span으로 여러 칸을 차지하고, minItemWidth면 폭에 맞춰 칸 수가 바뀌어요.
+
+```tsx
+import { Avatar, Inline, Text, DescriptionItem, DescriptionList } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <DescriptionList minItemWidth={140} size="sm" aria-label="계정 정보" style={{ width: '100%' }}>
+      <DescriptionItem label="담당자">
+        <Inline gap={2} wrap={false}>
+          <Avatar name="김민지" size={20} />
+          김민지
+        </Inline>
+      </DescriptionItem>
+      <DescriptionItem label="요금제">팀 · 연간</DescriptionItem>
+      <DescriptionItem label="다음 결제">11월 1일</DescriptionItem>
+      <DescriptionItem label="메모" span={2}>
+        <Text variant="body-sm" tone="secondary">
+          이도현 님이 10월 25일에 좌석 3개를 추가했어요.
+        </Text>
+      </DescriptionItem>
+    </DescriptionList>
+  )
+}
+```