@mindlogic-ai/logician-ui 5.0.0-alpha.0 → 5.0.0-alpha.10

package/src/components/ProgressBar/ProgressBar.usage.mdx

@@ -0,0 +1,210 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as ProgressBarStories from './ProgressBar.stories';
+
+<Meta of={ProgressBarStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# ProgressBar
+
+A horizontal bar that shows how much of something is done or used: an upload,
+a completion rate, a budget.
+
+## When to use
+
+- A job with a known length: files uploaded, steps finished.
+- A share of a limit: credits used this month, a completion rate in a table
+  row.
+- `indeterminate` only when there is no denominator yet, such as a sync whose
+  size is not known.
+
+## When not to use
+
+- Several parts of one whole (sent, failed, remaining) → `SegmentedProgressBar`.
+- A share split into categories, shown as a ring → `RadialProgress`.
+- A short wait with no length → `Spinner`. An indeterminate bar says only
+  "something is happening", which a spinner says in less space.
+- A value the reader sets → `Slider`.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# ProgressBar
+
+업로드, 완료율, 예산처럼 얼마나 끝났는지 또는 얼마나 썼는지 보여 주는 가로 막대입니다.
+
+## 언제 쓰나요
+
+- 길이를 아는 작업: 올린 파일 수, 끝난 단계 수.
+- 한도 중 쓴 비율: 이번 달 쓴 크레딧, 표의 행마다 보이는 완료율.
+- `indeterminate`는 동기화처럼 전체 크기를 아직 모를 때만 씁니다.
+
+## 언제 쓰지 않나요
+
+- 한 전체를 이루는 여러 부분(보냄, 실패, 남음)은 `SegmentedProgressBar`를 씁니다.
+- 분류별로 나눈 비율을 고리로 보여 줄 때는 `RadialProgress`를 씁니다.
+- 길이를 모르는 짧은 대기는 `Spinner`를 씁니다. 진행률을 모르는 막대는 "무언가 처리
+  중"이라는 말만 하는데, 스피너는 같은 말을 더 작은 자리에서 합니다.
+- 사용자가 값을 정한다면 `Slider`를 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={ProgressBarStories} include={['value', 'size', 'indeterminate', 'filledTrackColor']} />
+
+<En>
+
+| Prop | Means | Notes |
+| --- | --- | --- |
+| `value` | Percentage done, 0–100 by default | Change `max` (Chakra) for another scale |
+| `size` | `xs` 4px · `sm` 8px · `md` 16px (default) · `lg` 24px · `xl` 32px | `xs`/`sm` in table rows and cards |
+| `filledTrackColor` | Fill colour, default `primary.main` | `danger.solid` only when the value means a problem (over a limit) |
+| `indeterminate` | Length unknown; a block slides across | `value` is ignored |
+
+The fill moves with the house `travel` motion, so an update reads as the bar
+catching up. Under `prefers-reduced-motion` the indeterminate block stops
+sliding.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 뜻 | 참고 |
+| --- | --- | --- |
+| `value` | 끝난 비율, 기본 0–100 | 다른 단위라면 Chakra의 `max`를 바꿉니다 |
+| `size` | `xs` 4px · `sm` 8px · `md` 16px(기본) · `lg` 24px · `xl` 32px | 표의 행과 카드에서는 `xs`/`sm` |
+| `filledTrackColor` | 채움 색, 기본 `primary.main` | 값이 문제를 뜻할 때(한도 초과)만 `danger.solid` |
+| `indeterminate` | 길이를 모름. 막대 조각이 가로질러 움직임 | `value`는 무시됨 |
+
+채움은 공통 `travel` 모션으로 움직여서, 값이 바뀌면 막대가 따라잡는 것처럼 보입니다.
+`prefers-reduced-motion`에서는 indeterminate 조각이 움직이지 않습니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={ProgressBarStories.DoLabelAndNumber} />
+<Verdict
+  kind="do"
+  en="Say what is being measured and give the number in words. The bar is the picture; the text is the information."
+  ko="무엇을 재는지 쓰고 숫자를 글자로 보여 줍니다. 막대는 그림이고, 정보는 글자가 전합니다."
+/>
+
+<Canvas of={ProgressBarStories.DontBareBar} />
+<Verdict
+  kind="dont"
+  en="Show a bar with nothing next to it. Sighted readers guess; screen readers hear only '60%'."
+  ko="옆에 아무것도 없는 막대만 두지 마세요. 보는 사람은 짐작해야 하고, 화면 낭독기 사용자는 '60%'만 듣습니다."
+/>
+
+<Canvas of={ProgressBarStories.DoDangerWhenOver} />
+<Verdict
+  kind="do"
+  en="Switch the fill to danger.solid when the value is a problem, and say so in words (WCAG 1.4.1)."
+  ko="값이 문제를 뜻할 때는 채움을 danger.solid로 바꾸고, 그 사실을 글자로도 씁니다(WCAG 1.4.1)."
+/>
+
+<Canvas of={ProgressBarStories.DoIndeterminateWithHint} />
+<Verdict
+  kind="do"
+  en="With an indeterminate bar, add a line that says what is happening and roughly how long it may take."
+  ko="indeterminate 막대에는 무슨 일이 일어나는지, 대략 얼마나 걸릴지 알려 주는 한 줄을 붙입니다."
+/>
+
+<En>
+
+## Content
+
+- Label: what is measured, as a noun phrase (문서 업로드, 이번 달 크레딧).
+- Number: the form the reader thinks in, such as 3 / 5 or 112%, next to the
+  label.
+- When the bar is full, replace it with the result if the result matters
+  (업로드 완료).
+
+## Accessibility
+
+What ProgressBar does for you:
+
+- The track is `role="progressbar"` with `aria-valuemin`, `aria-valuemax` and
+  `aria-valuenow`; indeterminate leaves out `aria-valuenow` (WCAG 4.1.2).
+
+What you still have to do:
+
+- **The bar's accessible name is its percentage**, such as "60%". Chakra puts
+  that `aria-label` on the track, and props you pass to `ProgressBar` land on
+  the wrapper, so an `aria-label` of yours does not reach it. Put the label and
+  the number in visible text next to the bar (WCAG 1.3.1).
+- Progress changes are not announced. For a long job, announce the milestones
+  that matter (started, finished, failed) in a `role="status"` region, as
+  FactChat does with `aria-live="polite"` on the row (WCAG 4.1.3).
+- The `bg.track` track and the fill are drawn so the bar reads on any
+  background (WCAG 1.4.11). A custom `filledTrackColor` has to keep that.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨: 무엇을 재는지 명사구로 씁니다(문서 업로드, 이번 달 크레딧).
+- 숫자: 사용자가 생각하는 형태(3 / 5, 112%)로 라벨 옆에 씁니다.
+- 결과가 중요하다면, 막대가 다 차면 막대 대신 결과를 보여 줍니다(업로드 완료).
+
+## 접근성
+
+ProgressBar가 알아서 하는 일
+
+- 트랙에 `role="progressbar"`와 `aria-valuemin`, `aria-valuemax`, `aria-valuenow`가
+  붙습니다. indeterminate일 때는 `aria-valuenow`가 빠집니다(WCAG 4.1.2).
+
+직접 챙겨야 하는 일
+
+- **막대의 접근 가능한 이름은 "60%" 같은 비율입니다.** Chakra가 그 `aria-label`을
+  트랙에 붙이고, `ProgressBar`에 넘긴 속성은 바깥 요소로 가기 때문에 직접 넘긴
+  `aria-label`은 트랙에 닿지 않습니다. 라벨과 숫자는 막대 옆에 눈에 보이는 글자로
+  씁니다(WCAG 1.3.1).
+- 진행률이 바뀌어도 알려 주지 않습니다. 오래 걸리는 작업이라면 시작, 완료, 실패처럼
+  중요한 순간을 `role="status"` 영역으로 알립니다. FactChat은 행에
+  `aria-live="polite"`를 붙여 이렇게 합니다(WCAG 4.1.3).
+- `bg.track` 트랙과 채움은 어떤 배경에서도 막대가 보이도록 정해져 있습니다(WCAG
+  1.4.11). `filledTrackColor`를 바꾼다면 이 점을 지켜야 합니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={ProgressBarStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **SegmentedProgressBar**: several parts of one whole.
+- **RadialProgress**: a share split into categories, as a ring.
+- **Spinner** / **Loaders**: a wait with no length.
+- **Slider**: a value the reader sets.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **SegmentedProgressBar**: 한 전체를 이루는 여러 부분.
+- **RadialProgress**: 분류별로 나눈 비율을 고리로.
+- **Spinner** / **Loaders**: 길이를 모르는 대기.
+- **Slider**: 사용자가 정하는 값.
+
+</Ko>

package/src/components/Pulse/Pulse.usage.mdx

@@ -0,0 +1,102 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as PulseStories from './Pulse.stories';
+
+<Meta of={PulseStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Pulse
+
+Pops its content once each time `trigger` changes, to draw the eye to a value
+that just updated for the better.
+
+</En>
+
+<Ko>
+
+# Pulse
+
+`trigger`가 바뀔 때마다 내용을 한 번 톡 튀게 해서, 방금 좋아진 값으로 시선을 끕니다.
+
+</Ko>
+
+<Canvas of={PulseStories.Default} />
+
+<En>
+
+## When to use
+
+- A count or balance that just grew: missions finished, credits added.
+- A step indicator that just filled, or a level card when the level changes.
+- A badge or chip that just landed, for example at the end of a `FlyTo`.
+
+## When not to use
+
+- The change is a refusal or an error → `Shake`. The pair must stay apart: a
+  pulse reads as "good, look here", a shake as "no".
+- The element is appearing for the first time → `Appear`. Pulse never plays on
+  the first render, so a value that is already set on mount stays still.
+- The number itself should be seen changing → `CountUp` (it can sit inside a
+  Pulse).
+- Values that update continuously (a timer, live progress) → no Pulse. It
+  would play on every tick.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` the pop is removed outright. The value
+  has already changed by then; only the emphasis is lost.
+- Replaying does not remount the children, so keyboard focus and input state
+  inside the Pulse are kept.
+- The pop is not announced. If the change matters to someone who cannot see
+  it, announce the new value yourself (WCAG 4.1.3).
+- Pulse adds one `div` (`display: inline-flex`) around `children`. Inside a
+  `<button>` pass `as="span"` (ACCESSIBILITY.md §5).
+
+## Props
+
+Any changing value works as `trigger`: a counter, an id, a timestamp. Going
+back to an earlier value (`0 → 1 → 0`) still pops.
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 개수나 잔액이 방금 늘었을 때: 완료한 미션 수, 추가된 크레딧.
+- 단계 표시가 방금 채워졌거나, 레벨이 바뀌어 레벨 카드가 달라졌을 때.
+- 배지나 칩이 방금 도착했을 때. 예를 들어 `FlyTo`가 끝나는 자리입니다.
+
+## 언제 쓰지 않나요
+
+- 거절이나 오류를 알리는 변화라면 `Shake`를 씁니다. 둘은 섞으면 안 됩니다. Pulse는
+  "좋아요, 여기 보세요"로, Shake는 "아니요"로 읽힙니다.
+- 요소가 처음 나타나는 것이라면 `Appear`를 씁니다. Pulse는 첫 렌더에서 재생되지 않으므로,
+  마운트할 때 이미 정해진 값은 움직이지 않습니다.
+- 숫자가 바뀌는 과정 자체를 보여 줘야 한다면 `CountUp`을 씁니다(Pulse 안에 넣어도 됩니다).
+- 타이머나 실시간 진행률처럼 계속 바뀌는 값에는 Pulse를 쓰지 않습니다. 바뀔 때마다
+  튀게 됩니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 튀는 효과를 아예 뺍니다. 값은 이미 바뀌었으니
+  잃는 것은 강조뿐입니다.
+- 다시 재생할 때 자식을 새로 마운트하지 않으므로, Pulse 안의 키보드 초점과 입력 상태가
+  그대로 유지됩니다.
+- 튀는 효과는 읽어 주지 않습니다. 보지 못하는 사람에게도 중요한 변화라면 새 값을 직접
+  알립니다(WCAG 4.1.3).
+- Pulse는 `children` 바깥에 `div`(`display: inline-flex`)를 하나 더합니다. `<button>`
+  안에서는 `as="span"`을 넘깁니다(ACCESSIBILITY.md 5절).
+
+## 속성
+
+`trigger`에는 바뀌는 값이면 무엇이든 넣을 수 있습니다. 카운터, id, 타임스탬프 모두
+됩니다. 이전 값으로 돌아가도(`0 → 1 → 0`) 다시 튑니다.
+
+</Ko>
+
+<ArgTypes of={PulseStories} include={['trigger', 'peak']} />

package/src/components/RadialProgress/RadialProgress.stories.tsx

@@ -1,6 +1,9 @@
-import { Box } from '@chakra-ui/react';
+import { Box, Flex, HStack, Stack } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Subtext, Text } from '../Typography';
 import RadialProgress from './RadialProgress';
 
 const meta = {
@@ -271,3 +274,73 @@ export const EmptySegments: Story = {
     },
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `RadialProgress.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`); `tags` is written on each story because the indexer
+// reads CSF statically.
+
+const STORAGE = [
+  { label: '문서', color: 'category.blue.fg', value: 42 },
+  { label: '이미지', color: 'category.purple.fg', value: 28 },
+  { label: '오디오', color: 'category.orange.fg', value: 12 },
+];
+
+export const DoTokensAndLegend: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: category tokens and a text legend',
+  render: () => (
+    <Flex gap={6} align="center" wrap="wrap">
+      <RadialProgress
+        size={160}
+        total={100}
+        unit="GB"
+        segments={STORAGE.map(({ color, value }) => ({ color, value }))}
+        aria-hidden
+        width="auto"
+      />
+      <Stack gap={1}>
+        <Text fontWeight="bold">저장 공간 100GB 중 82GB 사용</Text>
+        {STORAGE.map(({ label, color, value }) => (
+          <HStack key={label} gap={2}>
+            <Box boxSize="10px" borderRadius="full" bg={color} />
+            <Subtext>
+              {label} {value}GB
+            </Subtext>
+          </HStack>
+        ))}
+      </Stack>
+    </Flex>
+  ),
+};
+
+export const DontHexNoLegend: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: hex colours and no legend",
+  args: {
+    size: 160,
+    total: 100,
+    unit: 'GB',
+    segments: [
+      { color: '#4ECDC4', value: 42 },
+      { color: '#FF6B6B', value: 28 },
+      { color: '#FFD93D', value: 12 },
+    ],
+  },
+};
+
+/** Tokens the chart reads besides its segments, from `RadialProgress.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.track', use: <T en="remaining arc" ko="남은 부분의 호" /> },
+        { token: 'bg.surface', use: <T en="background" ko="배경" /> },
+        { token: 'fg.subtle', use: <T en="centre number" ko="가운데 숫자" /> },
+        { token: 'bg.muted', use: <T en="shadow under the ring" ko="고리 아래 그림자" /> },
+      ]}
+    />
+  ),
+};

