@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.4

package/src/components/SegmentedProgressBar/SegmentedProgressBar.usage.mdx

@@ -0,0 +1,145 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SegmentedProgressBarStories from './SegmentedProgressBar.stories';
+
+<Meta of={SegmentedProgressBarStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SegmentedProgressBar
+
+One bar split into parts of a single whole, such as messages sent, failed and
+still to go.
+
+## When to use
+
+- A batch job with more than one outcome: sent and failed, accepted and
+  rejected.
+- A total split into two or three parts the reader compares at a glance.
+
+## When not to use
+
+- A single value against a limit → `ProgressBar`.
+- Many categories, or a share of storage or budget → `RadialProgress` with a
+  legend, or a table.
+
+## How it works
+
+- `<SegmentedProgressBar max={total}>` draws the `bg.track` remainder; each
+  `<ProgressSegment value={n} filledTrackColor="…" />` inside it takes
+  `n / max` of the width, in order.
+- `height` defaults to 16px; pass `height` for a slimmer bar.
+
+</En>
+
+<Ko>
+
+# SegmentedProgressBar
+
+보낸 메시지, 실패한 메시지, 남은 메시지처럼 하나의 전체를 이루는 부분을 막대 하나에
+나눠 보여 줍니다.
+
+## 언제 쓰나요
+
+- 결과가 둘 이상인 일괄 작업: 보냄과 실패, 승인과 거절.
+- 전체를 두세 부분으로 나눠 한눈에 비교할 때.
+
+## 언제 쓰지 않나요
+
+- 한도에 대한 값 하나는 `ProgressBar`를 씁니다.
+- 분류가 많거나 저장 공간, 예산의 비율이라면 범례를 붙인 `RadialProgress`나 표를
+  씁니다.
+
+## 동작 방식
+
+- `<SegmentedProgressBar max={total}>`이 `bg.track` 바탕을 그리고, 그 안의
+  `<ProgressSegment value={n} filledTrackColor="…" />`가 차례대로 폭의 `n / max`만큼
+  차지합니다.
+- 높이 기본값은 16px입니다. 더 얇게 하려면 `height`를 넘깁니다.
+
+</Ko>
+
+<ArgTypes of={SegmentedProgressBarStories} include={['max', 'height']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SegmentedProgressBarStories.DoCountsInText} />
+<Verdict
+  kind="do"
+  en="Write each count next to the bar and colour the failure count's text too. Hide the bar itself from screen readers (aria-hidden) when the text says everything."
+  ko="부분별 개수를 막대 옆에 글자로 쓰고, 실패 개수는 글자에도 색을 입힙니다. 글자가 모든 정보를 전한다면 막대는 화면 낭독기에서 숨깁니다(aria-hidden)."
+/>
+
+<Canvas of={SegmentedProgressBarStories.DontColourOnly} />
+<Verdict
+  kind="dont"
+  en="Show the segments with no words. Green and red are the only way to tell them apart, and each segment is announced as a full progress bar."
+  ko="글자 없이 세그먼트만 보여 주지 마세요. 초록과 빨강 말고는 구분할 방법이 없고, 세그먼트마다 꽉 찬 진행 막대로 읽힙니다."
+/>
+
+<En>
+
+## Accessibility
+
+- **Each segment is announced as a separate, full progress bar.**
+  `ProgressSegment` is a `ProgressBar` with `max` set to its own `value`, so a
+  screen reader hears "100%" once per segment, and the container has no role
+  or name. Until that changes, put the counts in text and set `aria-hidden` on
+  the bar (WCAG 1.3.1, 4.1.2).
+- **Words, not colour alone** (WCAG 1.4.1).
+- Status colours (`success.solid`, `danger.solid`) only when the parts are
+  outcomes; other parts take `primary.main` or category tokens. Use tokens,
+  not hex.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- **세그먼트마다 따로, 꽉 찬 진행 막대로 읽힙니다.** `ProgressSegment`는 `max`를 자기
+  `value`로 정한 `ProgressBar`라서, 화면 낭독기는 세그먼트마다 "100%"라고 읽습니다.
+  바깥 요소에는 역할도 이름도 없습니다. 이 문제가 고쳐질 때까지는 개수를 글자로 쓰고
+  막대에 `aria-hidden`을 붙입니다(WCAG 1.3.1, 4.1.2).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1).
+- 부분이 작업 결과일 때만 상태색(`success.solid`, `danger.solid`)을 씁니다. 그 밖의
+  부분은 `primary.main`이나 category 토큰을 씁니다. 16진수가 아니라 토큰을 씁니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SegmentedProgressBarStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **ProgressBar**: one value against a limit.
+- **RadialProgress**: a share split into categories.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **ProgressBar**: 한도에 대한 값 하나.
+- **RadialProgress**: 분류별로 나눈 비율.
+
+</Ko>

