# Components

LafLabs Web Design 2026.10.3. A stable component has a supported public contract; a candidate API can change.

## Accordion (`accordion`)

- Maturity: **candidate**
- Category: **disclosure**
- Purpose: Expands and collapses longer content by heading. / 긴 설명을 제목 단위로 펼치고 접습니다.
- Use: Use it for FAQs or supporting detail that need not be visible at once. / 모든 내용을 동시에 볼 필요가 없는 FAQ나 보조 설명에 씁니다.
- Avoid: Do not hide essential information or short primary copy by default. / 핵심 정보나 짧은 본문을 기본으로 숨기지 않습니다.
- Accessibility: Preserves real headings, buttons, aria-expanded, and arrow-key movement. / 실제 heading과 button, aria-expanded 관계 및 방향키 이동을 유지합니다.
- Related components: `tabs`, `separator`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the heading predicts the hidden content. / 제목만으로 숨은 내용을 예측할 수 있는지 확인합니다.
  - `open` [fixture]: Confirm expanded state and caret direction change together. / 확장 상태와 캐럿 방향이 함께 바뀌는지 확인합니다.
  - `disabled` [fixture]: Confirm disabled items are removed from the focus sequence. / 비활성 항목이 초점 순서에서 제외되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `"single" \| "multiple"` | Yes | Controls whether one or many items may be open. / 동시에 열 수 있는 항목 수를 정합니다. |
| `collapsible` | `boolean` | No | Allows all items to close in single mode. / single 모드에서 모두 닫을 수 있게 합니다. |
| `value` | `string \| string[]` | No | The controlled open item value. / 제어되는 열린 항목 값입니다. |

### Usage shape

```tsx
<Accordion type="single" collapsible>
  <AccordionItem value="one">
    <AccordionTrigger>Question</AccordionTrigger>
    <AccordionContent>Answer</AccordionContent>
  </AccordionItem>
</Accordion>
```

## Alert (`alert`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Explains a persistent inline state and its next action. / 본문 흐름 안에 계속 남아 있는 상태와 다음 행동을 설명합니다.
- Use: Use it when information, success, warning, or error must remain with the task. / 정보, 성공, 주의, 오류가 다음 작업과 함께 남아야 할 때 씁니다.
- Avoid: Use Toast for brief outcomes and Alert Dialog for decisions. / 짧게 끝난 결과나 명시적 결정에는 Toast나 Alert Dialog를 씁니다.
- Accessibility: Labels the region from a visible title and reserves live for new urgent errors. / 보이는 제목으로 영역을 이름 붙이고 새 긴급 오류에만 live를 사용합니다.
- Related components: `toast`, `alert-dialog`, `button`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `info` [fixture]: Distinguish information with the left status signal and title. / 왼쪽 상태 신호와 제목으로 정보를 구분합니다.
  - `warning` [fixture]: State the caution and next action concretely. / 주의 상태와 다음 행동을 구체적으로 적습니다.
  - `error` [fixture]: Provide the error reason and an available recovery action. / 오류 원인과 가능한 복구 동작을 함께 제공합니다.
  - `live` [fixture]: Announce only a newly created urgent state as an alert. / 새 긴급 상태만 alert로 발표합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | No | Compatibility shorthand for a visible title. / 기존 사용법을 위한 단축 제목입니다. |
| `variant` | `"info" \| "success" \| "warning" \| "error"` | No | Sets the feedback meaning. / 상태의 의미입니다. |
| `live` | `boolean` | No | Announces a newly rendered urgent state. / 새 긴급 상태를 즉시 발표합니다. |

### Usage shape

```tsx
<Alert variant="error">
  <AlertContent>
    <AlertTitle>Save failed</AlertTitle>
    <AlertDescription>Review the title.</AlertDescription>
  </AlertContent>
  <AlertAction>Retry</AlertAction>
</Alert>
```

## Alert Dialog (`alert-dialog`)

- Maturity: **candidate**
- Category: **overlay**
- Purpose: Requests an explicit decision before a consequential action. / 되돌리기 어려운 행동 전에 명시적인 결정을 받습니다.
- Use: Use it for immediate actions such as deletion or permission changes. / 삭제나 권한 변경처럼 결과가 즉시 적용되는 행동에 씁니다.
- Avoid: Use Dialog or Alert for general information or reversible actions. / 일반 안내나 쉽게 되돌릴 수 있는 행동에는 Dialog나 Alert를 씁니다.
- Accessibility: Requires cancel or action, ignores outside dismissal, and restores focus. / 바깥 클릭으로 닫지 않고 취소와 실행을 명확히 제공하며 초점을 복귀합니다.
- Related components: `dialog`, `alert`, `button`
- Dependencies: `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the trigger names the consequence. / 트리거가 결과를 구체적으로 설명하는지 확인합니다.
  - `open` [interactive]: Inspect action hierarchy, initial focus, and focus restoration. / 취소와 실행의 위계, 초기 초점과 초점 복귀를 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `destructive` [interactive]: Use Error Deep with a white foreground for a destructive action. / 위험 동작은 Error Deep 면과 흰색 글자를 사용합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "destructive"` | No | Sets the confirmation action intent. / 확인 동작의 의미입니다. |
| `children` | `ReactNode` | No | Composes Header, Body, and Footer. / Header, Body와 Footer를 조합합니다. |

### Usage shape

```tsx
<AlertDialog>
  <AlertDialogContent>
    <AlertDialogBody>This cannot be undone.</AlertDialogBody>
    <AlertDialogCancel>Cancel</AlertDialogCancel>
    <AlertDialogAction variant="destructive">Archive</AlertDialogAction>
  </AlertDialogContent>
</AlertDialog>
```

## Breadcrumb (`breadcrumb`)

- Maturity: **candidate**
- Category: **navigation**
- Purpose: Shows where the current page sits in the information hierarchy. / 현재 페이지가 정보 구조에서 어디에 있는지 보여줍니다.
- Use: Use it in documents or admin views more than one level deep. / 두 단계 이상 깊은 문서나 관리 화면에서 상위 경로를 제공할 때 씁니다.
- Avoid: Do not use it on a single-level page or as a progress indicator. / 단일 단계 페이지나 진행 단계를 설명하는 용도로 쓰지 않습니다.
- Accessibility: Uses a named nav, ordered list, current-page state, and hidden separators. / 이름 있는 nav, 순서 목록, 현재 페이지와 숨겨진 구분자를 사용합니다.
- Related components: `text-link`, `dropdown-menu`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `default` [fixture]: Distinguish the current page from navigable ancestors. / 현재 페이지와 이동 가능한 상위 경로를 구분합니다.
  - `collapsed` [fixture]: Collapse long intermediate paths with a named Ellipsis. / 긴 중간 경로는 이름 있는 Ellipsis로 축약합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | No | A name that distinguishes this navigation region. / 여러 탐색 영역을 구분하는 이름입니다. |
| `label` | `string` | Yes | The accessible name for BreadcrumbEllipsis. / BreadcrumbEllipsis의 접근 가능한 이름입니다. |

### Usage shape

```tsx
<Breadcrumb>
  <BreadcrumbList>
    <BreadcrumbItem>
      <BreadcrumbLink href="/">Home</BreadcrumbLink>
    </BreadcrumbItem>
    <BreadcrumbSeparator />
    <BreadcrumbItem>
      <BreadcrumbPage>Design</BreadcrumbPage>
    </BreadcrumbItem>
  </BreadcrumbList>
</Breadcrumb>
```

## Button (`button`)

- Maturity: **stable**
- Category: **action**
- Purpose: Runs an action in the current interface. / 현재 화면에서 동작을 실행합니다.
- Use: Use it for immediate actions such as save, submit, and confirm. / 저장, 제출, 확인처럼 즉시 실행되는 동작에 씁니다.
- Avoid: Use Button Link or Text Link for navigation. / 다른 주소로 이동할 때는 Button Link나 Text Link를 씁니다.
- Accessibility: Keep an action-specific name, expose busy and disabled states, and name icon buttons with aria-label. / 동작을 설명하는 이름을 유지하고 busy와 disabled 상태를 함께 알립니다. 아이콘 버튼에는 aria-label이 필요합니다.
- Related components: `button-link`, `button-group`
- States and inspection:
  - `primary` [fixture]: Reserve the blue surface for the most important action in a view. / 한 화면의 가장 중요한 동작에만 파란 면을 씁니다.
  - `secondary` [fixture]: Render secondary actions with a Paper surface and one-pixel rule. / 보조 동작은 Paper 면과 1px 선으로 표시합니다.
  - `outline` [fixture]: Use an Ink outline to distinguish an action without a filled surface. / 채운 면 없이 Ink 경계로 동작을 분명히 구분합니다.
  - `inverse` [fixture]: Confirm the boundary and label remain clear on dark surfaces. / 어두운 면 위에서 경계와 이름이 선명한지 확인합니다.
  - `ghost` [fixture]: Keep the target and focus indicator even at low visual emphasis. / 시각적 무게가 낮아도 조작 영역과 초점 표시는 유지합니다.
  - `icon` [fixture]: For icon-only controls, verify the accessible name and 44px mobile target. / 아이콘만 보일 때 접근성 이름과 모바일 44px 조작 영역을 확인합니다.
  - `disabled` [fixture]: Confirm the disabled action cannot run. / 비활성 상태에서 실행되지 않는지 확인합니다.
  - `loading` [fixture]: Confirm busy state is exposed without replacing the label. / 이름을 유지하면서 busy 상태를 알리는지 확인합니다.
  - `danger` [fixture]: Use Error Deep with a white foreground only for destructive actions. / 파괴적 동작에만 Error Deep과 흰색 전경을 씁니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `variant` | `"primary" \| "secondary" \| "outline" \| "inverse" \| "danger" \| "ghost"` | No | Sets action hierarchy and semantics. / 동작의 위계와 의미를 정합니다. |
