@iamfiro/design 0.0.0-stage → 0.1.0

package/agents/typography/AGENTS.md

@@ -0,0 +1,396 @@
+# Typography
+
+> 파운데이션 · `@iamfiro/design` · 직접 만들지 말고 이 컴포넌트를 쓴다.
+
+글자는 역할(role)로 골라요. tokens.css의 --type-* 토큰이 역할마다 크기·줄 높이·굵기·자간을 정하고, Text · Heading이 그 값을 그대로 써요. 컨테이너에 data-density를 붙이면 그 안의 본문·라벨·헤딩이 함께 촘촘해지거나 여유로워져요. 마크다운처럼 이미 만들어진 HTML은 Prose로 감싸요.
+
+```tsx
+import { Heading, Prose, Text, type TextVariant } from '@iamfiro/design'
+```
+
+## API
+
+### Text
+
+나머지 props는 렌더되는 요소로 전달돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `variant` | `TextVariant` | `'body-md'` | 역할. display-lg/md/sm · heading-xl/lg/md/sm/xs · body-lg/md/sm/xs · label-lg/md/sm/xs · caption · overline · number-xl/lg/md/sm · code. |
+| `as` | `ElementType` |  | 렌더할 요소. 생략하면 역할에 맞게(display → h1, heading → h2, body → p, code → code, 나머지 → span). |
+| `tone` | `TextTone` | `'default'` | 'default' \| 'secondary' \| 'tertiary' \| 'disabled' \| 'accent' \| 'success' \| 'warning' \| 'danger' \| 'inverse' \| 'inherit' |
+| `weight` | `'regular' \| 'medium' \| 'semibold' \| 'bold'` |  | 역할의 굵기를 덮어써요. |
+| `align` | `'start' \| 'center' \| 'end'` |  | 정렬. |
+| `truncate` | `boolean` |  | 한 줄 말줄임. |
+| `lineClamp` | `number` |  | N줄까지 보여주고 말줄임. |
+| `numeric` | `boolean` |  | 고정폭 숫자(tabular-nums). number-* 역할은 항상 켜져 있어요. |
+| `wrap` | `'balance' \| 'pretty'` |  | balance는 줄 길이를 고르게(제목), pretty는 마지막 줄에 단어 하나만 남지 않게(본문). |
+
+### Heading
+
+Text의 나머지 props(tone, weight, align, truncate …)를 모두 받아요. as · variant는 받지 않아요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `level` | `1 \| 2 \| 3 \| 4 \| 5 \| 6` | `2` | 문서 구조 레벨(h1–h6). 1 → heading-xl, 2 → heading-lg, 3 → heading-md, 4 → heading-sm, 5·6 → heading-xs. |
+| `size` | `TextVariant` |  | 레벨과 상관없이 보이는 크기. 예: level={2} size="display-sm". |
+| `wrap` | `'balance' \| 'pretty'` | `'balance'` | 줄 나눔 방식. |
+
+### Prose
+
+h1–h4, p, ul/ol, blockquote, code, pre, table, hr, a를 정돈해요. 나머지 props는 div로 전달돼요.
+
+| prop | 타입 | 기본값 | 설명 |
+| --- | --- | --- | --- |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | 블록 전체 글자 크기. 제목과 간격도 함께 커지고 작아져요. |
+
+## 예제
+
+예제를 감싼 `style={{ ... }}` div는 미리보기 배치용이다. 실제 화면 배치는 `Stack` · `Inline` · `Grid`로 한다.
+
+### 타입 스케일
+
+디스플레이 · 헤딩 · 본문 · 라벨 · 작은 글씨 · 숫자 · 코드. 디스플레이는 화면 폭에 따라 유동적으로 커져요.
+
+```tsx
+import { Text, type TextVariant } from '@iamfiro/design'
+
+const SCALE: Array<{ group: string; roles: Array<[TextVariant, string]> }> = [
+  {
+    group: '디스플레이',
+    roles: [
+      ['display-lg', '팀의 모든 일을 한곳에서'],
+      ['display-md', '이번 달 매출 12% 성장'],
+      ['display-sm', '아직 프로젝트가 없어요'],
+    ],
+  },
+  {
+    group: '헤딩',
+    roles: [
+      ['heading-xl', '프로젝트 설정'],
+      ['heading-lg', '결제 및 구독'],
+      ['heading-md', '알림 채널'],
+      ['heading-sm', '최근 활동'],
+      ['heading-xs', '팀원 6명'],
+    ],
+  },
+  {
+    group: '본문',
+    roles: [
+      ['body-lg', '변경사항은 저장하는 즉시 모든 팀원에게 반영돼요.'],
+      ['body-md', '변경사항은 저장하는 즉시 모든 팀원에게 반영돼요.'],
+      ['body-sm', '변경사항은 저장하는 즉시 모든 팀원에게 반영돼요.'],
+      ['body-xs', '변경사항은 저장하는 즉시 모든 팀원에게 반영돼요.'],
+    ],
+  },
+  {
+    group: '라벨',
+    roles: [
+      ['label-lg', '변경사항 저장'],
+      ['label-md', '팀원 초대'],
+      ['label-sm', '필터 초기화'],
+      ['label-xs', '베타'],
+    ],
+  },
+  {
+    group: '작은 글씨 · 숫자 · 코드',
+    roles: [
+      ['caption', '마지막 수정 2분 전 · 김민지'],
+      ['overline', 'Workspace'],
+      ['number-xl', '₩12,480,000'],
+      ['number-lg', '98.6%'],
+      ['number-md', '1,284건'],
+      ['number-sm', '00:42:17'],
+      ['code', 'npm i @lumen/ui'],
+    ],
+  },
+]
+
+export default function Example() {
+  return (
+    <div style={{ width: '100%', display: 'grid', gap: 36 }}>
+      {SCALE.map((group) => (
+        <section key={group.group} style={{ display: 'grid', gap: 14 }}>
+          <Text as="h4" variant="overline" tone="tertiary">
+            {group.group}
+          </Text>
+          {group.roles.map(([variant, sample]) => (
+            <div key={variant} style={{ display: 'grid', gridTemplateColumns: '96px minmax(0, 1fr)', alignItems: 'baseline', gap: 16 }}>
+              <Text as="code" variant="label-xs" tone="tertiary">
+                {variant}
+              </Text>
+              <Text as="div" variant={variant} truncate>
+                {sample}
+              </Text>
+            </div>
+          ))}
+        </section>
+      ))}
+    </div>
+  )
+}
+```
+
+### 톤
+
+글자 색은 tone으로. 진한 정도(default · secondary · tertiary · disabled)와 상태색, 어두운 배경용 inverse가 있어요.
+
+```tsx
+import { Text, type TextTone } from '@iamfiro/design'
+
+const TONES: Array<[TextTone, string]> = [
+  ['default', '본문과 제목'],
+  ['secondary', '보조 설명'],
+  ['tertiary', '메타 정보 · 날짜'],
+  ['disabled', '사용할 수 없음'],
+  ['accent', '링크 · 강조'],
+  ['success', '결제 완료'],
+  ['warning', '검토 필요'],
+  ['danger', '연결 실패'],
+]
+
+export default function Example() {
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(4, 140px)', gap: '20px 24px' }}>
+      {TONES.map(([tone, sample]) => (
+        <div key={tone} style={{ display: 'grid', gap: 4 }}>
+          <Text variant="label-md" tone={tone}>
+            {sample}
+          </Text>
+          <Text as="code" variant="caption" tone="tertiary">
+            {tone}
+          </Text>
+        </div>
+      ))}
+    </div>
+  )
+}
+```
+
+### 말줄임
+
+truncate는 한 줄, lineClamp는 N줄에서 말줄임표로 잘라요. 부모에 폭이 있어야 해요.
+
+```tsx
+import { Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 340, display: 'grid', gap: 24 }}>
+      <div style={{ display: 'grid', gap: 4 }}>
+        <Text variant="caption" tone="tertiary">
+          truncate
+        </Text>
+        <Text variant="label-md" truncate>
+          2026년 3분기 이사회 보고서 최종본 — 재무, 인사, 제품 로드맵, 다음 분기 채용 계획 포함.pdf
+        </Text>
+      </div>
+      <div style={{ display: 'grid', gap: 4 }}>
+        <Text variant="caption" tone="tertiary">
+          lineClamp=2
+        </Text>
+        <Text tone="secondary" lineClamp={2}>
+          이번 업데이트로 대시보드 로딩 속도가 두 배 빨라졌고, 모든 리포트를 한 번의 클릭으로 CSV로 내보낼 수 있어요. 권한 설정도 팀 단위로
+          세분화되어 관리자가 프로젝트별로 접근 범위를 정할 수 있어요.
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 숫자 정렬
+
+number-* 역할은 자동으로, 다른 역할은 numeric을 켜면 고정폭 숫자를 써요. 값이 바뀌어도 폭이 흔들리지 않아요.
+
+```tsx
+import { useEffect, useState } from 'react'
+import { Text } from '@iamfiro/design'
+
+export default function Example() {
+  const [visitors, setVisitors] = useState(18204)
+
+  useEffect(() => {
+    const id = window.setInterval(() => setVisitors((v) => v + Math.floor(Math.random() * 37)), 150)
+    return () => window.clearInterval(id)
+  }, [])
+
+  return (
+    <div style={{ display: 'grid', gridTemplateColumns: 'repeat(2, 200px)', gap: 32 }}>
+      <div style={{ display: 'grid', gap: 4 }}>
+        <Text variant="label-sm" tone="secondary">
+          오늘 방문자
+        </Text>
+        <Text variant="number-lg">{visitors.toLocaleString('ko-KR')}</Text>
+        <Text variant="caption" tone="tertiary">
+          number-lg · 자동으로 고정폭
+        </Text>
+      </div>
+      <div style={{ display: 'grid', gap: 4 }}>
+        <Text variant="label-sm" tone="secondary">
+          평균 체류 시간
+        </Text>
+        <Text variant="heading-lg" numeric>
+          {(visitors / 97).toFixed(2)}초
+        </Text>
+        <Text variant="caption" tone="tertiary">
+          heading-lg + numeric
+        </Text>
+      </div>
+    </div>
+  )
+}
+```
+
+### 제목 레벨과 크기
+
+level은 문서 구조(h1–h6), size는 보이는 크기. 구조는 지키면서 모양만 바꿀 수 있어요. 줄 길이는 기본으로 균형 있게 나눠요.
+
+```tsx
+import { Heading, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <div style={{ width: 420, display: 'grid', gap: 28 }}>
+      <div style={{ display: 'grid', gap: 10 }}>
+        <Heading level={1}>프로젝트 설정</Heading>
+        <Heading level={2}>결제 및 구독</Heading>
+        <Heading level={3}>알림 채널</Heading>
+        <Heading level={4}>최근 활동</Heading>
+        <Heading level={5}>팀원 6명</Heading>
+      </div>
+      <div style={{ display: 'grid', gap: 6 }}>
+        <Text variant="caption" tone="tertiary">
+          {'level={2} size="display-sm"'}
+        </Text>
+        <Heading level={2} size="display-sm">
+          팀원이 초대를 수락하면 바로 프로젝트에 참여할 수 있어요
+        </Heading>
+      </div>
+    </div>
+  )
+}
+```
+
+### 밀도
+
+데이터가 많은 화면은 compact, 읽는 화면은 comfortable. 컨테이너 단위로 바꿔요.
+
+```tsx
+import { useState } from 'react'
+import { Heading, Text, Card, CardBody, ToggleGroup, ToggleGroupItem } from '@iamfiro/design'
+
+type Density = 'compact' | 'default' | 'comfortable'
+
+export default function Example() {
+  const [density, setDensity] = useState<Density | null>('default')
+
+  return (
+    <div style={{ width: 400, display: 'grid', gap: 20, justifyItems: 'start' }}>
+      <ToggleGroup type="single" required value={density} onValueChange={setDensity} aria-label="밀도">
+        <ToggleGroupItem value="compact">촘촘하게</ToggleGroupItem>
+        <ToggleGroupItem value="default">기본</ToggleGroupItem>
+        <ToggleGroupItem value="comfortable">여유있게</ToggleGroupItem>
+      </ToggleGroup>
+      <Card data-density={density === 'default' ? undefined : density} style={{ width: '100%' }}>
+        <CardBody>
+          <div style={{ display: 'grid', gap: 12 }}>
+            <Heading level={3}>결제 수단</Heading>
+            <Text tone="secondary">등록된 카드로 매월 1일에 자동 결제돼요. 언제든 변경할 수 있어요.</Text>
+            <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+              <Text variant="label-md">기본 카드</Text>
+              <Text variant="body-sm" tone="tertiary" numeric>
+                신한 •••• 4821
+              </Text>
+            </div>
+            <div style={{ display: 'flex', justifyContent: 'space-between' }}>
+              <Text variant="label-md">다음 결제</Text>
+              <Text variant="body-sm" tone="tertiary" numeric>
+                11월 1일 · ₩29,000
+              </Text>
+            </div>
+          </div>
+        </CardBody>
+      </Card>
+    </div>
+  )
+}
+```
+
+### 인라인 코드 칩
+
+문장 안의 명령 · 값은 Text variant="code"(<code>)로. 회색 채움 칩에 고정폭 글자가 들어가요. 문장 맨 앞 "/명령" 칩에도 그대로 써요.
+
+```tsx
+import { Stack, Text } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Stack gap={3} style={{ maxWidth: 420 }}>
+      <Text variant="body-md">
+        <Text variant="code">/수정</Text> 소개 문단을 두 문장으로 줄여 주세요.
+      </Text>
+      <Text variant="body-sm" tone="secondary">
+        설정 파일의 <Text variant="code">theme</Text> 값을 <Text variant="code">light</Text>로 바꾸면 밝은 화면으로 돌아가요.
+      </Text>
+    </Stack>
+  )
+}
+```
+
+### Prose
+
+마크다운으로 만든 문서, 변경 로그, 도움말, AI 답변 같은 HTML을 그대로 정돈해 보여줘요.
+
+```tsx
+import { Prose } from '@iamfiro/design'
+
+export default function Example() {
+  return (
+    <Prose style={{ width: '100%', maxWidth: 640 }}>
+      <h2>Lumen 2.5 업데이트</h2>
+      <p>
+        이번 버전은 <strong>대시보드 성능</strong>과 <a href="#permissions">권한 관리</a>에 집중했어요. 기존 설정은 그대로 유지돼요.
+      </p>
+      <h3>새로워진 점</h3>
+      <ul>
+        <li>대시보드 로딩이 평균 2배 빨라졌어요.</li>
+        <li>
+          모든 리포트를 <code>CSV</code>로 내보낼 수 있어요.
+        </li>
+        <li>팀 단위 권한을 지원해요.</li>
+      </ul>
+      <blockquote>업데이트 후 처음 접속하면 새 기능 안내가 한 번 표시돼요.</blockquote>
+      <pre>
+        <code>npm i @lumen/ui@2.5.0</code>
+      </pre>
+      <table>
+        <thead>
+          <tr>
+            <th>플랜</th>
+            <th>월 요금</th>
+            <th>팀원</th>
+          </tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td>스타터</td>
+            <td>₩9,000</td>
+            <td>3명</td>
+          </tr>
+          <tr>
+            <td>팀</td>
+            <td>₩29,000</td>
+            <td>20명</td>
+          </tr>
+          <tr>
+            <td>엔터프라이즈</td>
+            <td>문의</td>
+            <td>무제한</td>
+          </tr>
+        </tbody>
+      </table>
+    </Prose>
+  )
+}
+```