@ceed/ads 1.29.1 → 1.30.0-next.1

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

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-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.
+Typography 컴포넌트는 텍스트를 표시하기 위한 핵심 컴포넌트입니다. Joy UI의 Typography를 기반으로 하며, 다양한 텍스트 레벨과 스타일을 제공합니다. 제목, 본문, 라벨 등 모든 텍스트 요소에 일관된 타이포그래피를 적용할 수 있습니다.
 
 ```tsx
 <Typography children="Typography" />
@@ -21,10 +21,10 @@ import { Typography } from '@ceed/ads';
 function MyComponent() {
   return (
     <div>
-      <Typography level="h1">Main Heading</Typography>
-      <Typography level="body-md">This is body text.</Typography>
+      <Typography level="h1">메인 제목</Typography>
+      <Typography level="body-md">본문 텍스트입니다.</Typography>
       <Typography level="body-sm" color="neutral">
-        This is supporting description text.
+        보조 설명 텍스트입니다.
       </Typography>
     </div>
   );
@@ -33,110 +33,20 @@ 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 - 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>
+<Typography level="h1">H1 - 페이지 메인 제목</Typography>
+<Typography level="h2">H2 - 섹션 제목</Typography>
+<Typography level="h3">H3 - 하위 섹션 제목</Typography>
+<Typography level="h4">H4 - 세부 제목</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>
@@ -146,210 +56,13 @@ Title levels are used for UI labels, card titles, and other emphasized text that
 
 ### 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 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>
+<Typography level="body-lg">큰 본문 텍스트</Typography>
+<Typography level="body-md">일반 본문 텍스트</Typography>
+<Typography level="body-sm">작은 본문 텍스트</Typography>
+<Typography level="body-xs">매우 작은 텍스트</Typography>
 ```
 
 ## Common Use Cases
@@ -361,24 +74,24 @@ function ArticlePage() {
   return (
     <article>
       <Typography level="h1" sx={{ mb: 2 }}>
-        Article Title
+        기사 제목
       </Typography>
 
       <Typography level="body-sm" color="neutral" sx={{ mb: 3 }}>
-        January 15, 2024 · Written by John Doe
+        2024년 1월 15일 · 김철수 작성
       </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>
   );
@@ -391,15 +104,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">
@@ -415,58 +128,41 @@ function ArticlePage() {
 <Stack spacing={2}>
   <FormControl>
     <Typography level="title-sm" component="label">
-      Username
+      사용자 이름
     </Typography>
-    <Input placeholder="Enter your name" />
+    <Input placeholder="이름을 입력하세요" />
     <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">Server Status:</Typography>
+    <Typography level="body-md">서버 상태:</Typography>
     <Typography level="body-md" color="success">
-      Operating Normally
+      정상 운영 중
     </Typography>
   </Box>
 
   <Box>
-    <Typography level="body-md">Last Updated:</Typography>
+    <Typography level="body-md">마지막 업데이트:</Typography>
     <Typography level="body-sm" color="neutral">
-      2 minutes ago
+      2분 전
     </Typography>
   </Box>
 </Stack>
@@ -476,7 +172,7 @@ function ArticlePage() {
 
 ```tsx
 <Stack spacing={1}>
-  <Typography level="title-md">Todo List</Typography>
+  <Typography level="title-md">할 일 목록</Typography>
 
   {todoItems.map((item) => (
     <Box key={item.id} sx={{ pl: 2 }}>
@@ -484,7 +180,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}
@@ -497,41 +193,79 @@ function ArticlePage() {
 </Stack>
 ```
 
-## Best Practices
+## Colors
 
-1. **Semantic Structure**: Use heading levels in order (`h1` → `h2` → `h3`) to create a clear document hierarchy.
+Typography는 다양한 색상을 지원합니다:
 
 ```tsx
-// ✅ 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>
+<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>
 ```
 
-2. **Consistency**: Use the same level for text serving the same purpose across the application.
+## Component Prop
 
-3. **Readability**: Provide proper line spacing and paragraph separation for body text.
+다른 HTML 요소나 React 컴포넌트로 렌더링할 수 있습니다:
 
-4. **Color Contrast**: Maintain sufficient color contrast to ensure accessibility.
+```tsx
+<Typography level="h1" component="h2">
+  h2 태그로 렌더링되는 h1 스타일
+</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="body-md" component="span">
+  인라인 텍스트
+</Typography>
 
-6. **Avoid inline style overrides**: Prefer the `level` prop over `sx` for font sizing. Use `level` for consistent design tokens.
+<Typography level="title-md" component={Link} href="/page">
+  링크 컴포넌트로 렌더링
+</Typography>
+```
 
-7. **Use `textColor` for custom colors**: When the five semantic colors are insufficient, use `textColor` to apply any palette value directly.
+## Responsive Typography
 
-8. **Use `body-xs` sparingly**: Reserve `body-xs` (12px) for auxiliary information such as timestamps, counters, and footnotes — not for primary content.
+반응형 레벨을 사용할 수 있습니다:
+
+```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. **색상 대비**: 충분한 색상 대비를 유지하여 접근성을 보장하세요.
 
 ## Accessibility
 
-- 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).
+- 적절한 HTML 시맨틱 태그 사용
+- 스크린 리더 지원
+- 키보드 탐색 가능 (링크나 버튼으로 사용될 때)
+- 충분한 색상 대비
+
+Typography는 사용자 인터페이스에서 정보를 효과적으로 전달하고 시각적 계층 구조를 만드는 데 핵심적인 역할을 합니다. 적절한 레벨과 스타일을 선택하여 읽기 쉽고 접근 가능한 콘텐츠를 만들 수 있습니다.