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

package/src/components/ErrorFallback/ErrorFallback.usage.mdx

@@ -0,0 +1,127 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ErrorFallbackStories from './ErrorFallback.stories';
+
+<Meta of={ErrorFallbackStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# ErrorFallback
+
+The full-height card an error boundary renders when a page or a large section
+fails to render: what happened, details for support, and a way to try again.
+
+## When to use
+
+- As the `fallback` of a React error boundary or a route-level error page
+  (FactChat uses it in its `ErrorBoundary` and route error screens).
+
+## When not to use
+
+- A request failed but the page still works → `Banner` (`danger`) in place, or
+  a `Toast`.
+- One block inside a page, such as a code block or a table in a chat message,
+  failed → a small inline fallback. ErrorFallback is at least one screen tall
+  (`100svh`).
+
+## Props
+
+</En>
+
+<Ko>
+
+# ErrorFallback
+
+페이지나 큰 영역을 그리지 못했을 때 에러 바운더리가 대신 그리는 전체 높이의
+카드입니다. 무슨 일이 있었는지, 지원팀에 전할 정보, 다시 시도하는 방법을 보여 줍니다.
+
+## 언제 쓰나요
+
+- React 에러 바운더리의 `fallback`이나 라우트 단위 오류 화면으로 씁니다(FactChat은
+  `ErrorBoundary`와 라우트 오류 화면에서 씁니다).
+
+## 언제 쓰지 않나요
+
+- 요청은 실패했지만 페이지는 쓸 수 있다면, 그 자리에 `Banner`(`danger`)를 두거나
+  `Toast`를 씁니다.
+- 채팅 메시지 안의 코드 블록이나 표처럼 페이지 안의 한 덩어리만 실패했다면 작은 인라인
+  대체 화면을 씁니다. ErrorFallback은 높이가 화면 하나(`100svh`) 이상입니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={ErrorFallbackStories} />
+
+<En>
+
+What it shows and does:
+
+- Title, subtitle, help text and button labels come from the library's
+  translations, in the app's language.
+- `error.message` is shown to the reader as is, in a `danger.bg` box. Throw
+  errors whose message a person can read, or pass an `Error` with a
+  user-facing message.
+- The support block lists the error ID (generated when `errorId` is missing),
+  the time, `componentName`, `userId` and the page path.
+- **Copy error details** copies a report with the ID, `timestamp`, component,
+  message, full URL, user ID and user agent, then confirms with a toast. The
+  app must mount `<Toaster />` for that toast to appear.
+- **Try again** calls `onErrorReset`; **Refresh page** reloads the window.
+- The time on screen is when the card rendered; the `timestamp` prop goes only
+  into the copied report.
+
+<Canvas of={ErrorFallbackStories.Default} />
+
+## Accessibility
+
+- The card is a `<section>` named by its title, so it is a landmark even when
+  the page's `<main>` failed with it (WCAG 1.3.1).
+- The title is an `<h1>` and the support block an `<h2>`, so the outline does
+  not skip levels (`ACCESSIBILITY.md` §2, KWCAG 5.2.4.2).
+- Move focus to the card's heading when it replaces content the reader was
+  using, so a screen reader user learns that the page changed (WCAG 2.4.3).
+
+## Related
+
+- **Banner**: a failure the page survives.
+- **Toast**: a failed background action.
+
+</En>
+
+<Ko>
+
+보여 주는 것과 하는 일
+
+- 제목, 부제, 도움말, 버튼 라벨은 라이브러리 번역에서 앱의 언어로 가져옵니다.
+- `error.message`는 `danger.bg` 상자 안에 그대로 보입니다. 사람이 읽을 수 있는
+  메시지로 오류를 던지거나, 사용자에게 보여 줄 메시지를 담은 `Error`를 넘깁니다.
+- 지원 정보에는 오류 ID(`errorId`가 없으면 새로 만듦), 시간, `componentName`,
+  `userId`, 페이지 경로가 나옵니다.
+- **오류 정보 복사**는 ID, `timestamp`, 컴포넌트, 메시지, 전체 URL, 사용자 ID,
+  사용자 에이전트를 담은 보고서를 복사하고 토스트로 알립니다. 그 토스트가 보이려면 앱에
+  `<Toaster />`가 있어야 합니다.
+- **다시 시도**는 `onErrorReset`을 부르고, **페이지 새로고침**은 창을 다시 엽니다.
+- 화면의 시간은 카드를 그린 시각입니다. `timestamp` 속성은 복사되는 보고서에만
+  들어갑니다.
+
+<Canvas of={ErrorFallbackStories.Default} />
+
+## 접근성
+
+- 카드는 제목으로 이름을 붙인 `<section>`이라서, 페이지의 `<main>`이 함께 사라져도
+  랜드마크가 남습니다(WCAG 1.3.1).
+- 제목은 `<h1>`, 지원 정보는 `<h2>`라서 제목 수준을 건너뛰지 않습니다
+  (`ACCESSIBILITY.md` §2, KWCAG 5.2.4.2).
+- 사용자가 쓰던 내용을 이 카드가 대신한다면 카드 제목으로 초점을 옮깁니다. 그래야 화면
+  낭독기 사용자가 페이지가 바뀐 것을 압니다(WCAG 2.4.3).
+
+## 관련 컴포넌트
+
+- **Banner**: 페이지는 살아 있는 실패.
+- **Toast**: 백그라운드 작업의 실패.
+
+</Ko>

package/src/components/ExpandableText/ExpandableText.stories.tsx

@@ -1,5 +1,8 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { LINK_RAMP, Text } from '../Typography';
 import { ExpandableText } from './ExpandableText';
 
 const meta = {
@@ -163,3 +166,55 @@ export const ComponentComparison: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `ExpandableText.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`); `tags` is written out on each story because the
+// indexer reads CSF statically.
+
+const DESCRIPTION =
+  '회의 내용을 바탕으로 요약, 결정 사항, 할 일을 정리해 주는 챗봇입니다. 녹음 파일이나 회의록을 올리면 참석자별 발언을 나눠 보여 주고, 다음 회의 전에 확인할 항목을 골라 줍니다. 팀 공용 챗봇으로 공유해 같은 형식의 회의록을 쓸 수 있습니다.';
+
+export const DoSecondaryDescription: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a long secondary description in a card',
+  render: () => (
+    <Card p={5} maxW="360px">
+      <Text fontWeight="bold" mb={1}>
+        회의록 도우미
+      </Text>
+      <ExpandableText lineClamp={2} component="Subtext">
+        {DESCRIPTION}
+      </ExpandableText>
+    </Card>
+  ),
+};
+
+export const DontClipTheMessage: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: clip what the reader must not miss",
+  render: () => (
+    <Card p={5} maxW="360px">
+      <ExpandableText lineClamp={1}>
+        이 작업은 되돌릴 수 없습니다. 그룹을 삭제하면 그룹에 속한 멤버 42명의
+        크레딧 한도와 챗봇 공유 설정이 함께 지워집니다.
+      </ExpandableText>
+    </Card>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: LINK_RAMP.default, use: '더보기 / 접기 (Link)' },
+        { token: 'fg.default', use: '더보기 / 접기 · hover' },
+      ]}
+    />
+  ),
+};