| `size` | `"compact" \| "default" \| "icon"` | No | Sets control density, including the icon-only size. / 컨트롤 밀도와 아이콘 전용 크기를 정합니다. |
| `loading` | `boolean` | No | Prevents duplicate activation and exposes busy state. / 중복 실행을 막고 busy 상태를 알립니다. |
| `type` | `"button" \| "submit" \| "reset"` | No | Defaults to button. / 기본값은 button입니다. |
| `children` | `ReactNode` | Yes | The action label or icon. / 동작 이름 또는 아이콘입니다. |

### Usage shape

```tsx
<Button type="submit">Save</Button>
```

## Button Group (`button-group`)

- Maturity: **candidate**
- Category: **action**
- Purpose: Composes related actions and supporting parts in one connected frame. / 관련 동작과 보조 요소를 하나의 연결된 틀로 묶습니다.
- Use: Use it for related actions, split actions, or an input paired with its action. / 저장과 발행, 분할 동작, 입력과 실행처럼 같은 맥락의 요소를 묶을 때 씁니다.
- Avoid: Do not force unrelated actions or long explanations into one row. / 서로 무관한 동작이나 긴 설명을 한 줄에 억지로 넣지 않습니다.
- Accessibility: Name the group while preserving a specific name for every control. / 그룹 이름으로 관계를 알리고 각 컨트롤의 고유 이름도 유지합니다.
- Related components: `button`, `button-link`, `dropdown-menu`, `input-group`
- States and inspection:
  - `horizontal` [fixture]: Check adjacent one-pixel borders read as one structure. / 인접 요소의 1px 선이 하나의 구조로 읽히는지 확인합니다.
  - `vertical` [fixture]: Check naming and action order in the vertical layout. / 세로 배치에서도 이름과 조작 순서를 확인합니다.
  - `split` [fixture]: Inspect the boundary and names of the main action and options menu. / 주요 동작과 옵션 메뉴의 경계와 이름을 확인합니다.
  - `input` [fixture]: Confirm the input and action read as one composed field. / 입력과 실행 버튼이 하나의 필드처럼 연결되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | No | The accessible name for the related controls. / 관련 요소 전체의 접근성 이름입니다. |
| `orientation` | `"horizontal" \| "vertical"` | No | The direction used to arrange controls. / 요소를 배치할 방향입니다. |
| `children` | `ReactNode` | Yes | Buttons, inputs, text, separators, or nested groups to compose. / Button, 입력, 텍스트, 구분선 등 함께 배치할 요소입니다. |

### Usage shape

```tsx
<ButtonGroup label="Document actions">
  <Button>Save</Button>
  <ButtonGroupSeparator />
  <Button>Publish</Button>
</ButtonGroup>
```

## Button Link (`button-link`)

- Maturity: **stable**
- Category: **action**
- Purpose: Uses Button's appearance while preserving a native anchor for navigation. / Button과 같은 모양을 쓰되 native anchor로 다른 주소에 이동합니다.
- Use: Use it only when a prominent CTA navigates to another page or address. / 강한 CTA가 페이지나 주소 이동일 때만 씁니다.
- Avoid: Use Button for in-place actions such as save, submit, or opening a dialog. / 저장, 제출, 모달 열기처럼 현재 화면에서 실행되는 동작에는 Button을 씁니다.
- Accessibility: Do not replace it with Button; preserve native anchor semantics and a destination-specific name. / Button으로 대체하지 말고 native anchor 의미와 목적지가 드러나는 이름을 유지합니다.
- Related components: `button`, `text-link`
- States and inspection:
  - `primary` [fixture]: Present the primary destination on a blue surface. / 주요 이동 목적지를 파란 면으로 표시합니다.
  - `secondary` [fixture]: Present supporting navigation with Paper and a one-pixel rule. / 보조 이동은 Paper 면과 1px 선으로 표시합니다.
  - `outline` [fixture]: Use an Ink outline for navigation that needs button emphasis without a fill. / 채운 면 없이 Ink 경계로 이동 동작을 구분합니다.
  - `inverse` [fixture]: Confirm the destination remains clear on dark surfaces. / 어두운 면에서도 링크 목적지가 선명한지 확인합니다.
  - `ghost` [fixture]: Keep link focus visible at low hierarchy. / 낮은 위계의 이동에도 링크 초점 표시를 유지합니다.
  - `icon` [fixture]: Icon links require an aria-label that names the destination. / 아이콘 링크에는 목적지를 설명하는 aria-label이 필요합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `href` | `string` | Yes | The navigation destination. / 이동할 주소입니다. |
| `variant` | `"primary" \| "secondary" \| "outline" \| "inverse" \| "danger" \| "ghost"` | No | Sets the link's visual hierarchy. / 링크의 시각 위계를 정합니다. |
| `size` | `"compact" \| "default" \| "icon"` | No | Sets the control density. / 컨트롤 밀도를 정합니다. |
| `children` | `ReactNode` | Yes | The destination label or icon. / 목적지를 설명하는 이름 또는 아이콘입니다. |

### Usage shape

```tsx
<ButtonLink href="/design">Design guide</ButtonLink>
```

## Checkbox (`checkbox`)

- Maturity: **candidate**
- Category: **selection**
- Purpose: Turns an independent selection on or off. / 서로 독립적인 선택을 켜고 끕니다.
- Use: Use it for independent consent, list, or multi-select values. / 복수 선택, 동의, 목록 선택처럼 각 값이 독립적일 때 씁니다.
- Avoid: Use Switch for a single setting that changes immediately. / 즉시 설정을 바꾸는 단일 동작에는 Switch를 씁니다.
- Accessibility: Preserve the native checkbox and expose mixed state through aria-checked. / native checkbox를 유지하고 mixed 상태는 aria-checked로 함께 알립니다.
- Related components: `radio-group`, `switch`
- States and inspection:
  - `unchecked` [fixture]: Inspect the label and unchecked square control. / 이름과 선택되지 않은 사각 컨트롤을 확인합니다.
  - `checked` [fixture]: Confirm the inner square shared with Radio Group communicates selection alongside color. / Radio Group과 같은 안쪽 사각형으로 선택 상태가 함께 드러나는지 확인합니다.
  - `indeterminate` [fixture]: Confirm partial selection is exposed as mixed. / 부분 선택이 mixed 상태로 전달되는지 확인합니다.
  - `disabled` [fixture]: Confirm the disabled control cannot change. / 비활성 컨트롤이 실행되지 않는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | Yes | The visible name of the selection. / 선택값을 설명하는 보이는 이름입니다. |
| `description` | `ReactNode` | No | Supporting copy that explains the consequence. / 선택 결과를 설명하는 보조 문구입니다. |
| `indeterminate` | `boolean` | No | The mixed state for a partial selection. / 일부만 선택된 mixed 상태입니다. |

### Usage shape

```tsx
<Checkbox label="Select all" indeterminate />
```

## Code Block (`code-block`)

- Maturity: **stable**
- Category: **content**
- Purpose: A readable code region with a language label and copy action. / 언어 이름과 복사 동작을 갖춘 코드 읽기 영역입니다.
- Use: Use it to present multiline code or commands verbatim in documentation. / 문서에서 여러 줄의 코드나 명령을 원문 그대로 보여줄 때 씁니다.
- Avoid: Do not use it for short inline identifiers or as an executable editor. / 짧은 inline 식별자나 실행 가능한 편집기에는 쓰지 않습니다.
- Accessibility: The copy button names the language, and the source remains selectable after a copy failure. / 복사 버튼 이름에는 언어를 넣습니다. 실패해도 원문을 선택할 수 있어야 합니다.
- Related components: `button`
- States and inspection:
  - `idle` [fixture]: Inspect the real source, language name, and copy action in the idle state. / 실제 코드 원문, 언어 이름, 복사 버튼을 초기 상태에서 확인합니다.
  - `copied` [interactive]: Use the real copy action and inspect its COPIED label and polite status message. / 실제 복사 버튼을 눌러 COPIED label과 polite 상태 안내를 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `error` [environment]: Deny clipboard access, then inspect the real RETRY label while the source remains selectable. / 클립보드 권한을 거부한 뒤 실제 복사 버튼의 RETRY label과 선택 가능한 원문을 확인합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `children` | `ReactNode` | Yes | The rendered code content placed inside the pre element. / pre 안에 표시할 코드 내용입니다. |
| `language` | `string` | No | The language identifier shown in the toolbar. / toolbar에 표시할 언어 식별자입니다. |
| `source` | `string` | Yes | The exact source copied to the clipboard. / 클립보드에 복사할 원문입니다. |

### Usage shape

```tsx
<CodeBlock language="ts" source={source}>{highlightedCode}</CodeBlock>
```