package/src/components/Select/Select.stories.tsx

@@ -9,11 +9,21 @@ import {
   Stack,
   Text,
 } from '@chakra-ui/react';
-import { Meta } from '@storybook/react';
+import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Badge } from '../Badge';
+import { Radio, RadioGroup } from '../Radio';
 import { IoCall, IoChatbubbleEllipses, IoIosMail } from '../Icon';
+import { ComboboxField } from './ComboboxField';
 import { Select } from './Select';
+import {
+  contentStyles,
+  indicatorStyles,
+  itemStyles,
+  triggerStyles,
+} from './Select.styles';
 import { SelectField } from './SelectField';
 
 const meta = {
@@ -771,3 +781,201 @@ export const WithOpenChange = () => {
     </HStack>
   );
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Select.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+type UsageStory = StoryObj;
+
+const LANGUAGES = [
+  { label: '한국어', value: 'ko' },
+  { label: 'English', value: 'en' },
+  { label: '日本語', value: 'ja' },
+];
+
+const GROUPS = [
+  '경영지원팀',
+  '고객성공팀',
+  '데이터팀',
+  '디자인팀',
+  '마케팅팀',
+  '백엔드팀',
+  '법무팀',
+  '보안팀',
+  '사업개발팀',
+  '세일즈팀',
+  '인사팀',
+  '재무팀',
+  '프론트엔드팀',
+].map((name) => ({ label: name, value: name }));
+
+export const DoLabelled: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a visible label',
+  render: () => (
+    <Box maxW="320px">
+      <SelectField label="답변 언어" options={LANGUAGES} defaultValue="ko" />
+    </Box>
+  ),
+};
+
+export const DontNameless: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: no label, ariaLabel or placeholder",
+  render: () => (
+    <Flex maxW="480px" align="center" justify="space-between" gap={4}>
+      <Text fontWeight="semibold">답변 언어</Text>
+      <Box w="180px">
+        <SelectField options={LANGUAGES} defaultValue="ko" />
+      </Box>
+    </Flex>
+  ),
+};
+
+export const DoComboboxForLongList: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ComboboxField for a long list',
+  render: () => (
+    <Box maxW="320px">
+      <ComboboxField
+        label="그룹"
+        placeholder="그룹 이름으로 찾기"
+        options={GROUPS}
+        emptyText="일치하는 그룹이 없습니다"
+      />
+    </Box>
+  ),
+};
+
+export const DontSelectForTwo: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a dropdown for two options",
+  render: () => (
+    <Box maxW="320px">
+      <SelectField
+        label="공개 범위"
+        options={[
+          { label: '전체 공개', value: 'public' },
+          { label: '그룹만', value: 'group' },
+        ]}
+        defaultValue="public"
+      />
+    </Box>
+  ),
+};
+
+export const DoRadioForTwo: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: Radio for two visible options',
+  render: () => (
+    <Stack gap={2} maxW="320px">
+      <Text id="usage-visibility" fontWeight="semibold">
+        공개 범위
+      </Text>
+      <RadioGroup
+        defaultValue="public"
+        aria-labelledby="usage-visibility"
+        display="flex"
+        gap={4}
+      >
+        <Radio value="public">
+          <Radio.Control />
+          <Radio.Text>전체 공개</Radio.Text>
+        </Radio>
+        <Radio value="group">
+          <Radio.Control />
+          <Radio.Text>그룹만</Radio.Text>
+        </Radio>
+      </RadioGroup>
+    </Stack>
+  ),
+};
+
+/**
+ * Tokens the trigger, list and options read, taken from the style objects in
+ * `Select.styles.ts` (shared by Select and Combobox).
+ */
+export const UsageTokens: UsageStory = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: triggerStyles.bg,
+          use: <T en="Trigger background" ko="트리거 배경" />,
+        },
+        {
+          token: triggerStyles.color,
+          use: <T en="Selected value" ko="선택한 값" />,
+        },
+        {
+          token: triggerStyles.borderColor,
+          use: <T en="Trigger border at rest" ko="트리거 평소 테두리" />,
+        },
+        {
+          token: triggerStyles._hover.borderColor,
+          use: <T en="Border on hover" ko="마우스를 올렸을 때 테두리" />,
+        },
+        {
+          token: triggerStyles._focus.borderColor,
+          use: (
+            <T
+              en="Border and ring on focus or open"
+              ko="초점을 받거나 열렸을 때 테두리와 링"
+            />
+          ),
+        },
+        {
+          token: triggerStyles._invalid.borderColor,
+          use: <T en="Border when invalid" ko="오류 상태 테두리" />,
+        },
+        {
+          token: triggerStyles._disabled.bg,
+          use: <T en="Disabled background" ko="비활성 배경" />,
+        },
+        {
+          token: triggerStyles._disabled.color,
+          use: <T en="Disabled text" ko="비활성 글자" />,
+        },
+        {
+          token: indicatorStyles.color,
+          use: <T en="Chevron" ko="펼침 화살표" />,
+        },
+        {
+          token: contentStyles.bg,
+          use: <T en="List background" ko="목록 배경" />,
+        },
+        {
+          token: contentStyles.borderColor,
+          use: <T en="List border" ko="목록 테두리" />,
+        },
+        {
+          token: itemStyles._highlighted.bg,
+          use: (
+            <T
+              en="Option under the pointer or keyboard"
+              ko="포인터나 키보드가 가리키는 항목"
+            />
+          ),
+        },
+        {
+          token: itemStyles._checked.bg,
+          use: <T en="Selected option" ko="선택된 항목" />,
+        },
+        {
+          token: itemStyles._disabled.color,
+          use: <T en="Disabled option" ko="선택할 수 없는 항목" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Select/Select.usage.mdx

@@ -0,0 +1,278 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SelectStories from './Select.stories';
+import { SelectField } from './SelectField';
+
+<Meta of={SelectStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Select, SelectField, Combobox, ComboboxField
+
+Pick one value from a list that is too long to show in full. `SelectField` and
+`ComboboxField` are ready-made fields; `Select` and `Combobox` are the styled
+parts for building your own.
+
+| Component       | Use it for                                                                           |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `SelectField`   | One value from a short, fixed list. Pass `options`, `value`, `onChange`.             |
+| `ComboboxField` | One value from a long list the user would rather search than scroll.                 |
+| `Select.*`      | Multi-select, grouped options, options with icons or descriptions, a custom trigger. |
+| `Combobox.*`    | A searchable list with groups or custom rows.                                        |
+
+## When to use
+
+- Five or more options, or options that would crowd the page if shown at once:
+  a language, a model, a role.
+- A setting in a dense list where each row ends in a choice: `SelectField`
+  with `variant="ghost"`.
+- A list the user searches by name, such as groups or members:
+  `ComboboxField`.
+
+## When not to use
+
+- Two to four options that fit on screen → `Radio`, so the user sees every
+  option without opening anything. A single on/off → `Switch` or `Checkbox`.
+- Switching the view of the same content → `SegmentedControl` or `Tabs`.
+- Running an action (Rename, Delete) → `Menu`. A select holds a value; a menu
+  does something.
+- Free text with suggestions the user may ignore → `Input`.
+
+## Variants and props
+
+</En>
+
+<Ko>
+
+# Select, SelectField, Combobox, ComboboxField
+
+다 펼쳐 보이기에는 긴 목록에서 값 하나를 고르게 합니다. `SelectField`와
+`ComboboxField`는 바로 쓰는 필드이고, `Select`와 `Combobox`는 직접 조합할 때 쓰는
+스타일이 입혀진 부품입니다.
+
+| 컴포넌트        | 쓰는 곳                                                                  |
+| --------------- | ------------------------------------------------------------------------ |
+| `SelectField`   | 짧고 정해진 목록에서 값 하나. `options`, `value`, `onChange`를 넘깁니다. |
+| `ComboboxField` | 스크롤보다 검색이 편한 긴 목록에서 값 하나.                              |
+| `Select.*`      | 여러 개 선택, 묶은 항목, 아이콘이나 설명이 붙은 항목, 직접 만든 트리거.  |
+| `Combobox.*`    | 묶음이나 직접 만든 행이 있는 검색 목록.                                  |
+
+## 언제 쓰나요
+
+- 선택지가 다섯 개 이상이거나, 한꺼번에 보이면 화면이 복잡해질 때: 언어, 모델, 역할.
+- 행마다 끝에 선택이 하나씩 있는 촘촘한 설정 목록: `variant="ghost"`인 `SelectField`.
+- 이름으로 찾는 목록(그룹, 멤버): `ComboboxField`.
+
+## 언제 쓰지 않나요
+
+- 화면에 다 들어가는 두세 개의 선택지는 `Radio`를 씁니다. 아무것도 열지 않고 모든
+  선택지를 볼 수 있습니다. 켜고 끄는 값 하나는 `Switch`나 `Checkbox`를 씁니다.
+- 같은 내용의 보기 방식을 바꿀 때는 `SegmentedControl`이나 `Tabs`를 씁니다.
+- 이름 바꾸기, 삭제 같은 동작은 `Menu`를 씁니다. 셀렉트는 값을 담고, 메뉴는 일을
+  합니다.
+- 제안을 무시하고 자유롭게 써도 되는 텍스트는 `Input`을 씁니다.
+
+## 변형과 속성
+
+</Ko>
+
+<ArgTypes
+  of={SelectField}
+  include={['variant', 'label', 'ariaLabel', 'placeholder', 'stagger']}
+/>
+
+<En>
+
+| Variant             | Means                                                                                      | Use for                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `outline` (default) | A bordered field, the same as `Input`. Width defaults to `full`.                           | Forms, modals, filters                                                                             |
+| `ghost`             | No border until hover or focus; sized to its value. An invalid field keeps its red border. | The trailing choice in a settings row, where a column of bordered triggers would outweigh the card |
+
+Other props: `size` (`xs`–`lg`, default `md`), `invalid`, `disabled`,
+`readOnly`, `required`, `name`, `width`. `onChange` receives the value, or
+`null` when the selection is cleared. `ComboboxField` adds `emptyText`; it has
+no `variant` or `stagger`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형             | 뜻                                                                                                                            | 쓰는 곳                                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `outline` (기본) | `Input`과 같은 테두리가 있는 필드. 너비 기본값은 `full`입니다.                                                                | 폼, 모달, 필터                                                                       |
+| `ghost`          | 마우스를 올리거나 초점을 받기 전에는 테두리가 없고, 값 길이에 맞춰 너비가 정해집니다. 오류 상태에서는 빨간 테두리가 남습니다. | 설정 목록의 행 끝 선택. 테두리 있는 트리거가 줄지어 있으면 카드보다 무거워 보이는 곳 |
+
+그 밖의 속성: `size`(`xs`~`lg`, 기본 `md`), `invalid`, `disabled`, `readOnly`,
+`required`, `name`, `width`. `onChange`는 고른 값을 받고, 선택을 지우면 `null`을
+받습니다. `ComboboxField`에는 `emptyText`가 더 있고, `variant`와 `stagger`는
+없습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SelectStories.DoLabelled} />
+<Verdict
+  kind="do"
+  en="Give the field a visible label with the label prop. It is rendered as the part the trigger is named by."
+  ko="label 속성으로 보이는 라벨을 붙입니다. 라벨은 트리거의 이름이 되는 부품으로 그려집니다."
+/>
+
+<Canvas of={SelectStories.DontNameless} />
+<Verdict
+  kind="dont"
+  en="Leave out label, ariaLabel and placeholder. The text next to it is not connected, so a screen reader announces a bare 'button', whatever the value says (KWCAG 5.3.4.1)."
+  ko="label, ariaLabel, placeholder를 모두 빼지 마세요. 옆에 있는 글자는 연결되지 않으므로, 화면 낭독기는 값이 무엇이든 그냥 '버튼'이라고만 읽습니다(KWCAG 5.3.4.1)."
+/>
+
+<Canvas of={SelectStories.Ghost} />
+<Verdict
+  kind="do"
+  en="In a settings list, use the ghost variant and pass the row title as ariaLabel."
+  ko="설정 목록에서는 ghost 변형을 쓰고, 행 제목을 ariaLabel로 넘깁니다."
+/>
+
+<Canvas of={SelectStories.DoComboboxForLongList} />
+<Verdict
+  kind="do"
+  en="Use ComboboxField when the user knows the name and the list is long. Translate emptyText; the default is English."
+  ko="사용자가 이름을 알고 목록이 길다면 ComboboxField를 씁니다. emptyText의 기본값은 영어이므로 번역해서 넘깁니다."
+/>
+
+<Canvas of={SelectStories.DontSelectForTwo} />
+<Verdict
+  kind="dont"
+  en="Hide two options behind a dropdown. The user has to open it to learn there is only one alternative."
+  ko="선택지 두 개를 드롭다운 안에 숨기지 마세요. 다른 선택지가 하나뿐이라는 것을 열어 봐야 압니다."
+/>
+
+<Canvas of={SelectStories.DoRadioForTwo} />
+<Verdict
+  kind="do"
+  en="Show a few options as Radio, so the choice is visible at a glance."
+  ko="선택지가 몇 개뿐이면 Radio로 펼쳐서 한눈에 보이게 합니다."
+/>
+
+<En>
+
+## Content
+
+- Label: a noun for what is chosen (답변 언어, 역할), not an instruction (언어를
+  선택하세요).
+- Placeholder: only when "nothing chosen yet" is a real state. It also becomes
+  the hidden name if there is no label, so make it meaningful, but prefer
+  `label` or `ariaLabel`.
+- Options: short, parallel, sentence case, sorted in a predictable order
+  (frequency, size, or alphabetical). Do not repeat the label in each option.
+- `emptyText` on `ComboboxField`: say what was not found (일치하는 그룹이
+  없습니다).
+
+## Accessibility
+
+What these components do for you:
+
+- **A name, if you give one.** `SelectField` and `ComboboxField` always render
+  the label part the trigger points at: visibly for `label`, visually hidden
+  for `ariaLabel` (or `placeholder` as a fallback). The name is in the server
+  markup, not added after hydration (KWCAG 5.3.4.1 레이블 제공).
+- **Keyboard.** The Chakra / Zag listbox handles it: Enter, Space or the arrow
+  keys open the list; arrows move; Enter selects; Escape closes and returns
+  focus to the trigger. In `ComboboxField` typing filters the list.
+- **Focus and states.** The trigger shows a `primary.main` border and ring on
+  focus and while open (WCAG 2.4.7). The selected option is bold on
+  `primary.selected` and carries a check mark, so it does not rely on colour
+  alone (WCAG 1.4.1).
+
+What you still have to do:
+
+- **Always pass `label` or `ariaLabel`.** Inside `FieldRow`, the row's label
+  does not reach the trigger: pass the same text as `ariaLabel`. The type does
+  not stop you from leaving all three out.
+- **Compose `Select.*` / `Combobox.*` with a `Label` part.** Leave it out and
+  the trigger has no name. When the label is elsewhere on screen, render
+  `<Select.Label srOnly>`.
+- Put errors in words (`FieldRow` `error`) as well as `invalid` (WCAG 3.3.1).
+
+## Tokens
+
+Generated from `Select.styles.ts`. Select and Combobox share these.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨: 고르는 대상을 명사로 씁니다(답변 언어, 역할). "언어를 선택하세요" 같은 지시문은
+  쓰지 않습니다.
+- 플레이스홀더: "아직 고르지 않음"이 실제로 있는 상태일 때만 씁니다. 라벨이 없으면
+  숨은 이름으로도 쓰이므로 뜻이 통하게 쓰되, 되도록 `label`이나 `ariaLabel`을 씁니다.
+- 선택지: 짧고 같은 형식으로 쓰며, 자주 쓰는 순, 크기순, 가나다순처럼 예측할 수 있는
+  순서로 둡니다. 선택지마다 라벨을 되풀이하지 않습니다.
+- `ComboboxField`의 `emptyText`: 무엇을 찾지 못했는지 씁니다(일치하는 그룹이
+  없습니다).
+
+## 접근성
+
+이 컴포넌트들이 알아서 하는 일
+
+- **이름을 주면 그대로 씁니다.** `SelectField`와 `ComboboxField`는 트리거가 가리키는
+  라벨 부품을 항상 그립니다. `label`이면 보이게, `ariaLabel`(없으면 `placeholder`)이면
+  시각적으로 숨겨서 그립니다. 이름은 하이드레이션 뒤에 붙는 것이 아니라 서버가 보낸
+  마크업 안에 있습니다(KWCAG 5.3.4.1 레이블 제공).
+- **키보드.** Chakra와 Zag의 목록 상자가 처리합니다. Enter, Space, 방향키로 목록을
+  열고, 방향키로 옮기고, Enter로 고르며, Escape로 닫으면 초점이 트리거로 돌아갑니다.
+  `ComboboxField`에서는 입력하면 목록이 걸러집니다.
+- **초점과 상태.** 트리거는 초점을 받거나 열려 있는 동안 `primary.main` 테두리와 링을
+  보여 줍니다(WCAG 2.4.7). 선택된 항목은 `primary.selected` 위에 굵은 글자와 체크
+  표시로 나타나므로 색에만 기대지 않습니다(WCAG 1.4.1).
+
+직접 챙겨야 하는 일
+
+- **`label`이나 `ariaLabel`을 반드시 넘깁니다.** `FieldRow` 안에서는 행의 라벨이
+  트리거까지 닿지 않으므로 같은 글자를 `ariaLabel`로 넘깁니다. 셋 다 빠뜨려도 타입
+  검사에서 걸리지 않습니다.
+- **`Select.*`나 `Combobox.*`로 조합할 때는 `Label` 부품을 넣습니다.** 빼면 트리거에
+  이름이 없습니다. 라벨이 화면의 다른 곳에 있다면 `<Select.Label srOnly>`를 씁니다.
+- 오류는 `invalid`와 함께 `FieldRow`의 `error`로 문구를 보여 줍니다(WCAG 3.3.1).
+
+## 토큰
+
+`Select.styles.ts`에서 자동으로 만듭니다. Select와 Combobox가 함께 씁니다.
+
+</Ko>
+
+<Canvas of={SelectStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Radio**: a few options, all visible.
+- **Switch** / **Checkbox**: on or off.
+- **SegmentedControl** / **Tabs**: switching views.
+- **Menu**: actions, not values.
+- **FieldRow**: label, helper and error around the field.
+- More compositions: the _Multi Select_, _Grouped Options_ and _Custom Items_
+  stories under Components/Select and Components/Combobox.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Radio**: 몇 개 안 되는 선택지를 모두 보여 줄 때.
+- **Switch** / **Checkbox**: 켜고 끄는 값.
+- **SegmentedControl** / **Tabs**: 보기 전환.
+- **Menu**: 값이 아니라 동작.
+- **FieldRow**: 필드를 둘러싼 라벨, 도움말, 오류 문구.
+- 조합 예시: Components/Select와 Components/Combobox 아래의 _Multi Select_,
+  _Grouped Options_, _Custom Items_ 스토리.
+
+</Ko>