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

package/src/components/Table/Table.usage.mdx

@@ -0,0 +1,235 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TableStories from './Table.stories';
+import { Tr } from './Tr';
+
+<Meta of={TableStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Table
+
+Rows of records that share the same columns, for reading and comparing
+values: members, usage, invoices, API keys.
+
+`TableContainer` › `Table` › `Thead` / `Tbody` › `Tr` › `Th` / `Td`. The
+container draws the rounded border, scrolls horizontally, and tracks scroll
+position for sticky columns.
+
+## When to use
+
+- A list where each item has the same attributes and the reader compares
+  across rows: a member list, usage by model, call history.
+- When the reader scans a column (a date, an amount, a status).
+
+## When not to use
+
+- Items that are read one at a time and have different shapes → `Card` in a
+  list or grid.
+- Two to five label–value pairs about one thing → a plain stack of `Text`.
+- A hierarchy (groups inside groups) → `Tree`.
+- Page layout. A table is for data only.
+
+## Row states and options
+
+</En>
+
+<Ko>
+
+# Table
+
+같은 열을 가진 기록을 행으로 늘어놓고 값을 읽고 비교하게 하는 컴포넌트입니다.
+멤버, 사용량, 청구서, API 키 목록에 씁니다.
+
+구조는 `TableContainer` › `Table` › `Thead` / `Tbody` › `Tr` › `Th` / `Td`입니다.
+컨테이너가 둥근 테두리를 그리고, 가로 스크롤을 맡고, 고정 열을 위해 스크롤 위치를
+추적합니다.
+
+## 언제 쓰나요
+
+- 항목마다 같은 속성이 있고 행끼리 비교해 읽는 목록: 멤버 목록, 모델별 사용량, 호출
+  기록.
+- 읽는 사람이 한 열(날짜, 금액, 상태)을 훑어볼 때.
+
+## 언제 쓰지 않나요
+
+- 하나씩 읽는 항목이고 모양이 서로 다르다면 목록이나 격자 안의 `Card`를 씁니다.
+- 한 대상의 라벨과 값 두세 쌍이라면 `Text`를 쌓아서 보여 줍니다.
+- 그룹 안의 그룹 같은 계층은 `Tree`를 씁니다.
+- 페이지 레이아웃에는 쓰지 않습니다. 표는 데이터에만 씁니다.
+
+## 행 상태와 옵션
+
+</Ko>
+
+<ArgTypes of={Tr} include={['state']} />
+
+<En>
+
+| Option | Means | Use for |
+| --- | --- | --- |
+| `<Tr state="selected">` | The row is part of the current selection (`primary.selected`) | Rows ticked for a bulk action |
+| `<Tr state="invalid">` | Something in the row is wrong (`bg.invalid.subtle`) | A failed import row |
+| `<Tr state="highlighted">` | Draw the eye to one row (`bg.highlighted`) | The row just added or edited |
+| `onClick` / `tabIndex` / `role="button"` on `Tr` | The row is clickable; it gets the pointer, `primary.wash` hover and a focus outline | Opening a detail drawer |
+| `<Thead sticky>` | The header stays at the top of the scroll area | Long lists in a fixed-height container |
+| `isSticky` + `stickyDirection` + `stickyIndex` on `Th`/`Td` | The column stays put while the table scrolls sideways | A name column on a wide table |
+| `Td wrap` | Long text wraps instead of being cut off | Addresses, descriptions |
+| `ExpandingTr` | A row with a detail row under it, opened by `isExpanded` | Error details for one row |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 옵션 | 뜻 | 쓰는 곳 |
+| --- | --- | --- |
+| `<Tr state="selected">` | 현재 선택에 포함된 행(`primary.selected`) | 일괄 작업을 위해 체크한 행 |
+| `<Tr state="invalid">` | 행 안의 무언가가 잘못됨(`bg.invalid.subtle`) | 가져오기에 실패한 행 |
+| `<Tr state="highlighted">` | 한 행으로 눈길을 끎(`bg.highlighted`) | 방금 추가하거나 고친 행 |
+| `Tr`의 `onClick` / `tabIndex` / `role="button"` | 누를 수 있는 행. 포인터, `primary.wash` 호버, 초점 테두리가 생김 | 상세 서랍 열기 |
+| `<Thead sticky>` | 스크롤해도 머리글이 위에 남음 | 높이가 정해진 영역 안의 긴 목록 |
+| `Th`/`Td`의 `isSticky` + `stickyDirection` + `stickyIndex` | 표를 옆으로 스크롤해도 그 열은 그대로 있음 | 넓은 표의 이름 열 |
+| `Td wrap` | 긴 글을 자르지 않고 줄바꿈함 | 주소, 설명 |
+| `ExpandingTr` | 아래에 상세 행이 붙은 행. `isExpanded`로 엶 | 한 행의 오류 상세 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TableStories.DoNumbersAligned} />
+<Verdict
+  kind="do"
+  en="Put a real link in the name cell, and align numbers to the end with tabular figures so they line up."
+  ko="이름 칸에는 실제 링크를 두고, 숫자는 끝에 맞추고 고정폭 숫자를 써서 자릿수가 맞게 합니다."
+/>
+
+<Canvas of={TableStories.DoStateWithWords} />
+<Verdict
+  kind="do"
+  en="Back a row state with words in a cell. The tint draws the eye; the Badge says what is wrong."
+  ko="행 상태는 칸 안의 문구로 함께 알립니다. 배경색은 눈길을 끌고, Badge가 무엇이 잘못됐는지 말합니다."
+/>
+
+<Canvas of={TableStories.DontStateColourOnly} />
+<Verdict
+  kind="dont"
+  en="Rely on the row tint alone. A screen reader does not announce it, and in some modes it is hard to see at all."
+  ko="행 배경색만으로 알리지 마세요. 화면 낭독기는 배경색을 읽지 않고, 모드에 따라 거의 보이지 않기도 합니다."
+/>
+
+<En>
+
+## Content
+
+- Column headers are short nouns: 이름, 그룹, 사용 크레딧. Put the unit in
+  the header, not in every cell.
+- Numbers and amounts align to the end (`textAlign="end"`); text aligns to the
+  start.
+- An empty value is "—", not a blank cell, so the reader knows nothing is
+  missing from the page.
+- Keep a status in its own column with a `Badge`, rather than colouring a
+  whole row.
+
+## Accessibility
+
+What Table does for you:
+
+- It renders native table elements (`<table>`, `<th>`, `<td>`), so screen
+  readers announce row and column positions.
+- A clickable `Tr` gets a pointer, a hover tint and a 2px inset focus
+  outline when focused from the keyboard. Static rows never highlight.
+- Sticky header and sticky columns get an opaque background, so text never
+  shows through.
+
+What you still have to do:
+
+- **A clickable row is not a button by itself.** `Tr` only styles it. Give
+  it `tabIndex={0}` and handle Enter in `onKeyDown` (WCAG 2.1.1), or better,
+  put a real link or button in the row and let that be the target (WCAG
+  4.1.2). Never put a button inside a row that is also `role="button"`
+  (nested interactive controls, see `ACCESSIBILITY.md` §3).
+- **Row states need words** (WCAG 1.4.1). `state` only tints the row.
+- **Name icon-only buttons in cells**: `aria-label` on the `IconButton`
+  (WCAG 4.1.2). For an `ExpandingTr` toggle, also pass `aria-expanded`.
+- Give the table a caption or a heading next to it so it has a name
+  (WCAG 1.3.1).
+- A cell cut off with an ellipsis hides content. Use `wrap`, or make the full
+  value available another way (WCAG 1.4.10).
+
+## Tokens
+
+Read from the table slot recipe (`theme/recipes/table.ts`) and the sticky
+styles in `Table.styles.ts`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 열 머리글은 짧은 명사로 씁니다: 이름, 그룹, 사용 크레딧. 단위는 칸마다 쓰지 않고
+  머리글에 씁니다.
+- 숫자와 금액은 끝에 맞추고(`textAlign="end"`), 글은 앞에 맞춥니다.
+- 값이 없으면 빈칸 대신 "—"를 써서, 화면에서 빠진 것이 없다는 것을 알립니다.
+- 상태는 행 전체에 색을 칠하지 않고 `Badge`로 따로 열을 둡니다.
+
+## 접근성
+
+Table이 알아서 하는 일
+
+- 기본 표 요소(`<table>`, `<th>`, `<td>`)로 그리므로 화면 낭독기가 행과 열의 위치를
+  읽어 줍니다.
+- 누를 수 있는 `Tr`에는 포인터, 호버 배경, 키보드 초점 시 안쪽 2px 테두리가 생깁니다.
+  누를 수 없는 행은 강조되지 않습니다.
+- 고정 머리글과 고정 열은 불투명한 배경을 가지므로 뒤의 글자가 비치지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **누를 수 있는 행이 저절로 버튼이 되지는 않습니다.** `Tr`은 모양만 바꿉니다.
+  `tabIndex={0}`를 주고 `onKeyDown`에서 Enter를 처리하거나(WCAG 2.1.1), 행 안에 실제
+  링크나 버튼을 두고 그것을 누르게 하는 편이 낫습니다(WCAG 4.1.2). `role="button"`인
+  행 안에 다시 버튼을 넣지 않습니다(상호작용 요소 중첩, `ACCESSIBILITY.md` 3절).
+- **행 상태는 문구로도 알립니다**(WCAG 1.4.1). `state`는 배경색만 바꿉니다.
+- **칸 안의 아이콘 버튼에는 이름을 붙입니다.** `IconButton`에 `aria-label`을 줍니다
+  (WCAG 4.1.2). `ExpandingTr`을 여닫는 버튼에는 `aria-expanded`도 줍니다.
+- 표에 캡션을 달거나 옆에 제목을 두어 이름을 붙입니다(WCAG 1.3.1).
+- 말줄임표로 잘린 칸은 내용을 숨깁니다. `wrap`을 쓰거나 전체 값을 다른 방법으로
+  볼 수 있게 합니다(WCAG 1.4.10).
+
+## 토큰
+
+표 슬롯 레시피(`theme/recipes/table.ts`)와 `Table.styles.ts`의 고정 열 스타일에서
+읽습니다.
+
+</Ko>
+
+<Canvas of={TableStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Badge**: a status in its own column.
+- **Pagination**: long lists split into pages.
+- **Checkbox**: row selection for bulk actions, with `state="selected"`.
+- **Tree**: hierarchical data.
+- **Card**: items with different shapes.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Badge**: 따로 둔 열의 상태 표시.
+- **Pagination**: 긴 목록을 쪽으로 나눕니다.
+- **Checkbox**: 일괄 작업을 위한 행 선택. `state="selected"`와 함께 씁니다.
+- **Tree**: 계층이 있는 데이터.
+- **Card**: 모양이 서로 다른 항목.
+
+</Ko>

package/src/components/Tabs/Tab/Tab.styles.ts

@@ -31,7 +31,7 @@ export const verticalStyles = {
  * The indicator moves with the label, EXCEPT on 5.0's BAZE palette: the
  * indicator is a 2px underline — a GRAPHIC judged at 3:1, not text at 4.5:1 —
  * so it reads the brand accent `primary.main` directly (black in light, the
- * inverted cream fill in dark), matching the house gallery spec. The label
+ * inverted off-white fill in dark), matching the house gallery spec. The label
  * stays on `fg.emphasized` (= `fg.default`): it is still a PLACE, not a
  * value, and `primary.main` in dark mode is a solid-fill colour tuned for a
  * button face under `fg.onPrimary`, not for text on the page.

package/src/components/Tabs/Tabs.stories.tsx

@@ -2,7 +2,10 @@ import { useState } from 'react';
 import { Button, CloseButton, Heading, Text } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Tab } from '@/components/Tabs/Tab/Tab';