## Combobox (`combobox`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Selects one value from a searchable list. / 검색 가능한 긴 목록에서 하나의 값을 고릅니다.
- Use: Use it when the option list is long or labels may be unfamiliar. / 선택지가 많거나 사용자가 정확한 이름을 모를 수 있을 때 씁니다.
- Avoid: Use Native Select or Select for short, fixed option lists. / 짧고 고정된 목록에는 Native Select나 Select를 씁니다.
- Accessibility: Exposes combobox/listbox relationships, active option, selection, and arrow-key operation. / combobox와 listbox 관계, 활성 항목, 선택 상태와 방향키 조작을 제공합니다.
- Related components: `field`, `select`, `input`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the selected value and input purpose are both readable. / 선택값과 입력 목적이 함께 읽히는지 확인합니다.
  - `open` [interactive]: Distinguish active, selected, and disabled options. / 활성 항목, 선택 항목, 비활성 항목을 구분합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `empty` [interactive]: State an empty search result in concise text. / 검색 결과가 없음을 짧은 문장으로 알립니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `options` | `readonly ComboboxOption[]` | Yes | The options available for search and selection. / 검색하고 선택할 항목입니다. |
| `value` | `string` | No | The controlled selected value. / 제어되는 선택값입니다. |
| `onValueChange` | `(value: string) => void` | No | Called when selection or query editing changes the current value. / 선택하거나 기존 선택을 편집해 값이 바뀔 때 호출됩니다. |
| `onValueCommit` | `(value: string) => void` | No | Called only when the user commits an option from the list. / 사용자가 목록의 항목을 확정했을 때만 호출됩니다. |
| `emptyText` | `string` | Yes | Copy shown when no option matches. / 검색 결과가 없을 때 표시할 문구입니다. |

### Usage shape

```tsx
<Combobox
  aria-label="Framework"
  options={options}
  value={value}
  onValueChange={setValue}
  emptyText="No results"
/>
```

## Data Table (`data-table`)

- Maturity: **candidate**
- Category: **content**
- Purpose: Displays structured data with sorting and an explicit empty state. / 정렬과 빈 상태가 필요한 구조화 데이터를 보여줍니다.
- Use: Use it for operational lists that people need to reorder by column. / 관리 목록처럼 사용자가 열 기준으로 데이터를 다시 정렬해야 할 때 씁니다.
- Avoid: Use Table for static comparison and Item for editorial browsing. / 정적 비교에는 Table을, 카드형 탐색에는 Item을 씁니다.
- Accessibility: Connects sort buttons with aria-sort while preserving real Table semantics. / 정렬 버튼과 aria-sort를 연결하고 실제 Table 구조를 유지합니다.
- Related components: `table`, `pagination`, `empty-state`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `default` [fixture]: Distinguish sortable columns from static columns. / 정렬 가능한 열과 정적 열을 구분합니다.
  - `sorted` [interactive]: Confirm the active column and direction appear visually and in the accessibility tree. / 현재 정렬 열과 방향이 아이콘과 접근성 트리에 함께 나타나는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `empty` [fixture]: Confirm the empty state spans the table with concise copy. / 빈 상태가 모든 열을 가로질러 짧게 설명되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `columns` | `readonly DataTableColumn<Row>[]` | Yes | Defines cell rendering and optional sort values. / 셀 렌더링과 선택적 정렬값을 정의합니다. |
| `rows` | `readonly Row[]` | Yes | The real records displayed by the table. / 표에 표시할 실제 데이터입니다. |
| `getRowKey` | `(row: Row) => string` | Yes | Returns a stable identifier for each row. / 각 행의 안정적인 식별자를 반환합니다. |
| `emptyText` | `string` | Yes | Copy shown when there are no rows. / 표시할 행이 없을 때의 안내입니다. |

### Usage shape

```tsx
<DataTable
  aria-label="Services"
  columns={columns}
  rows={rows}
  getRowKey={(row) => row.id}
  emptyText="No services"
/>
```

## Dialog (`dialog`)

- Maturity: **candidate**
- Category: **overlay**
- Purpose: Opens a focused, short task above the current flow. / 현재 흐름 위에서 집중이 필요한 짧은 작업을 엽니다.
- Use: Use it for settings or a short form without leaving context. / 설정이나 짧은 폼을 현재 맥락 안에서 처리할 때 씁니다.
- Avoid: Do not use it for long documents or consequential decisions. / 긴 문서나 되돌리기 어려운 결정에는 쓰지 않습니다.
- Accessibility: Preserves naming, focus trapping, Escape dismissal, and trigger focus restoration. / 제목과 설명, 초점 가두기, Escape 닫기와 트리거 초점 복귀를 유지합니다.
- Related components: `alert-dialog`, `button`, `field`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the trigger names the task it opens. / 트리거가 열릴 작업을 구체적으로 설명하는지 확인합니다.
  - `open` [interactive]: Inspect the title, body, actions, and close boundary. / 제목, 본문, 동작과 닫기 경계가 분명한지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `body-scroll` [interactive]: Confirm only the long body scrolls while title and actions remain reachable. / 긴 본문만 스크롤되고 제목과 동작은 접근 가능한지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `size` | `"small" \| "medium" \| "large" \| "full"` | No | Sets the dialog width for the task. / 작업에 맞는 대화상자 너비입니다. |
| `scroll` | `"content" \| "body"` | No | Chooses the content or DialogBody scrolling boundary. / 전체 또는 DialogBody의 스크롤 경계입니다. |
| `closeLabel` | `string` | No | Adds the compatibility close icon; new work composes DialogClose. / 호환용 닫기 아이콘을 추가합니다. 새 작업은 DialogClose를 조합합니다. |

### Usage shape

```tsx
<Dialog>
  <DialogTrigger>Settings</DialogTrigger>
  <DialogContent size="medium" scroll="body">
    <DialogBody>...</DialogBody>
    <DialogFooter>
      <DialogClose>Done</DialogClose>
    </DialogFooter>
  </DialogContent>
</Dialog>
```

## Dropdown Menu (`dropdown-menu`)

- Maturity: **candidate**
- Category: **navigation**
- Purpose: Opens related commands and settings from one trigger. / 한 트리거에서 관련 명령과 설정을 엽니다.
- Use: Use it to group related, secondary commands in one place. / 자주 쓰지 않는 관련 동작을 한곳에 묶을 때 씁니다.
- Avoid: Do not hide primary actions or replace straightforward page navigation. / 주요 행동을 숨기거나 단순한 페이지 이동 목록을 대신하지 않습니다.
- Accessibility: Preserves arrow keys, typeahead, Escape, submenus, and trigger focus restoration. / 방향키, typeahead, Escape, 하위 메뉴와 트리거 초점 복귀를 유지합니다.
- Related components: `button`, `select`, `dialog`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `default` [fixture]: Confirm the trigger clearly names the menu purpose. / 트리거가 메뉴의 목적을 분명히 말하는지 확인합니다.
  - `open` [interactive]: Confirm the current item and keyboard focus are clear. / 현재 항목과 키보드 초점이 명확한지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `disabled` [fixture]: Confirm disabled commands are skipped while their state remains clear. / 비활성 명령을 건너뛰면서 상태는 전달하는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No | The controlled open state. / 제어되는 열림 상태입니다. |
| `onOpenChange` | `(open: boolean) => void` | No | Called when open state changes. / 열림 상태가 바뀔 때 호출됩니다. |
| `modal` | `boolean` | No | Whether the menu limits outside interaction. / 메뉴가 바깥 상호작용을 제한할지 정합니다. |

### Usage shape

```tsx
<DropdownMenu>
  <DropdownMenuTrigger>More</DropdownMenuTrigger>
  <DropdownMenuContent>
    <DropdownMenuItem>Edit</DropdownMenuItem>
  </DropdownMenuContent>
</DropdownMenu>
```

## Empty State (`empty-state`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Explains why no content is present and what can happen next. / 표시할 내용이 없을 때 이유와 다음 행동을 안내합니다.
- Use: Use it for a genuinely empty result, document, or collection. / 검색 결과, 문서, 목록이 비어 있는 실제 상태에 씁니다.
- Avoid: Do not invent example data or use it as a promotional card. / 예시 데이터를 꾸며 빈 공간을 채우거나 일반 홍보 영역으로 쓰지 않습니다.
- Accessibility: Make the state understandable from title and description, with recovery when available. / 제목과 설명만으로 상태를 이해할 수 있고 가능할 때 복구 동작을 제공합니다.
- Related components: `button`, `text-link`, `skeleton`
- States and inspection:
  - `default` [fixture]: Confirm title and description state the reason concretely. / 제목과 설명이 원인을 구체적으로 말하는지 확인합니다.
  - `action` [fixture]: Confirm one clear next action is provided when recovery is possible. / 가능한 다음 행동이 하나의 명확한 버튼으로 제공되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `title` | `ReactNode` | Yes | A title that summarizes the empty state. / 빈 상태를 요약하는 제목입니다. |
| `description` | `ReactNode` | Yes | Explains the reason or next step. / 이유나 다음 단계를 설명합니다. |
| `action` | `ReactNode` | No | An action for recovery or creation. / 복구나 생성으로 이어지는 동작입니다. |

### Usage shape

```tsx
<EmptyState
  title="No documents"
  description="Create the first document."
  action={<Button>Create</Button>}
/>
```

## Field (`field`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Composes labels, controls, descriptions, and errors into complete form sections with FieldGroup and FieldSet. / FieldGroup과 FieldSet으로 레이블, 입력, 설명, 오류를 완전한 폼 구역으로 구성합니다.
- Use: Use Field for one control and FieldGroup with FieldSet for related form sections. / 하나의 입력은 Field로, 관련 입력 묶음은 FieldGroup과 FieldSet으로 구성합니다.
- Avoid: Do not group read-only content or unrelated controls under one label. / 읽기 전용 정보나 관련 없는 입력을 하나의 레이블로 묶지 않습니다.
- Accessibility: Links nested FieldContent descriptions and errors to the control and names groups with FieldLegend. / 중첩된 FieldContent 안의 설명과 오류도 컨트롤에 연결하고 FieldLegend로 그룹 목적을 알립니다.
- Related components: `label`, `input`, `textarea`, `native-select`
- States and inspection:
  - `default` [fixture]: Confirm label and control are exposed as one field. / 레이블과 입력이 하나의 항목으로 읽히는지 확인합니다.
  - `required` [fixture]: Check the visible marker and native required state together. / 필수 표시와 native required 상태를 함께 확인합니다.
  - `invalid` [fixture]: Check error copy and aria-invalid linkage. / 오류 문구와 aria-invalid 연결을 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `required` | `boolean` | No | Sets the required state for the nested control. / 중첩 컨트롤의 필수 상태입니다. |
