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

package/src/components/Chip/Chip.usage.mdx

@@ -0,0 +1,78 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ChipStories from './Chip.stories';
+
+<Meta of={ChipStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Chip (deprecated)
+
+**Use `Tag`.** Since 5.0 `Chip` is a thin alias of `Tag` and it is removed in
+6.0. It still renders so that unmigrated screens do not break, keeps the 4.x
+pill shape so they do not shift, and warns once per `colorScheme` × `variant`
+pair in development.
+
+Everything about when and how to use it is on **Components/Tag/Usage**.
+
+## Migrating
+
+| 4.x `colorScheme` | 4.x `variant` | Renders as | Write instead |
+| --- | --- | --- | --- |
+| `primary` (default), `secondary`, `neutral` | `soft` (default) or `outline` | neutral | `<Tag>` |
+| `primary`, `secondary`, `neutral` | `solid` | the selected look | `<Tag as="button" selected={…}>` for a filter chip |
+| `danger`, `success`, `warning` | `soft` | that tone | `<Tag tone="…">`, or `Badge` if it is a status |
+| `danger`, `success`, `warning` | `solid` | that tone (5.0 has no solid status fill) | Choose by hand |
+| `danger`, `success`, `warning` | `outline` | neutral | Choose by hand |
+
+"Choose by hand" pairs say so in the dev warning. A `solid` Chip gets the
+selected *look* only: it does not become a toggle and has no `aria-pressed`
+unless you pass `selected` yourself.
+
+Two things change when you swap `Chip` for `Tag`:
+
+- **Shape.** Tag uses the `md` radius and tighter padding. Chip's 32px pill
+  exists only for unmigrated screens.
+- **Interactivity.** If the chip was clickable, render the Tag `as="button"`
+  so it is keyboard-operable (WCAG 2.1.1).
+
+</En>
+
+<Ko>
+
+# Chip (지원 중단)
+
+**`Tag`를 씁니다.** 5.0부터 `Chip`은 `Tag`의 얇은 별칭이며 6.0에서 사라집니다.
+아직 옮기지 않은 화면이 깨지지 않도록 계속 그려지고, 화면이 밀리지 않도록 4.x의
+알약 모양을 유지하며, 개발 환경에서 `colorScheme` × `variant` 조합마다 한 번씩 경고를
+냅니다.
+
+언제, 어떻게 쓰는지는 모두 **Components/Tag/Usage**에 있습니다.
+
+## 옮기는 방법
+
+| 4.x `colorScheme` | 4.x `variant` | 지금 그려지는 모양 | 바꿔 쓸 코드 |
+| --- | --- | --- | --- |
+| `primary`(기본), `secondary`, `neutral` | `soft`(기본) 또는 `outline` | neutral | `<Tag>` |
+| `primary`, `secondary`, `neutral` | `solid` | 선택된 모양 | 필터 칩이라면 `<Tag as="button" selected={…}>` |
+| `danger`, `success`, `warning` | `soft` | 해당 tone | `<Tag tone="…">`, 상태라면 `Badge` |
+| `danger`, `success`, `warning` | `solid` | 해당 tone(5.0에는 진한 상태 바탕이 없음) | 직접 고릅니다 |
+| `danger`, `success`, `warning` | `outline` | neutral | 직접 고릅니다 |
+
+"직접 고릅니다"에 해당하는 조합은 개발 경고에도 그렇게 나옵니다. `solid` Chip은
+선택된 *모양*만 얻습니다. `selected`를 직접 넘기지 않는 한 토글이 되지 않고
+`aria-pressed`도 붙지 않습니다.
+
+`Chip`을 `Tag`로 바꾸면 두 가지가 달라집니다.
+
+- **모양.** Tag는 `md` 모서리와 더 좁은 여백을 씁니다. Chip의 32px 알약 모양은 아직
+  옮기지 않은 화면을 위해서만 남아 있습니다.
+- **누를 수 있는지.** 누를 수 있던 칩이라면 Tag를 `as="button"`으로 그려야 키보드로도
+  쓸 수 있습니다(WCAG 2.1.1).
+
+</Ko>
+
+<Canvas of={ChipStories.LegacyMapping} />

package/src/components/Code/Code.stories.tsx

@@ -1,5 +1,8 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Text } from '../Typography';
 import { Code } from './Code';
 import { BUNDLED_LANGUAGES } from './shikiAdapter';
 
