@ceed/cds 1.22.2 → 1.22.4

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

@@ -2,7 +2,9 @@
 
 ## Introduction
 
-InfoSign 컴포넌트는 사용자에게 추가 정보를 제공하기 위한 툴팁 아이콘입니다. 물음표 아이콘을 클릭하거나 호버할 때 상세한 설명이나 도움말을 표시할 수 있습니다. 폼 필드, 설정 항목, 복잡한 기능에 대한 설명을 제공할 때 유용합니다.
+InfoSign is a compact tooltip-trigger component that displays a small question-mark icon. When users hover over or focus on the icon, a tooltip appears with supplementary information. It is designed to provide contextual help without cluttering the interface -- ideal for explaining form fields, settings options, table column headers, and complex metrics.
+
+The component accepts a `message` prop for the tooltip content and a `placement` prop to control where the tooltip appears relative to the icon. InfoSign keeps the main UI clean while ensuring that detailed guidance is always one interaction away.
 
 ```tsx
 <InfoSign
@@ -22,21 +24,19 @@ import { InfoSign } from '@ceed/cds';
 
 function MyComponent() {
   return (
-    <div>
-      <label>
-        복잡한 설정 항목
-        <InfoSign message="이 설정은 시스템 전체 성능에 영향을 줄 수 있습니다. 변경하기 전에 관리자와 상의하세요." />
-      </label>
-    </div>
+    <label>
+      Complex Setting
+      <InfoSign
+        message="This setting affects overall system performance. Consult an administrator before making changes."
+      />
+    </label>
   );
 }
 ```
 
-## Examples
-
-### Basic Usage
+## Basic
 
-가장 기본적인 InfoSign 사용법입니다.
+The default InfoSign displays a question-mark icon that reveals a tooltip on hover or focus.
 
 ```tsx
 <InfoSign
@@ -50,104 +50,87 @@ function MyComponent() {
 ### Form Field Help
 
 ```tsx
-<FormControl>
-  <FormLabel>
-    비밀번호 복잡도
-    <InfoSign
-      message="비밀번호는 최소 8자 이상이며, 대문자, 소문자, 숫자, 특수문자를 포함해야 합니다."
-      placement="top"
-    />
-  </FormLabel>
-  <Input type="password" />
-</FormControl>
-```
-
-### Settings Explanation
+import { InfoSign } from '@ceed/cds';
+import { FormControl, FormLabel, Input } from '@ceed/cds';
 
-```tsx
-<Stack spacing={2}>
-  <Box>
-    <Typography level="title-sm">
-      자동 저장
-      <InfoSign message="이 기능을 활성화하면 5분마다 자동으로 작업 내용이 저장됩니다." placement="right" />
-    </Typography>
-    <Switch />
-  </Box>
-</Stack>
+function PasswordField() {
+  return (
+    <FormControl>
+      <FormLabel>
+        Password
+        <InfoSign
+          message="Must be at least 8 characters and include uppercase, lowercase, number, and special character."
+          placement="top"
+        />
+      </FormLabel>
+      <Input type="password" />
+    </FormControl>
+  );
+}
 ```
 
-### Complex Data Explanation
+### Table Column Header
 
 ```tsx
-<Card>
-  <CardContent>
-    <Typography level="title-md">
-      처리량 지표
-      <InfoSign
-        message="처리량은 최근 24시간 동안의 평균 요청 수를 나타냅니다. 이 값이 높을수록 시스템이 더 많은 작업을 처리하고 있다는 의미입니다."
-        placement="bottom"
-      />
-    </Typography>
-    <Typography level="h2">1,234 req/min</Typography>
-  </CardContent>
-</Card>
-```
-
-### Table Header Help
+import { InfoSign } from '@ceed/cds';
 
-```tsx
-<Table>
-  <thead>
-    <tr>
-      <th>
-        사용자 ID
-        <InfoSign message="시스템에서 자동 생성된 고유 식별자입니다." />
-      </th>
-      <th>
-        마지막 활동
-        <InfoSign message="사용자가 마지막으로 로그인하거나 활동한 시간입니다." />
-      </th>
-      <th>상태</th>
-    </tr>
-  </thead>
-</Table>
+function TableHeader() {
+  return (
+    <thead>
+      <tr>
+        <th>
+          User ID
+          <InfoSign message="Auto-generated unique identifier assigned by the system." />
+        </th>
+        <th>
+          Last Activity
+          <InfoSign message="The most recent login or action timestamp for this user." />
+        </th>
+        <th>Status</th>
+      </tr>
+    </thead>
+  );
+}
 ```
 
-## Props
-
-### placement
-
-툴팁이 나타나는 위치를 설정할 수 있습니다.
+### Dashboard Metric Explanation
 
 ```tsx
