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

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>
+  ),
+};

package/src/components/Container/Container.usage.mdx

@@ -0,0 +1,130 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as ContainerStories from './Container.stories';
+
+<Meta of={ContainerStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Container
+
+The centred page column. It is Chakra's `Container` plus a responsive
+`minWidth`: the largest theme breakpoint that still leaves a 10% gutter on
+each side of the **window**, recomputed on resize. `disableResponsive` turns
+that off.
+
+## When to use
+
+- Once per page, around the main content, so pages share the same width.
+
+## When not to use
+
+- Inside a card, a modal, a drawer or a sidebar → `Box` or `Stack` with a
+  `maxW`. The width comes from the window, not the parent, so it overflows a
+  narrow box.
+- To centre a small block → `Flex` / `Center`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Container
+
+가운데 정렬된 페이지 열입니다. Chakra의 `Container`에 반응형 `minWidth`를 더했습니다.
+**창** 양쪽에 10% 여백을 남기는 가장 큰 테마 중단점 값을 쓰고, 창 크기가 바뀌면 다시
+계산합니다. `disableResponsive`로 끌 수 있습니다.
+
+## 언제 쓰나요
+
+- 페이지마다 한 번, 본문을 감싸서 페이지들의 너비를 맞출 때.
+
+## 언제 쓰지 않나요
+
+- 카드, 모달, 서랍, 사이드바 안에서는 `maxW`를 준 `Box`나 `Stack`을 씁니다. 너비가
+  부모가 아니라 창에서 정해지므로 좁은 상자 밖으로 넘칩니다.
+- 작은 블록을 가운데 두려면 `Flex` / `Center`를 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={ContainerStories.DoPageLandmark} />
+<Verdict
+  kind="do"
+  en="Use one Container for the page column and render it as the main landmark (as='main')."
+  ko="페이지 열에 Container 하나를 쓰고, 본문 랜드마크로 그립니다(as='main')."
+/>
+
+<Canvas of={ContainerStories.DontInsideACard} />
+<Verdict
+  kind="dont"
+  en="Put a Container inside a narrow box. Its minimum width follows the window and spills out of the card."
+  ko="좁은 상자 안에 Container를 넣지 마세요. 최소 너비가 창을 따르므로 카드 밖으로 넘칩니다."
+/>
+
+<En>
+
+## Accessibility
+
+What Container does for you:
+
+- `as` changes the element and its props, so the page column can be a
+  landmark: `as="main"`, `as="section"`, `as="nav"`.
+
+What you still have to do:
+
+- **Mark the main content** with `as="main"` once per page, so "skip to
+  content" and landmark navigation work (WCAG 1.3.1, 2.4.1).
+- The `minWidth` is set after mount, from the window. Check pages at 320px
+  wide and at 400% zoom for sideways scrolling (WCAG 1.4.10).
+
+## Tokens
+
+Container sets no colour tokens.
+
+</En>
+
+<Ko>
+
+## 접근성
+
+Container가 알아서 하는 일
+
+- `as`가 요소와 그 속성을 함께 바꾸므로 페이지 열을 랜드마크로 만들 수 있습니다:
+  `as="main"`, `as="section"`, `as="nav"`.
+
+직접 챙겨야 하는 일
+
+- **본문을 표시합니다.** 페이지마다 한 번 `as="main"`을 써야 "본문 바로가기"와
+  랜드마크 이동이 동작합니다(WCAG 1.3.1, 2.4.1).
+- `minWidth`는 화면에 그려진 뒤 창 크기로 정해집니다. 폭 320px과 400% 확대에서 가로
+  스크롤이 생기지 않는지 확인합니다(WCAG 1.4.10).
+
+## 토큰
+
+Container는 색 토큰을 쓰지 않습니다.
+
+</Ko>
+
+<En>
+
+## Related
+
+- **Masonry**: a multi-column layout inside the page.
+- **Card**: a bounded block inside the page.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Masonry**: 페이지 안의 여러 열 레이아웃.
+- **Card**: 페이지 안의 경계 있는 블록.
+
+</Ko>

package/src/components/CopyableCode/CopyableCode.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 { CopyableCode } from './CopyableCode';
 import { CopyableCodeProps } from './CopyableCode.types';
 
@@ -20,3 +22,63 @@ export default meta;
 type Story = StoryObj<typeof CopyableCode>;
 
 export const Basic: Story = {};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `CopyableCode.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`); `tags` is written out on each story because the