package/src/components/ExpandableText/ExpandableText.usage.mdx

@@ -0,0 +1,176 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as ExpandableTextStories from './ExpandableText.stories';
+
+<Meta of={ExpandableTextStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# ExpandableText
+
+Text clipped to a number of lines, with a 더보기 / 접기 link that opens it.
+Opening animates the height, so the content below slides down rather than
+jumping. The link appears only when the text actually overflows.
+
+## When to use
+
+- A long secondary description in a card or a header: a chatbot's
+  description, an announcement preview, an image prompt in a history list.
+
+## When not to use
+
+- The main content the reader came for → show it in full.
+- Warnings, prices, terms, or anything the reader must not miss → show it in
+  full.
+- A section with a heading and structure → `Collapsible`.
+
+## Props
+
+| Prop | Means |
+| --- | --- |
+| `lineClamp` | Lines shown while closed. Default `3`. |
+| `component` | The typography tier that wraps it: `Text` (default), `Subtitle`, `Subtext`, `H1`–`H5`. Other props go to that component. |
+| `charLimit` | Deprecated and ignored. Truncation is by line. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# ExpandableText
+
+정해진 줄 수만큼만 보여 주고, '더보기' / '접기' 링크로 펼치는 글입니다. 펼칠 때 높이가
+움직이므로 아래 내용이 갑자기 튀지 않고 밀려 내려갑니다. 링크는 글이 실제로 넘칠 때만
+나타납니다.
+
+## 언제 쓰나요
+
+- 카드나 머리 영역의 긴 보조 설명: 챗봇 설명, 공지 미리보기, 이미지 기록 목록의
+  프롬프트.
+
+## 언제 쓰지 않나요
+
+- 읽는 사람이 보러 온 본 내용은 전부 보여 줍니다.
+- 경고, 가격, 약관처럼 놓치면 안 되는 내용은 전부 보여 줍니다.
+- 제목과 구조가 있는 섹션은 `Collapsible`을 씁니다.
+
+## 속성
+
+| 속성 | 뜻 |
+| --- | --- |
+| `lineClamp` | 접혀 있을 때 보여 줄 줄 수. 기본값 `3`. |
+| `component` | 감싸는 글자 단계: `Text`(기본값), `Subtitle`, `Subtext`, `H1`–`H5`. 나머지 속성은 이 컴포넌트로 넘어갑니다. |
+| `charLimit` | deprecated이며 무시됩니다. 글은 줄 단위로 자릅니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={ExpandableTextStories.DoSecondaryDescription} />
+<Verdict
+  kind="do"
+  en="Clip a long secondary description so the cards in a row stay the same height."
+  ko="긴 보조 설명을 접어서, 한 줄에 놓인 카드들의 높이를 맞춥니다."
+/>
+
+<Canvas of={ExpandableTextStories.DontClipTheMessage} />
+<Verdict
+  kind="dont"
+  en="Clip a warning. The consequence sits behind 더보기, where most people never look."
+  ko="경고를 접지 마세요. 결과가 '더보기' 뒤에 숨어 대부분의 사람이 보지 못합니다."
+/>
+
+<En>
+
+## Content
+
+- Put the most important sentence first, so the clipped lines still say what
+  the text is about.
+- Keep `lineClamp` the same for every item in a list.
+
+## Accessibility
+
+What ExpandableText does for you:
+
+- The toggle is a `<button>` styled as a link, with `aria-expanded`, and a
+  translated label (더보기 / 접기) (WCAG 2.1.1, 4.1.2).
+- The full text is in the DOM while closed; only its height is clipped, so
+  find-in-page and text selection reach it.
+
+What you still have to do:
+
+- While closed, the hidden lines are still read by a screen reader (they are
+  only clipped visually). Do not rely on the clamp to shorten what is
+  announced.
+- Do not use a heading tier (`H1`–`H5`) for a long paragraph only to get its
+  size; the whole paragraph becomes a heading (`ACCESSIBILITY.md` §2).
+- Known markup issue: the clipping box is a `<div>` inside the `<p>` (or
+  heading) that `component` renders, which a markup validator reports as a
+  nesting error (KWCAG 5.4.1.1). Tracked in the PR that added this page.
+
+## Tokens
+
+The toggle is a `Link`; on hover it turns `fg.default` instead of
+`fg.linkHover`, and it has no underline.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 가장 중요한 문장을 앞에 둡니다. 그래야 접힌 상태에서도 무엇에 관한 글인지 알 수
+  있습니다.
+- 한 목록 안의 항목은 모두 같은 `lineClamp`를 씁니다.
+
+## 접근성
+
+ExpandableText가 알아서 하는 일
+
+- 펼침 버튼은 링크 모양의 `<button>`이고, `aria-expanded`와 번역된 이름('더보기' /
+  '접기')이 있습니다(WCAG 2.1.1, 4.1.2).
+- 접혀 있어도 전체 글이 DOM에 있고 높이만 잘립니다. 그래서 페이지 내 검색과 글 선택이
+  닿습니다.
+
+직접 챙겨야 하는 일
+
+- 접혀 있어도 화면 낭독기는 숨은 줄까지 읽습니다(화면에서만 잘립니다). 읽히는 양을
+  줄이는 용도로 쓰지 않습니다.
+- 크기만 보고 긴 문단에 제목 단계(`H1`–`H5`)를 쓰지 않습니다. 문단 전체가 제목이
+  됩니다(`ACCESSIBILITY.md` 2절).
+- 알려진 마크업 문제: 자르는 상자가 `component`가 그리는 `<p>`(또는 제목) 안의
+  `<div>`라서, 마크업 검사기가 중첩 오류로 봅니다(KWCAG 5.4.1.1). 이 페이지를 추가한
+  PR에 기록해 두었습니다.
+
+## 토큰
+
+펼침 버튼은 `Link`입니다. 호버하면 `fg.linkHover`가 아니라 `fg.default`로 바뀌고,
+밑줄이 없습니다.
+
+</Ko>
+
+<Canvas of={ExpandableTextStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Collapsible**: a section with a trigger.
+- **Typography**: the tiers `component` can use.
+- **Markdown**: formatted long text.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Collapsible**: 트리거가 있는 섹션.
+- **Typography**: `component`로 고를 수 있는 글자 단계.
+- **Markdown**: 서식 있는 긴 글.
+
+</Ko>

package/src/components/FileInput/FileInput.stories.tsx

@@ -1,9 +1,12 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { useState } from 'react';
 
+import { Stack } from '@chakra-ui/react';
+
+import { FieldRow } from '../Form';
 import { FileInput } from '.';
 
- const meta = {
+const meta = {
   title: 'Components/FileInput',
   component: FileInput,
   args: {
@@ -36,3 +39,37 @@ export const Basic: Story = {
     return <FileInput onChange={handleChange} bgImage={bgImage} />;
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FileInput.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoSayWhatFits: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: say which files fit',
+  render: () => (
+    <Stack maxW="420px">
+      <FieldRow
+        label="멤버 목록 파일"
+        helperText="CSV 또는 XLSX, 최대 5MB. 첫 줄은 이메일, 이름 순서입니다."
+      >
+        <FileInput
+          accept=".csv,.xlsx"
+          fileInputLabel="파일을 눌러서 고르기"
+          onChange={() => {}}
+        />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DontUnexplained: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: no type, size or purpose",
+  render: () => (
+    <Stack maxW="420px">
+      <FileInput onChange={() => {}} />
+    </Stack>
+  ),
+};

package/src/components/FileInput/FileInput.usage.mdx

@@ -0,0 +1,178 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FileInputStories from './FileInput.stories';
+
+<Meta of={FileInputStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FileInput
+
+A dashed area that opens the system file picker when clicked, with an
+optional image preview behind it.
+
+## When to use
+
+- Uploading a file into a form: a member list CSV, a policy document,
+  reference images, a project file.
+- Replacing an image, with the current one shown through `bgImage`.
+
+## When not to use
+
+- Attaching files to a chat message → the chat composer's attach button.
+- Showing files already uploaded → `FileList` or `FileItem` (put them under
+  the FileInput).
+
+## Props
+
+</En>
+
+<Ko>
+
+# FileInput
+
+누르면 시스템 파일 선택 창이 열리는 점선 영역입니다. 뒤에 이미지 미리보기를 깔 수
+있습니다.
+
+## 언제 쓰나요
+
+- 폼에 파일을 올릴 때: 멤버 목록 CSV, 정책 문서, 참고 이미지, 프로젝트 파일.
+- 이미지를 바꿀 때. 지금 이미지는 `bgImage`로 보여 줍니다.
+
+## 언제 쓰지 않나요
+
+- 채팅 메시지에 파일을 붙일 때는 채팅 입력창의 첨부 버튼을 씁니다.
+- 이미 올린 파일을 보여 줄 때는 `FileList`나 `FileItem`을 씁니다(FileInput 아래에
+  둡니다).
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={FileInputStories}
+  include={[
+    'onChange',
+    'fileInputLabel',
+    'bgImage',
+    'isLoading',
+    'containerStyle',
+  ]}
+/>
+
+<En>
+
+`onChange` receives the browser's `FileList` (or `null`). Native input props
+such as `accept`, `multiple` and `name` pass through to the hidden
+`<input type="file">`, and the forwarded ref points at it. `isLoading`
+replaces the prompt with a spinner. The default prompt is translated
+(`upload_your_file`). The area does not handle drag and drop.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+`onChange`는 브라우저의 `FileList`(또는 `null`)를 받습니다. `accept`, `multiple`,
+`name` 같은 네이티브 속성은 숨은 `<input type="file">`에 그대로 전달되고, 넘긴 ref도 이
+입력을 가리킵니다. `isLoading`이면 안내 문구 대신 스피너를 보여 줍니다. 기본 안내
+문구는 번역됩니다(`upload_your_file`). 끌어다 놓기는 처리하지 않습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FileInputStories.DoSayWhatFits} />
+<Verdict
+  kind="do"
+  en="Label it, set accept, and say the allowed types, size limit and expected layout in helper text."
+  ko="라벨을 붙이고 accept를 지정하며, 받는 형식, 최대 크기, 내용 형식을 도움말로 알려 줍니다."
+/>
+
+<Canvas of={FileInputStories.DontUnexplained} />
+<Verdict
+  kind="dont"
+  en="Show the drop area with only the default prompt. The user finds out the rules by failing."
+  ko="기본 안내 문구만 있는 영역을 두지 마세요. 사용자는 실패하고 나서야 조건을 압니다."
+/>
+
+<En>
+
+## Content
+
+- The prompt says what to do with the pointer (파일을 눌러서 고르기). Do not
+  promise dragging; it is not supported.
+- Types and size limit go in `FieldRow` `helperText`, the same words the
+  error will use.
+
+## Accessibility
+
+What FileInput does for you:
+
+- The prompt sits inside a `<label>` around the file input, so clicking
+  anywhere in it opens the picker. There is no extra role on the wrapper
+  (`ACCESSIBILITY.md` §3).
+
+Known gap, and what to do:
+
+- **It cannot be reached by keyboard.** The file input is `hidden`, so it is
+  out of the tab order and the label is not focusable (WCAG 2.1.1). Until the
+  component is fixed, add a visible `Button` next to it that calls
+  `ref.current?.click()`.
+- Wrap it in `FieldRow` with a label so the purpose is in text (WCAG 3.3.2),
+  and report rejected files in words, not only with the red row in
+  `FileItem` (WCAG 3.3.1).
+
+## Tokens
+
+The dashed border is `border.default`; the prompt and icon are `fg.subtle` on
+a `bg.muted` tile, over an 85% `bg.surface` wash. With `bgImage` the prompt
+turns `fg.default` and appears on hover.
+
+## Related
+
+- **FileList** / **FileItem**: what was uploaded.
+- **FieldRow**: label, rules and error.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 안내 문구에는 포인터로 할 일을 씁니다(파일을 눌러서 고르기). 끌어다 놓기는 지원하지
+  않으므로 약속하지 않습니다.
+- 형식과 최대 크기는 `FieldRow`의 `helperText`에 쓰고, 오류 문구에서도 같은 표현을
+  씁니다.
+
+## 접근성
+
+FileInput이 알아서 하는 일
+
+- 안내 문구가 파일 입력을 감싼 `<label>` 안에 있어서 영역 어디를 눌러도 선택 창이
+  열립니다. 감싸는 요소에 불필요한 역할을 주지 않습니다(`ACCESSIBILITY.md` 3절).
+
+알려진 한계와 대처
+
+- **키보드로 닿을 수 없습니다.** 파일 입력이 `hidden`이라 Tab 순서에서 빠지고, 라벨도
+  초점을 받지 않습니다(WCAG 2.1.1). 고쳐지기 전까지는 옆에 `ref.current?.click()`을
+  호출하는 보이는 `Button`을 둡니다.
+- 라벨이 있는 `FieldRow`로 감싸 용도를 글자로 알리고(WCAG 3.3.2), 받지 못한 파일은
+  `FileItem`의 빨간 행만이 아니라 문구로 알립니다(WCAG 3.3.1).
+
+## 토큰
+
+점선 테두리는 `border.default`, 안내 문구와 아이콘은 `bg.muted` 타일 위의
+`fg.subtle`이며, 바탕은 85% `bg.surface`입니다. `bgImage`가 있으면 안내 문구가
+`fg.default`로 바뀌고 마우스를 올렸을 때 나타납니다.
+
+## 관련 컴포넌트
+
+- **FileList** / **FileItem**: 올린 파일.
+- **FieldRow**: 라벨, 조건, 오류 문구.
+
+</Ko>

package/src/components/FileItem/FileItem.stories.tsx

@@ -1,5 +1,10 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { Stack } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { FieldRow } from '../Form';
 import { FileItem } from './FileItem';
 
 const meta = {
@@ -53,3 +58,69 @@ export const Deleting: Story = {
     isDeleting: true,
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FileItem.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoErrorInText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: repeat the error in text',
+  render: () => (
+    <Stack maxW="480px">
+      <FieldRow error="members.xlsx: 파일이 5MB를 넘습니다. 나눠서 올려 주세요.">
+        <FileItem
+          fileName="members.xlsx"
+          error="파일이 5MB를 넘습니다."
+          onFileDelete={() => {}}
+        />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DontErrorInTooltipOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the reason only in a tooltip",
+  render: () => (
+    <Stack maxW="480px">
+      <FileItem
+        fileName="members.xlsx"
+        error="파일이 5MB를 넘습니다."
+        onFileDelete={() => {}}
+      />
+    </Stack>
+  ),
+};
+
+/** Tokens `FileItem.tsx` reads. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'border.subtle', use: <T en="Row border" ko="행 테두리" /> },
+        {
+          token: 'fg.muted',
+          use: <T en="File icon, action icons" ko="파일 아이콘, 동작 아이콘" />,
+        },
+        {
+          token: 'fg.subtle',
+          use: <T en="Cancel-upload icon" ko="업로드 취소 아이콘" />,
+        },
+        {
+          token: 'danger.fg',
+          use: (
+            <T
+              en="Error: left bar, icon, file name"
+              ko="오류: 왼쪽 막대, 아이콘, 파일 이름"
+            />
+          ),
+        },
+      ]}
+    />
+  ),
+};