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

package/src/components/Badge/Badge.stories.tsx

@@ -1,7 +1,14 @@
-import { Flex } from '@chakra-ui/react';
+import type { ReactNode } from 'react';
+import { Flex, Stack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
-import { Badge, badgeVariants } from '.';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Card } from '../Card';
+import { ClockIcon, MdError } from '../Icon';
+import { Tag } from '../Tag';
+import { Subtext, Text } from '../Typography';
+import { Badge, badgeVariants, badgeVariantStyles } from '.';
 
 const meta = {
   title: 'Components/Badge',
@@ -14,7 +21,7 @@ const meta = {
       control: 'select',
       options: badgeVariants,
       description:
-        'Colour role. `neutral` (grey wash) is the default; the rest report a status.',
+        '`neutral` (default): an attribute with no state. `success` / `warning` / `danger` / `info`: a well-defined meaning every user shares; `info` = a non-error system fact (scope, permission, read-only, New). Labels that only classify → `Tag` `category`.',
     },
     size: {
       control: 'select',
@@ -80,3 +87,186 @@ export const Sizes: Story = {
     </Flex>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Badge.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`) so the component's story list stays short; being stories,
+// they type-check with the rest of the code. `tags` must be written out on
+// each story: the indexer reads CSF statically and does not follow a spread.
+
+/** A settings card like FactChat's group credit limit. */
+const LimitCard = ({
+  title,
+  value,
+  badge,
+  bg = 'bg.surface',
+}: {
+  title: string;
+  value: string;
+  badge?: ReactNode;
+  bg?: string;
+}) => (
+  <Card bg={bg} p={4} minW="180px">
+    <Flex gap={2} align="center" mb={1}>
+      <Subtext>{title}</Subtext>
+      {badge}
+    </Flex>
+    <Text fontWeight="bold" fontSize="lg">
+      {value}
+    </Text>
+  </Card>
+);
+
+const CREDIT_CARDS = [
+  { title: '남은 크레딧', value: '0' },
+  { title: '이번 달 사용', value: '8,489' },
+  { title: '개인 한도', value: '2,000' },
+];
+
+export const DoScopeLabel: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: info for a scope',
+  render: () => (
+    <LimitCard
+      title="개인 크레딧 한도"
+      value="2,000"
+      badge={<Badge variant="info">이 그룹만</Badge>}
+    />
+  ),
+};
+
+export const DontStatusForTeams: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: status colours to tell teams apart",
+  render: () => (
+    <Flex gap={2}>
+      <Badge variant="success">마케팅</Badge>
+      <Badge variant="danger">영업</Badge>
+      <Badge variant="warning">개발</Badge>
+    </Flex>
+  ),
+};
+
+export const DoCategoryTags: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: Tag category for groups',
+  render: () => (
+    <Flex gap={2}>
+      <Tag category="blue">마케팅</Tag>
+      <Tag category="purple">영업</Tag>
+      <Tag category="brown">개발</Tag>
+    </Flex>
+  ),
+};
+
+export const DontNeutralOnLayer: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: neutral on layer.1",
+  render: () => (
+    <LimitCard
+      bg="layer.1"
+      title="개인 크레딧 한도"
+      value="2,000"
+      badge={<Badge variant="neutral">이 그룹만</Badge>}
+    />
+  ),
+};
+
+export const DontRepeatOnEveryCard: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: the same badge on every card",
+  render: () => (
+    <Flex gap={3} wrap="wrap">
+      {CREDIT_CARDS.map((card) => (
+        <LimitCard
+          key={card.title}
+          {...card}
+          badge={<Badge variant="info">이 그룹만</Badge>}
+        />
+      ))}
+    </Flex>
+  ),
+};
+
+export const DoOnceOnHeading: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: once, on the section heading',
+  render: () => (
+    <Stack gap={3}>
+      <Flex gap={2} align="center">
+        <Text as="h3" fontWeight="bold">
+          크레딧
+        </Text>
+        <Badge variant="info">이 그룹만</Badge>
+      </Flex>
+      <Flex gap={3} wrap="wrap">
+        {CREDIT_CARDS.map((card) => (
+          <LimitCard key={card.title} {...card} />
+        ))}
+      </Flex>
+    </Stack>
+  ),
+};
+
+export const DoTextCarriesMeaning: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: the words carry the meaning',
+  render: () => (
+    <Flex gap={2}>
+      <Badge variant="warning" gap={1}>
+        <ClockIcon boxSize="12px" aria-hidden />
+        대기 중
+      </Badge>
+      <Badge variant="danger" gap={1}>
+        <MdError boxSize="12px" aria-hidden />
+        결제 실패
+      </Badge>
+    </Flex>
+  ),
+};
+
+export const DontColourOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: colour with no words",
+  render: () => (
+    <Flex gap={3} align="center">
+      <Text>결제 1</Text>
+      <Badge variant="success" aria-hidden>
+        {'\u00A0'}
+      </Badge>
+      <Text>결제 2</Text>
+      <Badge variant="danger" aria-hidden>
+        {'\u00A0'}
+      </Badge>
+    </Flex>
+  ),
+};
+
+/** Tokens each variant reads, resolved from `Badge.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={badgeVariants.flatMap((variant) => [
+        {
+          token: badgeVariantStyles[variant].bgColor,
+          use: <T en={`${variant} · background`} ko={`${variant} · 배경`} />,
+        },
+        {
+          token: badgeVariantStyles[variant].color,
+          use: <T en={`${variant} · text`} ko={`${variant} · 글자`} />,
+        },
+      ])}
+    />
+  ),
+};

package/src/components/Badge/Badge.tsx

@@ -8,9 +8,11 @@ import { BadgeOwnProps } from './Badge.types';
 /**
  * Badge — a small, non-interactive label.
  *
- * `neutral` (default) is the grey-wash everyday badge; `success` / `warning` /
- * `danger` / `info` report a status. For an unread/notification number use
- * `CountBadge`; for a removable or selectable label use `Tag`.
+ * `neutral` (default) is the everyday badge; `success` / `warning` /
+ * `danger` / `info` carry a well-defined meaning (a status, or for `info` a
+ * system fact such as scope or permission). For an unread/notification number
+ * use `CountBadge`; for a removable, selectable or category-only label use
+ * `Tag`.
  *
  * @example
  * ```tsx

package/src/components/Badge/Badge.types.ts

@@ -7,11 +7,13 @@ import type { PolymorphicProps } from '../../types/polymorphic';
 /**
  * Badge variants (5.0).
  *
- * - `neutral` (default): neutral `bg.muted` with `secondary.fgStrong`
- *   text — the everyday label ("Pro", "Beta", "Draft").
- * - `success` / `warning` / `danger` / `info`: the status family's soft
- *   `{status}.bg` surface with `{status}.fg` text. Use these ONLY when the
- *   badge reports a status — never as decoration.
+ * - `neutral` (default): `bg.muted` + `secondary.fgStrong` — an attribute
+ *   with no state ("Pro", "Beta", "Draft").
+ * - `success` / `warning` / `danger` / `info`: `{status}.bg` + `{status}.fg`,
+ *   for a meaning every user shares and that is well defined. `info` is a
+ *   non-error system fact: scope ("이 그룹만"), permission, read-only, "New".
+ *   A label that only classifies or groups is a `Tag` with `category`, never
+ *   a status colour. The same label gets the same variant on every screen.
  *
  * **Breaking in 5.0:** `primary` and `secondary` were removed. At runtime they
  * still render (as `neutral`) and warn once in development.

package/src/components/Badge/Badge.usage.mdx

@@ -0,0 +1,265 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BadgeStories from './Badge.stories';
+
+<Meta of={BadgeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Badge
+
+A short, non-interactive label that states an attribute of the thing next to
+it: a status, a plan, or a scope.
+
+## When to use
+
+- To state a fixed attribute next to a title or value: "Pro", "Beta".
+- To report a status the user should read: 완료, 대기 중, 실패.
+- To give a well-defined system fact such as scope, permission, read-only or
+  "New": 이 그룹만.
+
+## When not to use
+
+- The label only classifies or groups and has no fixed meaning → `Tag` with
+  `category`.
+- The user can click, select or remove it → `Tag` (`selected`, close button).
+- An unread count → `CountBadge`. An explanation → `Tooltip` or `InfoSprinkle`.
+- A sentence-length status → `Banner` or `Toast`.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Badge
+
+옆에 있는 대상의 속성(상태, 요금제, 적용 범위)을 짧게 알려 주는 라벨입니다. 누르거나
+선택할 수 없습니다.
+
+## 언제 쓰나요
+
+- 제목이나 값 옆에 고정된 속성을 표시할 때: "Pro", "Beta".
+- 사용자가 읽어야 할 상태를 알릴 때: 완료, 대기 중, 실패.
+- 적용 범위, 권한, 읽기 전용, "New"처럼 뜻이 명확한 시스템 사실을 알릴 때: 이 그룹만.
+
+## 언제 쓰지 않나요
+
+- 뜻은 없고 분류나 묶음만 나타낸다면 `Tag`의 `category`를 씁니다.
+- 사용자가 누르거나 고르거나 지울 수 있다면 `Tag`(`selected`, 닫기 버튼)를 씁니다.
+- 읽지 않은 개수는 `CountBadge`, 설명은 `Tooltip`이나 `InfoSprinkle`을 씁니다.
+- 한 문장 길이의 상태 안내는 `Banner`나 `Toast`를 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={BadgeStories} include={['variant']} />
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `neutral` (default) | An attribute with no state | Plan, version, "Draft" |
+| `info` | A well-defined system fact; nothing is wrong | Scope (이 그룹만), "New", read-only, permission |
+| `success` | Finished or healthy | 완료, 연결됨 |
+| `warning` | Needs attention, still works | 대기 중, 만료 임박 |
+| `danger` | Failed or blocked | 실패, 차단됨 |
+
+### Choosing a colour
+
+1. **Does the colour carry a meaning every user shares** (a status, a scope, a
+  risk)? → Badge with a status variant. The same label always gets the same
+  variant, on every screen.
+2. **Does it only tell items apart?** → `Tag` with `category` (twelve hues, no
+  meaning). Never borrow a status colour for this.
+3. **Neither?** → `neutral`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `neutral` (기본) | 상태가 없는 속성 | 요금제, 버전, "Draft" |
+| `info` | 뜻이 명확한 시스템 사실이며, 문제가 있다는 뜻은 아님 | 적용 범위(이 그룹만), "New", 읽기 전용, 권한 |
+| `success` | 끝났거나 정상 | 완료, 연결됨 |
+| `warning` | 확인이 필요하지만 동작은 함 | 대기 중, 만료 임박 |
+| `danger` | 실패했거나 막힘 | 실패, 차단됨 |
+
+### 색 고르기
+
+1. **모든 사용자가 같은 뜻으로 읽는 색인가요?**(상태, 적용 범위, 위험) 그렇다면 상태
+  변형의 Badge를 씁니다. 같은 라벨은 어느 화면에서나 같은 변형을 씁니다.
+2. **항목을 나누기만 하나요?** 그렇다면 `Tag`의 `category`(뜻이 없는 열두 가지 색)를
+  씁니다. 이때 상태색을 빌려 쓰지 않습니다.
+3. **둘 다 아니라면** `neutral`을 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BadgeStories.DoScopeLabel} />
+<Verdict
+  kind="do"
+  en="Use info for a scope label. Scope is a fixed system meaning, and the colour lifts it off the card."
+  ko="적용 범위 라벨에는 info를 씁니다. 적용 범위는 뜻이 정해진 시스템 사실이고, 색이 있어 카드 위에서 잘 보입니다."
+/>
+
+<Canvas of={BadgeStories.DontStatusForTeams} />
+<Verdict
+  kind="dont"
+  en="Borrow status colours to tell teams apart. Readers will take 영업 to mean an error."
+  ko="팀을 나누려고 상태색을 빌려 쓰지 마세요. 읽는 사람은 '영업'을 오류로 받아들입니다."
+/>
+
+<Canvas of={BadgeStories.DoCategoryTags} />
+<Verdict
+  kind="do"
+  en="Use Tag category hues for labels that only classify."
+  ko="분류만 하는 라벨에는 Tag의 category 색을 씁니다."
+/>
+
+<Canvas of={BadgeStories.DontNeutralOnLayer} />
+<Verdict
+  kind="dont"
+  en="Put a neutral badge on a layer.1 surface. In light mode layer.1 and bg.muted are the same value, so the badge disappears. On layered grounds use a status variant, or no badge."
+  ko="layer.1 면 위에 neutral 배지를 두지 마세요. 라이트 모드에서 layer.1과 bg.muted는 같은 값이라 배지가 보이지 않습니다. 겹친 면 위에서는 상태 변형을 쓰거나 배지를 빼세요."
+/>
+
+<Canvas of={BadgeStories.DontRepeatOnEveryCard} />
+<Verdict
+  kind="dont"
+  en="Repeat the same badge on every card in a row. If all three say the same thing, the badge stops telling the reader anything."
+  ko="한 줄의 카드마다 같은 배지를 반복하지 마세요. 세 개가 모두 같은 말을 하면 배지는 아무것도 알려 주지 못합니다."
+/>
+
+<Canvas of={BadgeStories.DoOnceOnHeading} />
+<Verdict
+  kind="do"
+  en="Say it once, on the section heading, when it applies to the whole section."
+  ko="섹션 전체에 해당한다면 섹션 제목 옆에 한 번만 붙입니다."
+/>
+
+<Canvas of={BadgeStories.DoTextCarriesMeaning} />
+<Verdict
+  kind="do"
+  en="Let the words carry the meaning. Colour and icon back it up but never replace it (WCAG 1.4.1)."
+  ko="뜻은 문구가 전합니다. 색과 아이콘은 문구를 거들 뿐, 대신하지 않습니다(WCAG 1.4.1)."
+/>
+
+<Canvas of={BadgeStories.DontColourOnly} />
+<Verdict
+  kind="dont"
+  en="Use a coloured badge with no words. Someone who cannot tell green from red, or who uses a screen reader, gets nothing."
+  ko="문구 없이 색만 있는 배지를 쓰지 마세요. 초록과 빨강을 구분하기 어려운 사람이나 화면 낭독기 사용자에게는 아무 정보도 전달되지 않습니다."
+/>
+
+<En>
+
+## Content
+
+- One to three words. No full stop.
+- Sentence case in English ("This group only", not "This Group Only"). No
+  「」, quotation marks or brackets around Korean labels.
+- Describe a state, not an action: 하위 그룹 포함, not "Include subgroups",
+  which reads as an option that is still off.
+- Use the same words for the same state everywhere. If one screen says 대기 중,
+  another should not say 보류.
+
+## Accessibility
+
+What Badge does for you:
+
+- It renders as plain text (`<span>`), so the label is read as part of the
+  content around it. It is not focusable and has no role, which is right for a
+  label that does nothing.
+
+What you still have to do:
+
+- **Words, not colour alone** (WCAG 1.4.1). Every badge has a visible text
+  label; an icon inside it is decorative and gets `aria-hidden`.
+- **Mind the accessible name it joins.** A badge inside a button or link
+  becomes part of that control's name (WCAG 4.1.2). Keep the visible label and
+  the spoken name the same (WCAG 2.5.3), and put the badge outside when it
+  would make the name long or misleading, for example a whole-row link.
+- Place it next to a heading, not inside the `<h2>`, so heading navigation
+  reads the heading alone.
+- For a clickable badge (a citation link, `as="a"`), the badge becomes the
+  control: give it a name that makes sense on its own.
+
+## Tokens
+
+The table is generated from `Badge.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한 단어에서 세 단어까지 씁니다. 마침표를 찍지 않습니다.
+- 영어는 문장형 대소문자를 씁니다("This group only", "This Group Only"가 아님).
+  한국어 라벨에는 「」, 따옴표, 괄호를 두르지 않습니다.
+- 동작이 아니라 상태를 적습니다. "하위 그룹 포함"이라고 쓰고 "하위 그룹 포함하기"처럼
+  아직 꺼져 있는 선택지로 읽히는 문구는 피합니다.
+- 같은 상태에는 어디서나 같은 말을 씁니다. 한 화면에서 "대기 중"이라고 썼다면 다른
+  화면에서 "보류"라고 쓰지 않습니다.
+
+## 접근성
+
+Badge가 알아서 하는 일
+
+- 일반 텍스트(`<span>`)로 그려지므로 주변 내용과 함께 읽힙니다. 아무 동작이 없는
+  라벨이라 초점을 받지 않고 역할(role)도 없습니다.
+
+직접 챙겨야 하는 일
+
+- **색만으로 알리지 않습니다**(WCAG 1.4.1). 모든 배지에는 눈에 보이는 문구가 있어야
+  하며, 안에 넣은 아이콘은 장식이므로 `aria-hidden`을 붙입니다.
+- **배지가 들어가는 접근 가능한 이름을 확인합니다.** 버튼이나 링크 안의 배지는 그
+  컨트롤 이름의 일부가 됩니다(WCAG 4.1.2). 눈에 보이는 문구와 읽히는 이름이 같아야
+  하고(WCAG 2.5.3), 행 전체를 감싼 링크처럼 이름이 길어지거나 뜻이 흐려지면 배지를
+  컨트롤 밖에 둡니다.
+- 제목 옆에 두고 `<h2>` 안에는 넣지 않습니다. 그래야 제목으로 이동할 때 제목만
+  읽힙니다.
+- 누를 수 있는 배지(인용 링크, `as="a"`)는 그 자체가 컨트롤이 됩니다. 배지만 읽어도
+  뜻이 통하는 이름을 붙입니다.
+
+## 토큰
+
+아래 표는 `Badge.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={BadgeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tag**: classify (`category`), select (`selected`) or dismiss.
+- **CountBadge**: numbers, such as unread counts.
+- **Banner** / **Toast**: a sentence-length status.
+- **InfoSprinkle** / **Tooltip**: an explanation.
+- **Foundations/Brand & colour usage**: why status colours are never
+  decoration.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tag**: 분류(`category`), 선택(`selected`), 삭제.
+- **CountBadge**: 읽지 않은 개수 같은 숫자.
+- **Banner** / **Toast**: 한 문장 길이의 상태 안내.
+- **InfoSprinkle** / **Tooltip**: 설명.
+- **Foundations/Brand & colour usage**: 상태색을 장식으로 쓰지 않는 이유.
+
+</Ko>

package/src/components/Banner/Banner.stories.tsx

@@ -1,8 +1,14 @@
-import { VStack } from '@chakra-ui/react';
+import type { ReactNode } from 'react';
+import { Flex, Stack, VStack } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
-import { H5, Subtext } from '../Typography';
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { Card } from '../Card';
+import { H5, Subtext, Text } from '../Typography';
 import { Banner } from './Banner';
+import { accentStyles, bannerStyles } from './Banner.styles';
 
 const meta = {
   title: 'Components/Banner',
@@ -10,6 +16,14 @@ const meta = {
   args: {
     children: 'This is a banner message',
   },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['info', 'success', 'warning', 'danger', 'neutral'],
+      description:
+        '`info` (default): a system fact to know before acting; nothing is wrong. `success`: finished, and the result stays relevant here. `warning`: still works, read this first. `danger`: failed or blocked; the reader must act. `neutral`: a brand notice with no status.',
+    },
+  },
 } satisfies Meta<typeof Banner>;
 
 export default meta;
@@ -79,3 +93,139 @@ export const AllVariants: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Banner.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written on each story because the indexer reads
+// CSF statically.
+
+/** A confirm step like FactChat's credit distribution dialog. */
+const ConfirmPanel = ({ children }: { children?: ReactNode }) => (
+  <Card p={4} maxW="420px">
+    <Stack gap={3}>
+      <Text fontWeight="bold">크레딧 1,000을 하위 그룹 3곳에 나눕니다</Text>
+      {children}
+      <Flex gap={2} justify="flex-end">
+        <Button variant="secondary">취소</Button>
+        <Button variant="primary">나누기</Button>
+      </Flex>
+    </Stack>
+  </Card>
+);
+
+export const DoWarningBeforeAction: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: warning next to the action it is about',
+  render: () => (
+    <ConfirmPanel>
+      <Banner variant="warning" size="sm" my={0}>
+        나눈 크레딧은 되돌릴 수 없습니다.
+      </Banner>
+    </ConfirmPanel>
+  ),
+};
+
+export const DontBannerForTransientSuccess: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a banner for a passing success",
+  render: () => (
+    <Card p={4} maxW="420px">
+      <Stack gap={3}>
+        <Banner variant="success" size="sm" my={0}>
+          저장했습니다.
+        </Banner>
+        <Text fontWeight="bold">그룹 설정</Text>
+        <Subtext>이름, 설명, 관리자</Subtext>
+      </Stack>
+    </Card>
+  ),
+};
+
+export const DoInfoForLockedSetting: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: info for a locked setting',
+  render: () => (
+    <Card p={4} maxW="420px">
+      <Stack gap={2}>
+        <Text fontWeight="bold">인증 방식</Text>
+        <Banner variant="info" size="sm" my={0}>
+          인증 방식은 연결을 만든 뒤에는 바꿀 수 없습니다.
+        </Banner>
+      </Stack>
+    </Card>
+  ),
+};
+
+export const DontStackBanners: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a stack of banners",
+  render: () => (
+    <Stack gap={0} maxW="420px">
+      <Banner variant="info" size="sm">
+        이 그룹에만 적용됩니다.
+      </Banner>
+      <Banner variant="warning" size="sm">
+        크레딧이 7일 뒤 만료됩니다.
+      </Banner>
+      <Banner variant="warning" size="sm">
+        나눈 크레딧은 되돌릴 수 없습니다.
+      </Banner>
+      <Banner variant="danger" size="sm">
+        한 번에 50곳까지만 나눌 수 있습니다.
+      </Banner>
+    </Stack>
+  ),
+};
+
+export const DoDangerWithAlert: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: danger with role="alert" when it appears after submit',
+  render: () => (
+    <Stack gap={3} maxW="420px">
+      <Banner variant="danger" size="sm" my={0} role="alert">
+        저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요.
+      </Banner>
+      <Flex justify="flex-end">
+        <Button variant="primary">다시 저장</Button>
+      </Flex>
+    </Stack>
+  ),
+};
+
+const VARIANTS = ['info', 'success', 'warning', 'danger', 'neutral'] as const;
+
+/** Tokens each variant reads, from `Banner.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={VARIANTS.flatMap((variant) => [
+        {
+          token: bannerStyles[variant].bg as string,
+          use: <T en={`${variant} · background`} ko={`${variant} · 배경`} />,
+        },
+        {
+          token: bannerStyles[variant].borderColor as string,
+          use: <T en={`${variant} · border`} ko={`${variant} · 테두리`} />,
+        },
+        {
+          token: (accentStyles[variant] as { bg: string }).bg,
+          use: <T en={`${variant} · accent bar`} ko={`${variant} · 왼쪽 막대`} />,
+        },
+        {
+          token: bannerStyles[variant].color as string,
+          use: (
+            <T en={`${variant} · text and icon`} ko={`${variant} · 글자와 아이콘`} />
+          ),
+        },
+      ])}
+    />
+  ),
+};