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

package/src/components/Collapsible/Collapsible.usage.mdx

@@ -0,0 +1,173 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as CollapsibleStories from './Collapsible.stories';
+
+<Meta of={CollapsibleStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Collapsible
+
+One bordered section with a full-width trigger that shows or hides its
+content. `CollapsibleRoot` › `CollapsibleTrigger` + `CollapsibleContent`, or
+the same parts as `Collapsible.Root` / `.Trigger` / `.Content` /
+`.Indicator`. The height animates on the house presence clock (300 ms in,
+150 ms out), and the animation is dropped under reduced motion.
+
+## When to use
+
+- Optional detail the reader rarely needs: raw event data, advanced
+  settings, a model's internal process.
+- One section. For several sections in a row, use `Accordion`.
+
+## When not to use
+
+- Several sections in a stack → `Accordion`.
+- Clipping a paragraph to a few lines → `ExpandableText`.
+- Required input or a warning the reader must see → show it on the page.
+- A menu of actions → `Menu`.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `defaultOpen` / `open` + `onOpenChange` | Closed by default; open at start, or controlled |
+| `CollapsibleTrigger customIcon` | Replace the default indicator |
+| `lazyMount` / `unmountOnExit` | Mount content only when opened |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Collapsible
+
+테두리가 있는 섹션 하나와, 그 내용을 보이거나 숨기는 전체 너비 트리거로 이뤄진
+컴포넌트입니다. 구조는 `CollapsibleRoot` › `CollapsibleTrigger` +
+`CollapsibleContent`이고, 같은 파트를 `Collapsible.Root` / `.Trigger` / `.Content` /
+`.Indicator`로도 씁니다. 높이는 공통 등장 시간(열 때 300ms, 닫을 때 150ms)으로
+움직이고, 움직임 줄이기 설정에서는 애니메이션이 빠집니다.
+
+## 언제 쓰나요
+
+- 읽는 사람이 가끔만 필요한 부가 정보: 이벤트 원본 데이터, 고급 설정, 모델의 내부
+  처리 과정.
+- 섹션이 하나일 때. 여러 섹션이 이어진다면 `Accordion`을 씁니다.
+
+## 언제 쓰지 않나요
+
+- 섹션 여러 개를 쌓는다면 `Accordion`을 씁니다.
+- 문단을 몇 줄만 보여 주려면 `ExpandableText`를 씁니다.
+- 필수 입력이나 꼭 봐야 하는 경고는 페이지에 그대로 보여 줍니다.
+- 동작 목록이라면 `Menu`를 씁니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `defaultOpen` / `open` + `onOpenChange` | 기본은 닫힘. 처음부터 열어 두거나 제어 값으로 씀 |
+| `CollapsibleTrigger`의 `customIcon` | 기본 표시를 바꿈 |
+| `lazyMount` / `unmountOnExit` | 열 때만 내용을 그림 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={CollapsibleStories.DoOptionalDetail} />
+<Verdict
+  kind="do"
+  en="Keep optional detail closed, behind a trigger that names it."
+  ko="부가 정보는 닫아 두고, 그 정보의 이름을 적은 트리거 뒤에 둡니다."
+/>
+
+<Canvas of={CollapsibleStories.DontVagueTrigger} />
+<Verdict
+  kind="dont"
+  en="Label the trigger 더 보기. The reader cannot tell whether it is worth opening, and a screen reader announces only 더 보기, collapsed."
+  ko="트리거를 '더 보기'라고 쓰지 마세요. 열어 볼 가치가 있는지 알 수 없고, 화면 낭독기는 '더 보기, 접힘'만 읽습니다."
+/>
+
+<En>
+
+## Content
+
+- The trigger names what opens: 원본 데이터 보기, 고급 설정.
+- Do not change the trigger text when it opens; the indicator and
+  `aria-expanded` already say it is open.
+
+## Accessibility
+
+What Collapsible does for you:
+
+- The trigger is a `<button>` with `aria-expanded` and `aria-controls`
+  pointing at the content (WCAG 4.1.2). Enter and Space toggle it (WCAG
+  2.1.1).
+- Under reduced motion the height animation is replaced.
+
+What you still have to do:
+
+- `CollapsibleTrigger` does not add the shared focus ring; it relies on the
+  browser's outline. Check that focus is visible where you use it (WCAG
+  2.4.7).
+- Keep the trigger to phrasing content: text, icons, `Badge`
+  (`ACCESSIBILITY.md` §5).
+- If the section is part of the page outline, wrap the trigger in a heading
+  (WCAG 1.3.1).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 트리거에는 무엇이 열리는지 씁니다: 원본 데이터 보기, 고급 설정.
+- 열렸을 때 트리거 문구를 바꾸지 않습니다. 표시 아이콘과 `aria-expanded`가 이미 열린
+  상태를 알립니다.
+
+## 접근성
+
+Collapsible이 알아서 하는 일
+
+- 트리거는 `aria-expanded`와 내용을 가리키는 `aria-controls`가 있는 `<button>`입니다
+  (WCAG 4.1.2). Enter와 Space로 여닫습니다(WCAG 2.1.1).
+- 움직임 줄이기 설정에서는 높이 애니메이션이 다른 효과로 바뀝니다.
+
+직접 챙겨야 하는 일
+
+- `CollapsibleTrigger`는 공통 초점 링을 붙이지 않고 브라우저 기본 외곽선에
+  기댑니다. 쓰는 곳에서 초점이 보이는지 확인합니다(WCAG 2.4.7).
+- 트리거 안에는 글자, 아이콘, `Badge` 같은 phrasing content만 넣습니다
+  (`ACCESSIBILITY.md` 5절).
+- 섹션이 페이지 구조의 일부라면 트리거를 제목 요소로 감쌉니다(WCAG 1.3.1).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={CollapsibleStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Accordion**: several sections in a stack.
+- **ExpandableText**: clip a paragraph to a few lines.
+- **Card**: a section that is always open.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Accordion**: 여러 섹션을 쌓을 때.
+- **ExpandableText**: 문단을 몇 줄로 접을 때.
+- **Card**: 늘 열려 있는 섹션.
+
+</Ko>

package/src/components/ColorMode/ColorMode.stories.tsx

@@ -0,0 +1,50 @@
+import { HStack, Stack } from '@chakra-ui/react';
+import { Meta, StoryObj } from '@storybook/react';
+
+import { InlineCode } from '../InlineCode';
+import { Subtext, Text } from '../Typography';
+import { ColorModeToggle, useColorMode } from '.';
+
+/**
+ * The colour-mode runtime: `ColorModeProvider` (mounted by `LogicianProvider`),
+ * the `useColorMode` / `useColorModeValue` hooks, and a ready-made
+ * `ColorModeToggle`.
+ *
+ * In Storybook the toolbar's **Color mode** pins the canvas through
+ * `forcedColorMode`, so clicking the toggle here updates the stored
+ * preference (shown below) while the canvas keeps following the toolbar —
+ * the same thing an app sees during a forced-mode rollout.
+ */
+const meta = {
+  title: 'Setup/ColorMode',
+  component: ColorModeToggle,
+  args: { 'aria-label': '다크 모드 전환' },
+} satisfies Meta<typeof ColorModeToggle>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+const Readout = () => {
+  const { colorMode, colorModePreference } = useColorMode();
+  return (
+    <Stack gap={1}>
+      <Text>
+        colorMode: <InlineCode>{colorMode}</InlineCode>
+      </Text>
+      <Subtext mb={0}>
+        colorModePreference:{' '}
+        <InlineCode>{colorModePreference ?? 'undefined'}</InlineCode>
+      </Subtext>
+    </Stack>
+  );
+};
+
+export const Basic: Story = {
+  render: (args) => (
+    <HStack gap={4} align="center">
+      <ColorModeToggle {...args} />
+      <Readout />
+    </HStack>
+  ),
+};

package/src/components/ColorMode/ColorMode.usage.mdx

@@ -0,0 +1,135 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ColorModeStories from './ColorMode.stories';
+
+<Meta of={ColorModeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# ColorMode
+
+The light/dark runtime: `ColorModeProvider`, the `useColorMode` and
+`useColorModeValue` hooks, and a ready-made `ColorModeToggle` button.
+
+</En>
+
+<Ko>
+
+# ColorMode
+
+라이트·다크 모드를 다루는 부분입니다. `ColorModeProvider`, `useColorMode`와
+`useColorModeValue` 훅, 바로 쓸 수 있는 `ColorModeToggle` 버튼으로 이루어집니다.
+
+</Ko>
+
+<Canvas of={ColorModeStories.Basic} />
+
+<En>
+
+In Storybook the toolbar's **Color mode** pins the canvas with
+`forcedColorMode`. Clicking the toggle changes the stored preference shown next
+to it, while the canvas keeps following the toolbar.
+
+## When to use
+
+- `useColorMode().colorMode` when something cannot be a token and has to know
+  the rendered mode: a tenant logo with light and dark files, a diagram
+  library's theme, a chart palette.
+- `setColorMode` with `colorModePreference` for a settings picker that offers
+  light, dark and system.
+- `ColorModeToggle` for a quick light/dark switch in a header or a toolbar.
+- `ColorModeProvider` on its own only when the app composes providers by hand
+  and does not use `LogicianProvider`, which already mounts it.
+
+## When not to use
+
+- A colour that a semantic token can express → the token (`fg.default`,
+  `bg.surface`). Tokens switch with the mode in CSS; `useColorModeValue` is for
+  values that cannot be tokens.
+- A preference that must keep "system" → a picker on `setColorMode`, not
+  `ColorModeToggle`. The toggle only sets `light` or `dark`.
+
+## Accessibility
+
+- The toggle's default name is the English "Toggle color mode". In a Korean UI
+  pass your own `aria-label` (WCAG 4.1.2). The name does not change with the
+  mode, and the button has no pressed state.
+- Its sun and moon icons cross with a short rotation that drops to instant
+  under `prefers-reduced-motion: reduce`. The page-wide colour change is always
+  instant (`disableTransitionOnChange`).
+- Before hydration the toggle shows the light-mode icon, because the resolved
+  mode is only known on the client.
+- Both modes have to pass contrast (WCAG 1.4.3). Check the screen in light and
+  dark after any colour change.
+
+## Props and API
+
+| API                              | What it gives you                                                                                             |
+| -------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| `colorMode`                      | The mode being rendered, `'light'` or `'dark'`. A forced mode wins.                                           |
+| `colorModePreference`            | The stored preference, including `'system'`.                                                                  |
+| `setColorMode(mode)`             | Sets the preference: `'light'`, `'dark'` or `'system'`.                                                       |
+| `toggleColorMode()`              | Switches between light and dark from the user's resolved preference.                                          |
+| `useColorModeValue(light, dark)` | Returns one of two values for the rendered mode.                                                              |
+| `ColorModeToggle`                | An `IconButton`; takes its props except `children`.                                                           |
+| `ColorModeProvider`              | `next-themes` with the class strategy on `<html>`, storage key `logician-color-mode`, `system` resolution on. |
+
+The host app must add `suppressHydrationWarning` to its `<html>` element, and
+should not write `color-scheme` itself: the provider does.
+
+</En>
+
+<Ko>
+
+Storybook에서는 툴바의 **Color mode**가 `forcedColorMode`로 캔버스를 고정합니다.
+토글을 누르면 옆에 보이는 저장된 선호값은 바뀌지만, 캔버스는 계속 툴바를 따릅니다.
+
+## 언제 쓰나요
+
+- 토큰으로 표현할 수 없고 지금 그려지는 모드를 알아야 할 때
+  `useColorMode().colorMode`를 씁니다. 라이트·다크 파일이 따로 있는 테넌트 로고,
+  다이어그램 라이브러리의 테마, 차트 색 목록이 그런 예입니다.
+- 라이트, 다크, 시스템 설정을 고르는 설정 화면에는 `setColorMode`와
+  `colorModePreference`를 씁니다.
+- 헤더나 도구 막대에 빠르게 라이트·다크를 바꾸는 버튼이 필요하면 `ColorModeToggle`을
+  씁니다.
+- `ColorModeProvider`를 따로 쓰는 경우는 앱이 `LogicianProvider` 없이 프로바이더를
+  직접 조합할 때뿐입니다. `LogicianProvider`가 이미 이것을 마운트합니다.
+
+## 언제 쓰지 않나요
+
+- 시맨틱 토큰(`fg.default`, `bg.surface`)으로 표현할 수 있는 색은 토큰을 씁니다. 토큰은
+  CSS에서 모드에 따라 바뀝니다. `useColorModeValue`는 토큰이 될 수 없는 값에만 씁니다.
+- "시스템 설정"을 남겨야 하는 선호 설정에는 `ColorModeToggle` 대신 `setColorMode`로
+  고르는 화면을 만듭니다. 토글은 `light`와 `dark`만 정합니다.
+
+## 접근성
+
+- 토글의 기본 이름은 영어 "Toggle color mode"입니다. 한국어 화면에서는 `aria-label`을
+  직접 넘깁니다(WCAG 4.1.2). 이름은 모드에 따라 바뀌지 않고, 눌림 상태도 없습니다.
+- 해와 달 아이콘은 짧게 회전하며 바뀌는데, `prefers-reduced-motion: reduce`에서는 바로
+  바뀝니다. 페이지 전체의 색 전환은 늘 즉시 일어납니다(`disableTransitionOnChange`).
+- 하이드레이션 전에는 라이트 모드 아이콘을 보여 줍니다. 실제 모드는 클라이언트에서만 알
+  수 있기 때문입니다.
+- 두 모드 모두 명도 대비를 통과해야 합니다(WCAG 1.4.3). 색을 바꿨다면 라이트와 다크에서
+  화면을 확인합니다.
+
+## 속성과 API
+
+| API                              | 하는 일                                                                                                          |
+| -------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| `colorMode`                      | 지금 그려지는 모드, `'light'` 또는 `'dark'`. 강제 모드가 있으면 그 값입니다.                                     |
+| `colorModePreference`            | 저장된 선호값. `'system'`도 포함합니다.                                                                          |
+| `setColorMode(mode)`             | 선호값을 `'light'`, `'dark'`, `'system'` 중 하나로 정합니다.                                                     |
+| `toggleColorMode()`              | 사용자 선호를 기준으로 라이트와 다크를 오갑니다.                                                                 |
+| `useColorModeValue(light, dark)` | 지금 모드에 맞는 값 하나를 돌려줍니다.                                                                           |
+| `ColorModeToggle`                | `IconButton`이며, `children`을 뺀 그 속성을 받습니다.                                                            |
+| `ColorModeProvider`              | `next-themes` 기반. `<html>`에 클래스를 쓰고, 저장 키는 `logician-color-mode`, 시스템 설정 반영이 켜져 있습니다. |
+
+호스트 앱은 `<html>`에 `suppressHydrationWarning`을 붙여야 하고, `color-scheme`은 직접
+쓰지 않습니다. 프로바이더가 씁니다.
+
+</Ko>

package/src/components/ColorMode/ColorModeToggle.tsx

@@ -17,8 +17,13 @@ export interface ColorModeToggleProps extends Omit<
  * A ready-made light/dark toggle button. Shared across products so each app
  * doesn't reinvent the control.
  *
- * Renders nothing until mounted on the client to avoid an SSR/CSR icon
- * mismatch (the resolved mode is only known after hydration).
+ * Shows the light-mode state (moon) until mounted on the client, to avoid an
+ * SSR/CSR icon mismatch (the resolved mode is only known after hydration).
+ * Toggles between `light` and `dark` only; to offer `system` as well, build a
+ * picker on `useColorMode().setColorMode`.
+ *
+ * The icon wrappers render as `<span>`: only phrasing content may sit inside
+ * a `<button>` (see ACCESSIBILITY.md §5).
  *
  * @example
  * ```tsx
@@ -45,8 +50,9 @@ export const ColorModeToggle: React.FC<ColorModeToggleProps> = ({
           page-wide colour flip stays instant on purpose — `ColorModeProvider`
           sets `disableTransitionOnChange` so the whole UI doesn't wash through
           an intermediate state — this animates the control only. */}
-      <Box display="grid" placeItems="center">
+      <Box as="span" display="grid" placeItems="center">
         <Box
+          as="span"
           gridArea="1 / 1"
           display="grid"
           placeItems="center"
@@ -58,6 +64,7 @@ export const ColorModeToggle: React.FC<ColorModeToggleProps> = ({
           <SunIcon />
         </Box>
         <Box
+          as="span"
           gridArea="1 / 1"
           display="grid"
           placeItems="center"

package/src/components/Confetti/Confetti.types.ts

@@ -3,7 +3,11 @@ import type { BoxProps } from '@chakra-ui/react';
 export interface ConfettiProps extends BoxProps {
   /** How many pieces. Defaults to 50. */
   pieceCount?: number;
-  /** Colour token names to pick from. Defaults to the palette's five accents. */
+  /**
+   * Colours to pick from: any CSS colour string or colour token. Defaults to ten
+   * decorative colours — coral, beige and the eight system hues with no status
+   * meaning — as light-mode hex, so they do not follow dark mode.
+   */
   colors?: string[];
   /**
    * Changes the scatter. The generator is seeded rather than `Math.random()` so

package/src/components/Confetti/Confetti.usage.mdx

@@ -0,0 +1,111 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ConfettiStories from './Confetti.stories';
+
+<Meta of={ConfettiStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Confetti
+
+A one-shot celebratory burst over a container, for the rare moment a purchase
+completes or a reward lands.
+
+</En>
+
+<Ko>
+
+# Confetti
+
+컨테이너 위로 한 번 터지는 축하 효과입니다. 구매가 끝나거나 보상을 받는 드문 순간에 씁니다.
+
+</Ko>
+
+<Canvas of={ConfettiStories.Default} />
+
+<En>
+
+## When to use
+
+- A purchase confirmation, a completed course or a level-up: an outcome the
+  reader earned and does not see often.
+- At most once per moment. Mount it when the moment begins; pass a new `seed`
+  only to scatter a new burst.
+- A small win inside a flow, such as one correct answer, may pair a small burst
+  with its `Appear` stamp. Keep that burst smaller (fewer pieces, or scaled
+  down) than the ones for a purchase or a level-up, so the rarer moments still
+  read bigger.
+
+## When not to use
+
+- Routine success (saved, sent, copied) → `Toast`, or `Pulse` on the value
+  that changed.
+- Anything that went wrong or needs attention → never.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` the pieces mount but stay invisible.
+  The burst carries no information, so nothing is lost.
+- The overlay is `aria-hidden` and ignores the pointer, so it never covers a
+  button or reaches a screen reader. The success itself must be stated in text
+  on the screen.
+- Every piece finishes in under three seconds, so there is nothing to pause
+  (WCAG 2.2.2 covers motion longer than five seconds).
+
+## Props
+
+Confetti takes no children. It fills the nearest positioned ancestor, so give
+that element `position: relative`, or the burst covers the whole page. The
+default colours are decorative only: coral, beige and the system hues with no
+status meaning. Red, yellow, green and blue are left out of the defaults
+because they mean danger, warning, success and info. Passing them through
+`colors` is fine: a burst lasts under two seconds on a moment that is already
+a success, so no piece can be read as a status. The status-colour rule is for
+things that stay on screen, such as badges, chart lines and text. The defaults
+are light-mode values and do not change in dark mode; pass `colors` (tokens
+work) if that matters.
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 구매 확인, 과정 완료, 레벨 업처럼 사용자가 직접 얻어 냈고 자주 보지 않는 결과.
+- 한 순간에 한 번만 씁니다. 그 순간이 시작될 때 마운트하고, 새로 터뜨릴 때만 `seed`를
+  바꿉니다.
+- 정답 하나처럼 흐름 속의 작은 성공에는 `Appear` 표시와 함께 작은 폭죽을 터뜨려도
+  됩니다. 구매나 레벨 업 때보다 작게(조각을 줄이거나 크기를 줄여) 터뜨려야 드문 순간이
+  더 크게 느껴집니다.
+
+## 언제 쓰지 않나요
+
+- 저장, 전송, 복사처럼 흔한 성공에는 `Toast`를 쓰거나, 바뀐 값에 `Pulse`를 씁니다.
+- 잘못됐거나 확인이 필요한 일에는 절대 쓰지 않습니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 조각이 마운트되지만 보이지 않습니다. 이
+  효과에는 정보가 없으니 잃는 것도 없습니다.
+- 겹쳐진 층에는 `aria-hidden`이 붙고 포인터를 받지 않으므로, 버튼을 가리거나 화면
+  낭독기에 읽히지 않습니다. 성공했다는 사실은 화면의 문구로 따로 알려야 합니다.
+- 모든 조각이 3초 안에 끝나므로 멈춤 기능이 필요 없습니다(WCAG 2.2.2는 5초 넘게
+  움직이는 콘텐츠에 해당합니다).
+
+## 속성
+
+Confetti는 자식을 받지 않습니다. 가장 가까운 위치 지정 조상을 채우므로, 그 요소에
+`position: relative`를 줍니다. 그러지 않으면 페이지 전체를 덮습니다. 기본 색은 장식용으로,
+코랄, 베이지, 그리고 상태 뜻이 없는 시스템 색만 씁니다. 빨강, 노랑, 초록, 파랑은 각각
+위험, 경고, 성공, 정보를 뜻하므로 기본값에서 뺐습니다. 그래도 `colors`로 넘기는 것은
+괜찮습니다. 폭죽은 이미 성공한 순간에 2초도 안 돼 사라지므로, 어떤 조각도 상태 표시로
+읽히지 않습니다. 상태 색 규칙은 배지, 차트 선, 글자처럼 화면에 남는 요소에 적용합니다.
+기본 색은 라이트 모드 값이라 다크 모드에서 바뀌지 않습니다. 필요하면 `colors`를
+넘깁니다(토큰도 됩니다).
+
+</Ko>
+
+<ArgTypes of={ConfettiStories} include={['pieceCount', 'colors', 'seed']} />

package/src/components/Confetti/confettiColors.ts

@@ -2,11 +2,11 @@ import type { SystemHue } from '../../theme/colors';
 import { CORAL, RAMPS, SYSTEM_HUES } from '../../theme/palette.generated';
 
 /**
- * Hues that carry meaning elsewhere in the system and so never colour a piece
- * by default: red, yellow and green are the danger, warning and success
- * solids, and blue is info and links. The same rule as the chart series
- * defaults (`LineGraph/seriesColors.ts`) — a red piece in a "payment complete"
- * burst says something the screen does not.
+ * Hues left out of the *default* pieces: red, yellow and green are the
+ * danger, warning and success solids, and blue is info and links. This is a
+ * default, not a ban — a caller may pass them through `colors`, since a burst
+ * lasting under two seconds on a success moment cannot be read as a status
+ * (Confetti.usage.mdx).
  */
 export const CONFETTI_EXCLUDED_HUES = [
   'red',

package/src/components/Container/Container.stories.tsx

@@ -1,5 +1,7 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { Card } from '../Card';
+import { H1, Text } from '../Typography';
 import { Container } from './Container';
 
 const meta = {
@@ -18,3 +20,33 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Basic: Story = {};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Container.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 DoPageLandmark: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: the page column, as the main landmark',
+  args: { bg: undefined, p: 6, textAlign: 'start' },
+  render: (args) => (
+    <Container {...args} as="main">
+      <H1 mb={2}>사용량</H1>
+      <Text>이번 달 1일부터 오늘까지의 합계입니다.</Text>
+    </Container>
+  ),
+};
+
+export const DontInsideACard: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: a Container inside a narrow box",
+  args: { bg: 'primary.washActive', p: 4, textAlign: 'start' },
+  render: (args) => (
+    <Card p={4} maxW="320px" overflow="auto">
+      <Container {...args}>
+        폭이 창 크기로 정해져 카드 밖으로 넘칩니다.
+      </Container>
+    </Card>
+  ),
+};