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

package/src/components/Shake/Shake.usage.mdx

@@ -0,0 +1,107 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as ShakeStories from './Shake.stories';
+
+<Meta of={ShakeStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Shake
+
+Shakes its content once each time `trigger` changes: the "no, not that"
+gesture for a rejected answer, an invalid field or a refused action.
+
+</En>
+
+<Ko>
+
+# Shake
+
+`trigger`가 바뀔 때마다 내용을 한 번 좌우로 흔듭니다. 틀린 답, 잘못 입력한 칸, 거절된
+동작에 "그건 아니에요"라고 답하는 몸짓입니다.
+
+</Ko>
+
+<Canvas of={ShakeStories.Default} />
+
+<En>
+
+## When to use
+
+- A wrong answer in a quiz or a choice list, with the option row itself
+  shaking (`display="block"` and `w="100%"` keep a full-width row full width).
+- A submit that was refused because a field is invalid, shaking that field.
+
+## When not to use
+
+- The change is good news or plain emphasis → `Pulse`. A shake used as
+  emphasis reads as an error the reader then goes looking for.
+- As the only error signal → never. Pair it with colour, an icon and words.
+- On the first render → it never shakes then; show the error state instead.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` the shake is removed entirely, so for
+  some readers nothing moves at all. The refusal must be readable without it:
+  describe the error in text (WCAG 3.3.1) and do not rely on colour alone
+  (WCAG 1.4.1). The **동작 줄이기에서 남는 것** story shows both columns.
+- Replaying does not remount the children, so the keyboard focus of the person
+  who was just told no stays where it was.
+- Shake adds one `div` (`display: inline-flex`) around `children`. Inside a
+  `<button>` pass `as="span"` (ACCESSIBILITY.md §5).
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 퀴즈나 선택지 목록에서 틀린 답을 골랐을 때 그 선택지 행을 흔듭니다. 가로로 꽉 찬
+  행이라면 `display="block"`과 `w="100%"`를 넘겨 너비를 유지합니다.
+- 입력란이 잘못되어 제출이 거절됐을 때 그 입력란을 흔듭니다.
+
+## 언제 쓰지 않나요
+
+- 좋은 소식이거나 단순한 강조라면 `Pulse`를 씁니다. 강조하려고 흔들면 사용자는
+  오류로 읽고 무엇이 잘못됐는지 찾아 나섭니다.
+- 오류를 알리는 유일한 신호로는 쓰지 않습니다. 색, 아이콘, 문구와 함께 씁니다.
+- 첫 렌더에서는 흔들리지 않습니다. 처음부터 오류 상태라면 그 상태를 그대로 보여 줍니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 흔들림을 아예 빼므로, 어떤 사용자에게는 아무것도
+  움직이지 않습니다. 흔들림 없이도 거절이 읽혀야 합니다. 오류를 문구로 설명하고
+  (WCAG 3.3.1) 색에만 기대지 않습니다(WCAG 1.4.1). **동작 줄이기에서 남는 것**
+  스토리에서 두 경우를 나란히 볼 수 있습니다.
+- 다시 재생할 때 자식을 새로 마운트하지 않으므로, 방금 거절당한 사람의 키보드 초점이
+  제자리에 남습니다.
+- Shake는 `children` 바깥에 `div`(`display: inline-flex`)를 하나 더합니다. `<button>`
+  안에서는 `as="span"`을 넘깁니다(ACCESSIBILITY.md 5절).
+
+</Ko>
+
+<Canvas of={ShakeStories.ReducedMotion} />
+
+<En>
+
+## Props
+
+Any changing value works as `trigger`: an attempt counter, a verdict, a
+timestamp. Two rejections of the same answer are two shakes if the counter
+moves.
+
+</En>
+
+<Ko>
+
+## 속성
+
+`trigger`에는 바뀌는 값이면 무엇이든 넣을 수 있습니다. 시도 횟수, 판정 결과,
+타임스탬프 모두 됩니다. 같은 답을 두 번 틀려도 카운터가 올라가면 두 번 흔들립니다.
+
+</Ko>
+
+<ArgTypes of={ShakeStories} include={['trigger', 'distance']} />

package/src/components/Slider/Slider.stories.tsx

@@ -9,6 +9,11 @@ import {
   SliderThumbs,
   SliderTrack,
 } from '@/components/Slider';
+import { Flex } from '@chakra-ui/react';
+
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Text } from '../Typography';
 
 const meta = {
   title: 'Components/Slider',
@@ -277,3 +282,114 @@ export const Sizes: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Slider.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoValueBeside: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a name and the value beside it',
+  render: () => {
+    const [value, setValue] = useState([70]);
+    return (
+      <Flex align="center" gap={4} maxW="420px">
+        <Text id="usage-volume" fontWeight="semibold" minW="48px">
+          음량
+        </Text>
+        <Slider
+          flex={1}
+          ariaLabel="음량"
+          value={value}
+          min={0}
+          max={100}
+          onValueChange={(d) => setValue(d.value)}
+        >
+          <SliderTrack>
+            <SliderFilledTrack />
+          </SliderTrack>
+          <SliderThumb />
+        </Slider>
+        <Text minW="40px" textAlign="end">
+          {value[0]}%
+        </Text>
+      </Flex>
+    );
+  },
+};
+
+export const DontExactNumber: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a slider for an exact number",
+  render: () => {
+    const [value, setValue] = useState([1250]);
+    return (
+      <Flex align="center" gap={4} maxW="420px">
+        <Text fontWeight="semibold">월 한도</Text>
+        <Slider
+          flex={1}
+          ariaLabel="월 한도"
+          value={value}
+          min={0}
+          max={100000}
+          onValueChange={(d) => setValue(d.value)}
+        >
+          <SliderTrack>
+            <SliderFilledTrack />
+          </SliderTrack>
+          <SliderThumb />
+        </Slider>
+      </Flex>
+    );
+  },
+};
+
+/** Tokens the slider parts read, as written in their `.tsx` files. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'bg.track',
+          use: <T en="Empty rail (SliderTrack)" ko="빈 레일(SliderTrack)" />,
+        },
+        {
+          token: 'primary.main',
+          use: (
+            <T
+              en="Filled rail and thumb border"
+              ko="채운 레일과 손잡이 테두리"
+            />
+          ),
+        },
+        { token: 'bg.canvas', use: <T en="Thumb centre" ko="손잡이 가운데" /> },
+        {
+          token: 'bg.muted',
+          use: (
+            <T
+              en="Disabled thumb and filled rail"
+              ko="비활성 손잡이와 채운 레일"
+            />
+          ),
+        },
+        {
+          token: 'border.default',
+          use: <T en="Disabled thumb border" ko="비활성 손잡이 테두리" />,
+        },
+        {
+          token: 'focus.ring',
+          use: (
+            <T
+              en="Keyboard focus ring on the thumb"
+              ko="손잡이의 키보드 초점 링"
+            />
+          ),
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Slider/Slider.usage.mdx

@@ -0,0 +1,179 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SliderStories from './Slider.stories';
+
+<Meta of={SliderStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Slider
+
+A thumb the user drags along a rail to set a value, or two thumbs for a range,
+when the position matters more than the exact number.
+
+## When to use
+
+- Seeking in audio or video, setting a volume.
+- A value the user tunes by feel and sees the effect of right away, with the
+  number shown beside it.
+
+## When not to use
+
+- An exact number (a credit limit, a count) → `Input` with `type="number"`.
+- A choice between a few named levels → `Radio` or `SegmentedControl`.
+- Showing progress the user cannot change → `ProgressBar`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# Slider
+
+레일 위의 손잡이를 끌어 값을 정합니다. 손잡이 두 개로 범위도 정할 수 있습니다. 정확한
+숫자보다 위치가 중요할 때 씁니다.
+
+## 언제 쓰나요
+
+- 오디오나 영상의 재생 위치 이동, 음량 조절.
+- 감으로 맞추면서 결과를 바로 확인하는 값. 숫자는 옆에 함께 보여 줍니다.
+
+## 언제 쓰지 않나요
+
+- 크레딧 한도나 개수처럼 정확한 숫자는 `type="number"`인 `Input`을 씁니다.
+- 이름 붙은 몇 단계 중 하나를 고를 때는 `Radio`나 `SegmentedControl`을 씁니다.
+- 사용자가 바꿀 수 없는 진행 상황은 `ProgressBar`를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={SliderStories}
+  include={['value', 'defaultValue', 'onValueChange', 'ariaLabel']}
+/>
+
+<En>
+
+Values are arrays: `[50]` for one thumb, `[20, 80]` for a range. Compose
+`SliderTrack` > `SliderFilledTrack` and one `SliderThumb` per value (with
+`index`), or `SliderThumbs` to render one per value automatically. Children
+are wrapped in `SliderControl` for you. `min`, `max`, `step`, `disabled` and
+`onValueChangeEnd` come from Chakra's `Slider.Root`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+값은 배열입니다. 손잡이 하나는 `[50]`, 범위는 `[20, 80]`입니다. `SliderTrack` 안에
+`SliderFilledTrack`을 두고, 값마다 `SliderThumb`를 하나씩(`index`와 함께) 두거나
+`SliderThumbs`로 값 개수만큼 자동으로 그립니다. 자식은 `SliderControl`로 알아서
+감쌉니다. `min`, `max`, `step`, `disabled`, `onValueChangeEnd`는 Chakra
+`Slider.Root`의 속성입니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SliderStories.DoValueBeside} />
+<Verdict
+  kind="do"
+  en="Show the name and the current value beside the slider, and pass the name as ariaLabel."
+  ko="슬라이더 옆에 이름과 현재 값을 보여 주고, 이름은 ariaLabel로도 넘깁니다."
+/>
+
+<Canvas of={SliderStories.DontExactNumber} />
+<Verdict
+  kind="dont"
+  en="Ask for an exact number with a slider. One pixel covers dozens of values, and the user cannot see what they chose."
+  ko="정확한 숫자를 슬라이더로 받지 마세요. 1픽셀에 수십 개의 값이 걸리고, 무엇을 골랐는지도 보이지 않습니다."
+/>
+
+<En>
+
+## Content
+
+- Show the value with its unit (70%, 1:24) next to the rail, and update it
+  while dragging.
+- Label the ends when the meaning is not obvious (느리게 / 빠르게).
+
+## Accessibility
+
+What Slider does for you:
+
+- Each thumb is a `slider` with its value exposed. Arrow keys step, Page Up /
+  Page Down jump, Home / End go to the ends (Chakra / Zag) (WCAG 2.1.1).
+- The thumb shows the keyboard focus ring (WCAG 2.4.7). The empty rail is the
+  filled `bg.track`, which stays visible on sunken surfaces (WCAG 1.4.11).
+- With `ariaLabel` it renders a visually hidden label part, so the name is in
+  the server markup.
+
+What you still have to do:
+
+- **Pass `ariaLabel`, or compose a visible `Slider.Label`.** Without either
+  the thumb has no name: it points at a label part that does not exist
+  (`ACCESSIBILITY.md` §1; KWCAG 5.3.4.1 레이블 제공).
+- Dragging is not the only way: keyboard works, but give an `Input` as well
+  when people need an exact value (WCAG 2.5.7).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 레일 옆에 단위와 함께 값을 보여 주고(70%, 1:24), 끄는 동안 바로 바꿉니다.
+- 양 끝의 뜻이 분명하지 않다면 끝에 라벨을 붙입니다(느리게 / 빠르게).
+
+## 접근성
+
+Slider가 알아서 하는 일
+
+- 손잡이마다 값을 드러내는 `slider`입니다. 방향키로 한 단계씩, Page Up·Page Down으로
+  크게, Home·End로 끝까지 옮깁니다(Chakra와 Zag가 제공, WCAG 2.1.1).
+- 손잡이에 키보드 초점 링이 보입니다(WCAG 2.4.7). 빈 레일은 채워진 `bg.track`이라
+  움푹한 면 위에서도 보입니다(WCAG 1.4.11).
+- `ariaLabel`을 주면 시각적으로 숨긴 라벨 부품을 그리므로 이름이 서버 마크업 안에
+  있습니다.
+
+직접 챙겨야 하는 일
+
+- **`ariaLabel`을 넘기거나 보이는 `Slider.Label`을 조합합니다.** 둘 다 없으면 손잡이가
+  있지도 않은 라벨 부품을 가리켜서 이름이 없습니다(`ACCESSIBILITY.md` 1절, KWCAG
+  5.3.4.1 레이블 제공).
+- 끄는 것이 유일한 방법이 되지 않게 합니다. 키보드로도 움직일 수 있지만, 정확한 값이
+  필요한 사람을 위해 `Input`도 함께 둡니다(WCAG 2.5.7).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SliderStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Input**: exact numbers.
+- **ProgressBar**: progress the user cannot change.
+- **SegmentedControl**: a few named levels.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Input**: 정확한 숫자.
+- **ProgressBar**: 사용자가 바꿀 수 없는 진행 상황.
+- **SegmentedControl**: 이름 붙은 몇 단계.
+
+</Ko>

package/src/components/Spinner/Spinner.stories.tsx

@@ -1,5 +1,10 @@
+import { HStack } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { Subtext } from '../Typography';
 import { Spinner } from './Spinner';
 
 const meta = {
@@ -14,3 +19,62 @@ type Story = StoryObj<typeof meta>;
 export const Default: Story = {
   args: {},
 };
+
+export const Sizes: Story = {
+  render: () => (
+    <HStack gap={4}>
+      <Spinner size="xs" />
+      <Spinner size="sm" />
+      <Spinner size="md" />
+      <Spinner size="lg" />
+    </HStack>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Spinner.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`).
+
+export const DoSpinnerWithStatus: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: spinner and words in a status',
+  render: () => (
+    <HStack gap={2} role="status">
+      <Spinner size="sm" />
+      <Subtext>파일을 불러오는 중</Subtext>
+    </HStack>
+  ),
+};
+
+export const DoButtonLoading: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a busy button uses its own loading state',
+  render: () => (
+    <Button variant="primary" loading loadingText="저장 중">
+      저장
+    </Button>
+  ),
+};
+
+/** Tokens the spinner reads, from `Spinner.tsx` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: 'primary.main',
+          use: <T en="turning arc (default colour)" ko="도는 호(기본 색)" />,
+        },
+        {
+          token: 'bg.track',
+          use: <T en="track ring" ko="트랙 고리" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/Spinner/Spinner.usage.mdx

@@ -0,0 +1,136 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SpinnerStories from './Spinner.stories';
+
+<Meta of={SpinnerStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Spinner
+
+A small turning ring that says "still working" when the wait is short and its
+length is unknown.
+
+## When to use
+
+- Inline, next to the words that say what is loading: a list row, a menu, a
+  file being read.
+- Inside a custom control that has no loading state of its own.
+
+## When not to use
+
+- A busy button → the button's `loading` prop (Chakra draws the spinner and
+  disables the button).
+- A whole region or page → `SectionLoader` or `PageLoader`, which also
+  announce themselves.
+- The AI is working → `ThinkingDots` or the loaders' `thinking` variant.
+- Work with a known length → `ProgressBar`.
+
+## How it works
+
+- Chakra's `Spinner` with `color="primary.main"` and the `bg.track` ring.
+  `size` takes Chakra's `xs` to `xl`; `color` can be overridden with a token.
+- It turns at a constant rate. Under `prefers-reduced-motion` it keeps turning
+  at about a third of the speed, because a frozen spinner reads as a hung
+  request.
+
+## Do
+
+</En>
+
+<Ko>
+
+# Spinner
+
+대기가 짧고 얼마나 걸릴지 모를 때 "아직 처리 중"이라고 알려 주는 작은 회전 고리입니다.
+
+## 언제 쓰나요
+
+- 무엇을 불러오는지 알려 주는 글자 옆에 작게 둘 때: 목록 행, 메뉴, 읽는 중인 파일.
+- 로딩 상태를 따로 갖지 않은 직접 만든 컨트롤 안에 둘 때.
+
+## 언제 쓰지 않나요
+
+- 작업 중인 버튼은 그 버튼의 `loading` 속성을 씁니다(Chakra가 스피너를 그리고 버튼을
+  비활성으로 만듭니다).
+- 영역이나 페이지 전체는 `SectionLoader`나 `PageLoader`를 씁니다. 이 둘은 스스로 상태를
+  알립니다.
+- AI가 일하는 동안에는 `ThinkingDots`나 로더의 `thinking` 변형을 씁니다.
+- 길이를 아는 작업은 `ProgressBar`를 씁니다.
+
+## 동작 방식
+
+- `color="primary.main"`과 `bg.track` 고리를 쓴 Chakra `Spinner`입니다. `size`는
+  Chakra의 `xs`부터 `xl`까지 받으며, `color`는 토큰으로 바꿀 수 있습니다.
+- 일정한 속도로 돕니다. `prefers-reduced-motion`에서는 멈추지 않고 약 3분의 1 속도로
+  돕니다. 멈춘 스피너는 요청이 멈춘 것처럼 보이기 때문입니다.
+
+## 이렇게 하세요
+
+</Ko>
+
+<Canvas of={SpinnerStories.DoSpinnerWithStatus} />
+<Verdict
+  kind="do"
+  en='Put the spinner next to words that say what is loading, inside a role="status" element. The spinner itself is a plain span with no name.'
+  ko='스피너는 무엇을 불러오는지 알려 주는 글자 옆에 두고, 둘을 role="status" 요소로 감쌉니다. 스피너 자체는 이름 없는 span일 뿐입니다.'
+/>
+
+<Canvas of={SpinnerStories.DoButtonLoading} />
+<Verdict
+  kind="do"
+  en="For a busy button, use the button's loading state instead of placing a Spinner inside it."
+  ko="작업 중인 버튼에는 Spinner를 직접 넣지 말고 버튼의 loading 상태를 씁니다."
+/>
+
+<En>
+
+## Accessibility
+
+- **Spinner has no role and no accessible name.** On its own it says nothing
+  to a screen reader. Pair it with visible text and wrap both in
+  `role="status"` so the change is announced (WCAG 4.1.3, 1.1.1).
+- The `bg.track` ring is there so the spinner stays visible on any background
+  (WCAG 1.4.11).
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- **Spinner에는 역할도 접근 가능한 이름도 없습니다.** 혼자서는 화면 낭독기에 아무것도
+  알리지 않습니다. 눈에 보이는 글자와 함께 두고 둘을 `role="status"`로 감싸서 변화가
+  읽히게 합니다(WCAG 4.1.3, 1.1.1).
+- `bg.track` 고리 덕분에 어떤 배경 위에서도 스피너가 보입니다(WCAG 1.4.11).
+
+## 토큰
+
+</Ko>
+
+<Canvas of={SpinnerStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Loaders**: `PageLoader`, `SectionLoader`, `ThinkingDots`.
+- **ProgressBar**: work whose length is known.
+- **Button**: `loading`.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Loaders**: `PageLoader`, `SectionLoader`, `ThinkingDots`.
+- **ProgressBar**: 길이를 아는 작업.
+- **Button**: `loading`.
+
+</Ko>