| `invalid` | `boolean` | No | Enables invalid state and error relationships. / 오류 상태와 오류 설명 연결을 활성화합니다. |
| `orientation` | `"vertical" \| "horizontal" \| "responsive"` | No | Controls how label content and the control are arranged. / 레이블 영역과 컨트롤의 배치 방식입니다. |
| `children` | `ReactNode` | No | A composition of FieldContent, labels, descriptions, errors, and one control. / FieldContent, 레이블, 설명, 오류와 하나의 컨트롤 조합입니다. |

### Usage shape

```tsx
<FieldSet>
  <FieldLegend>Document settings</FieldLegend>
  <FieldGroup>
    <Field orientation="responsive">
      <FieldContent>
        <FieldTitle>Publishing</FieldTitle>
        <FieldLabel>Slug</FieldLabel>
        <FieldDescription>Public identifier</FieldDescription>
      </FieldContent>
      <Input />
    </Field>
  </FieldGroup>
</FieldSet>
```

## Input (`input`)

- Maturity: **candidate**
- Category: **form**
- Purpose: A native input for single-line values. / 한 줄 값을 입력받는 native input입니다.
- Use: Use it for single-line values such as email, title, or search. / 이메일, 제목, 검색어처럼 한 줄로 끝나는 값에 씁니다.
- Avoid: Use Textarea for multiline copy and Native Select for fixed choices. / 여러 줄 문장에는 Textarea를, 정해진 선택에는 Native Select를 씁니다.
- Accessibility: Provide a name through Field or Label and choose the correct native type. / Field나 Label로 이름을 제공하고 입력 목적에 맞는 type을 지정합니다.
- Related components: `field`, `label`, `textarea`, `native-select`
- States and inspection:
  - `default` [fixture]: Inspect Paper surface, Ink text, and Line border. / Paper 바탕, Ink 텍스트, Line 경계를 확인합니다.
  - `focus-visible` [interactive]: Inspect the two-pixel Primary focus outline. / 2px Primary 초점선을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `invalid` [fixture]: Inspect the Error border and associated error copy. / Error 경계와 연결된 오류 문구를 확인합니다.
  - `disabled` [fixture]: Confirm input is blocked with disabled cursor and opacity. / 입력이 막히고 커서와 불투명도가 바뀌는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `type` | `HTMLInputTypeAttribute` | No | The native input type for the value. / 값의 native 입력 형식입니다. |
| `name` | `string` | No | The name used for form submission. / 폼 제출에 쓰는 이름입니다. |
| `placeholder` | `string` | No | A short example that never replaces the label. / 레이블을 대신하지 않는 짧은 예시입니다. |

### Usage shape

```tsx
<Input name="email" type="email" autoComplete="email" />
```

## Input Group (`input-group`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Groups an input with a unit, prefix, or compact action. / 입력과 단위, 접두어, 짧은 동작을 하나의 컨트롤로 묶습니다.
- Use: Use it for prefixes, units, or actions directly tied to an input. / URL 접두어, 단위, 검증 버튼처럼 입력과 직접 연결된 요소에 씁니다.
- Avoid: Do not place independent fields or several primary actions inside one boundary. / 서로 독립적인 입력이나 여러 주요 행동을 한 경계 안에 넣지 않습니다.
- Accessibility: Keeps one native control in DOM order; the start and end aliases normalize to inline placements. / 실제 입력은 하나만 두고 DOM 순서를 유지합니다. 기존 start와 end 별칭은 inline 위치로 정규화됩니다.
- Related components: `field`, `input`, `button`
- States and inspection:
  - `default` [fixture]: Confirm prefixes and actions remain visibly connected to the value. / 접두어와 동작이 입력값과 시각적으로 연결되는지 확인합니다.
  - `focus-visible` [interactive]: Confirm the shared boundary communicates focus. / 그룹 전체 경계가 초점 상태를 보여주는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `invalid` [fixture]: Confirm Field error copy and group border communicate the same state. / Field 오류와 그룹 경계가 같은 상태를 전달하는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `placement` | `"inline-start" \| "inline-end" \| "block-start" \| "block-end"` | No | The logical addon position. start and end remain compatibility aliases. / Addon의 논리적 위치입니다. start와 end는 호환 별칭입니다. |
| `children` | `ReactNode` | No | A composition of Input or Textarea with Addon, Text, and Button parts. / Input 또는 Textarea와 Addon, Text, Button 조합입니다. |

### Usage shape

```tsx
<InputGroup>
  <InputGroupAddon placement="block-start">
    <InputGroupText>Markdown supported</InputGroupText>
  </InputGroupAddon>
  <InputGroupTextarea aria-label="Guidance" />
  <InputGroupAddon placement="block-end">
    <InputGroupText>0 / 240</InputGroupText>
  </InputGroupAddon>
</InputGroup>
```

## Item (`item`)

- Maturity: **candidate**
- Category: **structure**
- Purpose: Composes media, copy, metadata, and actions into one row. / 미디어, 본문, 메타데이터와 동작을 하나의 행으로 구성합니다.
- Use: Use it for repeated entities such as repositories, documents, or people without card grids. / 저장소, 문서, 사람처럼 반복되는 개체를 카드 없이 나열할 때 씁니다.
- Avoid: Use Table for column comparison and Panel for a standalone region. / 열 비교가 핵심이면 Table을, 독립된 영역이면 Panel을 씁니다.
- Accessibility: Chooses article, div, or li for the surrounding structure and labels the item from its title. / 주변 목록에 맞는 article, div, li 요소를 선택하고 제목으로 이름을 연결합니다.
- Related components: `panel`, `table`, `status-label`
- States and inspection:
  - `default` [fixture]: Inspect the reading order of title, description, metadata, and actions. / 제목, 설명, 메타데이터와 동작의 읽기 순서를 확인합니다.
  - `subtle` [fixture]: Confirm the quiet surface does not overpower adjacent row structure. / 조용한 면이 인접 행 경계보다 강해지지 않는지 확인합니다.
  - `inverse` [fixture]: Verify primary and supporting copy contrast on the Ink surface. / Ink 면에서 본문과 보조 문구 대비를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `as` | `"article" \| "div" \| "li"` | No | The HTML element that fits the surrounding document structure. / 주변 문서 구조에 맞는 HTML 요소입니다. |
| `tone` | `"default" \| "subtle" \| "inverse"` | No | The surface contrast of the row. / 행의 표면 대비입니다. |

### Usage shape

```tsx
<Item as="li">
  <ItemMedia>LF</ItemMedia>
  <ItemContent>
    <ItemTitle>lafetch</ItemTitle>
    <ItemDescription>Typed fetch utilities.</ItemDescription>
  </ItemContent>
  <ItemActions>Open</ItemActions>
</Item>
```

## Label (`label`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Provides a concise name for a form control. / 입력 요소의 목적을 짧게 설명합니다.
- Use: Use it to explicitly name a native control outside Field. / Field 밖에서 native 입력과 명시적으로 연결할 때 씁니다.
- Avoid: Do not use a label element for help text or decoration. / 설명 문구나 시각 장식만을 위해 label 요소를 쓰지 않습니다.
- Accessibility: Keep htmlFor equal to the target control ID. / htmlFor와 입력 id를 같은 값으로 유지합니다.
- Related components: `field`, `input`, `textarea`, `native-select`
- States and inspection:
  - `default` [fixture]: Confirm activating the label focuses its control. / 레이블 선택 시 연결된 입력으로 초점이 이동하는지 확인합니다.
  - `required` [fixture]: Confirm FieldLabel's required marker does not obscure its name. / FieldLabel의 필수 표시가 텍스트 의미를 방해하지 않는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `htmlFor` | `string` | No | The ID of the associated control. / 연결할 컨트롤의 id입니다. |
| `children` | `ReactNode` | No | A concise name for the control. / 컨트롤을 설명하는 짧은 이름입니다. |

### Usage shape

```tsx
<>
  <Label htmlFor="query">Search</Label>
  <Input id="query" />
</>
```

## Logo (`logo`)

- Maturity: **stable**
- Category: **brand**
- Purpose: Displays the official symbol with the LafLabs wordmark. / 공식 심볼과 LafLabs 워드마크를 함께 표시합니다.
- Use: Use it where the LafLabs identity must be explicit, such as the site header and footer. / 사이트 헤더와 푸터처럼 LafLabs임을 분명히 밝혀야 할 때 씁니다.
- Avoid: Do not use it as a decorative background or repeating motif. / 장식 배경이나 반복 무늬로 사용하지 않습니다.
- Accessibility: The component exposes the LafLabs name; check that an enclosing link does not create a redundant label. / Logo 단독 사용 시 LafLabs로 읽힙니다. 링크 안에서는 이름을 한 번만 제공합니다.
- Dependencies: `next`
- States and inspection:
  - `default` [fixture]: Inspect the 24px symbol and full wordmark together on one baseline. / 24px 심볼과 전체 워드마크가 기준선에서 함께 정렬되는지 확인합니다.
  - `compact` [fixture]: Inspect the 16px symbol for preserved proportions and wordmark spacing. / 16px 심볼에서도 원본 비율과 워드마크 간격이 유지되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `size` | `number` | No | The width and height of the official symbol. Defaults to 24. / 공식 심볼의 가로와 세로 크기입니다. 기본값은 24입니다. |

