@ceed/ads 1.25.1-next.3 → 1.27.0

package/dist/components/data-display/Typography.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-Typography 컴포넌트는 텍스트를 표시하기 위한 핵심 컴포넌트입니다. Joy UI의 Typography를 기반으로 하며, 다양한 텍스트 레벨과 스타일을 제공합니다. 제목, 본문, 라벨 등 모든 텍스트 요소에 일관된 타이포그래피를 적용할 수 있습니다.
+The Typography component is a core component for displaying text. It is based on Joy UI Typography and provides a variety of text levels and styles. You can apply consistent typography across all text elements such as headings, body text, and labels.
 
 ```tsx
 <Typography children="Typography" />
@@ -21,10 +21,10 @@ import { Typography } from '@ceed/ads';
 function MyComponent() {
   return (
     <div>
-      <Typography level="h1">메인 제목</Typography>
-      <Typography level="body-md">본문 텍스트입니다.</Typography>
+      <Typography level="h1">Main Heading</Typography>
+      <Typography level="body-md">This is body text.</Typography>
       <Typography level="body-sm" color="neutral">
-        보조 설명 텍스트입니다.
+        This is supporting description text.
       </Typography>
     </div>
   );
@@ -33,20 +33,110 @@ function MyComponent() {
 
 ## Typography Levels
 
+### Overview
+
+Typography levels are divided into three groups: **Headings**, **Titles**, and **Body**. The default level is `body-md`.
+
+- **Headings** (`h1`–`h4`): Used for page and section headings. Uses the display font family (Inter).
+- **Titles** (`title-lg`, `title-md`, `title-sm`): Used for UI labels, card titles, and emphasized text. Uses the body font family (Inter).
+- **Body** (`body-lg`, `body-md`, `body-sm`, `body-xs`): Used for readable content and descriptions. Uses the body font family (Inter).
+
+```tsx
+<>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h1">h1</Typography>
+    <Typography {...args} level="h1" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h2">h2</Typography>
+    <Typography {...args} level="h2" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h3">h3</Typography>
+    <Typography {...args} level="h3" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="h4">h4</Typography>
+    <Typography {...args} level="h4" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-lg">title-lg</Typography>
+    <Typography {...args} level="title-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-md">title-md</Typography>
+    <Typography {...args} level="title-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="title-sm">title-sm</Typography>
+    <Typography {...args} level="title-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-lg">body-lg</Typography>
+    <Typography {...args} level="body-lg" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-md">body-md</Typography>
+    <Typography {...args} level="body-md" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-sm">body-sm</Typography>
+    <Typography {...args} level="body-sm" />
+  </Stack>
+  <Stack direction="row" spacing={2}>
+    <Typography level="body-xs">body-xs</Typography>
+    <Typography {...args} level="body-xs" />
+  </Stack>
+</>
+```
+
+### Style Reference
+
+| Level    | Font Family     | Font Size       | Font Weight    | Line Height | Letter Spacing | Default Color  | HTML Tag |
+| -------- | --------------- | --------------- | -------------- | ----------- | -------------- | -------------- | -------- |
+| h1       | display (Inter) | 2.25rem (36px)  | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h1>`   |
+| h2       | display (Inter) | 1.875rem (30px) | 700 (Bold)     | 1.333       | -0.025em       | text.primary   | `<h2>`   |
+| h3       | display (Inter) | 1.5rem (24px)   | 600 (SemiBold) | 1.333       | -0.025em       | text.primary   | `<h3>`   |
+| h4       | display (Inter) | 1.25rem (20px)  | 600 (SemiBold) | 1.5         | -0.025em       | text.primary   | `<h4>`   |
+| title-lg | body (Inter)    | 1.125rem (18px) | 600 (SemiBold) | 1.333       | -              | text.primary   | `<p>`    |
+| title-md | body (Inter)    | 1rem (16px)     | 500 (Medium)   | 1.5         | -              | text.primary   | `<p>`    |
+| title-sm | body (Inter)    | 0.875rem (14px) | 500 (Medium)   | 1.429       | -              | text.primary   | `<p>`    |
+| body-lg  | body (Inter)    | 1.125rem (18px) | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-md  | body (Inter)    | 1rem (16px)     | inherit        | 1.5         | -              | text.secondary | `<p>`    |
+| body-sm  | body (Inter)    | 0.875rem (14px) | inherit        | 1.5         | -              | text.tertiary  | `<p>`    |
+| body-xs  | body (Inter)    | 0.75rem (12px)  | 500 (Medium)   | 1.5         | -              | text.tertiary  | `<span>` |
+
 ### Headings
 
