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

package/src/foundations/BrandColour.stories.tsx

@@ -0,0 +1,343 @@
+import { Flex, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+
+import { Badge } from '../components/Badge';
+import { Button } from '../components/Button';
+import { Card } from '../components/Card';
+import { CountBadge } from '../components/CountBadge';
+import { SendIcon, Sparkles } from '../components/Icon';
+import { IconButton } from '../components/IconButton';
+import { Tag } from '../components/Tag';
+import { Link, Text } from '../components/Typography';
+import { T } from '../guidelines/_components/Lang';
+import { TokenTable } from '../guidelines/_components/TokenTable';
+import { SYSTEM_HUE_NAMES } from '../theme/colors';
+
+/**
+ * Specimens for `BrandColour.mdx` (Foundations / Brand & colour usage).
+ *
+ * Every swatch is resolved from the shipped theme by `TokenTable`, and every
+ * live example is a real component, so the page follows the palette. Hidden
+ * from the sidebar (`!dev`); the MDX page is the entry point.
+ */
+const meta: Meta = {
+  title: 'Foundations/Brand & colour usage',
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+};
+export default meta;
+type Story = StoryObj;
+
+export const Neutrals: Story = {
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.canvas',
+          use: <T en="Page (layer 0)" ko="페이지 바탕 (layer 0)" />,
+        },
+        {
+          token: 'layer.1',
+          use: <T en="Sidebar, panel" ko="사이드바, 패널" />,
+        },
+        {
+          token: 'layer.2',
+          use: <T en="Card on a panel" ko="패널 위 카드" />,
+        },
+        {
+          token: 'bg.muted',
+          use: (
+            <T
+              en="Soft fill: neutral badge, wash card"
+              ko="옅은 면: 중립 배지, 카드"
+            />
+          ),
+        },
+        {
+          token: 'border.default',
+          use: <T en="Card border" ko="카드 테두리" />,
+        },
+        {
+          token: 'fg.default',
+          use: <T en="Body text (brand black)" ko="본문 글자 (브랜드 블랙)" />,
+        },
+        {
+          token: 'fg.muted',
+          use: <T en="Secondary text" ko="보조 글자" />,
+        },
+        {
+          token: 'fg.subtle',
+          use: <T en="Captions" ko="설명 글자" />,
+        },
+        {
+          token: 'fg.onPrimary',
+          use: <T en="Text on a primary fill" ko="주요 버튼 위 글자" />,
+        },
+      ]}
+    />
+  ),
+};
+
+export const ButtonStates: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Flex gap={3} wrap="wrap" align="center">
+        <Button variant="primary">
+          <T en="Subscribe" ko="구독하기" />
+        </Button>
+        <Button variant="secondary">
+          <T en="Cancel" ko="취소" />
+        </Button>
+        <Button variant="subtle">
+          <T en="More" ko="더보기" />
+        </Button>
+        <Button variant="ghost">
+          <T en="Edit" ko="수정" />
+        </Button>
+        <Button variant="primary" disabled>
+          <T en="Current plan" ko="현재 플랜" />
+        </Button>
+      </Flex>
+      <TokenTable
+        rows={[
+          {
+            token: 'primary.main',
+            use: (
+              <T
+                en="Primary fill, checked controls"
+                ko="주요 버튼 바탕, 켜진 컨트롤"
+              />
+            ),
+          },
+          { token: 'primary.hover', use: <T en="Hover" ko="호버" /> },
+          { token: 'primary.active', use: <T en="Pressed" ko="누름" /> },
+          {
+            token: 'primary.wash',
+            use: (
+              <T en="Hover on outline / ghost" ko="테두리·고스트 버튼 호버" />
+            ),
+          },
+          {
+            token: 'primary.washActive',
+            use: (
+              <T en="Pressed on outline / ghost" ko="테두리·고스트 버튼 누름" />
+            ),
+          },
+          {
+            token: 'primary.selected',
+            use: <T en="Selected row or menu item" ko="선택된 목록 행·메뉴" />,
+          },
+          {
+            token: 'focus.ring',
+            use: <T en="Focus ring (never coral)" ko="포커스 링 (코랄 금지)" />,
+          },
+          {
+            token: 'disabled.bg',
+            use: (
+              <T
+                en="Disabled fill (grey, no opacity)"
+                ko="비활성 바탕 (회색, 투명도 없음)"
+              />
+            ),
+          },
+          {
+            token: 'disabled.fg',
+            use: <T en="Disabled text" ko="비활성 글자" />,
+          },
+          {
+            token: 'disabled.fgGhost',
+            use: (
+              <T
+                en="Disabled text/icon of a fill-less ghost button"
+                ko="바탕 없는 고스트 버튼의 비활성 글자·아이콘"
+              />
+            ),
+          },
+        ]}
+      />
+    </Stack>
+  ),
+};
+
+export const Distinction: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Flex gap={3} wrap="wrap" align="center">
+        <Badge>Pro</Badge>
+        <Card px={3} py={2} borderColor="secondary.border">
+          <Text color="secondary.fgStrong" fontWeight="bold">
+            +4,500
+          </Text>
+        </Card>
+      </Flex>
+      <TokenTable
+        rows={[
+          {
+            token: 'secondary.fg',
+            use: <T en="Icons, accent numbers" ko="아이콘, 강조 숫자" />,
+          },
+          {
+            token: 'secondary.fgStrong',
+            use: <T en="Text (neutral Badge)" ko="글자 (중립 배지)" />,
+          },
+          {
+            token: 'secondary.border',
+            use: <T en="Borders, dividers" ko="테두리, 구분선" />,
+          },
+          {
+            token: 'secondary.surface',
+            use: (
+              <T
+                en="Tint only — not a background"
+                ko="틴트 전용 — 바탕으로 쓰지 않음"
+              />
+            ),
+          },
+        ]}
+      />
+    </Stack>
+  ),
+};
+
+export const Coral: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Flex gap={4} wrap="wrap" align="center">
+        <Button variant="action">
+          <Sparkles />
+          <T en="Generate image" ko="이미지 생성" />
+        </Button>
+        <IconButton variant="action" aria-label="보내기">
+          <SendIcon />
+        </IconButton>
+        <CountBadge count={3} label="읽지 않은 알림 3개" />
+      </Flex>
+      <TokenTable
+        rows={[
+          {
+            token: 'send.bg',
+            use: (
+              <T
+                en="Send button fill, Button accent"
+                ko="보내기 버튼 바탕, Button accent"
+              />
+            ),
+          },
+          {
+            token: 'send.fg',
+            use: <T en="Arrow / label on it" ko="그 위 화살표·글자" />,
+          },
+          {
+            token: 'action.iconOnSolid',
+            use: (
+              <T
+                en="Coral icon on the black run button"
+                ko="블랙 실행 버튼의 코랄 아이콘"
+              />
+            ),
+          },
+          {
+            token: 'action.bg',
+            use: <T en="Run button fill" ko="실행 버튼 바탕" />,
+          },
+          {
+            token: 'action.mark',
+            use: (
+              <T
+                en="AI-working mark, logo, large type"
+                ko="AI 작업 중 표시, 로고, 큰 글씨"
+              />
+            ),
+          },
+          {
+            token: 'count.bg',
+            use: <T en="Unread count badge" ko="읽지 않은 숫자 배지" />,
+          },
+          { token: 'count.fg', use: <T en="Number on it" ko="그 위 숫자" /> },
+        ]}
+      />
+    </Stack>
+  ),
+};
+
+const STATUS = [
+  { s: 'danger', en: 'Failed', ko: '실패' },
+  { s: 'warning', en: 'Pending', ko: '대기 중' },
+  { s: 'success', en: 'Done', ko: '완료' },
+  { s: 'info', en: 'This group only', ko: '이 그룹만' },
+] as const;
+
+export const Status: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Flex gap={2} wrap="wrap">
+        {STATUS.map(({ s, en, ko }) => (
+          <Badge key={s} variant={s}>
+            <T en={en} ko={ko} />
+          </Badge>
+        ))}
+      </Flex>
+      <TokenTable
+        rows={STATUS.flatMap(({ s }) => [
+          {
+            token: `${s}.bg`,
+            use: <T en={`${s} · surface`} ko={`${s} · 면`} />,
+          },
+          {
+            token: `${s}.fg`,
+            use: <T en={`${s} · text, icon`} ko={`${s} · 글자, 아이콘`} />,
+          },
+          {
+            token: `${s}.solid`,
+            use: <T en={`${s} · fill, bar`} ko={`${s} · 채움, 바`} />,
+          },
+        ])}
+      />
+    </Stack>
+  ),
+};
+
+export const Categories: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Flex gap={2} wrap="wrap">
+        {SYSTEM_HUE_NAMES.map((hue) => (
+          <Tag key={hue} category={hue} icon="#">
+            {hue}
+          </Tag>
+        ))}
+      </Flex>
+      <TokenTable
+        rows={SYSTEM_HUE_NAMES.flatMap((hue) => [
+          `category.${hue}.surface`,
+          `category.${hue}.fg`,
+        ])}
+      />
+    </Stack>
+  ),
+};
+
+export const Links: Story = {
+  render: () => (
+    <Stack gap={5}>
+      <Text>
+        <T en="Read the " ko="자세한 내용은 " />
+        <Link href="#">
+          <T en="usage policy" ko="이용 정책" />
+        </Link>
+        <T en=" before you share a chatbot." ko="을 확인하세요." />
+      </Text>
+      <TokenTable
+        rows={[
+          {
+            token: 'fg.link',
+            use: (
+              <T en="Link text, with underline" ko="링크 글자 (밑줄과 함께)" />
+            ),
+          },
+          { token: 'fg.linkHover', use: <T en="Link hover" ko="링크 호버" /> },
+        ]}
+      />
+    </Stack>
+  ),
+};