### Usage shape

```tsx
<Logo size={24} />
```

## Native Select (`native-select`)

- Maturity: **candidate**
- Category: **form**
- Purpose: A select that preserves native browser selection behavior. / 브라우저 기본 선택 동작을 유지하는 select입니다.
- Use: Use it to choose one value from a short, fixed list. / 짧고 고정된 선택지를 하나 고를 때 씁니다.
- Avoid: Do not use it for long searchable lists or multi-selection. / 검색이 필요한 긴 목록이나 여러 값을 고르는 UI에는 쓰지 않습니다.
- Accessibility: Keep the native select as the only interactive element and hide its decorative icon. / native select만 상호작용 요소로 두고 장식 화살표는 숨깁니다.
- Related components: `field`, `label`, `input`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `default` [fixture]: Inspect the current value and decorative caret. / 현재 선택값과 장식 화살표를 확인합니다.
  - `focus-visible` [interactive]: Open the native list by keyboard and inspect focus. / 키보드로 선택 목록을 열고 초점선을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `disabled` [fixture]: Confirm selection is blocked while the value remains readable. / 선택이 막히고 값은 읽을 수 있는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `name` | `string` | No | The name used for form submission. / 폼 제출에 쓰는 이름입니다. |
| `children` | `ReactNode` | No | Native option and optgroup elements. / native option과 optgroup입니다. |

### Usage shape

```tsx
<NativeSelect name="category">
  <option value="general">General</option>
</NativeSelect>
```

## Pagination (`pagination`)

- Maturity: **candidate**
- Category: **navigation**
- Purpose: Navigates a collection from one connected page rail. / 연결된 레일에서 컬렉션의 이전, 다음, 특정 페이지로 이동합니다.
- Use: Use it when a collection has multiple URL-addressable pages. / 목록이 URL로 구분된 여러 페이지를 가질 때 씁니다.
- Avoid: Do not use it for slides or in-page tabs. / 슬라이드나 현재 화면 안의 탭 전환에는 쓰지 않습니다.
- Accessibility: Uses a named nav, real links, aria-current, and disabled boundaries. / 이름 있는 nav, 실제 링크, aria-current와 비활성 경계를 제공합니다.
- Related components: `data-table`, `breadcrumb`, `text-link`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `default` [fixture]: Confirm previous and next are real destination links. / 이전과 다음이 실제 목적지 링크인지 확인합니다.
  - `current` [fixture]: Confirm the current page uses aria-current and the blue surface. / 현재 페이지가 aria-current와 파란 면으로 전달되는지 확인합니다.
  - `boundary` [fixture]: Confirm disabled boundary directions expose no destination. / 첫 페이지와 마지막 페이지의 비활성 방향이 목적지를 노출하지 않는지 확인합니다.
  - `collapsed` [fixture]: Collapse long ranges while preserving the current position. / 긴 범위는 축약하되 현재 위치는 유지합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `isCurrent` | `boolean` | No | Marks the current page link. / 현재 페이지 링크를 표시합니다. |
| `disabled` | `boolean` | No | Keeps a boundary visible without navigation. / 방향 경계를 보이되 이동은 막습니다. |
| `label` | `string` | Yes | Names a direction or ellipsis accessibly. / 방향이나 축약 표시의 접근 가능한 이름입니다. |

### Usage shape

```tsx
<Pagination aria-label="Document pages">
  <PaginationContent>
    <PaginationItem>
      <PaginationLink href="?page=2" isCurrent>2</PaginationLink>
    </PaginationItem>
  </PaginationContent>
</Pagination>
```

## Panel (`panel`)

- Maturity: **candidate**
- Category: **structure**
- Purpose: Structures related information and actions within one clear boundary. / 관련된 정보와 동작을 하나의 명확한 경계 안에 구성합니다.
- Use: Use it when a settings group or summary module needs a genuine independent boundary. / 설정 묶음, 요약 모듈처럼 콘텐츠의 독립된 경계가 실제로 필요할 때 씁니다.
- Avoid: Do not wrap every section or list row, and do not nest Panels inside Panels. / 모든 섹션과 목록 행을 감싸거나 Panel 안에 Panel을 중첩하지 않습니다.
- Accessibility: Name independent regions with aria-label or aria-labelledby and keep heading levels consistent with the document. / 독립된 영역이면 aria-label 또는 aria-labelledby로 이름을 붙이고 제목 단계는 문서 구조에 맞춥니다.
- Related components: `separator`, `button`, `status-label`
- States and inspection:
  - `default` [fixture]: Confirm the Paper surface and one-pixel boundary separate the module from surrounding content. / Paper 면과 1px 경계가 주변 콘텐츠와 구분되는지 확인합니다.
  - `subtle` [fixture]: Confirm the quiet blue surface does not compete with the content. / 옅은 파란 면이 내용보다 먼저 튀지 않는지 확인합니다.
  - `inverse` [fixture]: Confirm title, description, and status retain sufficient contrast on Ink. / Ink 면에서 제목, 설명, 상태의 대비를 확인합니다.
  - `action` [fixture]: Confirm the title and action stack naturally into one column on narrow screens. / 좁은 화면에서 제목과 동작이 한 열로 자연스럽게 쌓이는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tone` | `"default" \| "subtle" \| "inverse"` | No | The surface tone chosen for the surrounding context and information hierarchy. / 주변 표면과 정보 위계에 맞는 면 색입니다. |
| `aria-label / aria-labelledby` | `string` | No | An accessible name used when the Panel is exposed as an independent region. / 독립된 영역으로 노출할 때 쓰는 접근 가능한 이름입니다. |
| `children` | `ReactNode` | No | Composable Panel parts such as Header, Content, and Footer. / Header, Content, Footer 등 조합할 Panel 부분입니다. |
| `PanelTitle as` | `"h2" \| "h3" \| "h4"` | No | The heading level that matches the surrounding document. Defaults to h3. / 주변 문서 구조에 맞는 제목 단계입니다. 기본값은 h3입니다. |

### Usage shape

```tsx
<Panel aria-labelledby="settings-title" tone="subtle">
  <PanelHeader>
    <PanelTitle id="settings-title">Notification settings</PanelTitle>
    <PanelDescription>Choose which updates to receive.</PanelDescription>
  </PanelHeader>
  <PanelContent>...</PanelContent>
</Panel>
```

## Popover (`popover`)

- Maturity: **candidate**
- Category: **overlay**
- Purpose: Opens compact information or controls beside the current context. / 현재 맥락 옆에 짧은 정보나 조작을 펼칩니다.
- Use: Use it for supporting tasks such as filters or compact settings. / 필터나 짧은 설정처럼 페이지 이동이 필요 없는 보조 작업에 씁니다.
- Avoid: Use Dialog, Alert Dialog, or Dropdown Menu for long forms, confirmations, or command lists. / 긴 폼, 중요한 확인, 단순 명령 목록에는 각각 Dialog, Alert Dialog, Dropdown Menu를 씁니다.
- Accessibility: Names the supporting surface and preserves Escape dismissal and focus restoration. / 제목과 설명으로 보조 화면의 목적을 알리고 Escape와 초점 복귀를 유지합니다.
- Related components: `dropdown-menu`, `dialog`, `tooltip`
- Dependencies: `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the trigger name predicts the content it opens. / 트리거 이름만으로 펼쳐질 내용을 예상할 수 있는지 확인합니다.
  - `open` [interactive]: Inspect viewport collision and keyboard movement. / 화면 가장자리 충돌과 키보드 이동을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `open` | `boolean` | No | The controlled open state. / 제어되는 열림 상태입니다. |
| `sideOffset` | `number` | No | The distance between trigger and surface. / 트리거와 표면 사이 간격입니다. |
| `align` | `"start" \| "center" \| "end"` | No | Alignment relative to the trigger. / 트리거 기준 정렬입니다. |

### Usage shape

```tsx
<Popover>
  <PopoverTrigger>Filters</PopoverTrigger>
  <PopoverContent>
    <PopoverTitle>Filters</PopoverTitle>
    <PopoverDescription>Narrow results.</PopoverDescription>
  </PopoverContent>
</Popover>
```

## Progress (`progress`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Shows measurable completion or an indeterminate connection state. / 측정 가능한 작업의 진행률이나 연결 중 상태를 보여줍니다.
- Use: Use it for uploads, processing, or synchronization that takes time. / 업로드, 처리, 동기화처럼 시간이 걸리는 작업의 상태에 씁니다.
- Avoid: Do not use it for instant actions or final success status. / 즉시 끝나는 동작이나 최종 성공 상태를 표시하는 데 쓰지 않습니다.
- Accessibility: Connects native progress with a visible label and never invents a numeric value. / native progress와 보이는 label을 연결하고 알 수 없는 값을 임의로 만들지 않습니다.
- Related components: `spinner`, `skeleton`, `status-label`
- States and inspection:
  - `determinate` [fixture]: Confirm current value, maximum, and displayed percentage agree. / 현재 값, 최대값과 표시 백분율이 일치하는지 확인합니다.
  - `indeterminate` [fixture]: Confirm pending progress is communicated without a false number. / 숫자 없이 진행 중 상태만 전달하는지 확인합니다.
  - `reduced-motion` [environment]: Confirm a Primary Blue segment remains visible without motion. / 움직임 없이도 Primary Blue 구간으로 상태가 보이는지 확인합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes | The visible name of the task in progress. / 진행 중인 작업의 보이는 이름입니다. |