+// indexer reads CSF statically.
+
+/** CopyableCode does not touch the clipboard; the caller's `onCopy` does. */
+const copy = (text: string) => () => {
+  void navigator.clipboard?.writeText(text);
+};
+
+const ENDPOINT = 'https://api.example.com/v1/chat/completions';
+
+export const DoOneLineValue: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: one line the user pastes somewhere else',
+  args: { children: ENDPOINT, onCopy: copy(ENDPOINT) },
+};
+
+const SCRIPT = `import OpenAI from 'openai';
+const client = new OpenAI({ baseURL: '${ENDPOINT}' });
+const res = await client.chat.completions.create({ model: 'gpt-4o' });`;
+
+export const DontMultiLine: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a multi-line snippet",
+  args: { children: SCRIPT, onCopy: copy(SCRIPT) },
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.surface',
+          use: (
+            <T
+              en="Card surface and the fade under the button"
+              ko="카드 바탕과 버튼 아래 흐려지는 부분"
+            />
+          ),
+        },
+        { token: 'border.subtle', use: <T en="Card border" ko="카드 테두리" /> },
+        {
+          token: 'primary.main',
+          use: <T en="Copy button (primary)" ko="복사 버튼(primary)" />,
+        },
+        {
+          token: 'fg.onPrimary',
+          use: <T en="Copy button label" ko="복사 버튼 글자" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/CopyableCode/CopyableCode.usage.mdx

@@ -0,0 +1,168 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as CopyableCodeStories from './CopyableCode.stories';
+
+<Meta of={CopyableCodeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# CopyableCode
+
+One line of code or a value in a card, with a 복사 button that confirms
+itself (the icon becomes a check and the label becomes 복사 완료 for 1.6
+seconds). FactChat uses it for model IDs and endpoints on the developer page.
+
+## When to use
+
+- A single value the user copies and pastes elsewhere: an endpoint, a model
+  ID, an embed URL.
+
+## When not to use
+
+- Several lines → `Code` with `onCopy`. CopyableCode renders on one line
+  (`white-space: nowrap`), so line breaks are lost.
+- A value inside a sentence → `InlineCode`.
+- A secret shown once (a new API key) → still fine, but say in the text that
+  it will not be shown again.
+
+## Props
+
+| Prop | Means |
+| --- | --- |
+| `children` | The value shown. |
+| `onCopy` | **Required, and it does the copying.** CopyableCode does not write to the clipboard; your handler must call `navigator.clipboard.writeText`. The button confirms when clicked either way. |
+| `containerProps` | Props for the outer `Flex` (width, margins). |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# CopyableCode
+
+카드 안에 코드 한 줄이나 값을 보여 주고 '복사' 버튼을 붙인 컴포넌트입니다. 버튼을
+누르면 1.6초 동안 아이콘이 체크로, 글자가 '복사 완료'로 바뀌어 스스로 확인해 줍니다.
+FactChat은 개발자 페이지의 모델 ID와 엔드포인트에 씁니다.
+
+## 언제 쓰나요
+
+- 사용자가 복사해서 다른 곳에 붙여 넣는 값 하나: 엔드포인트, 모델 ID, 임베드 URL.
+
+## 언제 쓰지 않나요
+
+- 여러 줄이라면 `onCopy`를 준 `Code`를 씁니다. CopyableCode는 한 줄로
+  그리므로(`white-space: nowrap`) 줄바꿈이 사라집니다.
+- 문장 안의 값은 `InlineCode`를 씁니다.
+- 한 번만 보여 주는 비밀 값(새 API 키)에도 쓸 수 있지만, 다시 볼 수 없다는 점을 본문에
+  적습니다.
+
+## 속성
+
+| 속성 | 뜻 |
+| --- | --- |
+| `children` | 보여 줄 값. |
+| `onCopy` | **필수이며, 복사는 이 함수가 합니다.** CopyableCode는 클립보드에 쓰지 않으므로 넘긴 함수에서 `navigator.clipboard.writeText`를 불러야 합니다. 버튼의 확인 표시는 어느 경우에나 나타납니다. |
+| `containerProps` | 바깥 `Flex`에 넘길 속성(너비, 여백). |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={CopyableCodeStories.DoOneLineValue} />
+<Verdict
+  kind="do"
+  en="Use it for one value, and write it to the clipboard in onCopy."
+  ko="값 하나에 쓰고, onCopy에서 클립보드에 씁니다."
+/>
+
+<Canvas of={CopyableCodeStories.DontMultiLine} />
+<Verdict
+  kind="dont"
+  en="Use it for a multi-line snippet. The lines run together and scroll sideways under the button. Use Code with onCopy."
+  ko="여러 줄 코드에 쓰지 마세요. 줄이 하나로 이어지고 버튼 아래로 가로 스크롤됩니다. onCopy를 준 Code를 씁니다."
+/>
+
+<En>
+
+## Content
+
+- Show the exact value, nothing around it: no quotes, no "URL:".
+- Put the label in the text above (모델 ID, 엔드포인트).
+
+## Accessibility
+
+What CopyableCode does for you:
+
+- The button is a real `Button` with a visible, translated label, so its name
+  matches what is shown (WCAG 2.5.3, 4.1.2).
+- Only one label is exposed at a time (the other is `aria-hidden`), and the
+  button keeps its width when the label changes.
+
+What you still have to do:
+
+- **Copy for real.** If `onCopy` does nothing, the button still says 복사
+  완료 and tells the user something false.
+- The confirmation is visual only; there is no live region. If the copy
+  result matters (a key shown once), also announce it, for example with a
+  `Toast` (WCAG 4.1.3).
+- A long value scrolls sideways under a fade. Make sure the start of the
+  value is the part that identifies it.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 값만 정확히 보여 줍니다. 따옴표나 "URL:" 같은 말을 붙이지 않습니다.
+- 라벨(모델 ID, 엔드포인트)은 위 본문에 씁니다.
+
+## 접근성
+
+CopyableCode가 알아서 하는 일
+
+- 버튼은 번역된 글자가 보이는 실제 `Button`이라, 보이는 글자와 읽히는 이름이
+  같습니다(WCAG 2.5.3, 4.1.2).
+- 한 번에 한 글자만 노출되고(다른 하나는 `aria-hidden`), 글자가 바뀌어도 버튼 너비가
+  그대로입니다.
+
+직접 챙겨야 하는 일
+
+- **실제로 복사합니다.** `onCopy`가 아무것도 하지 않아도 버튼은 '복사 완료'를 띄우므로
+  사용자에게 사실이 아닌 것을 알리게 됩니다.
+- 확인 표시는 화면에만 나타나고 라이브 영역이 없습니다. 복사 결과가 중요하다면(한 번만
+  보여 주는 키 등) `Toast` 같은 방법으로도 알립니다(WCAG 4.1.3).
+- 긴 값은 흐려지는 부분 아래로 가로 스크롤됩니다. 값의 앞부분만 보고도 무엇인지 알 수
+  있게 합니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={CopyableCodeStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Code**: multi-line snippets with a copy button.
+- **InlineCode**: a value inside a sentence.
+- **Toast**: announce a copy result that matters.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Code**: 복사 버튼이 있는 여러 줄 코드.
+- **InlineCode**: 문장 안의 값.
+- **Toast**: 중요한 복사 결과를 알릴 때.
+
+</Ko>

package/src/components/CountBadge/CountBadge.stories.tsx

@@ -1,9 +1,12 @@
 import { Flex, HStack, Text } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { BellIcon } from '../Icon';
 import { IconButton } from '../IconButton';
 import { CountBadge } from '.';
+import { countBadgeBaseStyles } from './CountBadge.styles';
 
 const meta = {
   title: 'Components/CountBadge',
@@ -107,3 +110,69 @@ export const OnIconButton: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `CountBadge.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written on each story because the indexer reads
+// CSF statically.
+
+const FOLDERS = [
+  { name: '연구 자료', files: 128 },
+  { name: '수업 자료', files: 42 },
+  { name: '행정 문서', files: 7 },
+];
+
+export const DontCountForTotals: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a count badge for a total",
+  render: () => (
+    <Flex direction="column" gap={2} w="240px">
+      {FOLDERS.map((folder) => (
+        <HStack key={folder.name} justify="space-between">
+          <Text>{folder.name}</Text>
+          <CountBadge count={folder.files} />
+        </HStack>
+      ))}
+    </Flex>
+  ),
+};
+
+export const DoTotalsAsText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: totals as plain text',
+  render: () => (
+    <Flex direction="column" gap={2} w="240px">
+      {FOLDERS.map((folder) => (
+        <HStack key={folder.name} justify="space-between">
+          <Text>{folder.name}</Text>
+          <Text textStyle="subtext" color="fg.muted">
+            파일 {folder.files}개
+          </Text>
+        </HStack>
+      ))}
+    </Flex>
+  ),
+};
+
+/** Tokens the badge reads, from `CountBadge.styles.ts` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: countBadgeBaseStyles.bgColor as string,
+          use: <T en="fill (number and dot)" ko="바탕(숫자, 점)" />,
+        },
+        {
+          token: countBadgeBaseStyles.color as string,
+          use: <T en="number" ko="숫자" />,
+        },
+      ]}
+    />
+  ),
+};