-제목을 위한 레벨들입니다. 페이지 구조를 명확하게 나타내는 데 사용됩니다.
+Heading levels define page structure and hierarchy. They use the display font family with heavier weights for visual prominence.
+
+```tsx
+<>
+  <Typography level="h1">h1 - Main page heading</Typography>
+  <Typography level="h2">h2 - Section heading</Typography>
+  <Typography level="h3">h3 - Subsection heading</Typography>
+  <Typography level="h4">h4 - Detail heading</Typography>
+</>
+```
 
 ```tsx
-<Typography level="h1">H1 - 페이지 메인 제목</Typography>
-<Typography level="h2">H2 - 섹션 제목</Typography>
-<Typography level="h3">H3 - 하위 섹션 제목</Typography>
-<Typography level="h4">H4 - 세부 제목</Typography>
+<Typography level="h1">H1 - Main page heading</Typography>
+<Typography level="h2">H2 - Section heading</Typography>
+<Typography level="h3">H3 - Subsection heading</Typography>
+<Typography level="h4">H4 - Detail heading</Typography>
 ```
 
 ### Titles
 
-중요한 제목이나 강조할 텍스트에 사용됩니다.
+Title levels are used for UI labels, card titles, and other emphasized text that is not a document heading.
+
+```tsx
+<>
+  <Typography level="title-lg">title-lg - Large title</Typography>
+  <Typography level="title-md">title-md - Medium title</Typography>
+  <Typography level="title-sm">title-sm - Small title</Typography>
+</>
+```
 
 ```tsx
 <Typography level="title-lg">Large Title</Typography>
@@ -56,13 +146,210 @@ function MyComponent() {
 
 ### Body Text
 
-본문 텍스트를 위한 레벨들입니다. 대부분의 읽기 내용에 사용됩니다.
+Body levels are used for readable content and descriptions. The default level `body-md` is suitable for most body text. Use `body-xs` sparingly for auxiliary information like timestamps or counters.
+
+```tsx
+<>
+  <Typography level="body-lg">body-lg - Large body text</Typography>
+  <Typography level="body-md">body-md - Regular body text</Typography>
+  <Typography level="body-sm">body-sm - Small body text</Typography>
+  <Typography level="body-xs">body-xs - Extra small text</Typography>
+</>
+```
+
+```tsx
+<Typography level="body-lg">Large body text</Typography>
+<Typography level="body-md">Regular body text</Typography>
+<Typography level="body-sm">Small body text</Typography>
+<Typography level="body-xs">Extra small text</Typography>
+```
+
+## Design Token Reference
+
+### Font Size Scale
+
+| Token | Value           |
+| ----- | --------------- |
+| xs    | 0.75rem (12px)  |
+| sm    | 0.875rem (14px) |
+| md    | 1rem (16px)     |
+| lg    | 1.125rem (18px) |
+| xl    | 1.25rem (20px)  |
+| xl2   | 1.5rem (24px)   |
+| xl3   | 1.875rem (30px) |
+| xl4   | 2.25rem (36px)  |
+
+### Font Weight Scale
+
+| Token | Value          |
+| ----- | -------------- |
+| sm    | 300 (Light)    |
+| md    | 500 (Medium)   |
+| lg    | 600 (SemiBold) |
+| xl    | 700 (Bold)     |
+
+### Line Height Scale
+
+| Token | Value |
+| ----- | ----- |
+| xs    | 1.333 |
+| sm    | 1.429 |
+| md    | 1.5   |
+| lg    | 1.556 |
+| xl    | 1.667 |
+
+### Font Families
+
+- **body**: `"Inter"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **display**: `"Inter"`, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, Helvetica, Arial, sans-serif
+- **code**: `"Source Code Pro"`, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace
+
+## Colors
+
+Typography supports five semantic colors via the `color` prop. Use `textColor` to apply any palette color directly.
+
+```tsx
+<>
+  <Typography color="primary">Primary color</Typography>
+  <Typography color="neutral">Neutral color</Typography>
+  <Typography color="danger">Danger color</Typography>
+  <Typography color="success">Success color</Typography>
+  <Typography color="warning">Warning color</Typography>
+</>
+```
+
+```tsx
+<Typography color="primary">Primary color</Typography>
+<Typography color="neutral">Neutral color</Typography>
+<Typography color="danger">Danger color</Typography>
+<Typography color="success">Success color</Typography>
+<Typography color="warning">Warning color</Typography>
+
+{/* Use textColor for specific palette values */}
+<Typography textColor="neutral.600">Custom palette color</Typography>
+```
+
+## Component Prop
+
+Use the `component` prop to render Typography as a different HTML element or React component. Each level has a default HTML tag mapping shown below.
+
+```tsx
+<>
+  <Typography level="h1" component="h2">
+    h1 style rendered as h2 tag
+  </Typography>
+  <Typography level="body-md" component="span">
+    body-md rendered as span
+  </Typography>
+  <Typography level="title-md" component="label">
+    title-md rendered as label
+  </Typography>
+</>
+```
+
+```tsx
+<Typography level="h1" component="h2">
+  h1 style rendered as an h2 tag
+</Typography>
+
+<Typography level="body-md" component="span">
+  Inline text
+</Typography>
+
+<Typography level="title-md" component="label">
+  Rendered as a label element
+</Typography>
+```
+
+**Default HTML tag mapping:**
+
+| Level    | Default HTML Tag |
+| -------- | ---------------- |
+| h1       | `<h1>`           |
+| h2       | `<h2>`           |
+| h3       | `<h3>`           |
+| h4       | `<h4>`           |
+| title-lg | `<p>`            |
+| title-md | `<p>`            |
+| title-sm | `<p>`            |
+| body-lg  | `<p>`            |
+| body-md  | `<p>`            |
+| body-sm  | `<p>`            |
+| body-xs  | `<span>`         |
+
+## Decorators
+
+Use `startDecorator` and `endDecorator` to add icons or other elements before or after the text.
+
+```tsx
+<>
+  <Typography startDecorator={<InfoOutlined />}>
+    Text with start decorator
+  </Typography>
+  <Typography endDecorator={<ArrowForward />}>
+    Text with end decorator
+  </Typography>
+  <Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+    Text with both decorators
+  </Typography>
+</>
+```
+
+```tsx
+import InfoOutlined from '@mui/icons-material/InfoOutlined';
+import ArrowForward from '@mui/icons-material/ArrowForward';
+
+<Typography startDecorator={<InfoOutlined />}>
+  Text with start decorator
+</Typography>
+
+<Typography endDecorator={<ArrowForward />}>
+  Text with end decorator
+</Typography>
+
+<Typography startDecorator={<InfoOutlined />} endDecorator={<ArrowForward />}>
+  Text with both decorators
+</Typography>
+```
+
+## Text Overflow (noWrap)
+
+Use the `noWrap` prop to truncate overflowing text with an ellipsis. Pair it with a `maxWidth` to constrain the text width.
+
+```tsx
+<Typography noWrap sx={{
+  maxWidth: 200
+}}>
+This is a long text that will be truncated with an ellipsis when it
+exceeds the maximum width of the container.
+</Typography>
+```
 
 ```tsx
-<Typography level="body-lg">큰 본문 텍스트</Typography>
-<Typography level="body-md">일반 본문 텍스트</Typography>
-<Typography level="body-sm">작은 본문 텍스트</Typography>
-<Typography level="body-xs">매우 작은 텍스트</Typography>
+<Typography noWrap sx={{ maxWidth: 200 }}>
+  This is a long text that will be truncated with an ellipsis when it exceeds
+  the maximum width.
+</Typography>
+```
+
+## Responsive Typography
+
+You can pass a responsive object to the `level` prop, or use `sx` to set responsive font sizes.
+
+```tsx
+{/* Responsive level */}
+<Typography level={{ xs: 'h3', sm: 'h2', md: 'h1' }}>
+  Responsive Heading
+</Typography>
+
+{/* Responsive font size via sx */}
+<Typography
+  sx={{
+    fontSize: { xs: '1rem', sm: '1.25rem', md: '1.5rem' },
+  }}
+>
+  Responsive text
+</Typography>
 ```
 
 ## Common Use Cases