| `value` | `number` | No | The current value; omit it for indeterminate progress. / 현재 진행값이며 생략하면 indeterminate 상태입니다. |
| `max` | `number` | No | The maximum value that represents completion. / 완료를 나타내는 최대값입니다. |
| `showValue` | `boolean` | No | Shows the calculated percentage as text. / 계산된 백분율을 문구로 표시합니다. |

### Usage shape

```tsx
<Progress label="Upload" value={50} max={200} showValue />
```

## Radio Group (`radio-group`)

- Maturity: **candidate**
- Category: **selection**
- Purpose: Selects exactly one value from a named group. / 한 그룹에서 하나의 값만 고릅니다.
- Use: Use it when a short list of options should stay visible for comparison. / 선택지가 적고 모두 한눈에 비교되어야 할 때 씁니다.
- Avoid: Use Native Select when space is tight or the list is long. / 공간이 좁거나 선택지가 많으면 Native Select를 씁니다.
- Accessibility: Keeps a named native radio set and communicates selection with square outer and inner indicators. / fieldset과 보이는 legend, native radio를 유지하며 선택은 바깥 사각형과 안쪽 사각형으로 함께 표시합니다.
- Related components: `checkbox`, `native-select`
- States and inspection:
  - `default` [fixture]: Inspect the legend and every option name. / legend와 모든 선택지 이름을 확인합니다.
  - `selected` [fixture]: Confirm only one option is selected at a time. / 한 번에 하나만 선택되는지 확인합니다.
  - `controlled` [interactive]: Confirm external value and change callback stay aligned. / 외부 value와 변경 콜백이 일치하는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `disabled` [fixture]: Inspect per-option and whole-group disabled states. / 개별 선택지와 전체 그룹 비활성 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `legend` | `ReactNode` | Yes | The visible name of the option group. / 선택지 그룹의 보이는 이름입니다. |
| `name` | `string` | Yes | The form name shared by all radio inputs. / 모든 radio가 공유하는 폼 이름입니다. |
| `options` | `readonly RadioOption[]` | Yes | Options containing value, label, description, and disabled state. / 값, 이름, 설명, 비활성 상태를 담은 선택지입니다. |
| `onValueChange` | `(value: string) => void` | No | Called when the selected value changes. / 선택값이 바뀔 때 호출합니다. |

### Usage shape

```tsx
<RadioGroup legend="Language" name="locale" options={options} />
```

## Segmented Control (`segmented-control`)

- Maturity: **candidate**
- Category: **selection**
- Purpose: Selects one value from two or more short options. / 둘 이상의 짧은 선택지 중 하나를 고릅니다.
- Use: Use it to switch short peer values such as locale, view, or status. / 언어, 보기 방식, 상태처럼 같은 수준의 짧은 값을 즉시 전환할 때 씁니다.
- Avoid: Use Radio Group or Select for verbose or numerous options. / 긴 설명이 필요하거나 선택지가 많으면 Radio Group이나 Select를 씁니다.
- Accessibility: Provides radiogroup and radio semantics, aria-checked, and arrow-key roving focus. / radiogroup과 radio 의미, aria-checked, 방향키 로빙 초점을 제공합니다.
- Related components: `radio-group`, `tabs`
- Dependencies: `motion`
- States and inspection:
  - `default` [fixture]: Confirm the named group and all options read as one control. / 이름 있는 그룹과 모든 선택지가 한 구조로 읽히는지 확인합니다.
  - `three-options` [fixture]: Confirm the selected surface fits three unequal labels. / 폭이 다른 세 선택지에서도 선택 면이 정확히 맞는지 확인합니다.
  - `focus-visible` [interactive]: Confirm arrow keys move focus and value to the next enabled option. / 방향키가 다음 활성 선택지로 초점과 값을 함께 옮기는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `selected` [fixture]: Confirm the selected surface and aria-checked change together. / 선택 면과 aria-checked가 함께 바뀌는지 확인합니다.
  - `disabled` [fixture]: Confirm pointer and keyboard navigation skip disabled options. / 비활성 선택지를 클릭과 방향키가 건너뛰는지 확인합니다.
  - `reduced-motion` [environment]: Keep selection immediately clear under reduced motion. / 동작 줄이기에서도 선택 상태는 즉시 분명해야 합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes | The accessible name for the option group. / 선택지 그룹의 접근성 이름입니다. |
| `value` | `Value` | Yes | The currently selected value. / 현재 선택한 값입니다. |
| `options` | `readonly SegmentedControlOption<Value>[]` | Yes | Two or more options with values, labels, content, and optional disabled state. / 값, 이름, 화면 내용, 비활성 상태를 담은 둘 이상의 선택지입니다. |
| `onValueChange` | `(value: Value) => void` | Yes | Called when the selected value changes. / 선택값이 바뀔 때 호출합니다. |

### Usage shape

```tsx
<SegmentedControl
  label="View"
  value={view}
  options={options}
  onValueChange={setView}
/>
```

## Select (`select`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Navigates a longer option list by keyboard or pointer. / 긴 선택 목록을 키보드와 포인터로 탐색합니다.
- Use: Use it when options need richer states and controlled popup placement. / native select보다 정교한 항목 상태와 팝업 배치가 필요할 때 씁니다.
- Avoid: Use Native Select for short lists or when the platform picker is preferable. / 선택지가 짧거나 모바일 native 선택 경험이 더 적합하면 Native Select를 씁니다.
- Accessibility: Provide a label and preserve arrow selection, disabled options, Escape dismissal, and focus return. / 레이블을 연결하고 방향키 선택, 비활성 항목, Escape 닫기와 초점 복귀를 유지합니다.
- Related components: `field`, `native-select`, `dropdown-menu`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `default` [fixture]: Confirm the current value and opening affordance are both visible. / 현재 값과 목록 열기 단서가 함께 보이는지 확인합니다.
  - `open` [interactive]: Inspect trigger-width sizing and viewport collision handling. / 목록 너비와 화면 충돌 처리가 자연스러운지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `disabled` [fixture]: Confirm disabled options remain readable and are skipped by navigation. / 비활성 항목을 건너뛰면서도 읽을 수 있는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | No | The controlled current value. / 제어되는 현재 값입니다. |
| `defaultValue` | `string` | No | The uncontrolled initial value. / 비제어 초기 값입니다. |
| `onValueChange` | `(value: string) => void` | No | Called when selection changes. / 선택이 바뀔 때 호출됩니다. |

### Usage shape

```tsx
<Select defaultValue="ko">
  <SelectTrigger aria-label="Language"><SelectValue /></SelectTrigger>
  <SelectContent>
    <SelectItem value="ko">한국어</SelectItem>
  </SelectContent>
</Select>
```

## Separator (`separator`)

- Maturity: **candidate**
- Category: **structure**
- Purpose: Creates a visual or semantic boundary between content. / 콘텐츠 사이의 시각적 또는 의미적 경계를 만듭니다.
- Use: Use it when spacing alone cannot distinguish rows or sections. / 간격만으로 관계를 구분하기 어려운 행과 구간 사이에 씁니다.
- Avoid: Do not box every element or repeat rules as decoration. / 모든 요소를 선으로 둘러싸거나 의미 없는 장식으로 반복하지 않습니다.
- Accessibility: Hide it by default and expose a separator only when the boundary carries meaning. / 기본은 장식으로 숨기고 구분 자체가 의미일 때만 separator로 노출합니다.
- Related components: `empty-state`
- States and inspection:
  - `decorative` [fixture]: Confirm the one-pixel rule is hidden from assistive technology. / 보조 기술에서 숨겨진 1px 선인지 확인합니다.
  - `horizontal` [fixture]: Confirm a meaningful horizontal boundary renders as hr. / 의미 있는 가로 경계가 hr로 노출되는지 확인합니다.
  - `vertical` [fixture]: Confirm vertical orientation is exposed semantically. / 세로 경계의 orientation이 전달되는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `decorative` | `boolean` | No | Defaults to true and hides the rule from assistive technology. / 기본값 true이며 보조 기술에서 숨깁니다. |
| `orientation` | `"horizontal" \| "vertical"` | No | The separator direction. / 선의 방향입니다. |

### Usage shape

```tsx
<Separator decorative={false} />
```

## Side Panel (`side-panel`)

- Maturity: **candidate**
- Category: **overlay**
- Purpose: Opens a larger workspace from a viewport edge without leaving the page. / 페이지 맥락을 유지한 채 가장자리에서 넓은 작업 공간을 엽니다.
- Use: Use it for settings, details, or editing that need more room than a Popover. / 설정, 상세 정보, 편집처럼 Popover보다 넓은 보조 작업에 씁니다.
- Avoid: Do not confine a primary page flow or complex multi-step task to a panel. / 핵심 페이지 흐름이나 여러 단계 작업을 패널에 가두지 않습니다.
- Accessibility: Preserves Dialog title, description, focus trap, Escape dismissal, and focus restoration. / Dialog의 제목, 설명, 초점 가두기, Escape 닫기와 초점 복귀를 유지합니다.
- Related components: `dialog`, `popover`, `panel`
- Dependencies: `@phosphor-icons/react`, `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the trigger clearly names the supporting task. / 트리거가 보조 작업임을 분명히 하는지 확인합니다.
  - `open` [interactive]: Inspect the page boundary, internal scroll, and close action. / 본문과 패널의 경계, 내부 스크롤과 닫기 동작을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | The viewport edge the panel enters from. / 패널이 들어오는 화면 가장자리입니다. |
| `closeLabel` | `string` | Yes | The accessible name for the close icon. / 닫기 아이콘의 접근 가능한 이름입니다. |
| `open` | `boolean` | No | The controlled open state. / 제어되는 열림 상태입니다. |

### Usage shape

```tsx
<SidePanel>
  <SidePanelTrigger>Settings</SidePanelTrigger>
  <SidePanelContent closeLabel="Close">
    <SidePanelTitle>Settings</SidePanelTitle>
    <SidePanelDescription>Manage the workspace.</SidePanelDescription>
  </SidePanelContent>