package/src/components/RadialProgress/RadialProgress.types.ts

@@ -1,16 +1,36 @@
 import { BoxProps } from '@chakra-ui/react';
 
 export interface Segment {
-  /** Color value - supports hex colors, CSS color names, and Chakra UI color tokens (e.g., 'primary.main', 'danger.solid') */
+  /**
+   * Colour token for the arc. Categories take `category.{hue}.fg`; a status
+   * colour (`danger.solid`, …) only when the segment means that status. Hex and
+   * CSS colour names still render but skip the theme (no dark mode).
+   */
   color: string;
+  /** Amount, in the same unit as `total`. */
   value: number;
 }
 
 export interface RadialProgressProps extends BoxProps {
+  /**
+   * Diameter in px; stroke, gaps and the centre text scale with it.
+   * @default 200
+   */
   size?: number;
+  /**
+   * The whole the segments are parts of, also shown as the centre number.
+   * Nothing renders when it is 0 or less.
+   * @default 100
+   */
   total?: number;
+  /** Unit after the centre number, e.g. `GB`. */
   unit?: string;
+  /**
+   * Arcs in order, clockwise from the top. Whatever `total` leaves over is
+   * drawn as a `bg.track` arc.
+   */
   segments?: Segment[];
+  /** Formats the centre number, e.g. thousands separators. */
   formatTotal?: (value: number) => string | number;
 }
 