-<InfoSign placement="top" message="위쪽에 표시" />
-<InfoSign placement="bottom" message="아래쪽에 표시" />
-<InfoSign placement="left" message="왼쪽에 표시" />
-<InfoSign placement="right" message="오른쪽에 표시" />
-```
-
-### message
+import { InfoSign, Typography, Stack } from '@ceed/cds';
 
-표시할 메시지 내용입니다. 긴 텍스트도 지원합니다.
-
-```tsx
-<InfoSign message="여러 줄로 된 긴 설명문도 표시할 수 있습니다.\n줄바꿈도 지원되므로 상세한 설명을 제공할 수 있습니다." />
+function MetricCard() {
+  return (
+    <Stack spacing={1}>
+      <Typography level="title-md">
+        Throughput
+        <InfoSign
+          message="Average requests per minute over the last 24 hours. Higher values indicate greater system load."
+          placement="right"
+        />
+      </Typography>
+      <Typography level="h2">1,234 req/min</Typography>
+    </Stack>
+  );
+}
 ```
 
 ## Best Practices
 
-1. **간결한 메시지**: 핵심 정보만 포함하여 사용자가 빠르게 이해할 수 있도록 합니다.
+- **Keep messages concise.** Tooltip messages should be 1-2 sentences that quickly answer "what does this mean?" Avoid paragraphs of text.
+  - ✔ "Maximum file size per upload. Files exceeding this limit will be rejected."
+  - ✘ A multi-paragraph explanation with examples and edge cases
 
-2. **적절한 배치**: 설명하려는 요소 바로 옆에 배치하여 연관성을 명확히 합니다.
+- **Place InfoSign directly adjacent to the element it explains.** Position it immediately after a label or header text so users can easily associate the help icon with the relevant field.
 
-3. **일관된 사용**: 비슷한 성격의 정보에는 일관되게 InfoSign을 사용합니다.
+- **Do not overuse InfoSign.** Adding a help icon to every single field creates visual noise and suggests the interface itself is too confusing. Reserve it for genuinely complex or ambiguous items.
 
-4. **과도한 사용 금지**: 모든 요소에 InfoSign을 붙이면 인터페이스가 복잡해집니다.
+- **Choose placement that avoids overlap.** Use `placement="top"` or `placement="right"` for fields near the bottom of a viewport, and `placement="bottom"` for elements near the top.
 
-## Accessibility
+- **Use InfoSign for supplementary information only.** Critical instructions or warnings should be displayed inline (e.g., with FormHelperText or Alert), not hidden behind a tooltip.
 
-- InfoSign은 키보드 탐색이 가능합니다
-- 스크린 리더가 메시지 내용을 읽을 수 있습니다
-- ARIA 라벨이 자동으로 적용됩니다
+## Accessibility
 
-InfoSign은 사용자에게 필요한 추가 정보를 제공하면서도 인터페이스를 깔끔하게 유지하는 데 도움이 되는 유용한 컴포넌트입니다.
+- InfoSign is keyboard-focusable, allowing users to trigger the tooltip using **Tab** navigation without requiring a mouse.
+- The tooltip content is announced by screen readers when the InfoSign receives focus, thanks to built-in ARIA attributes.
+- The question-mark icon serves as a universally recognized visual cue for "more information," making it intuitive for all users.
+- Ensure that the `message` text provides the same information available through other channels -- do not make the tooltip the only way to learn critical information.