+import { TAB_RAMP } from '@/components/Tabs/Tab/Tab.styles';
 import { TabList } from '@/components/Tabs/TabList';
 import { TabPanel } from '@/components/Tabs/TabPanel';
 import { TabPanels } from '@/components/Tabs/TabPanels';
@@ -260,3 +263,86 @@ export const DynamicTabs: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Tabs.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`).
+
+export const DoSectionsOfOnePlace: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: sections of one place, with a named list',
+  render: () => (
+    <Tabs defaultValue="credit">
+      <TabList aria-label="그룹 설정">
+        <Tab value="credit">크레딧</Tab>
+        <Tab value="security">보안</Tab>
+        <Tab value="notice">공지</Tab>
+      </TabList>
+      <TabPanel value="credit" pt={4}>
+        <Text>이 그룹의 월간 크레딧 한도와 사용량입니다.</Text>
+      </TabPanel>
+      <TabPanel value="security" pt={4}>
+        <Text>로그인과 파일 업로드 정책입니다.</Text>
+      </TabPanel>
+      <TabPanel value="notice" pt={4}>
+        <Text>이 그룹에만 보이는 공지입니다.</Text>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+export const DontTabsAsSteps: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: tabs as the steps of a flow",
+  render: () => (
+    <Tabs defaultValue="step1">
+      <TabList>
+        <Tab value="step1">1. 기본 정보</Tab>
+        <Tab value="step2">2. 모델 선택</Tab>
+        <Tab value="step3">3. 확인</Tab>
+      </TabList>
+      <TabPanel value="step1" pt={4}>
+        <Text>이름과 설명을 입력하세요.</Text>
+      </TabPanel>
+      <TabPanel value="step2" pt={4}>
+        <Text>모델을 고르세요.</Text>
+      </TabPanel>
+      <TabPanel value="step3" pt={4}>
+        <Text>입력한 내용을 확인하세요.</Text>
+      </TabPanel>
+    </Tabs>
+  ),
+};
+
+/** Tokens a tab reads: the selected ramp from `TAB_RAMP` in `Tab.styles.ts`, the rest from `Tab.tsx` and `TabList.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: TAB_RAMP.label,
+          use: <T en="Selected tab · label" ko="선택된 탭 · 글자" />,
+        },
+        {
+          token: TAB_RAMP.indicator,
+          use: <T en="Selected tab · indicator" ko="선택된 탭 · 표시 막대" />,
+        },
+        {
+          token: 'fg.muted',
+          use: <T en="Other tabs · label" ko="다른 탭 · 글자" />,
+        },
+        { token: 'primary.wash', use: <T en="Hover" ko="마우스 올림" /> },
+        {
+          token: 'bg.muted',
+          use: <T en="Vertical · selected fill" ko="세로 탭 · 선택 배경" />,
+        },
+        { token: 'border.subtle', use: <T en="List rule" ko="목록 아래 선" /> },
+      ]}
+    />
+  ),
+};

