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

package/src/components/Loaders/Loaders.usage.mdx

@@ -0,0 +1,180 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as LoadersStories from './Loaders.stories';
+
+<Meta of={LoadersStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Loaders
+
+Overlays that cover a page (`PageLoader`) or one region (`SectionLoader`) while
+its content loads, with a spinner or, for AI work, three pulsing coral dots.
+
+## When to use
+
+- `SectionLoader`: one card, panel or list is loading and the rest of the page
+  is usable.
+- `PageLoader`: nothing on the page can be used yet, such as while access is
+  being checked.
+- `variant="thinking"`: the wait is the AI working, not data loading.
+  `ThinkingDots` is the same mark without the overlay.
+
+## When not to use
+
+- A short wait inside a button → the button's own `loading` state.
+- Inline next to text → `Spinner`.
+- Work with a known length → `ProgressBar`.
+- The layout of the coming content is known → a skeleton keeps the page from
+  jumping.
+
+## How they behave
+
+| | `PageLoader` | `SectionLoader` |
+| --- | --- | --- |
+| Covers | The whole viewport (`position: fixed`, `100dvh`) | Its nearest positioned parent (`position: absolute`, 100% × 100%) |
+| Background | `bg.canvas` at 50% opacity | `bg.canvas`, opaque |
+| `isLoading={false}` | Stays mounted at opacity 0 and exposes no status | Renders nothing |
+| `variant` | `default` (spinner) or `thinking` (dots) | Same |
+| `label` | Spoken text, default 로딩 중 (translated) | Same |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Loaders
+
+내용을 불러오는 동안 페이지 전체(`PageLoader`)나 한 영역(`SectionLoader`)을 덮는
+화면입니다. 스피너를 보여 주거나, AI가 일하는 중이라면 코럴 점 세 개가 차례로
+깜박입니다.
+
+## 언제 쓰나요
+
+- `SectionLoader`: 카드, 패널, 목록 하나만 불러오는 중이고 나머지 페이지는 쓸 수 있을 때.
+- `PageLoader`: 권한을 확인하는 동안처럼 페이지에서 아무것도 쓸 수 없을 때.
+- `variant="thinking"`: 데이터를 불러오는 것이 아니라 AI가 일하는 동안 기다릴 때.
+  덮개 없이 같은 표시만 필요하다면 `ThinkingDots`를 씁니다.
+
+## 언제 쓰지 않나요
+
+- 버튼 안의 짧은 대기는 그 버튼의 `loading` 상태를 씁니다.
+- 글자 옆에 작게 둘 때는 `Spinner`를 씁니다.
+- 길이를 아는 작업은 `ProgressBar`를 씁니다.
+- 나올 내용의 배치를 안다면 스켈레톤을 써서 화면이 밀리지 않게 합니다.
+
+## 동작 방식
+
+| | `PageLoader` | `SectionLoader` |
+| --- | --- | --- |
+| 덮는 범위 | 화면 전체(`position: fixed`, `100dvh`) | 가장 가까운 위치 지정 부모(`position: absolute`, 100% × 100%) |
+| 배경 | 불투명도 50%의 `bg.canvas` | 불투명한 `bg.canvas` |
+| `isLoading={false}` | 불투명도 0으로 남아 있고 상태를 알리지 않음 | 아무것도 그리지 않음 |
+| `variant` | `default`(스피너) 또는 `thinking`(점) | 같음 |
+| `label` | 화면 낭독기가 읽는 문구, 기본값 "로딩 중"(번역됨) | 같음 |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={LoadersStories.DoSectionLoaderInParent} />
+<Verdict
+  kind="do"
+  en="Give SectionLoader a parent with position: relative and say what is loading in label. Without the positioned parent it covers the nearest positioned ancestor, which may be the whole page."
+  ko="SectionLoader의 부모에는 position: relative를 주고, label에는 무엇을 불러오는지 씁니다. 위치 지정 부모가 없으면 가장 가까운 위치 지정 조상을 덮고, 그것이 페이지 전체일 수도 있습니다."
+/>
+
+<Canvas of={LoadersStories.DoThinkingForAI} />
+<Verdict
+  kind="do"
+  en="Use the thinking variant only while the AI is working. Coral is the AI-working mark; on an ordinary data load it means nothing."
+  ko="thinking 변형은 AI가 일하는 동안에만 씁니다. 코럴은 AI 작업 표시이며, 평범한 데이터 로딩에서는 아무 뜻도 전하지 못합니다."
+/>
+
+<En>
+
+## Content
+
+- `label` says what is loading, as a noun phrase: 멤버 목록을 불러오는 중,
+  답변을 준비하는 중. The default 로딩 중 says nothing about what.
+- Pass the translated string; `label` is used as given.
+
+## Accessibility
+
+What the loaders do for you:
+
+- While loading, the overlay is `role="status"` with `aria-live="polite"` and
+  the label as visually hidden text, so screen readers announce it
+  (WCAG 4.1.3). When idle it exposes no status at all.
+- The spinner and the dots are decorative; the label carries the meaning.
+- The dots stop under `prefers-reduced-motion`; the spinner slows down instead,
+  because a frozen spinner reads as a hung request.
+
+What you still have to do:
+
+- **Keep focus out of what is covered.** The overlay does not trap or move
+  focus; controls underneath stay reachable with Tab. Disable them, or do not
+  render them, until loading ends (WCAG 2.4.3).
+- After a long load, move focus or announce the result when it matters.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- `label`에는 무엇을 불러오는지 명사구로 씁니다: 멤버 목록을 불러오는 중, 답변을
+  준비하는 중. 기본값 "로딩 중"은 무엇을 불러오는지 알려 주지 않습니다.
+- 번역된 문자열을 넘깁니다. `label`은 받은 그대로 씁니다.
+
+## 접근성
+
+Loaders가 알아서 하는 일
+
+- 불러오는 동안 덮개에 `role="status"`와 `aria-live="polite"`가 붙고, label이
+  화면에 보이지 않는 글자로 들어가서 화면 낭독기가 읽습니다(WCAG 4.1.3). 쉬는 동안에는
+  상태를 전혀 알리지 않습니다.
+- 스피너와 점은 장식이고, 뜻은 label이 전합니다.
+- `prefers-reduced-motion`에서는 점이 멈추고, 스피너는 멈추지 않고 느려집니다. 멈춘
+  스피너는 요청이 멈춘 것처럼 보이기 때문입니다.
+
+직접 챙겨야 하는 일
+
+- **덮인 영역으로 초점이 가지 않게 합니다.** 덮개는 초점을 가두거나 옮기지 않으므로,
+  아래에 있는 컨트롤에 Tab으로 여전히 닿습니다. 다 불러올 때까지 비활성으로 두거나
+  그리지 않습니다(WCAG 2.4.3).
+- 오래 걸린 로딩이 끝난 뒤 결과가 중요하다면 초점을 옮기거나 결과를 알립니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={LoadersStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Spinner**: the spinner on its own, inline.
+- **ProgressBar**: work whose length is known.
+- **Button**: `loading` for a busy button.
+- **Foundations/Brand & colour usage**: coral is the AI-working mark.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Spinner**: 글자 옆에 두는 스피너 단독형.
+- **ProgressBar**: 길이를 아는 작업.
+- **Button**: 작업 중인 버튼은 `loading`.
+- **Foundations/Brand & colour usage**: 코럴은 AI 작업 표시입니다.
+
+</Ko>

package/src/components/LogicianProvider/LogicianProvider.usage.mdx

@@ -0,0 +1,98 @@
+import { ArgTypes, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as LogicianProviderStories from './LogicianProvider.stories';
+
+<Meta of={LogicianProviderStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# LogicianProvider
+
+The root provider: it gives every component below it the Logician theme, the
+colour-mode runtime and the language for locale-aware parts.
+
+## When to use
+
+- Once, at the root of the app, around everything that renders Logician
+  components. Put it inside your styling registry (for example the Emotion
+  registry in a Next.js app) and outside your own providers.
+- With `config` to extend the theme, `language` from the user's locale, and
+  `defaultColorMode="system"` so a first visit follows the OS.
+- With `forcedColorMode` during a staged rollout, to pin one mode while
+  screens are migrated.
+
+## When not to use
+
+- A second LogicianProvider deeper in the tree to change density → use
+  `ScaledContext`.
+- To recolour one area → use semantic tokens on that area. A nested provider
+  builds a new Chakra system.
+- When the host already mounts its own `next-themes` provider → pass
+  `enableColorMode={false}` instead of mounting two.
+
+## Accessibility
+
+- `language` only feeds the date and month pickers and other locale-aware
+  parts. It does not set `<html lang>`; the app must do that (WCAG 3.1.1).
+- With `loadFonts` (on by default) it adds Pretendard Variable and Inter
+  stylesheets from public CDNs to `<head>`. Set it to `false` if the app loads
+  them itself, or if those hosts are blocked.
+- Colour mode follows the reader's OS setting by default and can be stored per
+  device. See **Setup/ColorMode/Usage** for the contract.
+
+## Props
+
+</En>
+
+<Ko>
+
+# LogicianProvider
+
+최상위 프로바이더입니다. 그 아래 모든 컴포넌트에 Logician 테마, 컬러 모드 동작, 날짜처럼
+지역 설정을 따르는 파트에 쓸 언어를 넘겨줍니다.
+
+## 언제 쓰나요
+
+- 앱의 최상위에서 한 번, Logician 컴포넌트를 그리는 모든 것을 감싸도록 둡니다. 스타일
+  레지스트리(예: Next.js 앱의 Emotion 레지스트리) 안쪽, 앱 자체 프로바이더 바깥쪽에 둡니다.
+- 테마를 넓힐 때는 `config`, 사용자 지역 설정에는 `language`, 첫 방문에서 운영체제 설정을
+  따르게 하려면 `defaultColorMode="system"`을 넘깁니다.
+- 화면을 단계적으로 옮기는 동안 한 모드로 고정하려면 `forcedColorMode`를 씁니다.
+
+## 언제 쓰지 않나요
+
+- 촘촘함을 바꾸려고 트리 안쪽에 LogicianProvider를 하나 더 두지 않습니다.
+  `ScaledContext`를 씁니다.
+- 한 영역의 색만 바꾸려면 그 영역에 시맨틱 토큰을 씁니다. 프로바이더를 겹치면 Chakra
+  시스템을 새로 만듭니다.
+- 호스트 앱이 이미 자체 `next-themes` 프로바이더를 마운트한다면 둘을 겹치지 말고
+  `enableColorMode={false}`를 넘깁니다.
+
+## 접근성
+
+- `language`는 날짜·월 선택기처럼 지역 설정을 따르는 파트에만 쓰입니다. `<html lang>`은
+  정하지 않으므로 앱이 직접 정해야 합니다(WCAG 3.1.1).
+- `loadFonts`(기본값 켜짐)는 Pretendard Variable과 Inter 스타일시트를 공개 CDN에서
+  `<head>`에 추가합니다. 앱이 직접 글꼴을 불러오거나 그 주소가 막혀 있다면 `false`로 둡니다.
+- 컬러 모드는 기본적으로 운영체제 설정을 따르고, 기기마다 저장될 수 있습니다. 자세한
+  약속은 **Setup/ColorMode/Usage**에 있습니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={LogicianProviderStories}
+  include={[
+    'config',
+    'theme',
+    'language',
+    'loadFonts',
+    'defaultColorMode',
+    'forcedColorMode',
+    'enableColorMode',
+  ]}
+/>

package/src/components/Markdown/Markdown.stories.tsx

@@ -1,5 +1,7 @@
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { Markdown } from './Markdown';
 
 const meta = {
@@ -216,3 +218,54 @@ The quadratic formula: $x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}$
 *Markdown component with full GFM support!*`,
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Markdown.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 DoGeneratedAnswer: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: authored or generated long-form text',
+  args: {
+    children: `요청하신 내용을 정리했습니다.
+
+### 바꿀 점
+1. 요청 본문의 \`model\` 값을 확인합니다.
+2. 응답이 끊기면 \`max_tokens\`를 늘립니다.
+
+| 항목 | 값 |
+| --- | --- |
+| 모델 | gpt-4o |
+| 최대 토큰 | 4,096 |
+
+자세한 내용은 [API 문서](https://example.com/docs)를 보세요.`,
+  },
+};
+
+export const DontUiCopy: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: Markdown for a fixed UI string",
+  args: { children: '**저장되었습니다.**' },
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'fg.default',
+          use: <T en="Container text colour" ko="컨테이너 글자색" />,
+        },
+        { token: 'fg.emphasized', use: <T en="Headings" ko="제목" /> },
+        { token: 'fg.link', use: <T en="Links" ko="링크" /> },
+        { token: 'bg.subtle', use: <T en="Inline code" ko="인라인 코드" /> },
+      ]}
+    />
+  ),
+};

