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

package/src/components/Toast/Toast.usage.mdx

@@ -0,0 +1,265 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as ToastStories from './Toast.stories';
+
+<Meta of={ToastStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Toast
+
+A short message that confirms the result of something the reader just did,
+then goes away on its own.
+
+## When to use
+
+- To confirm an action that has no other visible result: 링크를 복사했습니다,
+  설정을 저장했습니다.
+- To report that a background action failed or finished, when the reader is
+  no longer looking at where it started.
+- To offer one follow-up to that result: undo a delete, open the exported file.
+
+## When not to use
+
+- The message must stay until the condition changes → `Banner`.
+- An error about one field → the field's error text (`FormControl`). The
+  toast disappears; the field is still wrong.
+- The reader has to decide before going on → `Modal`.
+- Progress of a long job → `ProgressBar`, in the place where the job runs.
+- A status attached to one item → `Badge`.
+
+## How it works
+
+- Mount `<Toaster />` once, at the root of the app. Then call
+  `const showToast = useToast()` and `showToast({ status, title?, description, action? })`.
+  It returns the toast id; `showToast.update(id, options)`,
+  `showToast.dismiss(id)` and `showToast.dismissAll()` work on it.
+- A toast closes after 5 s, or 8 s when it has an `action`, unless you pass
+  `duration`. Hovering or focusing the toasts pauses the timer, and so does
+  leaving the browser tab.
+- `useToast` keeps at most three of its toasts; a fourth closes the oldest.
+- Every toast appears at the top of the window. Placement is set once in
+  `Toaster.tsx`, not per toast.
+- `useToast()` returns a new function on every render. Do not list it as an
+  effect dependency without wrapping it first.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Toast
+
+사용자가 방금 한 일의 결과를 짧게 확인해 주고, 잠시 뒤 저절로 사라지는 메시지입니다.
+
+## 언제 쓰나요
+
+- 화면에 다른 결과가 보이지 않는 동작을 확인해 줄 때: 링크를 복사했습니다, 설정을
+  저장했습니다.
+- 백그라운드 작업이 끝나거나 실패했는데, 사용자가 이미 다른 곳을 보고 있을 때.
+- 그 결과에 이어서 할 일이 하나 있을 때: 삭제 되돌리기, 내보낸 파일 열기.
+
+## 언제 쓰지 않나요
+
+- 원인이 해결될 때까지 남아 있어야 하는 안내는 `Banner`를 씁니다.
+- 입력란 하나의 오류는 그 입력란의 오류 문구(`FormControl`)로 알립니다. 토스트는
+  사라지지만 입력란은 여전히 틀린 상태입니다.
+- 사용자가 결정해야 다음으로 넘어갈 수 있다면 `Modal`을 씁니다.
+- 오래 걸리는 작업의 진행률은 그 작업이 돌아가는 자리에 `ProgressBar`로 보여 줍니다.
+- 항목 하나에 붙는 상태는 `Badge`를 씁니다.
+
+## 동작 방식
+
+- 앱 맨 위에 `<Toaster />`를 한 번만 둡니다. 그다음 `const showToast = useToast()`를
+  부르고 `showToast({ status, title?, description, action? })`로 띄웁니다. 반환값은
+  토스트 id이며, `showToast.update(id, options)`, `showToast.dismiss(id)`,
+  `showToast.dismissAll()`에 씁니다.
+- `duration`을 넘기지 않으면 5초 뒤에 닫히고, `action`이 있으면 8초 뒤에 닫힙니다.
+  토스트 위에 마우스를 올리거나 초점을 옮기면 시간이 멈추고, 브라우저 탭을 떠나도
+  멈춥니다.
+- `useToast`로 띄운 토스트는 세 개까지 남고, 네 번째가 뜨면 가장 오래된 것이 닫힙니다.
+- 토스트는 모두 창 위쪽에 뜹니다. 위치는 `Toaster.tsx`에서 한 번 정하며, 토스트마다
+  바꿀 수 없습니다.
+- `useToast()`는 렌더할 때마다 새 함수를 돌려줍니다. 감싸지 않은 채 effect 의존성에
+  넣지 않습니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={ToastStories} include={['status', 'action']} />
+
+<En>
+
+| Status | Means | Use for |
+| --- | --- | --- |
+| `neutral` (default) | A plain result with no status; no icon. Inverted (`tooltip.bg` / `tooltip.fg`) so it stands out on a white page | Copied, moved, sent |
+| `success` | Done as asked | Saved, uploaded, deleted |
+| `info` | A fact about what just happened; nothing is wrong | Export ready, model switched for you |
+| `warning` | Done, but not quite as expected | Some files skipped |
+| `error` | It did not happen | Request failed, out of credits |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 상태 | 뜻 | 예 |
+| --- | --- | --- |
+| `neutral` (기본) | 상태가 없는 단순한 결과이며 아이콘도 없음. 흰 화면에서도 잘 보이도록 반전색(`tooltip.bg` / `tooltip.fg`)을 씀 | 복사, 이동, 전송 |
+| `success` | 요청한 대로 끝남 | 저장, 업로드, 삭제 |
+| `info` | 방금 일어난 일에 대한 사실이며, 문제가 있다는 뜻은 아님 | 내보내기 완료, 모델 자동 변경 |
+| `warning` | 끝났지만 예상과 조금 다름 | 일부 파일 건너뜀 |
+| `error` | 일어나지 않음 | 요청 실패, 크레딧 부족 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={ToastStories.DoActionProp} />
+<Verdict
+  kind="do"
+  en="Pass the follow-up as action. It renders as a text action in the toast's own colour, lined up with the message."
+  ko="이어서 할 일은 action으로 넘깁니다. 토스트와 같은 색의 글자 버튼으로, 메시지와 줄을 맞춰 그려집니다."
+/>
+
+<Canvas of={ToastStories.DontButtonInDescription} />
+<Verdict
+  kind="dont"
+  en="Put a Button inside description. It carries none of the toast's colours and reads as a separate card on top."
+  ko="description 안에 Button을 넣지 마세요. 토스트의 색을 따르지 않아서 위에 따로 얹은 카드처럼 보입니다."
+/>
+
+<Canvas of={ToastStories.DoUndoAfterDelete} />
+<Verdict
+  kind="do"
+  en="Confirm a delete and offer undo. One action only; closing is the ×."
+  ko="삭제를 확인해 주고 되돌리기를 제안합니다. 동작은 하나만 두고, 닫기는 ×가 맡습니다."
+/>
+
+<Canvas of={ToastStories.DontToastForFieldError} />
+<Verdict
+  kind="dont"
+  en="Report a field error in a toast. It is gone in five seconds and does not say which field. Show the error under the field."
+  ko="입력란 오류를 토스트로 알리지 마세요. 5초 뒤에 사라지고, 어느 입력란인지도 알려 주지 않습니다. 오류는 입력란 아래에 보여 줍니다."
+/>
+
+<Canvas of={ToastStories.DoNeutralResult} />
+<Verdict
+  kind="do"
+  en="Use neutral for a plain result. A green check on every copy makes success mean nothing."
+  ko="단순한 결과에는 neutral을 씁니다. 복사할 때마다 초록 체크를 띄우면 success가 아무 뜻도 전하지 못합니다."
+/>
+
+<En>
+
+## Content
+
+- One sentence in `description`, in the past tense for a result:
+  "채팅을 삭제했습니다." Add a `title` only when the description needs a
+  heading to make sense.
+- Say what happened, not what the system is: "크레딧이 부족해 응답을 생성하지
+  못했습니다", not "402 Payment Required".
+- The action label is a short verb phrase: 되돌리기, 크레딧 구매, 파일 열기.
+- Do not put information the reader needs later only in a toast. It will be
+  gone.
+
+## Accessibility
+
+What Toast does for you:
+
+- Each toast is `role="status"` inside a polite live region, so screen readers
+  read it without moving focus (WCAG 4.1.3).
+- `Alt+T` moves focus to the toasts; `Escape` closes the focused toast. The
+  action and the × are real buttons (WCAG 2.1.1).
+- Hover and focus pause the timer, and the action toast stays longer (8 s), so
+  the reader has time to act (WCAG 2.2.1).
+- Text, icon, action and × use the status `.fg` colour, which the contrast
+  audit checks on `.bg` in both modes (WCAG 1.4.3).
+
+What you still have to do:
+
+- **Errors are announced politely, not as alerts.** If the reader must not miss
+  it, also show it on the page (`Banner` with `role="alert"`).
+- **The × has no accessible name yet.** The close trigger is a button with only
+  an icon (WCAG 4.1.2); a fix belongs in `Toast.tsx`. Until then, do not make
+  the × the only way to act on a toast.
+- Words, not colour alone (WCAG 1.4.1): the description says it failed; the red
+  is a second signal.
+
+## Tokens
+
+The table is generated from `Toast.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- `description`에 한 문장을 씁니다. 결과는 과거형으로 씁니다: "채팅을 삭제했습니다."
+  `title`은 설명만으로 뜻이 통하지 않을 때만 붙입니다.
+- 시스템 상태가 아니라 일어난 일을 씁니다. "402 Payment Required"가 아니라 "크레딧이
+  부족해 응답을 생성하지 못했습니다"라고 씁니다.
+- 동작 라벨은 짧은 동사구로 씁니다: 되돌리기, 크레딧 구매, 파일 열기.
+- 나중에 다시 봐야 하는 정보를 토스트에만 담지 않습니다. 곧 사라집니다.
+
+## 접근성
+
+Toast가 알아서 하는 일
+
+- 토스트마다 `role="status"`가 붙고, 공손한(polite) 라이브 영역 안에 있습니다.
+  화면 낭독기는 초점을 옮기지 않고 내용을 읽습니다(WCAG 4.1.3).
+- `Alt+T`를 누르면 토스트로 초점이 옮겨지고, `Escape`를 누르면 초점이 있는 토스트가
+  닫힙니다. 동작과 ×는 실제 버튼입니다(WCAG 2.1.1).
+- 마우스를 올리거나 초점을 두면 시간이 멈추고, 동작이 있는 토스트는 8초 동안 남아서
+  읽고 누를 시간이 있습니다(WCAG 2.2.1).
+- 글자, 아이콘, 동작, ×는 상태의 `.fg` 색을 씁니다. 이 색은 대비 감사에서 라이트·다크
+  모두 `.bg` 위에서 검사합니다(WCAG 1.4.3).
+
+직접 챙겨야 하는 일
+
+- **오류도 공손하게 읽힐 뿐, 경고(alert)로 읽히지 않습니다.** 놓치면 안 되는 오류라면
+  페이지에도 보여 줍니다(`role="alert"`를 붙인 `Banner`).
+- **×에는 아직 접근 가능한 이름이 없습니다.** 닫기 버튼에 아이콘만 있습니다(WCAG
+  4.1.2). 고칠 곳은 `Toast.tsx`입니다. 그 전까지는 ×를 토스트에 대응하는 유일한
+  방법으로 만들지 않습니다.
+- 색만으로 알리지 않습니다(WCAG 1.4.1). 실패했다는 사실은 문구가 전하고, 빨간색은
+  두 번째 신호입니다.
+
+## 토큰
+
+아래 표는 `Toast.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={ToastStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Banner**: a message that stays until the condition changes.
+- **Modal**: a decision the reader has to make now.
+- **ErrorFallback**: the page failed to render.
+- **Guidelines/Actions in feedback surfaces**: the `action` recipe and why.
+- **Foundations/Brand & colour usage**: status colours mean status.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Banner**: 원인이 해결될 때까지 남아 있는 안내.
+- **Modal**: 사용자가 지금 내려야 하는 결정.
+- **ErrorFallback**: 페이지를 그리지 못했을 때.
+- **Guidelines/Actions in feedback surfaces**: `action`의 쓰임과 이유.
+- **Foundations/Brand & colour usage**: 상태색은 상태를 뜻합니다.
+
+</Ko>

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -2,7 +2,12 @@ import { useState } from 'react';
 import { Box, Button, HStack, IconButton, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { FaRegCopy } from '../Icon';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button as LogicianButton } from '../Button';
+import { FaRegCopy, RefreshIcon, TrashIcon } from '../Icon';
+import { IconButton as LogicianIconButton } from '../IconButton';
+import { Link } from '../Typography';
 import { Tooltip } from './Tooltip';
 
 const meta = {
@@ -281,3 +286,83 @@ export const CustomStylesWithoutArrow: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Tooltip.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each tooltip is held open (`open`) so the page shows it
+// without a hover.
+
+export const DoNameIconButton: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: name an icon button',
+  render: () => (
+    <Box pt={10} pb={2} px={2}>
+      <Tooltip content="새로고침" open>
+        <LogicianIconButton aria-label="새로고침" variant="ghost">
+          <RefreshIcon aria-hidden />
+        </LogicianIconButton>
+      </Tooltip>
+    </Box>
+  ),
+};
+
+export const DontLinkInTooltip: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a link inside a tooltip",
+  render: () => (
+    <Box pt={12} pb={2} px={20}>
+      <Tooltip
+        open
+        content={
+          <>
+            관리자만 바꿀 수 있습니다. <Link href="#">자세히 보기</Link>
+          </>
+        }
+      >
+        <LogicianButton variant="secondary">정책 변경</LogicianButton>
+      </Tooltip>
+    </Box>
+  ),
+};
+
+export const DontStatusColourTooltip: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a status colour on a tooltip",
+  render: () => (
+    <Box pt={10} pb={2} px={2}>
+      <Tooltip
+        content="삭제"
+        open
+        contentProps={{
+          css: { '--tooltip-bg': 'var(--chakra-colors-danger-solid)' },
+          bgColor: 'danger.solid',
+        }}
+      >
+        <LogicianIconButton aria-label="삭제" variant="ghost">
+          <TrashIcon aria-hidden />
+        </LogicianIconButton>
+      </Tooltip>
+    </Box>
+  ),
+};
+
+/** Tokens the tooltip reads, as set in `Tooltip.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'tooltip.bg',
+          use: <T en="Background and arrow" ko="배경·화살표" />,
+        },
+        { token: 'tooltip.fg', use: <T en="Text" ko="글자" /> },
+      ]}
+    />
+  ),
+};

package/src/components/Tooltip/Tooltip.usage.mdx

@@ -0,0 +1,219 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as TooltipStories from './Tooltip.stories';
+
+<Meta of={TooltipStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Tooltip
+
+A short text label that appears when the pointer rests on, or the keyboard
+focuses, the element it describes.
+
+## When to use
+
+- To show the name of an icon-only button: 새로고침, 복사, 공유.
+- To show the full text of a label that is cut off, when the element is
+  focusable.
+- To give the label of a collapsed navigation item.
+
+## When not to use
+
+- Anything the user must read to succeed, such as a password rule or an error →
+  visible helper text, `FormControl`, or `Banner`. Touch screens never show a
+  tooltip.
+- A definition or an explanation with more than one sentence → `InfoSprinkle`.
+- Anything clickable, such as a link or a button → `Popover`. The pointer cannot
+  reach a tooltip and the keyboard cannot focus inside it.
+- A status → `Badge`, `Toast` or `Banner`.
+
+## Variants and what they mean
+
+Tooltip has one look, `tooltip.bg` with `tooltip.fg`. These props change where
+and whether it shows:
+
+</En>
+
+<Ko>
+
+# Tooltip
+
+포인터를 올리거나 키보드 초점이 닿았을 때 그 요소를 설명하는 짧은 라벨입니다.
+
+## 언제 쓰나요
+
+- 아이콘만 있는 버튼의 이름을 보일 때: 새로고침, 복사, 공유.
+- 잘린 라벨의 전체 문구를 보일 때. 단, 그 요소가 초점을 받을 수 있어야 합니다.
+- 접힌 내비게이션 항목의 이름을 보일 때.
+
+## 언제 쓰지 않나요
+
+- 비밀번호 규칙이나 오류처럼 꼭 읽어야 하는 내용은 눈에 보이는 도움말, `FormControl`,
+  `Banner`로 보입니다. 터치 화면에서는 툴팁이 뜨지 않습니다.
+- 용어 설명이나 두 문장 이상의 설명은 `InfoSprinkle`을 씁니다.
+- 링크나 버튼처럼 누를 수 있는 것은 `Popover`에 넣습니다. 툴팁에는 포인터가 닿지 못하고
+  키보드 초점도 들어가지 못합니다.
+- 상태는 `Badge`, `Toast`, `Banner`로 알립니다.
+
+## 변형과 뜻
+
+Tooltip의 모양은 `tooltip.bg` 배경에 `tooltip.fg` 글자 하나뿐입니다. 아래 속성은
+위치와 표시 여부를 정합니다.
+
+</Ko>
+
+<ArgTypes of={TooltipStories} include={['content', 'placement', 'showArrow', 'disabled']} />
+
+<En>
+
+| Prop | Default | Notes |
+| --- | --- | --- |
+| `placement` | `top` | Use `right` for a collapsed side navigation. |
+| `showArrow` | `false` | Turn it on when the trigger is small or sits among others, so it is clear which one the tooltip belongs to. |
+| `disabled` | `false` | Renders the children with no tooltip at all, e.g. when the label is not truncated. |
+| `openDelay` | `300` ms | Moving from one open tooltip to the next shows the next one at once. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 기본값 | 참고 |
+| --- | --- | --- |
+| `placement` | `top` | 접힌 사이드 내비게이션에서는 `right`를 씁니다. |
+| `showArrow` | `false` | 여는 요소가 작거나 여러 개가 붙어 있어 어느 것의 툴팁인지 헷갈릴 때 켭니다. |
+| `disabled` | `false` | 툴팁 없이 자식만 그립니다. 라벨이 잘리지 않았을 때처럼 툴팁이 필요 없을 때 씁니다. |
+| `openDelay` | `300`ms | 열린 툴팁에서 옆 툴팁으로 옮겨 가면 기다리지 않고 바로 뜹니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={TooltipStories.DoNameIconButton} />
+<Verdict
+  kind="do"
+  en="Give the icon button an aria-label and show the same words in the tooltip. The tooltip is a description, not the button's name."
+  ko="아이콘 버튼에 aria-label을 붙이고 툴팁에도 같은 말을 씁니다. 툴팁은 버튼의 이름이 아니라 설명입니다."
+/>
+
+<Canvas of={TooltipStories.DontLinkInTooltip} />
+<Verdict
+  kind="dont"
+  en="Put a link in a tooltip. It closes as the pointer moves toward it, and keyboard focus can never land on it. Use a Popover or visible text."
+  ko="툴팁에 링크를 넣지 마세요. 포인터를 옮기는 사이에 툴팁이 닫히고, 키보드 초점은 그 링크에 닿지 못합니다. Popover나 눈에 보이는 문구를 씁니다."
+/>
+
+<Canvas of={TooltipStories.DontStatusColourTooltip} />
+<Verdict
+  kind="dont"
+  en="Recolour a tooltip with a status colour. Status colours carry a meaning; a red tooltip on a delete button reads as an error."
+  ko="툴팁을 상태색으로 칠하지 마세요. 상태색에는 뜻이 있어서, 삭제 버튼의 빨간 툴팁은 오류로 읽힙니다."
+/>
+
+<En>
+
+## Content
+
+- One to five words for a button name; one short sentence at most. No full
+  stop on a name.
+- Match the accessible name of the trigger word for word (WCAG 2.5.3).
+- Do not repeat visible text. A button that already says "공유" needs no
+  tooltip.
+
+## Accessibility
+
+What Tooltip does for you:
+
+- Opens on hover after 300 ms and on keyboard focus; `Escape` closes it, and so
+  does scrolling (WCAG 1.4.13).
+- While open, the trigger gets `aria-describedby` pointing at the content,
+  which has `role="tooltip"` (WCAG 4.1.2).
+
+What you still have to do:
+
+- **Name the trigger yourself.** `aria-describedby` adds a description; it does
+  not give an icon-only button a name. Pass `aria-label` on the button.
+- **The trigger must be focusable.** Tooltip wraps its child with
+  `asChild`, so the child must be a real button, link or other focusable
+  element. A disabled button gets no hover or focus, so its tooltip never
+  shows.
+- Never put the only copy of required information in a tooltip; touch screens
+  have no hover.
+- **Tooltip + Menu on one trigger: share `ids.trigger`.** Both make the
+  button their trigger and each gives it its own id, so the menu cannot find
+  its anchor and opens at the top-left of the page. Pass one `useId()` to
+  both: `<Menu ids={{ trigger: id }}><Tooltip ids={{ trigger: id }} …>`.
+
+## Tokens
+
+The table lists the tokens set in `Tooltip.tsx`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 버튼 이름은 한 단어에서 다섯 단어, 길어도 짧은 한 문장까지 씁니다. 이름에는 마침표를
+  찍지 않습니다.
+- 여는 요소의 접근 가능한 이름과 글자 하나까지 같게 씁니다(WCAG 2.5.3).
+- 화면에 보이는 문구를 되풀이하지 않습니다. 이미 "공유"라고 쓰인 버튼에는 툴팁이
+  필요 없습니다.
+
+## 접근성
+
+Tooltip이 알아서 하는 일
+
+- 포인터를 올리고 300ms가 지나면, 또는 키보드 초점이 닿으면 열립니다. `Escape`를
+  누르거나 스크롤하면 닫힙니다(WCAG 1.4.13).
+- 열려 있는 동안 여는 요소에 `aria-describedby`가 붙어 `role="tooltip"`인 내용을
+  가리킵니다(WCAG 4.1.2).
+
+직접 챙겨야 하는 일
+
+- **여는 요소의 이름은 직접 붙입니다.** `aria-describedby`는 설명을 더할 뿐, 아이콘만
+  있는 버튼에 이름을 주지 않습니다. 버튼에 `aria-label`을 넘깁니다.
+- **여는 요소가 초점을 받을 수 있어야 합니다.** Tooltip은 자식을 `asChild`로 감싸므로
+  자식은 실제 버튼, 링크처럼 초점을 받는 요소여야 합니다. 비활성 버튼은 포인터도 초점도
+  받지 않아 툴팁이 뜨지 않습니다.
+- 꼭 필요한 정보를 툴팁에만 두지 않습니다. 터치 화면에는 마우스 올리기가 없습니다.
+- **한 버튼에 Tooltip과 Menu를 함께 걸 때는 `ids.trigger`를 같이 씁니다.** 둘 다 그 버튼을
+  여는 요소로 삼고 각자 다른 id를 붙이므로, 메뉴가 기준 위치를 못 찾고 화면 왼쪽 위에서
+  열립니다. `useId()` 하나를 양쪽에 넘깁니다:
+  `<Menu ids={{ trigger: id }}><Tooltip ids={{ trigger: id }} …>`.
+
+## 토큰
+
+아래 표는 `Tooltip.tsx`에서 정한 토큰입니다.
+
+</Ko>
+
+<Canvas of={TooltipStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **InfoSprinkle**: a definition or explanation next to a label.
+- **Popover**: anything with links or controls.
+- **IconButton**: the usual trigger, which needs its own `aria-label`.
+- **Foundations/Brand & colour usage**: why status colours are never
+  decoration.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **InfoSprinkle**: 라벨 옆의 용어 설명이나 해설.
+- **Popover**: 링크나 컨트롤이 들어가는 내용.
+- **IconButton**: 툴팁을 여는 가장 흔한 요소이며, 자기 `aria-label`이 따로 필요합니다.
+- **Foundations/Brand & colour usage**: 상태색을 장식으로 쓰지 않는 이유.
+
+</Ko>

package/src/components/Tree/Tree.stories.tsx

@@ -3,6 +3,8 @@ import { Box, HStack, Stack, Text } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 import { IoFolder, IoFolderOpen } from 'react-icons/io5';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Tree } from './Tree';
 import {
   createTreeCollection,
@@ -562,3 +564,90 @@ export const MultipleSelection: Story = {
     </Box>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Tree.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 DoNamedWithElbows: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: a named tree, elbow guides for depth',
+  args: {
+    collection: orgCollection,
+    defaultExpandedValue: ['hq', 'hq-dev', 'hq-dev-backend'],
+    defaultSelectedValue: ['hq-dev-backend-api'],
+  },
+  render: (args) => (
+    <Box maxWidth="360px">
+      <Tree.Root {...args}>
+        <Tree.Label>조직</Tree.Label>
+        <Tree.Tree>
+          <Tree.Node
+            indentGuide={<Tree.BranchIndentGuide elbow />}
+            render={renderNode}
+          />
+        </Tree.Tree>
+      </Tree.Root>
+    </Box>
+  ),
+};
+
+const flatCollection = createTreeCollection<Node>({
+  rootNode: {
+    id: 'root',
+    name: '',
+    children: [
+      { id: 'a', name: '마케팅' },
+      { id: 'b', name: '영업' },
+      { id: 'c', name: '개발' },
+    ],
+  },
+  nodeToValue: (node) => node.id,
+  nodeToString: (node) => node.name,
+});
+
+export const DontFlatList: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: a tree for a flat list",
+  args: { collection: flatCollection, 'aria-label': '팀' },
+  render: (args) => (
+    <Box maxWidth="360px">
+      <Tree.Root {...args}>
+        <Tree.Tree>
+          <Tree.Node render={renderNode} />
+        </Tree.Tree>
+      </Tree.Root>
+    </Box>
+  ),
+};
+
+/** Tokens the Tree parts set (TreeItem / TreeBranchControl / TreeLabel / guide). */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Tokens',
+  args: { collection: orgCollection },
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'fg.default', use: <T en="Row text" ko="행 글자" /> },
+        { token: 'bg.subtle', use: <T en="Row hover" ko="행 호버" /> },
+        {
+          token: 'primary.selected',
+          use: <T en="Selected row" ko="선택된 행" />,
+        },
+        { token: 'fg.muted', use: <T en="Tree.Label" ko="Tree.Label" /> },
+        {
+          token: 'border.default',
+          use: (
+            <T
+              en="BranchIndentGuide · guideColor default"
+              ko="BranchIndentGuide · guideColor 기본값"
+            />
+          ),
+        },
+        { token: 'focus.ring', use: <T en="Focus ring" ko="초점 링" /> },
+      ]}
+    />
+  ),
+};