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

package/src/components/Icon/Icon.usage.mdx

@@ -0,0 +1,158 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as IconStories from './Icon.stories';
+
+<Meta of={IconStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Icon
+
+The icon set: named exports such as `DownloadIcon`, `TrashIcon` and
+`CheckIcon`, wrapped from react-icons and custom SVGs with `createIcon`.
+Every icon takes `boxSize` (`2xs` 14px, `xs` 16px, `sm` 20px, `md` 24px
+default, `lg` 32px, `xl` 40px) and paints `currentColor`, so it takes the
+text colour around it unless you pass `color`.
+
+## When to use
+
+- To help recognise an action or item next to its label.
+- Inside an `IconButton`, where the button carries the name.
+
+## When not to use
+
+- As the only way to say something (a status, an error) → words, with the
+  icon as support (`Badge`, `Banner`).
+- As a decorative illustration → an image.
+- A new icon from another set inline at the call site → add it to the set
+  (see `ICON_MANAGEMENT.md`) so every app gets the same one.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Icon
+
+아이콘 모음입니다. `DownloadIcon`, `TrashIcon`, `CheckIcon` 같은 이름으로 내보내며,
+react-icons와 직접 만든 SVG를 `createIcon`으로 감쌌습니다. 모든 아이콘은
+`boxSize`(`2xs` 14px, `xs` 16px, `sm` 20px, 기본 `md` 24px, `lg` 32px, `xl` 40px)를 받고
+`currentColor`로 칠하므로, `color`를 넘기지 않으면 주변 글자색을 따릅니다.
+
+## 언제 쓰나요
+
+- 라벨 옆에서 동작이나 항목을 알아보기 쉽게 할 때.
+- `IconButton` 안에서. 이름은 버튼이 가집니다.
+
+## 언제 쓰지 않나요
+
+- 아이콘만으로 무언가(상태, 오류)를 알리지 않습니다. 문구를 쓰고 아이콘은 거들게
+  합니다(`Badge`, `Banner`).
+- 장식용 그림에는 이미지를 씁니다.
+- 다른 아이콘 모음의 아이콘을 호출부에서 바로 쓰지 않습니다. 모든 앱이 같은 아이콘을
+  쓰도록 모음에 추가합니다(`ICON_MANAGEMENT.md` 참고).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={IconStories.DoIconWithLabel} />
+<Verdict
+  kind="do"
+  en="Next to a label the icon is decorative (aria-hidden). On its own, the IconButton carries the name (aria-label)."
+  ko="라벨 옆의 아이콘은 장식이므로 aria-hidden을 붙입니다. 아이콘만 있다면 IconButton이 이름(aria-label)을 가집니다."
+/>
+
+<Canvas of={IconStories.DontIconAsStatus} />
+<Verdict
+  kind="dont"
+  en="Use a green check and a red cross as the only status. Without words the meaning rests on colour and shape alone."
+  ko="초록 체크와 빨간 X만으로 상태를 알리지 마세요. 문구가 없으면 색과 모양에만 뜻이 실립니다."
+/>
+
+<En>
+
+## Content
+
+- Use the same icon for the same action everywhere (`TrashIcon` is always
+  delete).
+- Match the icon size to the text: `xs` beside body text and small buttons,
+  `sm`–`md` on their own.
+
+## Accessibility
+
+What Icon does for you:
+
+- It renders an inline SVG in `currentColor`, so it follows the text colour
+  in light, dark and high-contrast modes.
+
+What you still have to do:
+
+- **Mark decorative icons `aria-hidden`.** The icon does not hide itself.
+- **Name icon-only controls** with `aria-label` on the button (WCAG 4.1.2),
+  and keep the label the same as any visible tooltip (WCAG 2.5.3).
+- **Icons do not replace words** (WCAG 1.4.1). A standalone icon that means
+  something needs at least 3:1 against its background (WCAG 1.4.11);
+  `fg.icon` is tuned for that.
+
+## Tokens
+
+The icon paints `currentColor`; these are the roles to set when you pass
+`color`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 같은 동작에는 어디서나 같은 아이콘을 씁니다(`TrashIcon`은 언제나 삭제).
+- 아이콘 크기는 글자에 맞춥니다. 본문과 작은 버튼 옆에는 `xs`, 아이콘만 있을 때는
+  `sm`–`md`를 씁니다.
+
+## 접근성
+
+Icon이 알아서 하는 일
+
+- `currentColor`로 칠하는 인라인 SVG라서 라이트, 다크, 고대비 모드에서 글자색을
+  따릅니다.
+
+직접 챙겨야 하는 일
+
+- **장식 아이콘에는 `aria-hidden`을 붙입니다.** 아이콘이 스스로 숨지 않습니다.
+- **아이콘만 있는 컨트롤에는 버튼에 `aria-label`로 이름을 붙이고**(WCAG 4.1.2), 보이는
+  툴팁이 있다면 같은 말을 씁니다(WCAG 2.5.3).
+- **아이콘이 문구를 대신하지 않습니다**(WCAG 1.4.1). 뜻을 가진 아이콘이 혼자 있다면
+  바탕과 3:1 이상이어야 하며(WCAG 1.4.11), `fg.icon`이 그 기준에 맞춰져 있습니다.
+
+## 토큰
+
+아이콘은 `currentColor`로 칠합니다. 아래는 `color`를 넘길 때 쓰는 역할입니다.
+
+</Ko>
+
+<Canvas of={IconStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **IconButton**: an icon-only control with a name.
+- **Badge** / **Banner**: status in words, with an icon as support.
+- `ICON_MANAGEMENT.md`: adding an icon to the set.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **IconButton**: 이름이 있는 아이콘 전용 컨트롤.
+- **Badge** / **Banner**: 아이콘이 거드는 문구 상태.
+- `ICON_MANAGEMENT.md`: 아이콘 추가 방법.
+
+</Ko>

package/src/components/IconButton/IconButton.stories.tsx

@@ -1,8 +1,21 @@
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Grid, HStack, Text, VStack } from '@chakra-ui/react';
-import { FaUniversity, SendIcon, TrashIcon } from '../Icon';
-import { IconButton, iconButtonVariants } from '.';
+import { Box, Flex, Grid, HStack, Text, VStack } from '@chakra-ui/react';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import {
+  CopyIcon,
+  DownloadIcon,
+  EditIcon,
+  FaUniversity,
+  PlusIcon,
+  SendIcon,
+  ShareIcon,
+  TrashIcon,
+} from '../Icon';
+import { Tooltip } from '../Tooltip';
+import { IconButton, iconButtonVariants, iconButtonVariantStyles } from '.';
 import { IconButtonVariant } from './IconButton.types';
 
 const meta = {
@@ -16,11 +29,13 @@ const meta = {
     variant: {
       control: 'select',
       options: iconButtonVariants,
-      description: 'Role. Default `ghost`.',
+      description:
+        'Role. `ghost` (default): toolbars and row actions, glyph in `fg.icon`. `secondary`: ghost with an outline, for a control that must read as a button on its own. `primary`: black fill, the one main icon action. `danger`: red fill, confirms a destructive step. `action`: the coral send button of a chat composer.',
     },
     isDestructive: {
       control: 'boolean',
-      description: 'Danger icon on ghost / secondary',
+      description:
+        'Danger-coloured glyph (`danger.fg`) on `ghost` / `secondary`, for a delete icon in a row. Ignored on filled roles.',
     },
     children: {
       table: { disable: true },
@@ -121,3 +136,192 @@ export const ActionSend: Story = {
     </HStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `IconButton.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+/** A chat message's action row: copy, edit, share, delete. */
+export const DoGhostToolbar: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: ghost icon buttons in a toolbar',
+  render: () => (
+    <HStack gap={1}>
+      <Tooltip content="복사">
+        <IconButton aria-label="복사" size="sm">
+          <CopyIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="수정">
+        <IconButton aria-label="수정" size="sm">
+          <EditIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="공유">
+        <IconButton aria-label="공유" size="sm">
+          <ShareIcon />
+        </IconButton>
+      </Tooltip>
+      <Tooltip content="삭제">
+        <IconButton aria-label="삭제" size="sm" isDestructive>
+          <TrashIcon />
+        </IconButton>
+      </Tooltip>
+    </HStack>
+  ),
+};
+
+export const DontFilledToolbar: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: filled icon buttons in a toolbar",
+  render: () => (
+    <HStack gap={1}>
+      <IconButton aria-label="복사" size="sm" variant="primary">
+        <CopyIcon />
+      </IconButton>
+      <IconButton aria-label="수정" size="sm" variant="primary">
+        <EditIcon />
+      </IconButton>
+      <IconButton aria-label="공유" size="sm" variant="primary">
+        <ShareIcon />
+      </IconButton>
+      <IconButton aria-label="삭제" size="sm" variant="danger">
+        <TrashIcon />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+/** A chat composer: the coral send button is the one run signal. */
+export const DoActionForSend: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: action only for send',
+  render: () => (
+    <Flex
+      align="center"
+      gap={2}
+      maxW="420px"
+      px={4}
+      py={2}
+      borderWidth="1px"
+      borderColor="border.default"
+      borderRadius="xl"
+      bg="bg.surface"
+    >
+      <Tooltip content="파일 첨부">
+        <IconButton aria-label="파일 첨부" size="sm">
+          <PlusIcon />
+        </IconButton>
+      </Tooltip>
+      <Text flex={1} fontSize="sm" color="fg.default">
+        지난달 사용량을 요약해 줘
+      </Text>
+      <IconButton aria-label="보내기" size="sm" variant="action">
+        <SendIcon />
+      </IconButton>
+    </Flex>
+  ),
+};
+
+export const DontActionForAdd: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the coral action button for a non-send action",
+  render: () => (
+    <Flex align="center" justify="space-between" maxW="420px">
+      <Text fontWeight="bold" color="fg.default">
+        멤버
+      </Text>
+      <IconButton aria-label="멤버 추가" size="sm" variant="action">
+        <PlusIcon />
+      </IconButton>
+    </Flex>
+  ),
+};
+
+export const DoTextWhenUnclear: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a labelled Button when the icon is not obvious',
+  render: () => (
+    <Box>
+      <Button variant="secondary" size="sm">
+        <DownloadIcon />
+        사용 내역 내려받기
+      </Button>
+    </Box>
+  ),
+};
+
+export const DontUnclearIcon: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: an icon only you can read",
+  render: () => (
+    <HStack gap={1}>
+      <IconButton aria-label="사용 내역 내려받기" variant="secondary" size="sm">
+        <FaUniversity />
+      </IconButton>
+    </HStack>
+  ),
+};
+
+type StateStyles = {
+  bgColor?: unknown;
+  borderColor?: unknown;
+  color?: unknown;
+  _hover?: { bgColor?: unknown; color?: unknown };
+  _active?: { bgColor?: unknown };
+};
+
+type Use = { en: string; ko: string };
+
+/**
+ * One row per token, listing every role and state that reads it. Read from
+ * `iconButtonVariantStyles`, so a recipe change shows up on the next build.
+ */
+const iconButtonTokenRows = () => {
+  const uses = new Map<string, Use[]>();
+  const add = (token: unknown, use: Use) => {
+    if (typeof token !== 'string' || token === 'transparent') return;
+    uses.set(token, [...(uses.get(token) ?? []), use]);
+  };
+  iconButtonVariants.forEach((variant) => {
+    const s = iconButtonVariantStyles[variant] as StateStyles;
+    const at = (en: string, ko: string) => ({
+      en: `${variant} ${en}`,
+      ko: `${variant} ${ko}`,
+    });
+    add(s.bgColor, at('fill', '바탕'));
+    add(s.borderColor, at('border', '테두리'));
+    add(s.color, at('icon', '아이콘'));
+    add(s._hover?.bgColor, at('hover fill', '마우스 올림 바탕'));
+    add(s._hover?.color, at('hover icon', '마우스 올림 아이콘'));
+    add(s._active?.bgColor, at('pressed fill', '누름 바탕'));
+  });
+  add('danger.fg', { en: 'isDestructive icon', ko: 'isDestructive 아이콘' });
+  add('disabled.bg', { en: 'disabled fill', ko: '비활성 바탕' });
+  add('disabled.fg', { en: 'disabled icon', ko: '비활성 아이콘' });
+  add('focus.ring', { en: 'keyboard focus ring', ko: '키보드 초점 링' });
+  return [...uses].map(([token, list]) => ({
+    token,
+    use: (
+      <T
+        en={list.map((u) => u.en).join(', ')}
+        ko={list.map((u) => u.ko).join(', ')}
+      />
+    ),
+  }));
+};
+
+/** Tokens each role reads, resolved from `IconButton.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => <TokenTable rows={iconButtonTokenRows()} />,
+};

package/src/components/IconButton/IconButton.usage.mdx

@@ -0,0 +1,273 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as IconButtonStories from './IconButton.stories';
+
+<Meta of={IconButtonStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# IconButton
+
+A round button with an icon and no visible label, for actions so common that
+the icon alone is enough: close, copy, edit, delete, send.
+
+## When to use
+
+- Toolbars and per-item actions where a row of labels would crowd the
+  content: the copy, edit and share actions under a chat message, the delete
+  icon on a list row.
+- Close and back in dialogs, drawers and panels.
+- The send button of a chat composer (`variant="action"`).
+
+## When not to use
+
+- The icon is not universally understood, or the action is rare or
+  destructive enough that the user should read it → `Button` with an icon and
+  a label.
+- Opening a menu of more actions on its own → wrap the IconButton in
+  `Menu.Trigger asChild`, so the menu supplies the popup ARIA.
+- A setting that stays on or off → `Switch`.
+- "Load more" at the end of a list → `SeeMoreButton`.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# IconButton
+
+글자 없이 아이콘만 있는 둥근 버튼입니다. 닫기, 복사, 수정, 삭제, 보내기처럼 아이콘만
+봐도 알 만큼 흔한 동작에 씁니다.
+
+## 언제 쓰나요
+
+- 라벨을 늘어놓으면 내용이 답답해지는 툴바와 항목별 동작: 채팅 메시지 아래의 복사,
+  수정, 공유, 목록 행의 삭제 아이콘.
+- 대화상자, 서랍, 패널의 닫기와 뒤로 가기.
+- 채팅 입력창의 보내기 버튼(`variant="action"`).
+
+## 언제 쓰지 않나요
+
+- 누구나 아는 아이콘이 아니거나, 드물게 쓰거나, 사용자가 글로 읽어야 할 만큼 위험한
+  동작이라면 아이콘과 라벨을 함께 넣은 `Button`을 씁니다.
+- 더 많은 동작을 담은 메뉴를 IconButton 혼자 열게 하지 않습니다. `Menu.Trigger asChild`로
+  감싸 메뉴가 팝업 ARIA를 붙이게 합니다.
+- 켜짐과 꺼짐이 유지되는 설정이라면 `Switch`를 씁니다.
+- 목록 끝의 "더보기"라면 `SeeMoreButton`을 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={IconButtonStories} include={['variant', 'isDestructive']} />
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `ghost` (default) | A routine action next to content. Glyph `fg.icon`, darkens on hover | 닫기, 복사, 수정, 뒤로 가기 |
+| `secondary` | Ghost with an outline, so it reads as a button on its own | 이전 / 다음, 일시정지, 수정 취소 |
+| `primary` | The one main icon action of its area. Black fill | 재생, 수정 저장 (check icon) |
+| `danger` | Confirms a destructive step. Red fill | Rare; prefer `ghost` + `isDestructive` |
+| `action` | Send. Coral fill, dark arrow | The chat composer's 보내기, nothing else |
+
+`isDestructive` turns the glyph `danger.fg` on `ghost` and `secondary`; it is
+ignored on the filled roles.
+
+In FactChat, `ghost` makes up most IconButtons; `secondary` is used about a
+fifth as often, and the filled roles are rare. Start from `ghost`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `ghost` (기본) | 내용 옆의 일상적인 동작. 아이콘은 `fg.icon`이며 마우스를 올리면 진해짐 | 닫기, 복사, 수정, 뒤로 가기 |
+| `secondary` | 테두리가 있는 ghost. 혼자 있어도 버튼으로 보임 | 이전 / 다음, 일시정지, 수정 취소 |
+| `primary` | 그 영역의 주 아이콘 동작 하나. 검정 바탕 | 재생, 수정 저장(체크 아이콘) |
+| `danger` | 되돌릴 수 없는 단계를 확정. 빨간 바탕 | 드물게 씀. 보통은 `ghost` + `isDestructive` |
+| `action` | 보내기. 코랄 바탕에 어두운 화살표 | 채팅 입력창의 보내기에만 씀 |
+
+`isDestructive`는 `ghost`와 `secondary`의 아이콘을 `danger.fg`로 바꿉니다. 바탕이
+있는 변형에서는 무시됩니다.
+
+FactChat에서는 IconButton 대부분이 `ghost`이고, `secondary`는 그 5분의 1 정도이며,
+바탕이 있는 변형은 드뭅니다. `ghost`에서 시작합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={IconButtonStories.DoGhostToolbar} />
+<Verdict
+  kind="do"
+  en="Use ghost icon buttons in a toolbar, each with an aria-label and a tooltip that says the same thing. Mark delete with isDestructive."
+  ko="툴바에는 ghost 아이콘 버튼을 쓰고, 버튼마다 aria-label과 같은 말을 담은 툴팁을 붙입니다. 삭제에는 isDestructive를 붙입니다."
+/>
+
+<Canvas of={IconButtonStories.DontFilledToolbar} />
+<Verdict
+  kind="dont"
+  en="Fill every icon in a toolbar. Four black and red circles compete with the content they act on, and none of them is the main action."
+  ko="툴바의 아이콘마다 바탕을 채우지 마세요. 검정과 빨강 원 네 개가 정작 내용보다 눈에 띄고, 그중 어느 것도 주 행동이 아닙니다."
+/>
+
+<Canvas of={IconButtonStories.DoActionForSend} />
+<Verdict
+  kind="do"
+  en="Keep the coral action variant for send. It is the screen's one run signal; the attach button next to it stays ghost."
+  ko="코랄 action 변형은 보내기에만 씁니다. 화면의 유일한 실행 신호이며, 옆의 첨부 버튼은 ghost로 둡니다."
+/>
+
+<Canvas of={IconButtonStories.DontActionForAdd} />
+<Verdict
+  kind="dont"
+  en="Use the coral action button for add, settings or anything else. Coral means send or run; on any other action it reads as a second run signal."
+  ko="추가, 설정 같은 다른 동작에 코랄 action 버튼을 쓰지 마세요. 코랄은 보내기와 실행을 뜻하므로, 다른 동작에 쓰면 실행 신호가 두 개로 보입니다."
+/>
+
+<Canvas of={IconButtonStories.DoTextWhenUnclear} />
+<Verdict
+  kind="do"
+  en="When the icon would need explaining, use a Button with an icon and a label."
+  ko="아이콘에 설명이 필요하다면 아이콘과 라벨을 함께 넣은 Button을 씁니다."
+/>
+
+<Canvas of={IconButtonStories.DontUnclearIcon} />
+<Verdict
+  kind="dont"
+  en="Rely on an icon only its designer can read. The aria-label helps screen readers, but sighted users still have to guess."
+  ko="만든 사람만 알아보는 아이콘에 기대지 마세요. aria-label은 화면 낭독기 사용자에게만 도움이 되고, 화면을 보는 사용자는 여전히 짐작해야 합니다."
+/>
+
+<En>
+
+## Content
+
+IconButton has no visible text, so its content is the `aria-label` and the
+tooltip.
+
+- Name the action, not the icon: 삭제, not 휴지통; 보내기, not 화살표.
+- Add the object when the row alone does not make it clear: 멤버 삭제,
+  파일 내려받기.
+- Use the same word as the tooltip and as any Button for the same action
+  elsewhere in the flow.
+- Sentence case in English ("Copy link"). No full stop.
+
+## Accessibility
+
+What IconButton does for you:
+
+- It renders a native `<button>`, so Tab reaches it and Enter and Space
+  activate it (WCAG 2.1.1).
+- A keyboard focus ring (`focus.ring` with a canvas-coloured inner band) on
+  `:focus-visible` only (WCAG 2.4.7).
+- The resting glyph on `ghost` and `secondary` is `fg.icon`, chosen for 3:1
+  against the surface as a non-text graphic (WCAG 1.4.11).
+- Disabled is a fixed colour pair, not opacity, and does not react to hover or
+  press.
+
+What you still have to do:
+
+- **Always pass `aria-label`.** The type does not require it, and without it
+  the button has no accessible name (WCAG 4.1.2; axe `button-name`, KWCAG
+  5.3.4.1 in ACCESSIBILITY.md §1). Pass it on the first render, not after
+  hydration.
+- **A tooltip is not the name.** Give the tooltip the same words as the
+  `aria-label`, so what a sighted user sees and what a speech-input user says
+  match (WCAG 2.5.3).
+- **Hide nothing behind colour.** `isDestructive` and `danger` colour the
+  glyph; the label (삭제) is what carries the meaning (WCAG 1.4.1).
+- **No IconButton inside another control** (ACCESSIBILITY.md §3, axe
+  `nested-interactive`). A delete icon on a clickable card goes next to the
+  card's link, not inside it.
+- **Say why it is disabled.** A disabled send button (nothing typed yet) is
+  skipped by Tab; the empty input already explains it. Elsewhere, explain in
+  text.
+
+## Tokens
+
+The table is generated from `IconButton.styles.ts` and the theme.
+`transparent` fills and borders are left out. `primary` and `danger` reuse
+Button's styles.
+
+</En>
+
+<Ko>
+
+## 문구
+
+IconButton에는 보이는 글자가 없으므로 문구는 `aria-label`과 툴팁입니다.
+
+- 아이콘이 아니라 동작을 적습니다. "휴지통"이 아니라 "삭제", "화살표"가 아니라
+  "보내기"입니다.
+- 행만 보고는 대상이 분명하지 않다면 대상을 붙입니다: 멤버 삭제, 파일 내려받기.
+- 툴팁, 그리고 같은 흐름에서 같은 동작을 하는 Button과 같은 말을 씁니다.
+- 영어는 문장형 대소문자를 쓰고("Copy link") 마침표를 찍지 않습니다.
+
+## 접근성
+
+IconButton이 알아서 하는 일
+
+- 기본 `<button>`으로 렌더하므로 Tab으로 이동하고 Enter와 Space로 실행합니다(WCAG
+  2.1.1).
+- 키보드 초점에만(`:focus-visible`) 초점 링을 그립니다. `focus.ring`에 바탕색 안쪽
+  띠를 더한 모양입니다(WCAG 2.4.7).
+- `ghost`와 `secondary`의 평소 아이콘 색은 `fg.icon`입니다. 글자가 아닌 그래픽으로서
+  바탕과 3:1 대비를 맞춘 값입니다(WCAG 1.4.11).
+- 비활성 상태는 투명도가 아니라 고정된 색 한 쌍이며, 마우스를 올리거나 눌러도 변하지
+  않습니다.
+
+직접 챙겨야 하는 일
+
+- **`aria-label`을 반드시 줍니다.** 타입이 강제하지 않으며, 빠뜨리면 버튼에 접근 가능한
+  이름이 없습니다(WCAG 4.1.2, axe `button-name`, ACCESSIBILITY.md 1절의 KWCAG
+  5.3.4.1). 하이드레이션 이후가 아니라 첫 렌더부터 줍니다.
+- **툴팁은 이름이 아닙니다.** 툴팁에 `aria-label`과 같은 말을 넣어, 눈으로 보는 말과
+  음성으로 부르는 말이 같게 합니다(WCAG 2.5.3).
+- **색에 뜻을 숨기지 않습니다.** `isDestructive`와 `danger`는 아이콘 색만 바꾸고, 뜻은
+  "삭제" 같은 라벨이 전합니다(WCAG 1.4.1).
+- **컨트롤 안에 IconButton을 넣지 않습니다**(ACCESSIBILITY.md 3절, axe
+  `nested-interactive`). 누를 수 있는 카드의 삭제 아이콘은 카드 링크 안이 아니라
+  옆에 둡니다.
+- **왜 비활성인지 알립니다.** 아직 아무것도 입력하지 않아 비활성인 보내기 버튼은 Tab이
+  건너뛰지만, 빈 입력창이 이유를 보여 줍니다. 다른 자리에서는 글로 이유를 적습니다.
+
+## 토큰
+
+아래 표는 `IconButton.styles.ts`와 테마에서 자동으로 만듭니다. `transparent`인
+바탕과 테두리는 뺐습니다. `primary`와 `danger`는 Button의 스타일을 그대로 씁니다.
+
+</Ko>
+
+<Canvas of={IconButtonStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Button**: the same roles with a visible label.
+- **Tooltip**: the visible name of an IconButton.
+- **Menu**: an icon that opens more actions.
+- **Foundations/Brand & colour usage**: why the send button is the one coral
+  fill.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Button**: 보이는 라벨이 있는 버튼. 역할은 같습니다.
+- **Tooltip**: IconButton의 이름을 눈에 보이게 하는 도구.
+- **Menu**: 더 많은 동작을 여는 아이콘.
+- **Foundations/Brand & colour usage**: 보내기 버튼만 코랄 바탕인 이유.
+
+</Ko>