@mindlogic-ai/logician-ui 5.0.0-alpha.3 → 5.0.0-alpha.30

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

@@ -0,0 +1,275 @@
+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. `ghost` has no fill to grey out, so its disabled glyph is the lighter
+  `disabled.fgGhost` — `disabled.fg` sat too close to the resting `fg.icon`.
+
+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).
+- 비활성 상태는 투명도가 아니라 고정된 색 한 쌍이며, 마우스를 올리거나 눌러도 변하지
+  않습니다. `ghost`는 회색으로 바꿀 바탕이 없어서 비활성 아이콘을 더 옅은
+  `disabled.fgGhost`로 칠합니다. `disabled.fg`는 평소 아이콘 색 `fg.icon`과 거의 같아 보였습니다.
+
+직접 챙겨야 하는 일
+
+- **`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>

package/src/components/InfoSprinkle/InfoSprinkle.stories.tsx

@@ -1,7 +1,11 @@
 import { Box, HStack, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Subtitle, Text } from '../Typography';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { Input } from '../Input';
+import { Subtext, Subtitle, Text } from '../Typography';
 import { InfoSprinkle } from './InfoSprinkle';
 
 const meta = {
@@ -39,3 +43,75 @@ export const LargerBaseFontSize: Story = {
     baseFontSize: '18px',
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `InfoSprinkle.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each card is held open (`open`) so the page shows it
+// without a hover.
+
+export const DoDefineALabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: define the label next to it',
+  render: () => (
+    <Box pt="96px" px={16}>
+      <Card p={4} w="240px">
+        <HStack gap={1}>
+          <Subtext>활성 멤버</Subtext>
+          <InfoSprinkle
+            open
+            iconButtonProps={{ size: 'xs', 'aria-label': '활성 멤버 설명' }}
+          >
+            <Text maxW="220px">
+              최근 30일 동안 한 번 이상 대화한 멤버 수입니다.
+            </Text>
+          </InfoSprinkle>
+        </HStack>
+        <Text fontWeight="bold" fontSize="lg">
+          128
+        </Text>
+      </Card>
+    </Box>
+  ),
+};
+
+export const DontHideTheRule: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: hide a rule the user must follow",
+  render: () => (
+    <Box pt="96px" px={16}>
+      <VStack align="stretch" gap={1} w="260px">
+        <HStack gap={1}>
+          <Text as="label" htmlFor="usage-password" fontWeight="semibold">
+            새 비밀번호
+          </Text>
+          <InfoSprinkle
+            open
+            iconButtonProps={{ size: 'xs', 'aria-label': '비밀번호 규칙' }}
+          >
+            <Text maxW="220px">
+              8자 이상, 숫자와 특수문자를 포함해야 합니다.
+            </Text>
+          </InfoSprinkle>
+        </HStack>
+        <Input id="usage-password" type="password" />
+      </VStack>
+    </Box>
+  ),
+};
+
+/** Tokens the trigger and card read: the icon colour from `InfoSprinkle.tsx`, the card from the Chakra HoverCard recipe. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'fg.muted', use: <T en="Icon" ko="아이콘" /> },
+        { token: 'bg.panel', use: <T en="Card" ko="카드" /> },
+      ]}
+    />
+  ),
+};

package/src/components/InfoSprinkle/InfoSprinkle.usage.mdx

@@ -0,0 +1,189 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as InfoSprinkleStories from './InfoSprinkle.stories';
+
+<Meta of={InfoSprinkleStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# InfoSprinkle
+
+A small info icon next to a label that opens a card with a definition or a
+short explanation, on hover, on focus, or on tap.
+
+## When to use
+
+- To define a term on a stat card or a table header: what "활성 멤버" counts,
+  whether a member count includes subgroups.
+- To explain how a number is calculated, such as rounding.
+- To say when something runs, such as an analysis schedule.
+
+## When not to use
+
+- A rule the user must follow to succeed (password rules, file limits) → put it
+  in visible helper text under the field.
+- The name of an icon-only button → `Tooltip`.
+- Content with links or controls → `Popover`.
+- A warning or a status → `Banner` or `Badge`.
+
+## Variants and what they mean
+
+InfoSprinkle has no visual variants. Set the size and name of the icon with
+`iconButtonProps`, the card's padding with `contentProps`, and its placement
+with `positioning` (default `top`).
+
+</En>
+
+<Ko>
+
+# InfoSprinkle
+
+라벨 옆의 작은 정보 아이콘입니다. 포인터를 올리거나, 초점이 닿거나, 누르면 용어 설명이나
+짧은 해설을 담은 카드가 열립니다.
+
+## 언제 쓰나요
+
+- 통계 카드나 표 머리글의 용어를 설명할 때: "활성 멤버"가 무엇을 세는지, 멤버 수에 하위
+  그룹이 들어가는지.
+- 반올림처럼 숫자를 계산하는 방식을 설명할 때.
+- 분석 일정처럼 무언가가 언제 실행되는지 알릴 때.
+
+## 언제 쓰지 않나요
+
+- 비밀번호 규칙이나 파일 제한처럼 사용자가 꼭 지켜야 하는 규칙은 입력란 아래에 눈에 보이는
+  도움말로 씁니다.
+- 아이콘만 있는 버튼의 이름은 `Tooltip`으로 보입니다.
+- 링크나 컨트롤이 들어가는 내용은 `Popover`에 넣습니다.
+- 경고나 상태는 `Banner`나 `Badge`로 알립니다.
+
+## 변형과 뜻
+
+InfoSprinkle에는 모양 변형이 없습니다. 아이콘의 크기와 이름은 `iconButtonProps`로,
+카드 여백은 `contentProps`로, 위치는 `positioning`(기본 `top`)으로 정합니다.
+
+</Ko>
+
+<ArgTypes of={InfoSprinkleStories} include={['iconButtonProps', 'contentProps', 'baseFontSize']} />
+
+<En>
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={InfoSprinkleStories.DoDefineALabel} />
+<Verdict
+  kind="do"
+  en="Put it right after the label it explains, and name the icon after that label ('활성 멤버 설명')."
+  ko="설명하는 라벨 바로 뒤에 두고, 아이콘 이름도 그 라벨을 따라 붙입니다('활성 멤버 설명')."
+/>
+
+<Canvas of={InfoSprinkleStories.DontHideTheRule} />
+<Verdict
+  kind="dont"
+  en="Hide a rule the user must follow behind the icon. Most people will not open it, and they find out only when the form is rejected. Show the rule under the field."
+  ko="꼭 지켜야 하는 규칙을 아이콘 뒤에 숨기지 마세요. 대부분은 열어 보지 않고, 양식이 거부된 뒤에야 알게 됩니다. 규칙은 입력란 아래에 보이게 씁니다."
+/>
+
+<En>
+
+## Content
+
+- One or two sentences that define or explain. Full stops, sentence case.
+- Start with the answer: "최근 30일 동안 한 번 이상 대화한 멤버 수입니다.", not
+  "이 숫자는 …를 뜻합니다".
+- No links or buttons inside; the card closes as soon as the pointer or focus
+  leaves the icon.
+
+## Accessibility
+
+What InfoSprinkle does for you:
+
+- The trigger is a real `IconButton`, so it is reachable with `Tab`
+  (WCAG 2.1.1). The card opens on hover and on focus, and on tap on touch
+  devices that have no hover.
+- The card is portalled and closes when the pointer or focus moves away.
+
+What you still have to do:
+
+- **Name each icon.** The default `aria-label` is the English "Info", and every
+  icon on the screen gets the same one. Pass a name through `iconButtonProps`
+  that says what it explains: `'aria-label': '활성 멤버 설명'` (WCAG 2.4.6,
+  4.1.2).
+- **Do not rely on screen readers reading the card.** It is a Chakra
+  `HoverCard`: the trigger has no `aria-describedby` or `aria-expanded`
+  pointing at it, and the card sits at the end of the page. Keep the
+  information a screen reader user needs in visible text or in the label.
+- Do not put the only copy of required information in it.
+
+## Tokens
+
+The icon colour is set in `InfoSprinkle.tsx`; the card colour comes from
+Chakra's HoverCard recipe.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 용어를 정의하거나 해설하는 한두 문장을 씁니다. 마침표를 찍습니다.
+- 답부터 씁니다. "이 숫자는 …를 뜻합니다"가 아니라 "최근 30일 동안 한 번 이상 대화한
+  멤버 수입니다."처럼 씁니다.
+- 안에 링크나 버튼을 넣지 않습니다. 포인터나 초점이 아이콘을 떠나면 카드가 바로 닫힙니다.
+
+## 접근성
+
+InfoSprinkle이 알아서 하는 일
+
+- 여는 요소가 실제 `IconButton`이라 `Tab`으로 닿을 수 있습니다(WCAG 2.1.1). 포인터를
+  올리거나 초점이 닿으면 카드가 열리고, 마우스 올리기가 없는 터치 기기에서는 누르면
+  열립니다.
+- 카드는 포털로 그려지며, 포인터나 초점이 떠나면 닫힙니다.
+
+직접 챙겨야 하는 일
+
+- **아이콘마다 이름을 붙입니다.** 기본 `aria-label`은 영어 "Info"라서 화면의 모든 아이콘이
+  같은 이름을 갖게 됩니다. `iconButtonProps`로 무엇을 설명하는지 밝힌 이름을 넘깁니다.
+  예: `'aria-label': '활성 멤버 설명'`(WCAG 2.4.6, 4.1.2).
+- **화면 낭독기가 카드를 읽어 줄 것이라 기대하지 않습니다.** Chakra `HoverCard`라서
+  여는 버튼에 카드를 가리키는 `aria-describedby`나 `aria-expanded`가 없고, 카드는 페이지
+  맨 끝에 붙습니다. 화면 낭독기 사용자에게 필요한 정보는 보이는 문구나 라벨에 둡니다.
+- 꼭 필요한 정보를 이 카드에만 두지 않습니다.
+
+## 토큰
+
+아이콘 색은 `InfoSprinkle.tsx`에서, 카드 색은 Chakra HoverCard 레시피에서 정합니다.
+
+</Ko>
+
+<Canvas of={InfoSprinkleStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tooltip**: the name of an icon-only button.
+- **Popover**: a panel with links or controls.
+- **FormControl**: helper text under a field, for rules the user must follow.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tooltip**: 아이콘만 있는 버튼의 이름.
+- **Popover**: 링크나 컨트롤이 있는 패널.
+- **FormControl**: 사용자가 지켜야 하는 규칙을 담는 입력란 아래 도움말.
+
+</Ko>

package/src/components/InlineCode/InlineCode.stories.tsx

@@ -0,0 +1,75 @@
+import { Meta, StoryObj } from '@storybook/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Text } from '../Typography';
+import { InlineCode } from './InlineCode';
+
+const meta = {
+  title: 'Components/InlineCode',
+  component: InlineCode,
+  args: {
+    children: 'model_id',
+  },
+} satisfies Meta<typeof InlineCode>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Basic: Story = {};
+
+/** In running text, where it is meant to be used. */
+export const InSentence: Story = {
+  render: (args) => (
+    <Text>
+      요청 본문의 <InlineCode {...args} /> 칸에 모델 이름을 넣습니다.
+    </Text>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `InlineCode.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+export const DoIdentifierInSentence: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: names the user types or sees in code',
+  render: () => (
+    <Text>
+      응답이 끊기면 <InlineCode>finish_reason</InlineCode> 값이{' '}
+      <InlineCode>length</InlineCode>인지 확인하세요.
+    </Text>
+  ),
+};
+
+export const DontEmphasis: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: code styling for emphasis",
+  render: () => (
+    <Text>
+      이 작업은 <InlineCode>되돌릴 수 없습니다</InlineCode>.
+    </Text>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.subtle', use: <T en="Chip fill" ko="칩 배경" /> },
+        { token: 'fg.default', use: <T en="Text" ko="글자" /> },
+        {
+          token: 'border.subtle',
+          use: <T en="1px ring (box-shadow)" ko="1px 테두리(box-shadow)" />,
+        },
+      ]}
+    />
+  ),
+};