package/src/components/Tabs/Tabs.usage.mdx

@@ -0,0 +1,263 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TabsStories from './Tabs.stories';
+
+<Meta of={TabsStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Tabs
+
+A row (or column) of labels that switches between sections of the same place.
+One section shows at a time.
+
+## When to use
+
+- To split one object's settings or data into sections: a group's 크레딧,
+  보안 and 공지; a chatbot's 설정 and 분석.
+- To switch between dashboards of the same scope, such as usage by model and
+  usage by user.
+- For a long settings page in a side panel, with `orientation="vertical"`.
+
+## When not to use
+
+- To change how the same content is shown, or to filter it (일/주/월, 목록/카드)
+  → `SegmentedControl`. Tabs change _what_ you are looking at, not how.
+- For the steps of a flow the user must complete in order → a stepper or a
+  sequence of pages. Tabs let the user jump ahead.
+- For destinations or filters, such as the side navigation of an area or a
+  filter rail beside a list, and for a list that is long or keeps growing, or
+  whose rows carry counts or icons → `NavList`. Tabs own their panels, move
+  with the arrow keys and mark the choice with `aria-selected`; a rail is
+  links or filters, reached with Tab.
+- To show where this page sits in a hierarchy → `Breadcrumb`.
+- For two or three short panels the user needs side by side → show them on
+  the page.
+
+## Which component
+
+Tabs and `NavList` both mark one row as current; they say the same thing from
+opposite sides. Pick by what the rows are:
+
+| What you have                                                    | Use                                                                                          |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
+| A few sections of one object that swap a panel in place          | `Tabs`                                                                                       |
+| Destinations, or the side navigation of an area                  | `NavList`, each item with `href`                                                             |
+| A filter over one list or grid, with many options or with counts | `NavList`: links (`href`) when the filter state is in the URL, buttons (`onClick`) otherwise |
+| A short horizontal switch of two to five options                 | `SegmentedControl`                                                                           |
+| A hierarchy the user expands and collapses                       | `Tree`                                                                                       |
+| Commands (초대하기, 내보내기)                                    | `Button`, or a `Menu` when there are several                                                 |
+
+## Variants and what they mean
+
+Tabs has one look. A selected tab is a _place_, not a value, so it is marked
+with ink and weight, not with a brand or status colour. `orientation` decides
+the layout:
+
+</En>
+
+<Ko>
+
+# Tabs
+
+같은 곳의 여러 구역을 오가게 하는 라벨 한 줄(또는 한 열)입니다. 한 번에 한 구역만
+보입니다.
+
+## 언제 쓰나요
+
+- 한 대상의 설정이나 데이터를 구역으로 나눌 때: 그룹의 크레딧·보안·공지, 챗봇의 설정·분석.
+- 같은 범위의 대시보드 여러 개를 오갈 때: 모델별 사용량, 사용자별 사용량.
+- 사이드 패널의 긴 설정 화면을 나눌 때는 `orientation="vertical"`을 씁니다.
+
+## 언제 쓰지 않나요
+
+- 같은 내용을 보는 방식을 바꾸거나 거를 때(일/주/월, 목록/카드)는 `SegmentedControl`을
+  씁니다. 탭은 무엇을 보는지를 바꾸고, 어떻게 보는지를 바꾸지 않습니다.
+- 차례대로 끝내야 하는 흐름의 단계에는 단계 표시나 이어지는 페이지를 씁니다. 탭은 사용자가
+  단계를 건너뛰게 둡니다.
+- 다른 곳으로 옮겨 가는 항목이나 필터(한 영역의 옆 내비게이션, 목록 옆의 필터 레일)는
+  `NavList`가 맡습니다. 항목이 많거나 계속 늘어나는 목록, 항목에 개수나 아이콘이 붙는
+  목록도 `NavList`를 씁니다. 탭은 패널을 갖고, 방향키로 옮기며, 고른 것을
+  `aria-selected`로 알립니다. 레일은 링크나 필터이고 Tab 키로 오갑니다.
+- 이 페이지가 계층의 어디에 있는지 보여 줄 때는 `Breadcrumb`를 씁니다.
+- 나란히 봐야 하는 짧은 패널 두세 개는 탭에 숨기지 말고 페이지에 그대로 보입니다.
+
+## 어떤 컴포넌트를 쓰나요
+
+Tabs와 `NavList`는 둘 다 항목 하나를 현재 항목으로 표시합니다. 두 문서는 같은 기준을 서로
+반대쪽에서 설명합니다. 항목이 무엇인지를 보고 고릅니다.
+
+| 이런 경우                                                            | 쓰는 컴포넌트                                                            |
+| -------------------------------------------------------------------- | ------------------------------------------------------------------------ |
+| 한 대상의 구역 몇 개를 그 자리에서 패널로 바꿔 보여 줄 때            | `Tabs`                                                                   |
+| 다른 곳으로 옮겨 가는 항목, 한 영역의 옆 내비게이션                  | 항목마다 `href`를 준 `NavList`                                           |
+| 목록이나 그리드 하나를 거르는 필터로, 선택지가 많거나 개수를 붙일 때 | `NavList`. 필터 상태가 URL에 있으면 링크(`href`), 아니면 버튼(`onClick`) |
+| 선택지 둘에서 다섯 개를 가로로 짧게 바꿀 때                          | `SegmentedControl`                                                       |
+| 펼치고 접는 계층                                                     | `Tree`                                                                   |
+| 명령(초대하기, 내보내기)                                             | `Button`, 여러 개라면 `Menu`                                             |
+
+## 변형과 뜻
+
+Tabs의 모양은 하나입니다. 선택된 탭은 값이 아니라 지금 있는 곳이므로, 브랜드색이나
+상태색이 아니라 진한 글자와 굵기로 표시합니다. 배치는 `orientation`이 정합니다.
+
+</Ko>
+
+<ArgTypes
+  of={TabsStories}
+  include={['orientation', 'defaultValue', 'value', 'activationMode']}
+/>
+
+<En>
+
+| `orientation`          | Selected tab                                                             | Use for                                      |
+| ---------------------- | ------------------------------------------------------------------------ | -------------------------------------------- |
+| `horizontal` (default) | `fg.emphasized` label, semibold, with a 2px `primary.main` underline     | Sections across the top of a page or panel   |
+| `vertical`             | `bg.muted` fill, bold, with a 2px `primary.main` bar on the leading edge | A long settings page in a narrow side column |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| `orientation`       | 선택된 탭                                                             | 쓰는 곳                      |
+| ------------------- | --------------------------------------------------------------------- | ---------------------------- |
+| `horizontal` (기본) | `fg.emphasized` 글자를 semibold로 쓰고 아래에 2px `primary.main` 밑줄 | 페이지나 패널 위쪽의 구역    |
+| `vertical`          | `bg.muted` 배경에 bold, 앞쪽 가장자리에 2px `primary.main` 막대       | 좁은 옆 열에 둔 긴 설정 화면 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TabsStories.DoSectionsOfOnePlace} />
+<Verdict
+  kind="do"
+  en="Use short nouns for sections of one place, and name the list with aria-label ('그룹 설정')."
+  ko="한 곳의 구역에는 짧은 명사를 쓰고, 탭 목록에 aria-label('그룹 설정')로 이름을 붙입니다."
+/>
+
+<Canvas of={TabsStories.DontTabsAsSteps} />
+<Verdict
+  kind="dont"
+  en="Number tabs as the steps of a flow. Nothing stops the user from opening step 3 first."
+  ko="탭에 번호를 붙여 흐름의 단계로 쓰지 마세요. 사용자가 3단계를 먼저 열어도 막을 방법이 없습니다."
+/>
+
+<En>
+
+## Content
+
+- One or two words, a noun: "크레딧", "보안", "사용자별". No full stop and no
+  icons alone.
+- Keep labels the same length class; one long label next to short ones reads as
+  a different kind of tab.
+- Stay under about six horizontal tabs. More than that, use `vertical` or split
+  the page; if the rows are places or filters, use `NavList`.
+- Do not put a count in the label unless it changes what the user does next.
+
+## Accessibility
+
+What Tabs does for you:
+
+- `TabList` is `role="tablist"`, each `Tab` is `role="tab"` with
+  `aria-selected`, and each `TabPanel` is `role="tabpanel"` labelled by its tab
+  (WCAG 4.1.2).
+- Keyboard (WCAG 2.1.1): `Tab` lands on the selected tab and then moves on; the
+  arrow keys move between tabs and wrap at the ends, `Home` / `End` jump to the
+  first and last. With the default `activationMode="automatic"` the panel
+  changes as focus moves.
+- Each `Tab` is a `Button`, so it shows the focus ring (WCAG 2.4.7). The
+  selected label is `fg.emphasized`, at least 13:1 on every surface it can land
+  on (WCAG 1.4.3), and the underline is a second cue beside weight (WCAG
+  1.4.1).
+
+What you still have to do:
+
+- **Name the list.** Pass `aria-label` to `TabList` when there is no visible
+  heading right above it, or `aria-labelledby` pointing at the heading.
+- Give every `Tab` and `TabPanel` the same `value`. Both throw without one.
+- Put only phrasing content inside a `Tab`: it renders a `<button>`, so no
+  `<div>` or `<p>` inside (KWCAG 5.4.1.1, see `ACCESSIBILITY.md`).
+- If switching a panel is slow (it fetches data), use
+  `activationMode="manual"` so arrowing across the list does not fire a request
+  per tab.
+
+## Tokens
+
+The selected ramp is `TAB_RAMP` in `Tab.styles.ts`; the other tokens are set in
+`Tab.tsx` and `TabList.tsx`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한두 단어의 명사로 씁니다. "크레딧", "보안", "사용자별". 마침표를 찍지 않고, 아이콘만
+  두지 않습니다.
+- 라벨 길이를 비슷하게 맞춥니다. 짧은 라벨 사이의 긴 라벨 하나는 다른 종류의 탭처럼
+  보입니다.
+- 가로 탭은 여섯 개 안쪽으로 둡니다. 더 많으면 `vertical`을 쓰거나 페이지를 나눕니다.
+  항목이 곳이나 필터라면 `NavList`를 씁니다.
+- 다음 행동을 바꾸는 경우가 아니면 라벨에 개수를 넣지 않습니다.
+
+## 접근성
+
+Tabs가 알아서 하는 일
+
+- `TabList`는 `role="tablist"`, 각 `Tab`은 `aria-selected`가 붙은 `role="tab"`, 각
+  `TabPanel`은 자기 탭으로 이름이 붙는 `role="tabpanel"`입니다(WCAG 4.1.2).
+- 키보드(WCAG 2.1.1): `Tab`을 누르면 선택된 탭에 닿고, 한 번 더 누르면 목록을 벗어납니다. 방향키로 탭 사이를
+  옮기고 끝에서는 처음으로 돌아가며, `Home`/`End`로 처음과 끝으로 갑니다. 기본값인
+  `activationMode="automatic"`에서는 초점이 옮겨 가면 패널도 바뀝니다.
+- 각 `Tab`은 `Button`이라 초점 테두리가 보입니다(WCAG 2.4.7). 선택된 글자는
+  `fg.emphasized`로, 놓일 수 있는 어느 면에서도 13:1 이상입니다(WCAG 1.4.3). 굵기 말고도
+  밑줄이 한 번 더 알려 줍니다(WCAG 1.4.1).
+
+직접 챙겨야 하는 일
+
+- **탭 목록에 이름을 붙입니다.** 바로 위에 보이는 제목이 없다면 `TabList`에
+  `aria-label`을, 제목이 있다면 그 제목을 가리키는 `aria-labelledby`를 넘깁니다.
+- 모든 `Tab`과 `TabPanel`에 짝이 맞는 `value`를 줍니다. 없으면 둘 다 오류를 냅니다.
+- `Tab` 안에는 phrasing content만 넣습니다. `<button>`으로 그려지므로 안에 `<div>`나
+  `<p>`를 넣지 않습니다(KWCAG 5.4.1.1, `ACCESSIBILITY.md` 참고).
+- 패널을 바꿀 때 데이터를 불러와 느리다면 `activationMode="manual"`을 씁니다. 그래야
+  방향키로 탭을 훑을 때마다 요청이 나가지 않습니다.
+
+## 토큰
+
+선택 상태의 색은 `Tab.styles.ts`의 `TAB_RAMP`에서, 나머지 토큰은 `Tab.tsx`와
+`TabList.tsx`에서 정합니다.
+
+</Ko>
+
+<Canvas of={TabsStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **NavList**: destinations and filters, such as side navigation and filter
+  rails.
+- **SegmentedControl**: change how the same content is shown.
+- **Breadcrumb**: where this page sits in a hierarchy.
+- **Foundations/Brand & colour usage**: why a selected place is ink, not
+  colour.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **NavList**: 다른 곳으로 옮겨 가는 항목과 필터. 옆 내비게이션, 필터 레일.
+- **SegmentedControl**: 같은 내용을 보는 방식 바꾸기.
+- **Breadcrumb**: 이 페이지가 계층의 어디에 있는지.
+- **Foundations/Brand & colour usage**: 선택된 곳을 색이 아니라 진한 글자로 표시하는
+  이유.
+
+</Ko>