@@ -211,3 +214,60 @@ export const CustomContainer: Story = {
 };`,
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Code.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 DoLanguageAndCopy: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a language and a copy button for a snippet',
+  args: {
+    language: 'bash',
+    onCopy: () => {},
+    children: `curl https://api.example.com/v1/chat/completions \\
+  -H "Authorization: Bearer $API_KEY" \\
+  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "안녕"}]}'`,
+  },
+};
+
+export const DontBlockForIdentifier: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a block for one word in a sentence",
+  render: () => (
+    <>
+      <Text mb={2}>요청 본문의 모델 이름 칸에는</Text>
+      <Code>model</Code>
+      <Text mt={2}>을 넣습니다.</Text>
+    </>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'border.default', use: <T en="Border" ko="테두리" /> },
+        {
+          token: 'bg.surface',
+          use: <T en="Header background" ko="머리 영역 배경" />,
+        },
+        {
+          token: 'fg.default',
+          use: <T en="Language title" ko="언어 이름" />,
+        },
+        { token: 'fg.muted', use: <T en="Copy icon" ko="복사 아이콘" /> },
+        {
+          token: 'success.fg',
+          use: <T en="Copied check" ko="복사 완료 표시" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Code/Code.usage.mdx

@@ -0,0 +1,187 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as CodeStories from './Code.stories';
+
+<Meta of={CodeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Code
+
+A syntax-highlighted block of code (Shiki, `github-dark` token colours) with
+an optional language header and copy button. `Markdown` uses it for fenced
+code blocks.
+
+## When to use
+
+- A snippet the reader reads or copies: an API request, a config file, raw
+  JSON from an audit event.
+- More than one line, or a line too long to sit inside a sentence.
+
+## When not to use
+
+- A name or value inside a sentence → `InlineCode`.
+- A single line the user only needs to copy (an endpoint, a key) →
+  `CopyableCode`.
+- The same example in several languages → `CodeTabs`.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `language` | Highlighting language (`js` is read as `javascript`). With a language, the header shows its name. |
+| `onCopy` | Turns the copy button on. The component writes to the clipboard; `onCopy` receives the copied text for side effects. |
+| `hideHeader` | No header. If `onCopy` is set, the copy button floats in the top-right corner with a 복사 / 복사 완료 tooltip. |
+| `showLineNumbers` | Line numbers in the gutter. |
+| `containerProps` | Props for the CodeBlock root (margins, `maxH`, `className`). |
+
+Without `language`, there is no header, and without `onCopy`, no copy button.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Code
+
+문법 강조(Shiki, `github-dark` 색)가 적용된 코드 블록입니다. 언어 이름이 있는 머리
+영역과 복사 버튼을 켤 수 있습니다. `Markdown`의 코드 블록도 이 컴포넌트로 그립니다.
+
+## 언제 쓰나요
+
+- 읽거나 복사할 코드 조각: API 요청, 설정 파일, 감사 로그 이벤트의 원본 JSON.
+- 두 줄 이상이거나, 문장 안에 넣기에는 너무 긴 한 줄.
+
+## 언제 쓰지 않나요
+
+- 문장 안의 이름이나 값은 `InlineCode`를 씁니다.
+- 복사만 하면 되는 한 줄(엔드포인트, 키)은 `CopyableCode`를 씁니다.
+- 같은 예제를 여러 언어로 보여 준다면 `CodeTabs`를 씁니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `language` | 강조할 언어(`js`는 `javascript`로 읽음). 언어를 주면 머리 영역에 언어 이름이 나옵니다. |
+| `onCopy` | 복사 버튼을 켭니다. 클립보드에는 컴포넌트가 직접 쓰고, `onCopy`는 복사한 글을 받아 부가 작업에 씁니다. |
+| `hideHeader` | 머리 영역을 숨깁니다. `onCopy`가 있으면 복사 버튼이 오른쪽 위에 떠 있고 '복사' / '복사 완료' 툴팁이 붙습니다. |
+| `showLineNumbers` | 줄 번호를 보여 줍니다. |
+| `containerProps` | CodeBlock 루트에 넘길 속성(여백, `maxH`, `className`). |
+
+`language`가 없으면 머리 영역이 없고, `onCopy`가 없으면 복사 버튼도 없습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={CodeStories.DoLanguageAndCopy} />
+<Verdict
+  kind="do"
+  en="Set the language and turn on copy for anything the reader will paste into a terminal or file."
+  ko="터미널이나 파일에 붙여 넣을 코드에는 언어를 지정하고 복사 버튼을 켭니다."
+/>
+
+<Canvas of={CodeStories.DontBlockForIdentifier} />
+<Verdict
+  kind="dont"
+  en="Break a sentence with a block for one word. Use InlineCode inside the sentence."
+  ko="한 단어 때문에 블록으로 문장을 끊지 마세요. 문장 안에 InlineCode를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- Show code that runs as pasted. Mark placeholders clearly (`$API_KEY`,
+  `<chatbot_id>`) and never show a real secret.
+- Keep examples short; link to full documentation for the rest.
+- Explain the code in the text around it, not in long comments inside it.
+
+## Accessibility
+
+What Code does for you:
+
+- The code is text, so it can be selected, copied and read by a screen
+  reader.
+- The copy buttons are real buttons with names. The floating copy button
+  takes its name from the translated 복사 / 복사 완료 and has a focus ring
+  (WCAG 4.1.2, 2.4.7).
+
+What you still have to do:
+
+- The header copy button's name is the fixed English "Copy code". In a
+  Korean screen, consider `hideHeader` with `onCopy` (translated name), or
+  note it for a follow-up fix.
+- Introduce the block in the text before it, so a screen reader user knows
+  what the code is for (WCAG 1.3.1).
+- A long line scrolls sideways inside the block. Keep it readable at 320px
+  width by breaking long commands (WCAG 1.4.10).
+
+## Tokens
+
+Shiki's `github-dark` paints the code itself; these are the tokens the
+component sets around it.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 붙여 넣으면 바로 동작하는 코드를 보여 줍니다. 바꿔 넣을 자리는 `$API_KEY`,
+  `<chatbot_id>`처럼 분명히 표시하고, 실제 비밀 값은 보여 주지 않습니다.
+- 예제는 짧게 두고, 나머지는 전체 문서로 연결합니다.
+- 설명은 코드 안의 긴 주석이 아니라 코드 앞뒤의 본문에 씁니다.
+
+## 접근성
+
+Code가 알아서 하는 일
+
+- 코드는 글자이므로 선택하고 복사할 수 있고 화면 낭독기도 읽습니다.
+- 복사 버튼은 이름이 있는 실제 버튼입니다. 떠 있는 복사 버튼은 번역된 '복사' /
+  '복사 완료'를 이름으로 쓰고 초점 링이 있습니다(WCAG 4.1.2, 2.4.7).
+
+직접 챙겨야 하는 일
+
+- 머리 영역의 복사 버튼 이름은 영어 "Copy code"로 고정되어 있습니다. 한국어 화면에서는
+  `hideHeader`와 `onCopy`를 함께 써서 번역된 이름을 쓰는 방법을 검토하거나, 후속 수정
+  거리로 남깁니다.
+- 블록 앞 본문에서 이 코드가 무엇인지 먼저 알려, 화면 낭독기 사용자도 코드의 쓰임을
+  알 수 있게 합니다(WCAG 1.3.1).
+- 긴 줄은 블록 안에서 가로로 스크롤됩니다. 긴 명령은 줄을 나눠 폭 320px에서도 읽을
+  수 있게 합니다(WCAG 1.4.10).
+
+## 토큰
+
+코드 자체의 색은 Shiki의 `github-dark`가 칠합니다. 아래는 컴포넌트가 그 둘레에 쓰는
+토큰입니다.
+
+</Ko>
+
+<Canvas of={CodeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **InlineCode**: code inside a sentence.
+- **CopyableCode**: one line with a copy button.
+- **CodeTabs**: the same example in several languages.
+- **Markdown**: renders fenced code blocks with Code.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **InlineCode**: 문장 안의 코드.
+- **CopyableCode**: 복사 버튼이 달린 한 줄.
+- **CodeTabs**: 같은 예제를 여러 언어로.
+- **Markdown**: 코드 블록을 Code로 그립니다.
+
+</Ko>

package/src/components/CodeTabs/CodeTabs.stories.tsx

@@ -1,6 +1,9 @@
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { CodeTabs } from './CodeTabs';
+import { CODE_CHROME } from './CodeTabs.styles';
 
 const meta = {
   title: 'Components/CodeTabs',
@@ -50,3 +53,53 @@ export const WithCopyFunction: Story = {
     },
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `CodeTabs.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 DoSameCallPerLanguage: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: one call, one tab per language',
+  args: { code: CODE_SAMPLES, onCopy: () => {} },
+};
+
+export const DontStepsAsTabs: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: different steps behind language tabs",
+  args: {
+    code: {
+      bash: 'npm install openai',
+      javascript: "const client = new OpenAI({ apiKey: process.env.API_KEY });",
+      json: '{ "model": "gpt-4o", "stream": true }',
+    },
+  },
+};
+
+const CHROME_USE = {
+  bg: { en: 'Surface (tab bar and code)', ko: '바탕(탭 막대와 코드)' },
+  bgHover: { en: 'Tab and copy hover', ko: '탭과 복사 버튼 호버' },
+  bgActive: { en: 'Copy pressed', ko: '복사 버튼 누름' },
+  fg: {
+    en: 'Selected tab; unselected at 70%, divider at 15%',
+    ko: '선택된 탭. 선택 안 된 탭은 70%, 구분선은 15%',
+  },
+} as const;
+
+/** Read from `CODE_CHROME` in `CodeTabs.styles.ts`; alpha variants folded in. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Tokens',
+  args: { code: CODE_SAMPLES },
+  render: () => (
+    <TokenTable
+      rows={(Object.keys(CHROME_USE) as (keyof typeof CHROME_USE)[]).map(
+        (role) => ({
+          token: CODE_CHROME[role],
+          use: <T {...CHROME_USE[role]} />,
+        })
+      )}
+    />
+  ),
+};

package/src/components/CodeTabs/CodeTabs.styles.ts

@@ -4,14 +4,15 @@
  * The code is highlighted with Shiki's `github-dark`, whose token colours are
  * written for a dark ground in BOTH app modes, so the surface must stay dark in
  * both too. `bg.inverse` does not: it is `tooltip.bg`, near-black in light but
- * light sand in dark, and the `fg.muted` text on it flipped as well (~1.4:1 in
+ * a light warm grey in dark, and the `fg.muted` text on it flipped as well (~1.4:1 in
  * light, ~1.1:1 in dark).
  *
  * `action.*` is the one role pair that is dark in every mode (BAZE ink:
- * #252525 light / #38332E dark, `action.fg` 12.5–13.2:1 on it, high contrast
+ * #252525 light / #2E2F2F dark, `action.fg` 10.8–13.4:1 on it, high contrast
  * included), so the chrome reads it. The unselected label is `action.fg` at
- * 70% — ≥ 7.0:1 on `action.bg` and ≥ 5.6:1 on `action.bgHover`, both schemes,
- * all four modes.
+ * 80% — ≥ 7.4:1 on `action.bg` and ≥ 6.7:1 on `action.bgHover`, both schemes,
+ * all four modes. (70% fell to 6.1:1 once dark `action.fg` became the
+ * off-white body text instead of pure white.)
  *
  * Borrowed rather than owned: `action.*` is the Run button's role. A dedicated
  * `code.*` role family (bg / fg / fgMuted / bgHover) would be the clean home.
@@ -21,6 +22,6 @@ export const CODE_CHROME = {
   bgHover: 'action.bgHover',
   bgActive: 'action.bgActive',
   fg: 'action.fg',
-  fgMuted: 'action.fg/70',
+  fgMuted: 'action.fg/80',
   divider: 'action.fg/15',
 } as const;

package/src/components/CodeTabs/CodeTabs.usage.mdx

@@ -0,0 +1,176 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as CodeTabsStories from './CodeTabs.stories';
+
+<Meta of={CodeTabsStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# CodeTabs
+
+One example shown in several languages, one tab per language, with an
+optional copy button for the tab that is showing. FactChat uses it for the
+API access snippet in a chatbot's share settings.
+
+## When to use
+
+- The same call written in two or more languages (cURL, Python,
+  JavaScript), where the reader needs only one of them.
+
+## When not to use
+
+- One snippet → `Code`.
+- Steps the reader needs in order (install, configure, run) → one `Code`
+  block per step, in sequence, so none are hidden.
+- Content that is not code → `Tabs`.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `code` | `{ [language]: source }`. The keys are the tab labels and the highlighting language, in the order given. The first is selected. |
+| `onCopy` | Turns the copy button on. The component writes the selected tab's code to the clipboard, then calls `onCopy(code)`. |
+
+The chrome is dark in both colour modes, because the `github-dark` token
+colours need a dark ground.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# CodeTabs
+
+하나의 예제를 여러 언어로 보여 주는 컴포넌트입니다. 언어마다 탭이 하나씩 있고, 보이는
+탭의 코드를 복사하는 버튼을 켤 수 있습니다. FactChat은 챗봇 공유 설정의 API 접근
+예제에 씁니다.
+
+## 언제 쓰나요
+
+- 같은 호출을 두 가지 이상의 언어(cURL, Python, JavaScript)로 보여 주고, 읽는 사람은
+  그중 하나만 필요할 때.
+
+## 언제 쓰지 않나요
+
+- 코드가 하나라면 `Code`를 씁니다.
+- 순서대로 모두 필요한 단계(설치, 설정, 실행)라면 단계마다 `Code` 블록을 차례로 두어
+  숨기는 것이 없게 합니다.
+- 코드가 아닌 내용은 `Tabs`를 씁니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `code` | `{ [언어]: 코드 }`. 키가 탭 이름이자 강조 언어이고, 넘긴 순서대로 나옵니다. 첫 탭이 선택됩니다. |
+| `onCopy` | 복사 버튼을 켭니다. 선택된 탭의 코드를 컴포넌트가 클립보드에 쓰고 `onCopy(code)`를 부릅니다. |
+
+`github-dark` 색은 어두운 바탕을 전제로 하므로, 두 색 모드 모두에서 어두운 바탕을
+씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={CodeTabsStories.DoSameCallPerLanguage} />
+<Verdict
+  kind="do"
+  en="One call, one tab per language. The reader picks theirs and copies it."
+  ko="호출 하나에 언어마다 탭 하나. 읽는 사람이 자기 언어를 골라 복사합니다."
+/>
+
+<Canvas of={CodeTabsStories.DontStepsAsTabs} />
+<Verdict
+  kind="dont"
+  en="Put different steps (install, set up the client, the request body) behind language tabs. The reader needs all three, and the tabs hide two of them."
+  ko="서로 다른 단계(설치, 클라이언트 설정, 요청 본문)를 언어 탭 뒤에 나누지 마세요. 세 단계가 모두 필요한데 탭은 둘을 숨깁니다."
+/>
+
+<En>
+
+## Content
+
+- Use a language identifier Shiki knows as the key (`python`,
+  `javascript`, `bash`); it is shown in uppercase, and any other key fails to
+  highlight.
+- Keep the examples equivalent: same call, same values, same placeholders.
+
+## Accessibility
+
+What CodeTabs does for you:
+
+- The tabs are the house `Tabs`, so the tab pattern (`tablist`, `tab`,
+  arrow-key movement) comes with them (WCAG 2.1.1, 4.1.2).
+- Hidden panels are `aria-hidden` and invisible, so only the selected
+  language is read.
+- Text on the dark chrome is at least 7:1 (`action.fg` 70% on `action.bg`)
+  in every mode (WCAG 1.4.3).
+
+What you still have to do:
+
+- The copy button's name is the fixed English "Copy"; its tooltip is
+  translated. Note it if your screen is Korean-only.
+- Say in the text above what the example does (WCAG 1.3.1).
+
+## Tokens
+
+Read from `CODE_CHROME` in `CodeTabs.styles.ts`. It borrows the `action.*`
+roles because they are the one pair that stays dark in every mode.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 키에는 Shiki가 아는 언어 식별자(`python`, `javascript`, `bash`)를 씁니다. 화면에는
+  대문자로 나오며, 다른 키를 쓰면 강조가 실패합니다.
+- 예제끼리 내용을 맞춥니다. 같은 호출, 같은 값, 같은 바꿔 넣을 자리를 씁니다.
+
+## 접근성
+
+CodeTabs가 알아서 하는 일
+
+- 탭은 이 디자인 시스템의 `Tabs`이므로 탭 패턴(`tablist`, `tab`, 화살표 키 이동)을
+  그대로 따릅니다(WCAG 2.1.1, 4.1.2).
+- 숨겨진 패널은 `aria-hidden`이고 보이지 않으므로, 선택된 언어만 읽힙니다.
+- 어두운 바탕 위의 글자는 모든 모드에서 7:1 이상입니다(`action.bg` 위의 `action.fg`
+  70%, WCAG 1.4.3).
+
+직접 챙겨야 하는 일
+
+- 복사 버튼 이름은 영어 "Copy"로 고정되어 있고 툴팁만 번역됩니다. 한국어 전용
+  화면이라면 이 점을 기록해 둡니다.
+- 예제가 무엇을 하는지 위 본문에서 알립니다(WCAG 1.3.1).
+
+## 토큰
+
+`CodeTabs.styles.ts`의 `CODE_CHROME`에서 읽습니다. 모든 모드에서 어두운 유일한 역할
+쌍이라 `action.*`을 빌려 씁니다.
+
+</Ko>
+
+<Canvas of={CodeTabsStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Code**: a single snippet.
+- **Tabs**: tabs for anything that is not code.
+- **CopyableCode**: one line with a copy button.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Code**: 코드 하나.
+- **Tabs**: 코드가 아닌 내용의 탭.
+- **CopyableCode**: 복사 버튼이 달린 한 줄.
+
+</Ko>

package/src/components/Collapsible/Collapsible.stories.tsx

@@ -1,6 +1,9 @@
 import { Meta, StoryObj } from '@storybook/react';
 import { Text } from '@chakra-ui/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Code } from '../Code';
 import { Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from '.';
 
 const meta = {
@@ -65,3 +68,58 @@ export const CompoundAPI: Story = {
     </Collapsible.Root>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Collapsible.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 DoOptionalDetail: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: optional detail, closed by default',
+  render: (args) => (
+    <CollapsibleRoot {...args} maxW="560px">
+      <CollapsibleTrigger>원본 데이터 보기</CollapsibleTrigger>
+      <CollapsibleContent>
+        <Code language="json">{`{ "event": "member.invite", "count": 3 }`}</Code>
+      </CollapsibleContent>
+    </CollapsibleRoot>
+  ),
+};
+
+export const DontVagueTrigger: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a trigger that does not say what opens",
+  render: (args) => (
+    <CollapsibleRoot {...args} maxW="560px">
+      <CollapsibleTrigger>더 보기</CollapsibleTrigger>
+      <CollapsibleContent>
+        <Text>초대 메일은 7일 뒤에 만료됩니다.</Text>
+      </CollapsibleContent>
+    </CollapsibleRoot>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'border.subtle',
+          use: (
+            <T
+              en="Root border, trigger bottom border"
+              ko="루트 테두리, 트리거 아래 테두리"
+            />
+          ),
+        },
+        { token: 'bg.subtle', use: <T en="Trigger hover" ko="트리거 호버" /> },
+      ]}
+    />
+  ),
+};