@@ -74,24 +361,24 @@ function ArticlePage() {
   return (
     <article>
       <Typography level="h1" sx={{ mb: 2 }}>
-        기사 제목
+        Article Title
       </Typography>
 
       <Typography level="body-sm" color="neutral" sx={{ mb: 3 }}>
-        2024년 1월 15일 · 김철수 작성
+        January 15, 2024 · Written by John Doe
       </Typography>
 
       <Typography level="body-md" sx={{ mb: 2 }}>
-        기사의 본문 내용이 여기에 들어갑니다. 이 텍스트는 읽기 쉬운
-        크기와 줄 간격을 가지고 있습니다.
+        The main content of the article goes here. This text uses a readable size
+        and line spacing.
       </Typography>
 
       <Typography level="h2" sx={{ mt: 4, mb: 2 }}>
-        섹션 제목
+        Section Title
       </Typography>
 
       <Typography level="body-md">
-        섹션의 내용이 계속됩니다.
+        The section content continues here.
       </Typography>
     </article>
   );
@@ -104,15 +391,15 @@ function ArticlePage() {
 <Card>
   <CardContent>
     <Typography level="title-md" sx={{ mb: 1 }}>
-      제품명
+      Product Name
     </Typography>
 
     <Typography level="body-sm" color="neutral" sx={{ mb: 2 }}>
-      카테고리: 전자제품
+      Category: Electronics
     </Typography>
 
     <Typography level="body-md" sx={{ mb: 2 }}>
-      제품에 대한 상세 설명이 여기에 들어갑니다.
+      A detailed description of the product goes here.
     </Typography>
 
     <Typography level="title-lg" color="primary">
@@ -128,41 +415,58 @@ function ArticlePage() {
 <Stack spacing={2}>
   <FormControl>
     <Typography level="title-sm" component="label">
-      사용자 이름
+      Username
     </Typography>
-    <Input placeholder="이름을 입력하세요" />
+    <Input placeholder="Enter your name" />
     <Typography level="body-xs" color="neutral">
-      실명으로 입력해 주세요.
+      Please enter your real name.
     </Typography>
   </FormControl>
 
   <FormControl error>
     <Typography level="title-sm" component="label">
-      이메일 주소
+      Email Address
     </Typography>
     <Input placeholder="email@example.com" />
     <Typography level="body-xs" color="danger">
-      올바른 이메일 형식이 아닙니다.
+      The email format is invalid.
     </Typography>
   </FormControl>
 </Stack>
 ```
 
+> 💡 **Tip: Use built-in form props instead**
+>
+> Input, Select, Textarea, DatePicker 등 Input 계열 컴포넌트는 `label`, `helperText` prop을 자체적으로 지원합니다.
+> Form을 구성할 때는 Typography로 직접 label/helperText를 만드는 것보다 각 컴포넌트의 내장 prop을 사용하는 것이 권장됩니다.
+>
+> ```tsx
+> // ✅ Recommended: 컴포넌트 내장 prop 사용
+> <Input label="Username" helperText="Please enter your real name." />
+>
+> // ❌ Not recommended: Typography로 직접 구성
+> <FormControl>
+>   <Typography level="title-sm" component="label">Username</Typography>
+>   <Input placeholder="Enter your name" />
+>   <Typography level="body-xs" color="neutral">Please enter your real name.</Typography>
+> </FormControl>
+> ```
+
 ### Status and Indicators
 
 ```tsx
 <Stack spacing={2}>
   <Box>
-    <Typography level="body-md">서버 상태:</Typography>
+    <Typography level="body-md">Server Status:</Typography>
     <Typography level="body-md" color="success">
-      정상 운영 중
+      Operating Normally
     </Typography>
   </Box>
 
   <Box>
-    <Typography level="body-md">마지막 업데이트:</Typography>
+    <Typography level="body-md">Last Updated:</Typography>
     <Typography level="body-sm" color="neutral">
-      2분 전
+      2 minutes ago
     </Typography>
   </Box>
 </Stack>
@@ -172,7 +476,7 @@ function ArticlePage() {
 
 ```tsx
 <Stack spacing={1}>
-  <Typography level="title-md">할 일 목록</Typography>
+  <Typography level="title-md">Todo List</Typography>
 
   {todoItems.map((item) => (
     <Box key={item.id} sx={{ pl: 2 }}>
@@ -180,7 +484,7 @@ function ArticlePage() {
         level="body-md"
         sx={{
           textDecoration: item.completed ? 'line-through' : 'none',
-          color: item.completed ? 'neutral.500' : 'text.primary'
+          color: item.completed ? 'neutral.500' : 'text.primary',
         }}
       >
         {item.text}
@@ -193,79 +497,41 @@ function ArticlePage() {
 </Stack>
 ```
 
-## Colors
+## Best Practices
 
-Typography는 다양한 색상을 지원합니다:
+1. **Semantic Structure**: Use heading levels in order (`h1` → `h2` → `h3`) to create a clear document hierarchy.
 
 ```tsx
-<Stack spacing={1}>
-  <Typography color="primary">Primary 색상</Typography>
-  <Typography color="neutral">Neutral 색상</Typography>
-  <Typography color="danger">Danger 색상</Typography>
-  <Typography color="success">Success 색상</Typography>
-  <Typography color="warning">Warning 색상</Typography>
-</Stack>
+// ✅ Correct order
+<Typography level="h1">Main heading</Typography>
+<Typography level="h2">Section heading</Typography>
+<Typography level="h3">Subsection</Typography>
+
+// ❌ Incorrect order — skipping h2
+<Typography level="h1">Main heading</Typography>
+<Typography level="h3">Section heading</Typography>
 ```
 
-## Component Prop
+2. **Consistency**: Use the same level for text serving the same purpose across the application.
 
-다른 HTML 요소나 React 컴포넌트로 렌더링할 수 있습니다:
+3. **Readability**: Provide proper line spacing and paragraph separation for body text.
 
-```tsx
-<Typography level="h1" component="h2">
-  h2 태그로 렌더링되는 h1 스타일
-</Typography>
+4. **Color Contrast**: Maintain sufficient color contrast to ensure accessibility.
 
-<Typography level="body-md" component="span">
-  인라인 텍스트
-</Typography>
+5. **Level Selection Guide**:
+   - **Headings** (`h1`–`h4`): Use for document structure and section titles.
+   - **Titles** (`title-lg/md/sm`): Use for UI labels, card headers, and emphasized text.
+   - **Body** (`body-lg/md/sm/xs`): Use for content, descriptions, and supporting text.
 
-<Typography level="title-md" component={Link} href="/page">
-  링크 컴포넌트로 렌더링
-</Typography>
-```
+6. **Avoid inline style overrides**: Prefer the `level` prop over `sx` for font sizing. Use `level` for consistent design tokens.
 
-## Responsive Typography
+7. **Use `textColor` for custom colors**: When the five semantic colors are insufficient, use `textColor` to apply any palette value directly.
 
-반응형 레벨을 사용할 수 있습니다:
-
-```tsx
-<Typography
-  level={{ xs: 'h3', sm: 'h2', md: 'h1' }}
-  sx={{
-    fontSize: { xs: '1.5rem', sm: '2rem', md: '2.5rem' }
-  }}
->
-  반응형 제목
-</Typography>
-```
-
-## Best Practices
-
-1. **의미적 구조**: 제목 레벨을 순서대로 사용하여 명확한 문서 구조를 만드세요.
-
-```tsx
-// ✅ 올바른 순서
-<Typography level="h1">메인 제목</Typography>
-<Typography level="h2">섹션 제목</Typography>
-<Typography level="h3">하위 섹션</Typography>
-
-// ❌ 잘못된 순서
-<Typography level="h1">메인 제목</Typography>
-<Typography level="h3">섹션 제목</Typography>
-```
-
-2. **일관성**: 같은 용도의 텍스트에는 같은 레벨을 사용하세요.
-
-3. **가독성**: 본문 텍스트에는 적절한 줄 간격과 문단 구분을 제공하세요.
-
-4. **색상 대비**: 충분한 색상 대비를 유지하여 접근성을 보장하세요.
+8. **Use `body-xs` sparingly**: Reserve `body-xs` (12px) for auxiliary information such as timestamps, counters, and footnotes — not for primary content.
 
 ## Accessibility
 
-- 적절한 HTML 시맨틱 태그 사용
-- 스크린 리더 지원
-- 키보드 탐색 가능 (링크나 버튼으로 사용될 때)
-- 충분한 색상 대비
-
-Typography는 사용자 인터페이스에서 정보를 효과적으로 전달하고 시각적 계층 구조를 만드는 데 핵심적인 역할을 합니다. 적절한 레벨과 스타일을 선택하여 읽기 쉽고 접근 가능한 콘텐츠를 만들 수 있습니다.
+- Use sequential heading levels (`h1` → `h2` → `h3`). Do not skip levels.
+- Use the `component` prop to separate visual style from semantic meaning (e.g., `level="h1" component="h2"` when you need h1 styling but h2 semantics).
+- Avoid using `body-xs` (12px) for essential content — the small size may be difficult to read.
+- Maintain sufficient color contrast ratios (WCAG AA: 4.5:1 for normal text, 3:1 for large text).