package/src/components/Markdown/Markdown.usage.mdx

@@ -0,0 +1,182 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as MarkdownStories from './Markdown.stories';
+
+<Meta of={MarkdownStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Markdown
+
+Renders a Markdown string with the design system's own components: headings
+become `H1`–`H5` (and `h6` a `Subtitle as="h6"`), paragraphs `Text`, links
+`Link`, code `InlineCode` or `Code`, tables `Table`. GitHub-flavoured
+Markdown, line breaks, highlight markers and KaTeX maths are on.
+
+## When to use
+
+- Long-form text written by someone else or generated: model answers,
+  announcements, release notes, help articles.
+
+## When not to use
+
+- A fixed UI string (a label, a toast, an error message) → `Text`. Markdown is
+  for content you do not control at build time.
+- A chat message with app-specific blocks (citations, tool output) → the
+  app's own renderer, passing overrides through `components`.
+
+## Props
+
+| Prop | Means |
+| --- | --- |
+| `children` | The Markdown string. |
+| `components` | Overrides merged over the built-in mapping (`baseMarkdownComponents`, exported). Use it to change heading levels or add custom blocks. |
+| `className` | Added to the wrapper next to the built-in spacing styles. |
+| Other `react-markdown` options | Passed through. Plugins you pass replace the built-in plugin lists. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Markdown
+
+마크다운 글을 이 디자인 시스템의 컴포넌트로 그립니다. 제목은 `H1`–`H5`(`h6`는
+`Subtitle as="h6"`), 문단은 `Text`, 링크는 `Link`, 코드는 `InlineCode`나 `Code`, 표는
+`Table`이 됩니다. GitHub식 마크다운, 줄바꿈, 형광펜 표시, KaTeX 수식이 켜져 있습니다.
+
+## 언제 쓰나요
+
+- 다른 사람이 썼거나 생성된 긴 글: 모델 답변, 공지, 릴리스 노트, 도움말.
+
+## 언제 쓰지 않나요
+
+- 고정된 화면 문구(라벨, 토스트, 오류 메시지)는 `Text`를 씁니다. Markdown은 빌드할 때
+  내용을 알 수 없는 글에 씁니다.
+- 인용, 도구 결과처럼 앱 고유의 블록이 있는 채팅 메시지는 앱의 렌더러를 쓰고,
+  `components`로 덮어씁니다.
+
+## 속성
+
+| 속성 | 뜻 |
+| --- | --- |
+| `children` | 마크다운 글. |
+| `components` | 기본 매핑(`baseMarkdownComponents`, 내보냄) 위에 덮어쓸 컴포넌트. 제목 수준을 바꾸거나 블록을 추가할 때 씁니다. |
+| `className` | 기본 간격 스타일과 함께 바깥 요소에 붙습니다. |
+| 그 밖의 `react-markdown` 옵션 | 그대로 넘깁니다. 플러그인을 넘기면 기본 플러그인 목록을 대신합니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={MarkdownStories.DoGeneratedAnswer} />
+<Verdict
+  kind="do"
+  en="Render authored or generated long-form text. Lists, code, tables and links all come out as design-system components."
+  ko="작성하거나 생성된 긴 글을 그립니다. 목록, 코드, 표, 링크가 모두 디자인 시스템 컴포넌트로 나옵니다."
+/>
+
+<Canvas of={MarkdownStories.DontUiCopy} />
+<Verdict
+  kind="dont"
+  en="Pass a fixed UI string through Markdown to make it bold. Use Text with fontWeight; the copy belongs in your translations, not in Markdown."
+  ko="고정된 화면 문구를 굵게 하려고 Markdown을 거치지 마세요. fontWeight를 준 Text를 쓰고, 문구는 마크다운이 아니라 번역 파일에 둡니다."
+/>
+
+<En>
+
+## Content
+
+- Write headings in order, starting from the level that fits under the
+  page's own heading.
+- Write link text that names the destination, and alt text for every image.
+
+## Accessibility
+
+What Markdown does for you:
+
+- Headings stay real headings, including `######` (`as="h6"`), so the
+  author's structure reaches the outline (KWCAG 5.2.4.2 제목 제공).
+- Tables are real tables, links are underlined `Link`s, and code blocks get
+  `Code`'s copy button.
+
+What you still have to do:
+
+- **Fit the heading levels to the page.** `#` becomes an `<h1>`. If the page
+  already has an `h1`, map the levels down with `components` (WCAG 1.3.1,
+  2.4.6).
+- **Images need alt text from the author.** An image written without alt in
+  raw HTML gets the placeholder "chat-image", which describes nothing (WCAG
+  1.1.1).
+- **Links open in a new tab** (`target="_blank"`) with no warning. Say so near
+  the content if it matters, or override `a` in `components` (WCAG 3.2.5).
+- **Raw HTML is rendered** (`rehype-raw`) and not sanitised. Sanitise
+  untrusted input before you pass it in.
+
+## Tokens
+
+The wrapper sets `fg.default`; everything else comes from the components it
+maps to.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 제목은 차례대로 쓰고, 페이지 제목 아래에 맞는 수준에서 시작합니다.
+- 링크 문구에는 이동할 곳을 적고, 모든 이미지에 대체 글을 씁니다.
+
+## 접근성
+
+Markdown이 알아서 하는 일
+
+- 제목은 `######`(`as="h6"`)까지 실제 제목으로 남으므로, 작성자가 만든 구조가 문서
+  구조에 그대로 들어갑니다(KWCAG 5.2.4.2 제목 제공).
+- 표는 실제 표로, 링크는 밑줄이 있는 `Link`로 그려지고, 코드 블록에는 `Code`의 복사
+  버튼이 붙습니다.
+
+직접 챙겨야 하는 일
+
+- **제목 수준을 페이지에 맞춥니다.** `#`은 `<h1>`이 됩니다. 페이지에 이미 `h1`이
+  있다면 `components`로 수준을 한 단계씩 내립니다(WCAG 1.3.1, 2.4.6).
+- **이미지 대체 글은 작성자가 써야 합니다.** HTML로 쓴 이미지에 alt가 없으면 아무것도
+  설명하지 않는 "chat-image"가 들어갑니다(WCAG 1.1.1).
+- **링크는 안내 없이 새 탭에서 열립니다**(`target="_blank"`). 중요하다면 내용 근처에
+  알리거나 `components`에서 `a`를 덮어씁니다(WCAG 3.2.5).
+- **HTML이 그대로 그려지고**(`rehype-raw`) 정제되지 않습니다. 믿을 수 없는 입력은
+  넘기기 전에 정제합니다.
+
+## 토큰
+
+바깥 요소는 `fg.default`를 쓰고, 나머지는 매핑된 컴포넌트에서 옵니다.
+
+</Ko>
+
+<Canvas of={MarkdownStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Typography**: the heading and text components Markdown maps to.
+- **Code** / **InlineCode**: code blocks and inline code.
+- **Table**: Markdown tables.
+- **ExpandableText**: clip long text to a few lines.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Typography**: Markdown이 매핑하는 제목·본문 컴포넌트.
+- **Code** / **InlineCode**: 코드 블록과 인라인 코드.
+- **Table**: 마크다운 표.
+- **ExpandableText**: 긴 글을 몇 줄로 접어 둘 때.
+
+</Ko>

package/src/components/Masonry/Masonry.stories.tsx

@@ -1,6 +1,8 @@
 import { Box, SimpleGrid, Text, useBreakpointValue } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { Card } from '../Card';
+import { Subtext } from '../Typography';
 import { Masonry } from './Masonry';
 
 const meta = {
@@ -25,7 +27,7 @@ const meta = {
     horizontalArrangement: {
       control: 'boolean',
       description:
-        'Whether to arrange items horizontally (true) or balance column heights (false)',
+        'Deal items round-robin across columns (true) or balance column heights (false)',
       defaultValue: false,
     },
   },
@@ -310,3 +312,63 @@ export const ComparisonWithGrid: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Masonry.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+const MODEL_GROUPS = [
+  { title: '대화', items: ['GPT-4o', 'Claude', 'Gemini', 'Solar', 'Llama'] },
+  { title: '이미지', items: ['Imagen', 'FLUX'] },
+  { title: '음성', items: ['TTS', 'STT', '음성 복제'] },
+  { title: '검색', items: ['웹 검색'] },
+  { title: '영상', items: ['Veo', 'Kling', 'Runway', 'Pika'] },
+  { title: '코드', items: ['Codex', 'Claude Code'] },
+];
+
+export const DoUnorderedGroups: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: unordered groups of different heights',
+  args: { numCols: 3 },
+  render: (args) => (
+    <Masonry {...args}>
+      {MODEL_GROUPS.map((group) => (
+        <Card key={group.title} p={4}>
+          <Text fontWeight="bold" mb={2}>
+            {group.title}
+          </Text>
+          {group.items.map((item) => (
+            <Subtext key={item}>{item}</Subtext>
+          ))}
+        </Card>
+      ))}
+    </Masonry>
+  ),
+};
+
+const STEPS = [
+  '1. 그룹을 만듭니다',
+  '2. 멤버를 초대합니다 — 초대 메일은 7일 동안 유효합니다',
+  '3. 크레딧 한도를 정합니다',
+  '4. 챗봇을 공유합니다',
+  '5. 사용량을 확인합니다 — 대시보드에서 날짜별로 볼 수 있습니다',
+  '6. 결제 수단을 등록합니다',
+];
+
+export const DontOrderedContent: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: steps or a ranking",
+  args: { numCols: 3 },
+  render: (args) => (
+    <Masonry {...args}>
+      {STEPS.map((step) => (
+        <Card key={step} p={4}>
+          <Text>{step}</Text>
+        </Card>
+      ))}
+    </Masonry>
+  ),
+};

package/src/components/Masonry/Masonry.types.ts

@@ -2,7 +2,8 @@ import { GridProps } from '@chakra-ui/react';
 
 export interface MasonryProps extends Omit<GridProps, 'gap'> {
   /**
-   * Number of columns in the masonry layout
+   * Number of columns. A plain number, not a responsive object: for a
+   * responsive count, pass the result of `useBreakpointValue`.
    */
   numCols: number;
   /**
@@ -11,8 +12,12 @@ export interface MasonryProps extends Omit<GridProps, 'gap'> {
    */
   gap?: number | string;
   /**
-   * Whether to arrange items from left to right (true) or top to bottom (false)
-   * @default false (arrange vertically)
+   * `false` (default): each item goes into the currently shortest column, so
+   * the column heights stay balanced. `true`: items are dealt round-robin
+   * across the columns (item 1 → column 1, item 2 → column 2, …), so the
+   * first row reads left to right. Either way the DOM order is column by
+   * column, which is the order keyboard and screen-reader users get.
+   * @default false
    */
   horizontalArrangement?: boolean;
 }