</SidePanel>
```

## Skeleton (`skeleton`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Reserves content structure while data is loading. / 콘텐츠 구조가 불러와지는 동안 자리를 유지합니다.
- Use: Use it for brief loading when the final layout shape is known. / 최종 레이아웃의 크기를 알고 짧게 기다릴 때 씁니다.
- Avoid: Do not replace progress feedback or an empty state with a skeleton. / 오래 걸리는 작업의 진행률이나 빈 상태를 대신하지 않습니다.
- Accessibility: Always hide it from assistive technology and announce loading separately. / 보조 기술에서는 항상 숨기고 별도 상태 문구로 로딩을 알립니다.
- Related components: `empty-state`
- States and inspection:
  - `loading` [fixture]: Confirm the placeholder matches the final content shape. / 최종 콘텐츠와 비슷한 크기로 배치되는지 확인합니다.
  - `reduced-motion` [environment]: Confirm it remains static when reduced motion is requested. / 동작 줄이기에서 정적인 면으로 남는지 확인합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `className` | `string` | No | Provides layout-specific size and placement. / 구체적인 플레이스홀더 크기와 배치에 씁니다. |
| `style` | `CSSProperties` | No | Sets a known final size directly. / 알려진 최종 크기를 직접 지정할 때 씁니다. |

### Usage shape

```tsx
<Skeleton style={{ height: 48 }} />
```

## Spinner (`spinner`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Signals indeterminate progress as one gap travels around a stationary square perimeter. / 고정된 사각 테두리를 따라 열린 구간이 흐르며 완료 시점을 알 수 없는 진행을 알립니다.
- Use: Use it inside a button or compact inline task. / 버튼이나 짧은 인라인 작업에서 잠시 기다릴 때 씁니다.
- Avoid: Use Progress for measurable work and Skeleton for page loading. / 진행률을 알 수 있거나 넓은 페이지 로딩에는 Progress나 Skeleton을 씁니다.
- Accessibility: Provides a named status and hides the stationary square track as presentation. / 이름 있는 status를 제공하고 하나의 사각 궤적은 장식으로 숨깁니다.
- Related components: `button`, `progress`, `skeleton`
- States and inspection:
  - `compact` [fixture]: Confirm the task name remains specific inside a button. / 버튼 안에서도 작업 이름이 구체적인지 확인합니다.
  - `default` [fixture]: Confirm the square remains fixed while its gap travels around the perimeter. / 사각형은 고정된 채 열린 구간만 테두리를 따라 흐르는지 확인합니다.
  - `reduced-motion` [environment]: Confirm one quiet gap communicates pending state without motion. / 움직임 없이도 하나의 열린 변으로 대기 상태가 보이는지 확인합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `string` | Yes | Names the pending task. / 진행 중인 작업의 접근 가능한 이름입니다. |
| `size` | `"compact" \| "default" \| "large"` | No | Sets the square indicator size. / 사각 표시 크기입니다. |

### Usage shape

```tsx
<Spinner label="Saving document" size="compact" />
```

## Status Label (`status-label`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Shows a real entity state with a small color square and concise text. / 작은 색상 사각형과 짧은 텍스트로 실제 개체 상태를 나타냅니다.
- Use: Use it for static document or media lifecycle metadata. / 문서나 미디어의 발행·처리 상태처럼 정적인 메타데이터에 씁니다.
- Avoid: Do not use it as an action, filter, long explanation, or live error. / 클릭 동작, 필터, 긴 설명이나 실시간 오류를 대신하지 않습니다.
- Accessibility: Always provide explicit status text that remains clear without color. / 색이 없어도 뜻이 분명한 텍스트를 반드시 제공합니다.
- Related components: `alert`, `panel`, `toast`
- States and inspection:
  - `neutral` [fixture]: Describe a neutral state such as Draft concisely. / 초안 같은 중립 상태를 짧은 문구로 표시합니다.
  - `info` [fixture]: Pair an in-progress state with explicit text. / 처리 중 상태를 정보 문구와 함께 표시합니다.
  - `success` [fixture]: Name the completed state explicitly. / 완료 상태를 구체적인 텍스트로 표시합니다.
  - `warning` [fixture]: Explain what state requires review. / 확인이 필요한 상태를 문구로 설명합니다.
  - `error` [fixture]: Label the failed state without replacing the error explanation. / 실패 상태를 오류 원인과 혼동하지 않게 짧게 표시합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "error"` | No | Sets the semantic color of the status square. / 상태 사각형의 의미 색상입니다. |
| `variant` | `"neutral" \| "info" \| "success" \| "warning" \| "error"` | No | Compatibility alias retained for one release. / 한 번의 호환 기간 동안 유지되는 별칭입니다. |
| `children` | `ReactNode` | Yes | Concise text that names the state. / 상태를 직접 설명하는 짧은 문구입니다. |

### Usage shape

```tsx
<StatusLabel tone="success">Published</StatusLabel>
```

## Switch (`switch`)

- Maturity: **candidate**
- Category: **selection**
- Purpose: Turns one immediately applied setting on or off. / 즉시 적용되는 하나의 설정을 켜고 끕니다.
- Use: Use it for a binary setting that takes effect immediately. / 변경 즉시 효력이 생기는 이진 설정에 씁니다.
- Avoid: Use Checkbox when consent is only committed on form submission. / 폼 제출 전까지 확정되지 않는 동의에는 Checkbox를 씁니다.
- Accessibility: Preserves native checkbox behavior and a stable label; tone applies only to the checked surface. / native checkbox 동작과 고정된 이름을 유지하며 tone은 켜진 상태에만 적용합니다.
- Related components: `checkbox`, `segmented-control`
- States and inspection:
  - `off` [fixture]: Confirm the setting remains clear while off. / 꺼짐 상태에서도 설정 이름이 분명한지 확인합니다.
  - `on` [fixture]: Confirm thumb position and native checked state change together. / thumb 위치와 native checked 상태가 함께 바뀌는지 확인합니다.
  - `focus-visible` [interactive]: Inspect the keyboard focus outline around the track. / 트랙 바깥의 키보드 초점선을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `disabled` [fixture]: Confirm the current value stays visible but cannot change. / 현재 값은 보이지만 바꿀 수 없는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `label` | `ReactNode` | Yes | A stable visible name for the setting. / 설정의 의미를 설명하는 고정된 이름입니다. |
| `description` | `ReactNode` | No | Supporting copy that explains the setting effect. / 설정 효과를 설명하는 보조 문구입니다. |
| `checked` | `boolean` | No | The current state in controlled mode. / 제어 모드의 현재 상태입니다. |
| `defaultChecked` | `boolean` | No | The initial state in uncontrolled mode. / 비제어 모드의 초기 상태입니다. |
| `tone` | `"primary" \| "success" \| "warning" \| "danger" \| "neutral"` | No | The semantic tone applied only to the checked track. / 켜진 트랙에만 적용되는 의미 색상입니다. |

### Usage shape

```tsx
<Switch label="Allow analytics" />
```

## Table (`table`)

- Maturity: **candidate**
- Category: **content**
- Purpose: Presents information that must be compared across native table rows and columns. / 열과 행으로 비교해야 하는 정보를 native table로 보여줍니다.
- Use: Use it to compare the same attributes, such as status, name, or date, across records. / 상태, 이름, 날짜처럼 같은 속성을 여러 항목에서 비교할 때 씁니다.
- Avoid: Use Item for one record's details or a list whose sequence matters more than column comparison. / 한 항목의 상세 정보나 작은 화면에서 순서만 중요한 목록에는 Item을 씁니다.
- Accessibility: Preserves native caption, thead, tbody, and scoped header semantics. / caption, thead, tbody, th scope 등 native 표 구조를 유지합니다.
- Related components: `data-table`, `item`, `separator`
- States and inspection:
  - `default` [fixture]: Confirm column headers and row values scan as one relationship. / 열 제목과 행의 대응 관계가 빠르게 읽히는지 확인합니다.
  - `overflow` [environment]: Confirm small screens scroll horizontally without breaking table semantics. / 작은 화면에서 표 의미를 유지한 채 가로 스크롤되는지 확인합니다. Inspection: Change the relevant system or browser setting to inspect this state. / 운영체제나 브라우저 설정을 바꾼 뒤 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `aria-label` | `string` | No | Names the table when no visible caption is present. / 보이는 caption이 없을 때 표의 이름을 제공합니다. |
| `align` | `"start" \| "center" \| "end"` | No | Aligns header and cell content. / 열 제목과 셀 내용의 정렬입니다. |
| `scope` | `string` | No | The row or column scope described by TableHead. / TableHead가 설명하는 행이나 열 범위입니다. |

### Usage shape

```tsx
<Table aria-label="Deployments">
  <TableHeader>
    <TableRow>
      <TableHead>Service</TableHead>
    </TableRow>
  </TableHeader>
  <TableBody>
    <TableRow>
      <TableCell>Laf ID</TableCell>
    </TableRow>
  </TableBody>
</Table>
```

