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

package/src/components/CodeTabs/CodeTabs.usage.mdx

@@ -0,0 +1,176 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as CodeTabsStories from './CodeTabs.stories';
+
+<Meta of={CodeTabsStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# CodeTabs
+
+One example shown in several languages, one tab per language, with an
+optional copy button for the tab that is showing. FactChat uses it for the
+API access snippet in a chatbot's share settings.
+
+## When to use
+
+- The same call written in two or more languages (cURL, Python,
+  JavaScript), where the reader needs only one of them.
+
+## When not to use
+
+- One snippet → `Code`.
+- Steps the reader needs in order (install, configure, run) → one `Code`
+  block per step, in sequence, so none are hidden.
+- Content that is not code → `Tabs`.
+
+## Options
+
+| Prop | Means |
+| --- | --- |
+| `code` | `{ [language]: source }`. The keys are the tab labels and the highlighting language, in the order given. The first is selected. |
+| `onCopy` | Turns the copy button on. The component writes the selected tab's code to the clipboard, then calls `onCopy(code)`. |
+
+The chrome is dark in both colour modes, because the `github-dark` token
+colours need a dark ground.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# CodeTabs
+
+하나의 예제를 여러 언어로 보여 주는 컴포넌트입니다. 언어마다 탭이 하나씩 있고, 보이는
+탭의 코드를 복사하는 버튼을 켤 수 있습니다. FactChat은 챗봇 공유 설정의 API 접근
+예제에 씁니다.
+
+## 언제 쓰나요
+
+- 같은 호출을 두 가지 이상의 언어(cURL, Python, JavaScript)로 보여 주고, 읽는 사람은
+  그중 하나만 필요할 때.
+
+## 언제 쓰지 않나요
+
+- 코드가 하나라면 `Code`를 씁니다.
+- 순서대로 모두 필요한 단계(설치, 설정, 실행)라면 단계마다 `Code` 블록을 차례로 두어
+  숨기는 것이 없게 합니다.
+- 코드가 아닌 내용은 `Tabs`를 씁니다.
+
+## 옵션
+
+| 속성 | 뜻 |
+| --- | --- |
+| `code` | `{ [언어]: 코드 }`. 키가 탭 이름이자 강조 언어이고, 넘긴 순서대로 나옵니다. 첫 탭이 선택됩니다. |
+| `onCopy` | 복사 버튼을 켭니다. 선택된 탭의 코드를 컴포넌트가 클립보드에 쓰고 `onCopy(code)`를 부릅니다. |
+
+`github-dark` 색은 어두운 바탕을 전제로 하므로, 두 색 모드 모두에서 어두운 바탕을
+씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={CodeTabsStories.DoSameCallPerLanguage} />
+<Verdict
+  kind="do"
+  en="One call, one tab per language. The reader picks theirs and copies it."
+  ko="호출 하나에 언어마다 탭 하나. 읽는 사람이 자기 언어를 골라 복사합니다."
+/>
+
+<Canvas of={CodeTabsStories.DontStepsAsTabs} />
+<Verdict
+  kind="dont"
+  en="Put different steps (install, set up the client, the request body) behind language tabs. The reader needs all three, and the tabs hide two of them."
+  ko="서로 다른 단계(설치, 클라이언트 설정, 요청 본문)를 언어 탭 뒤에 나누지 마세요. 세 단계가 모두 필요한데 탭은 둘을 숨깁니다."
+/>
+
+<En>
+
+## Content
+
+- Use a language identifier Shiki knows as the key (`python`,
+  `javascript`, `bash`); it is shown in uppercase, and any other key fails to
+  highlight.
+- Keep the examples equivalent: same call, same values, same placeholders.
+
+## Accessibility
+
+What CodeTabs does for you:
+
+- The tabs are the house `Tabs`, so the tab pattern (`tablist`, `tab`,
+  arrow-key movement) comes with them (WCAG 2.1.1, 4.1.2).
+- Hidden panels are `aria-hidden` and invisible, so only the selected
+  language is read.
+- Text on the dark chrome is at least 7:1 (`action.fg` 70% on `action.bg`)
+  in every mode (WCAG 1.4.3).
+
+What you still have to do:
+
+- The copy button's name is the fixed English "Copy"; its tooltip is
+  translated. Note it if your screen is Korean-only.
+- Say in the text above what the example does (WCAG 1.3.1).
+
+## Tokens
+
+Read from `CODE_CHROME` in `CodeTabs.styles.ts`. It borrows the `action.*`
+roles because they are the one pair that stays dark in every mode.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 키에는 Shiki가 아는 언어 식별자(`python`, `javascript`, `bash`)를 씁니다. 화면에는
+  대문자로 나오며, 다른 키를 쓰면 강조가 실패합니다.
+- 예제끼리 내용을 맞춥니다. 같은 호출, 같은 값, 같은 바꿔 넣을 자리를 씁니다.
+
+## 접근성
+
+CodeTabs가 알아서 하는 일
+
+- 탭은 이 디자인 시스템의 `Tabs`이므로 탭 패턴(`tablist`, `tab`, 화살표 키 이동)을
+  그대로 따릅니다(WCAG 2.1.1, 4.1.2).
+- 숨겨진 패널은 `aria-hidden`이고 보이지 않으므로, 선택된 언어만 읽힙니다.
+- 어두운 바탕 위의 글자는 모든 모드에서 7:1 이상입니다(`action.bg` 위의 `action.fg`
+  70%, WCAG 1.4.3).
+
+직접 챙겨야 하는 일
+
+- 복사 버튼 이름은 영어 "Copy"로 고정되어 있고 툴팁만 번역됩니다. 한국어 전용
+  화면이라면 이 점을 기록해 둡니다.
+- 예제가 무엇을 하는지 위 본문에서 알립니다(WCAG 1.3.1).
+
+## 토큰
+
+`CodeTabs.styles.ts`의 `CODE_CHROME`에서 읽습니다. 모든 모드에서 어두운 유일한 역할
+쌍이라 `action.*`을 빌려 씁니다.
+
+</Ko>
+
+<Canvas of={CodeTabsStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Code**: a single snippet.
+- **Tabs**: tabs for anything that is not code.
+- **CopyableCode**: one line with a copy button.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Code**: 코드 하나.
+- **Tabs**: 코드가 아닌 내용의 탭.
+- **CopyableCode**: 복사 버튼이 달린 한 줄.
+
+</Ko>

package/src/components/Collapsible/Collapsible.stories.tsx

@@ -1,6 +1,9 @@
 import { Meta, StoryObj } from '@storybook/react';
 import { Text } from '@chakra-ui/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Code } from '../Code';
 import { Collapsible, CollapsibleContent, CollapsibleRoot, CollapsibleTrigger } from '.';
 
 const meta = {
@@ -65,3 +68,58 @@ export const CompoundAPI: Story = {
     </Collapsible.Root>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Collapsible.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 DoOptionalDetail: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: optional detail, closed by default',
+  render: (args) => (
+    <CollapsibleRoot {...args} maxW="560px">
+      <CollapsibleTrigger>원본 데이터 보기</CollapsibleTrigger>
+      <CollapsibleContent>
+        <Code language="json">{`{ "event": "member.invite", "count": 3 }`}</Code>
+      </CollapsibleContent>
+    </CollapsibleRoot>
+  ),
+};
+
+export const DontVagueTrigger: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a trigger that does not say what opens",
+  render: (args) => (
+    <CollapsibleRoot {...args} maxW="560px">
+      <CollapsibleTrigger>더 보기</CollapsibleTrigger>
+      <CollapsibleContent>
+        <Text>초대 메일은 7일 뒤에 만료됩니다.</Text>
+      </CollapsibleContent>
+    </CollapsibleRoot>
+  ),
+};
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'border.subtle',
+          use: (
+            <T
+              en="Root border, trigger bottom border"
+              ko="루트 테두리, 트리거 아래 테두리"
+            />
+          ),
+        },
+        { token: 'bg.subtle', use: <T en="Trigger hover" ko="트리거 호버" /> },
+      ]}
+    />
+  ),
+};

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