package/src/components/RadialProgress/RadialProgress.usage.mdx

@@ -0,0 +1,153 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as RadialProgressStories from './RadialProgress.stories';
+
+<Meta of={RadialProgressStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# RadialProgress
+
+A ring split into coloured arcs that shows how a total is used, category by
+category, with the total in the middle.
+
+## When to use
+
+- A share of one total split into a few categories: storage by file type,
+  a budget by team.
+- A summary tile where a ring reads faster than a table.
+
+## When not to use
+
+- One value against a limit → `ProgressBar`.
+- Parts of a job in progress (sent, failed, remaining) → `SegmentedProgressBar`.
+- More than five or six categories, or values the reader must compare
+  precisely → a bar chart or a table.
+
+## Props
+
+</En>
+
+<Ko>
+
+# RadialProgress
+
+전체가 분류별로 어떻게 쓰였는지 색이 다른 호로 나눠 보여 주고, 가운데에 전체 값을
+적는 고리입니다.
+
+## 언제 쓰나요
+
+- 하나의 전체를 몇 가지 분류로 나눈 비율: 파일 종류별 저장 공간, 팀별 예산.
+- 표보다 고리가 더 빨리 읽히는 요약 카드.
+
+## 언제 쓰지 않나요
+
+- 한도에 대한 값 하나는 `ProgressBar`를 씁니다.
+- 진행 중인 작업의 부분(보냄, 실패, 남음)은 `SegmentedProgressBar`를 씁니다.
+- 분류가 대여섯 개를 넘거나 값을 정확히 비교해야 한다면 막대그래프나 표를 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes of={RadialProgressStories} include={['segments', 'total', 'unit', 'size', 'formatTotal']} />
+
+<En>
+
+- The centre shows `total` (through `formatTotal` if given) and `unit`, not
+  the used amount. Put "82GB used" in text next to the ring.
+- Segments are drawn clockwise from the top with a gap between arcs. Whatever
+  `total` leaves over is a `bg.track` arc.
+- RadialProgress is a default export re-exported as
+  `import { RadialProgress } from '@mindlogic-ai/logician-ui'`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- 가운데에는 쓴 양이 아니라 `total`(`formatTotal`이 있으면 그 결과)과 `unit`이
+  보입니다. "82GB 사용" 같은 문구는 고리 옆에 글자로 씁니다.
+- 세그먼트는 위쪽에서 시작해 시계 방향으로, 호 사이에 틈을 두고 그려집니다. `total`에서
+  남은 부분은 `bg.track` 호로 그려집니다.
+- 기본 내보내기이며, `import { RadialProgress } from '@mindlogic-ai/logician-ui'`로
+  가져옵니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={RadialProgressStories.DoTokensAndLegend} />
+<Verdict
+  kind="do"
+  en="Colour segments with category.{hue}.fg tokens and add a text legend with each value. Mark the ring aria-hidden when the legend says everything."
+  ko="세그먼트 색은 category.{hue}.fg 토큰으로 정하고, 값을 함께 적은 글자 범례를 붙입니다. 범례가 모든 정보를 전한다면 고리에는 aria-hidden을 붙입니다."
+/>
+
+<Canvas of={RadialProgressStories.DontHexNoLegend} />
+<Verdict
+  kind="dont"
+  en="Pass hex colours and leave out the legend. Hex skips the theme, so dark mode keeps light-mode colours, and without a legend nobody knows what each arc is."
+  ko="16진수 색을 넘기고 범례를 빼지 마세요. 16진수는 테마를 거치지 않아 다크 모드에서도 라이트 모드 색이 그대로 남고, 범례가 없으면 각 호가 무엇인지 아무도 모릅니다."
+/>
+
+<En>
+
+## Accessibility
+
+- **RadialProgress exposes nothing to assistive tech except the centre
+  number.** The SVG has no role, title or description, and the arcs have no
+  names. Give the same information in text (a legend, a sentence) next to it
+  (WCAG 1.1.1, 1.3.1).
+- **Words, not colour alone** (WCAG 1.4.1). The legend names each category;
+  the colours only connect legend and arc.
+- Status colours mean status: use `danger.solid` for a segment only when that
+  segment is a problem, such as an overrun.
+
+## Tokens
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- **RadialProgress는 가운데 숫자 말고는 보조 기술에 아무것도 알리지 않습니다.** SVG에는
+  역할, 제목, 설명이 없고 호에도 이름이 없습니다. 같은 정보를 범례나 문장 같은 글자로
+  옆에 씁니다(WCAG 1.1.1, 1.3.1).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1). 분류 이름은 범례가 알려 주고, 색은 범례와
+  호를 이어 줄 뿐입니다.
+- 상태색은 상태를 뜻합니다. 초과 사용처럼 그 세그먼트가 문제일 때만 `danger.solid`를
+  씁니다.
+
+## 토큰
+
+</Ko>
+
+<Canvas of={RadialProgressStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **ProgressBar**: one value against a limit.
+- **SegmentedProgressBar**: parts of one job, as a bar.
+- **LineGraph**: change over time.
+- **Foundations/Brand & colour usage**: category hues for categories.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **ProgressBar**: 한도에 대한 값 하나.
+- **SegmentedProgressBar**: 한 작업의 부분을 막대로.
+- **LineGraph**: 시간에 따른 변화.
+- **Foundations/Brand & colour usage**: 분류에는 category 색을 씁니다.
+
+</Ko>