## Tabs (`tabs`)

- Maturity: **candidate**
- Category: **disclosure**
- Purpose: Switches between peer panels within one context. / 같은 맥락의 패널을 한 번에 하나씩 전환합니다.
- Use: Use it for quickly switching between a few peer views. / 사용자가 같은 수준의 두세 보기를 빠르게 오갈 때 씁니다.
- Avoid: Do not use it for sequential steps or independent page navigation. / 순서가 있는 단계나 서로 독립된 페이지 이동에는 쓰지 않습니다.
- Accessibility: Preserves tablist, tab, tabpanel relationships and arrow-key roving focus. / tablist, tab, tabpanel 관계와 방향키 로빙 초점을 유지합니다.
- Related components: `segmented-control`, `accordion`
- Dependencies: `radix-ui`
- States and inspection:
  - `default` [fixture]: Confirm the initial panel is associated with the active tab. / 첫 패널과 활성 탭이 연결되는지 확인합니다.
  - `selected` [fixture]: Confirm the blue state rule and aria-selected change together. / 파란 상태선과 aria-selected가 함께 바뀌는지 확인합니다.
  - `disabled` [fixture]: Confirm arrow navigation skips disabled tabs. / 비활성 탭을 방향키가 건너뛰는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `value` | `string` | No | The controlled active tab value. / 제어되는 활성 탭 값입니다. |
| `defaultValue` | `string` | No | The uncontrolled initial tab value. / 비제어 초기 탭 값입니다. |
| `orientation` | `"horizontal" \| "vertical"` | No | The navigation orientation. / 탭의 탐색 방향입니다. |

### Usage shape

```tsx
<Tabs defaultValue="overview">
  <TabsList aria-label="Views">
    <TabsTrigger value="overview">Overview</TabsTrigger>
  </TabsList>
  <TabsContent value="overview">Content</TabsContent>
</Tabs>
```

## Text Link (`text-link`)

- Maturity: **stable**
- Category: **navigation**
- Purpose: A reusable link that pairs text with an arrow toward the next destination. / 텍스트와 화살표로 다음 목적지를 알립니다.
- Use: Use it at the end of a section or row for lightweight onward navigation. / 구간 끝이나 목록 행에서 다음 페이지를 가볍게 안내할 때 씁니다.
- Avoid: Do not use it for primary submission actions or icon-only controls. / 주요 제출 동작이나 아이콘만 있는 컨트롤에는 쓰지 않습니다.
- Accessibility: The link text must identify its destination; treat the arrow as decorative. / 링크 텍스트만 읽어도 목적지를 알 수 있어야 하며 화살표는 장식으로 처리합니다.
- Related components: `button-link`
- Dependencies: `@phosphor-icons/react`
- States and inspection:
  - `default` [fixture]: Inspect the real link's destination text, underline, and decorative arrow. / 실제 링크의 목적지 텍스트, 밑줄, 장식 화살표를 함께 확인합니다.
  - `hover` [interactive]: Hover the real link and inspect its Blue transition and arrow movement. / 실제 링크에 포인터를 올려 Blue 전환과 화살표 이동을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `focus-visible` [interactive]: Tab to the real link and inspect its outside focus outline. / Tab으로 실제 링크에 초점을 옮겨 외부 focus outline을 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `visited` [interactive]: Open the real link and return to inspect the deep-blue visited state without losing its destination meaning. / 실제 링크를 연 뒤 돌아와 deep blue 방문 상태가 목적지 의미를 유지하는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `href` | `string` | Yes | The internal or external destination. / 이동할 내부 또는 외부 주소입니다. |
| `children` | `ReactNode` | Yes | Text that identifies the destination. / 목적지를 설명하는 텍스트입니다. |

### Usage shape

```tsx
<TextLink href="/design/components">Components</TextLink>
```

## Textarea (`textarea`)

- Maturity: **candidate**
- Category: **form**
- Purpose: Accepts longer multiline text. / 여러 줄의 긴 텍스트를 입력받습니다.
- Use: Use it for values that need line breaks, such as inquiries or summaries. / 문의 내용이나 문서 요약처럼 줄바꿈이 필요한 값에 씁니다.
- Avoid: Do not use it as a code editor or for single-line values. / 코드 편집기나 한 줄 값에는 쓰지 않습니다.
- Accessibility: Associate a visible label and expose length guidance as a description when needed. / 보이는 레이블을 연결하고 필요하면 글자 수 안내를 설명으로 제공합니다.
- Related components: `field`, `label`, `input`
- States and inspection:
  - `default` [fixture]: Inspect the 132px minimum height and vertical resize. / 132px 최소 높이와 세로 크기 조절을 확인합니다.
  - `focus-visible` [interactive]: Confirm focus and width remain stable with long content. / 긴 글을 입력해도 초점선과 너비가 유지되는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `invalid` [fixture]: Confirm error copy is associated with the entered content. / 오류 문구가 입력 내용과 함께 읽히는지 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `rows` | `number` | No | The initial visible row count. / 초기 표시 줄 수입니다. |
| `name` | `string` | No | The name used for form submission. / 폼 제출에 쓰는 이름입니다. |

### Usage shape

```tsx
<Textarea name="message" rows={6} />
```

## Toast (`toast`)

- Maturity: **candidate**
- Category: **feedback**
- Purpose: Reports a brief result through one application-wide queue. / 현재 작업을 막지 않고 짧은 결과를 전역 큐로 알립니다.
- Use: Use it for brief save, upload, or undo outcomes. / 저장, 업로드, 되돌리기처럼 짧은 결과와 선택 동작에 씁니다.
- Avoid: Use Alert or Alert Dialog for persistent errors or required decisions. / 지속되는 오류나 반드시 결정해야 하는 내용에는 Alert나 Alert Dialog를 씁니다.
- Accessibility: Announces routine results as status, errors as alert, and localizes dismissal. / 일반 결과는 status, 오류는 alert로 알리고 번역된 닫기 이름을 제공합니다.
- Related components: `alert`, `status-label`, `spinner`
- Dependencies: `radix-ui`
- States and inspection:
  - `success` [interactive]: Describe the completed outcome in one sentence. / 완료 결과를 한 문장으로 설명합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `error` [interactive]: Keep errors visible longer and recovery copy concise. / 오류는 더 오래 표시하고 복구 설명은 짧게 유지합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `action` [interactive]: Offer one supporting action such as Undo. / 되돌리기 같은 한 가지 보조 동작만 제공합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `queued` [interactive]: Queue notifications beyond the three visible items. / 세 개를 넘는 알림은 앞선 알림이 닫힐 때까지 대기합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.
  - `persistent` [interactive]: Use duration zero only for deliberate persistence. / duration 0은 사용자가 직접 닫을 때까지 유지합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `show` | `(options: ToastOptions) => string` | Yes | Shows a toast or updates a matching stable ID. / 알림을 표시하거나 같은 ID를 갱신합니다. |
| `duration` | `number` | No | Sets auto-dismiss time; zero persists. / 자동 닫기 시간이며 0이면 유지됩니다. |
| `tone` | `"neutral" \| "info" \| "success" \| "warning" \| "error"` | No | Sets the result tone. / 알림 결과의 의미입니다. |
| `action` | `{ label: string; onClick: () => void }` | No | Provides one optional action. / 한 가지 선택 동작입니다. |

### Usage shape

```tsx
const toast = useToast();
toast.success("Saved", { description: "Changes are live." })
```

## Tooltip (`tooltip`)

- Maturity: **candidate**
- Category: **overlay**
- Purpose: Provides a short supporting description on hover and focus. / 짧은 보조 설명을 hover와 focus에 제공합니다.
- Use: Use it to clarify controls whose visible name, such as an icon, is insufficient. / 아이콘처럼 보이는 이름만으로 뜻이 부족한 컨트롤을 보완할 때 씁니다.
- Avoid: Do not rely on it for essential information, long copy, or touch-only actions. / 필수 정보, 긴 설명, 터치만으로 접근해야 하는 행동에 의존하지 않습니다.
- Accessibility: Opens on keyboard focus as well as hover and is associated as the trigger description. / hover뿐 아니라 keyboard focus에서도 열리고 트리거 설명으로 연결됩니다.
- Related components: `button`
- Dependencies: `radix-ui`
- States and inspection:
  - `closed` [fixture]: Confirm the trigger keeps an accessible name without the tooltip. / 툴팁 없이도 트리거 이름이 남는지 확인합니다.
  - `open` [interactive]: Confirm concise copy stays in the viewport without obscuring the trigger. / 짧은 문장이 화면 안에 배치되고 트리거를 가리지 않는지 확인합니다. Inspection: Use the preview control to inspect this state. / 미리보기 컨트롤을 직접 조작해 이 상태를 확인합니다.

### Props

| Name | Type | Required | Description |
| --- | --- | --- | --- |
| `delayDuration` | `number` | No | Provider delay before opening on hover, in milliseconds. / Provider가 hover 열림 지연을 밀리초로 정합니다. |
| `side` | `"top" \| "right" \| "bottom" \| "left"` | No | The preferred placement side. / 우선 배치 방향입니다. |
| `sideOffset` | `number` | No | The distance from the trigger. / 트리거와의 간격입니다. |

### Usage shape

```tsx
<TooltipProvider>
  <Tooltip>
    <TooltipTrigger aria-label="Status">●</TooltipTrigger>
    <TooltipContent>Operational</TooltipContent>
  </Tooltip>
</TooltipProvider>
```