package/src/guidelines/ComponentPageTemplate.mdx

@@ -0,0 +1,84 @@
+import { Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from './_components/Lang';
+
+<Meta title="Guidelines/Component page template" />
+
+<LangToggle />
+
+<En>
+
+# Component page template
+
+Every component usage page follows the same eight sections, in this order.
+**Components/Badge/Usage** is the reference page.
+
+| # | Section | What goes in it | Source |
+| --- | --- | --- | --- |
+| 1 | **Overview** | One sentence under the title: what the component is for. | New prose |
+| 2 | **When to use / when not to** | Each "not" points to the alternative component. | New prose |
+| 3 | **Variants and what they mean** | `<ArgTypes of={Stories} include={['variant']} />`, then a table of meaning and examples. | The prop JSDoc, written once |
+| 4 | **Do / Don't** | Each specimen is a story, pulled in with `<Canvas of={…} />` and captioned with `<Verdict>`. | New stories |
+| 5 | **Content** | Length, case, wording, Korean label rules. | New prose |
+| 6 | **Accessibility** | What the component does for you, then what you still have to do. Cite WCAG success criteria; cite a KWCAG item only if `ACCESSIBILITY.md` already uses it. | `ACCESSIBILITY.md` |
+| 7 | **Tokens** | The tokens the component reads, light and dark, rendered with `TokenTable` from its `*.styles.ts`. | Generated |
+| 8 | **Related** | Neighbouring components and the Foundations page that explains the rule. | New prose |
+
+## How to write one
+
+1. Create `src/components/<Name>/<Name>.usage.mdx` and attach it to the stories
+   with `<Meta of={Stories} name="Usage" />`.
+2. Put `<LangToggle />` at the top. Write every block twice, in `<En>` and
+   `<Ko>`, in the same file. Leave a blank line inside each tag so Markdown
+   parses. For short captions use `<T en="…" ko="…" />`.
+3. Add each Do/Don't specimen to `<Name>.stories.tsx` with
+   `tags: ['!dev']` (hidden from the sidebar) and a name starting with
+   `Usage /`. **Never paste JSX into the MDX**: a story type-checks, a code
+   block does not.
+4. Use tokens, not hex, in prose. Swatches come from `TokenTable`, which reads
+   the shipped theme.
+5. Korean copy is written, not translated: complete sentences in 합니다체, no
+   한자, no translationese.
+
+The doc helpers (`src/guidelines/_components/`) are not exported from the
+library and are excluded from the rollup build.
+
+</En>
+
+<Ko>
+
+# 컴포넌트 페이지 템플릿
+
+컴포넌트 사용 페이지는 모두 같은 여덟 절을 같은 순서로 씁니다. 기준 페이지는
+**Components/Badge/Usage**입니다.
+
+| # | 절 | 들어갈 내용 | 출처 |
+| --- | --- | --- | --- |
+| 1 | **개요** | 제목 아래 한 문장. 이 컴포넌트를 어디에 쓰는지 | 새로 작성 |
+| 2 | **언제 쓰나요 / 언제 쓰지 않나요** | "쓰지 않는 경우"마다 대신 쓸 컴포넌트를 적습니다 | 새로 작성 |
+| 3 | **변형과 뜻** | `<ArgTypes of={Stories} include={['variant']} />` 다음에 뜻과 예를 담은 표 | 속성 JSDoc(한 곳에만 작성) |
+| 4 | **이렇게 하세요 / 이렇게 하지 마세요** | 예시마다 스토리를 만들어 `<Canvas of={…} />`로 불러오고 `<Verdict>`로 설명을 답니다 | 새 스토리 |
+| 5 | **문구** | 길이, 대소문자, 표현, 한국어 라벨 규칙 | 새로 작성 |
+| 6 | **접근성** | 컴포넌트가 알아서 하는 일, 그다음 직접 챙겨야 하는 일. WCAG 성공 기준을 인용하고, KWCAG 항목 번호는 `ACCESSIBILITY.md`에 이미 있는 것만 씁니다 | `ACCESSIBILITY.md` |
+| 7 | **토큰** | 컴포넌트가 읽는 토큰의 라이트·다크 값. `*.styles.ts`를 읽어 `TokenTable`로 그립니다 | 자동 생성 |
+| 8 | **관련 컴포넌트** | 이웃 컴포넌트와 규칙을 설명하는 Foundations 페이지 | 새로 작성 |
+
+## 작성 순서
+
+1. `src/components/<Name>/<Name>.usage.mdx`를 만들고
+   `<Meta of={Stories} name="Usage" />`로 스토리에 붙입니다.
+2. 맨 위에 `<LangToggle />`을 둡니다. 모든 블록을 한 파일 안에서 `<En>`과 `<Ko>`로 두
+   번 씁니다. 마크다운이 해석되도록 태그 안쪽에 빈 줄을 둡니다. 짧은 설명은
+   `<T en="…" ko="…" />`를 씁니다.
+3. 이렇게 하세요/하지 마세요 예시는 `<Name>.stories.tsx`에 `tags: ['!dev']`(사이드바에서
+   숨김)를 달고 이름을 `Usage /`로 시작해 추가합니다. **MDX에 JSX를 붙여 넣지 않습니다.**
+   스토리는 타입 검사를 받지만 코드 블록은 받지 않습니다.
+4. 본문에는 16진수 값이 아니라 토큰 이름을 씁니다. 색 견본은 실제 테마를 읽는
+   `TokenTable`로 그립니다.
+5. 한국어는 번역하지 말고 처음부터 씁니다. 합니다체의 완전한 문장으로 쓰고, 한자와
+   번역투를 쓰지 않습니다.
+
+문서용 도구(`src/guidelines/_components/`)는 라이브러리에서 내보내지 않으며 rollup
+빌드에서도 빠집니다.
+
+</Ko>

package/src/guidelines/FeedbackActions.mdx

@@ -1,7 +1,13 @@
 import { Meta } from '@storybook/blocks';
 
+import { En, Ko, LangToggle } from './_components/Lang';
+
 <Meta title="Guidelines/Actions in feedback surfaces" />
 
+<LangToggle />
+
+<En>
+
 # Actions in feedback surfaces
 
 Toasts, inline banners, panes and dialogs often need a control: "buy credits",
@@ -20,13 +26,13 @@ container it sits in?**
 ## Why this exists
 
 Until `Toast` had an `action` prop, callers who wanted a button in a toast put
-a `<Button>` inside `description` and styled it themselves. On the credit-402
-toast in FactChat that produced a neutral outline button (`#494949` text, ink
-hairline) on a rose toast (`#FFE6E8` background, `#69000A` text). It carried
-none of the toast's colors, so it read as a separate card dropped on top.
+a `<Button>` inside `description` and styled it themselves. On FactChat's
+credit-402 toast (4.x) that produced a neutral outline button on a rose
+toast. It carried none of the toast's colours, so it read as a separate card
+dropped on top.
 
 The fix is one recipe for every toast: the action uses the toast's own text
-color, the same treatment as the close ×.
+colour, the same treatment as the close ×.
 
 ---
 
@@ -37,11 +43,11 @@ color, the same treatment as the close ×.
 Toasts and inline banners carry **text actions**. Buttons belong to surfaces
 that own the space: a pane, a dialog, an empty state.
 
-### 2. The action takes the status color
+### 2. The action takes the status colour
 
-Inside a tinted container the action uses **that container's text color**
-(`danger.dark` on an error toast, `primary.dark` on an info toast). Never a
-neutral control.
+Inside a tinted container the action uses **that container's text colour**:
+`danger.fg` on an error toast, `info.fg` on an info toast (`{status}.fg` in
+general). Never a neutral control.
 
 ### 3. One action per toast; dismiss is ×
 
@@ -55,9 +61,9 @@ credits to continue". Toast copy stays **within 2 lines**.
 
 ### 5. In a pane, the fix is the primary
 
-In a pane or empty state, the action that fixes the problem is the primary
-(ink solid, `colorPalette="neutral" variant="solid"`). Dismiss is outline
-neutral (`colorPalette="neutral" variant="outline"`).
+In a pane or empty state, the action that fixes the problem is the primary:
+`<Button variant="primary">` (black fill). Dismiss is
+`<Button variant="secondary">` (outlined).
 
 ### 6. Toasts with an action stay longer
 
@@ -69,12 +75,12 @@ action defaults to **8s** instead of 5s. `useToast` does this for you when
 
 ## Which control goes where
 
-| Surface            | Primary action                                     | Secondary / dismiss              | Max actions | Copy                                       |
-| ------------------ | -------------------------------------------------- | -------------------------------- | ----------- | ------------------------------------------ |
-| Toast              | Text action in status color, via the `action` prop | × only                           | 1           | ≤ 2 lines, no hint that repeats the action |
-| Inline banner      | Trailing text action in status color               | × if dismissible                 | 1           | 1 line, wraps on mobile                    |
-| Pane / empty state | Ink solid (`neutral` `solid`)                      | Outline neutral                  | 2           | Title + reason + optional hint             |
-| Dialog             | Ink solid, right                                   | Outline neutral, left of primary | 2           | Title + body                               |
+| Surface | Primary action | Secondary / dismiss | Max actions | Copy |
+| --- | --- | --- | --- | --- |
+| Toast | Text action in `{status}.fg`, via the `action` prop | × only | 1 | ≤ 2 lines, no hint that repeats the action |
+| Inline banner | Trailing text action in `{status}.fg`, passed as children (Banner has no `action` prop) | × if dismissible | 1 | 1 line, wraps on mobile |
+| Pane / empty state | `Button variant="primary"` | `Button variant="secondary"` | 2 | Title + reason + optional hint |
+| Dialog | `Button variant="primary"`, right | `Button variant="secondary"`, left of primary | 2 | Title + body |
 
 ---
 
@@ -97,7 +103,7 @@ showToast({
 ```
 
 - The action renders under the description, aligned with the text column, in
-  the toast's status color with the same hover tint as the ×.
+  the toast's `{status}.fg` with the same hover tint as the × (`{status}.border`).
 - Clicking it calls `onClick` and dismisses the toast.
 - `label` accepts any `ReactNode`, but keep it a short verb phrase.
 - An explicit `duration` (including `null` for a persistent toast) always wins.
@@ -108,21 +114,21 @@ showToast({
 ### Don't: a button inside `description`
 
 ```tsx
-// ✗ A neutral control dropped onto a tinted toast; it carries none of the
-//   toast's colors, adds a third line, and dismissal is left to the caller.
+// ✗ A separate control dropped onto a tinted toast; it carries none of the
+//   toast's colours, adds a third line, and dismissal is left to the caller.
 showToast({
   status: 'error',
   description: (
     <>
       크레딧이 부족합니다. 크레딧을 구매하면 계속 사용할 수 있습니다.
-      <Button colorPalette="neutral" variant="outline" onClick={buy}>
+      <Button variant="secondary" onClick={buy}>
         크레딧 구매
       </Button>
     </>
   ),
 });
 
-// ✓ One action, in the toast's color, and the copy doesn't repeat it.
+// ✓ One action, in the toast's colour, and the copy doesn't repeat it.
 showToast({
   status: 'error',
   description: '크레딧이 부족합니다.',
@@ -131,3 +137,136 @@ showToast({
 ```
 
 See **Components/Toast → Action / …** for each status and a short-message case.
+
+</En>
+
+<Ko>
+
+# 피드백 영역 안의 동작
+
+토스트, 인라인 배너, 패널, 대화상자에는 "크레딧 구매", "되돌리기", "파일 열기" 같은
+컨트롤이 자주 필요합니다. 이 페이지는 어떤 컨트롤을 어디에 두고 어떤 모양으로 그리는지
+정리합니다.
+
+모든 경우에 묻는 질문은 하나입니다. **그 컨트롤이 놓인 영역의 일부처럼 보이나요?**
+
+> 전후 비교와 직접 해 볼 수 있는 시안:
+> [feedback-actions-proto.apps.mindlogic.tools](https://feedback-actions-proto.apps.mindlogic.tools/)
+> (사내 로그인 필요)
+
+---
+
+## 왜 필요한가요
+
+`Toast`에 `action` 속성이 생기기 전에는 토스트에 버튼을 넣으려면 `description` 안에
+`<Button>`을 넣고 직접 꾸며야 했습니다. FactChat의 크레딧 부족(402) 토스트(4.x)에서는
+그 결과 분홍 토스트 위에 중립 테두리 버튼이 올라갔습니다. 토스트의 색을 하나도 따르지
+않아서 다른 카드를 얹어 놓은 것처럼 보였습니다.
+
+그래서 모든 토스트에 같은 방식을 씁니다. 동작은 닫기 ×와 똑같이 토스트 자신의 글자
+색을 씁니다.
+
+---
+
+## 규칙
+
+### 1. 영역의 무게에 맞춥니다
+
+토스트와 인라인 배너에는 **텍스트 동작**을 둡니다. 버튼은 패널, 대화상자, 빈 화면처럼
+공간을 차지하는 영역에 둡니다.
+
+### 2. 동작은 상태색을 따릅니다
+
+색이 있는 영역 안의 동작은 **그 영역의 글자 색**을 씁니다. 오류 토스트에서는
+`danger.fg`, 정보 토스트에서는 `info.fg`, 일반적으로는 `{status}.fg`입니다. 중립
+컨트롤을 두지 않습니다.
+
+### 3. 토스트에는 동작을 하나만 두고, 닫기는 ×로 합니다
+
+토스트에 「닫기」나 「취소」 버튼을 두지 않습니다. ×가 이미 그 일을 합니다. 동작이 두
+개 필요한 메시지라면 토스트가 아니라 대화상자나 패널을 씁니다.
+
+### 4. 동작을 문구에서 되풀이하지 않습니다
+
+동작이 「크레딧 구매」라면 메시지에 "계속하려면 크레딧을 구매하세요"를 다시 쓰지
+않습니다. 토스트 문구는 **2줄 이내**로 씁니다.
+
+### 5. 패널에서는 문제를 푸는 동작이 주요 버튼입니다
+
+패널이나 빈 화면에서는 문제를 해결하는 동작을 `<Button variant="primary">`(블랙
+채움)로 둡니다. 닫기는 `<Button variant="secondary">`(테두리)입니다.
+
+### 6. 동작이 있는 토스트는 더 오래 보입니다
+
+읽는 사람은 메시지를 읽고 나서 누를지 정해야 합니다. 동작이 있는 토스트는 기본
+표시 시간이 5초가 아니라 **8초**입니다. `duration`을 주지 않으면 `useToast`가 알아서
+맞춥니다.
+
+---
+
+## 어떤 컨트롤을 어디에
+
+| 영역 | 주요 동작 | 보조 동작 / 닫기 | 최대 개수 | 문구 |
+| --- | --- | --- | --- | --- |
+| 토스트 | `action` 속성으로 넣은 `{status}.fg` 텍스트 동작 | ×만 | 1 | 2줄 이내, 동작을 되풀이하는 안내 없음 |
+| 인라인 배너 | 끝에 붙인 `{status}.fg` 텍스트 동작, children으로 전달(Banner에는 `action` 속성이 없음) | 닫을 수 있으면 × | 1 | 1줄, 모바일에서는 줄바꿈 |
+| 패널 / 빈 화면 | `Button variant="primary"` | `Button variant="secondary"` | 2 | 제목 + 이유 + 필요하면 안내 |
+| 대화상자 | `Button variant="primary"`, 오른쪽 | `Button variant="secondary"`, 주요 버튼 왼쪽 | 2 | 제목 + 본문 |
+
+---
+
+## 사용법
+
+```tsx
+import { useToast } from '@mindlogic-ai/logician-ui';
+
+const showToast = useToast();
+
+showToast({
+  status: 'error',
+  description: '크레딧이 부족해 응답을 생성하지 못했습니다.',
+  action: {
+    label: '크레딧 구매',
+    onClick: openCreditPurchaseModal,
+  },
+  // action이 있으므로 duration 기본값은 8000입니다
+});
+```
+
+- 동작은 설명 아래, 글자 열에 맞춰 토스트의 `{status}.fg` 색으로 그려지며 호버하면 ×와
+  같은 틴트(`{status}.border`)가 깔립니다.
+- 누르면 `onClick`을 부르고 토스트를 닫습니다.
+- `label`에는 어떤 `ReactNode`든 넣을 수 있지만 짧은 동사구로 씁니다.
+- `duration`을 직접 주면(계속 떠 있는 토스트의 `null` 포함) 항상 그 값을 따릅니다.
+- Chakra의 `toaster.create({ action: { label, onClick } })`도 같은 모양으로 그려집니다.
+  다만 이 경우 label은 문자열이어야 하고, 표시 시간 기본값은 8초가 아니라 Chakra의
+  기본값입니다.
+
+### 이렇게 하지 마세요: `description` 안의 버튼
+
+```tsx
+// ✗ 색이 있는 토스트 위에 별개의 컨트롤을 얹었습니다. 토스트의 색을 따르지 않고,
+//   줄이 하나 늘고, 닫는 처리도 호출하는 쪽에 떠넘깁니다.
+showToast({
+  status: 'error',
+  description: (
+    <>
+      크레딧이 부족합니다. 크레딧을 구매하면 계속 사용할 수 있습니다.
+      <Button variant="secondary" onClick={buy}>
+        크레딧 구매
+      </Button>
+    </>
+  ),
+});
+
+// ✓ 동작은 하나, 토스트의 색을 따르고, 문구에서 되풀이하지 않습니다.
+showToast({
+  status: 'error',
+  description: '크레딧이 부족합니다.',
+  action: { label: '크레딧 구매', onClick: buy },
+});
+```
+
+상태별 예시와 짧은 메시지 예시는 **Components/Toast → Action / …** 에 있습니다.
+
+</Ko>