@mindlogic-ai/logician-ui 5.0.0-alpha.2 → 5.0.0-alpha.21

package/src/components/SeeMoreButton/SeeMoreButton.types.ts

@@ -12,7 +12,15 @@ export type SeeMoreButtonOwnProps = Omit<
   ButtonOwnProps,
   'variant' | 'isDestructive'
 > & {
+  /**
+   * How many items the list shows now. Printed as the first number of
+   * `더보기 (currentCount/maxCount)`.
+   */
   currentCount: number;
+  /**
+   * How many items there are in total. The button does not disable or hide
+   * itself when `currentCount` reaches this; the caller does.
+   */
   maxCount: number;
 };
 

package/src/components/SeeMoreButton/SeeMoreButton.usage.mdx

@@ -0,0 +1,213 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SeeMoreButtonStories from './SeeMoreButton.stories';
+
+<Meta of={SeeMoreButtonStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SeeMoreButton
+
+A full-width button at the end of a list that shows more of the same list in
+place, and says how many are shown out of how many.
+
+## When to use
+
+- A list that grows where it is when the reader asks: reviews, recommended
+  questions, search results in a dropdown. In FactChat the store's reviews,
+  recommended questions and chatbot search use it.
+- When you know the total, so the count `(3/10)` is true.
+
+## When not to use
+
+- Opening the full list on another page → a link-shaped `Button`
+  (`as="a"`, `ghost`) such as 전체 보기, usually next to the section heading.
+- Paging through a long, numbered result set → `Pagination`.
+- Expanding one block of text → `ExpandableText`, which has its own
+  더보기 / 접기.
+- Showing more attached files → `FileList` already renders its own control.
+- You do not know the total → a `subtle` or `ghost` `Button` with your own
+  label, because SeeMoreButton always prints a count.
+
+## Props
+
+SeeMoreButton has no `variant`. It always renders the `ghost` Button recipe
+with a top hairline, takes the full width of its container, and accepts
+Button's other props (`onClick`, `disabled`, `loading`, `size` …).
+
+</En>
+
+<Ko>
+
+# SeeMoreButton
+
+목록 끝에 놓는 전체 너비 버튼입니다. 같은 목록을 그 자리에서 더 보여 주고, 전체 중
+몇 개를 보여 주는지 알려 줍니다.
+
+## 언제 쓰나요
+
+- 읽는 사람이 원할 때 그 자리에서 늘어나는 목록: 리뷰, 추천 질문, 드롭다운 안의 검색
+  결과. FactChat에서는 스토어의 리뷰, 추천 질문, 챗봇 검색에 씁니다.
+- 전체 개수를 알고 있어서 `(3/10)` 같은 개수가 사실일 때.
+
+## 언제 쓰지 않나요
+
+- 다른 화면에서 전체 목록을 연다면 링크 모양의 `Button`(`as="a"`, `ghost`)을 씁니다.
+  "전체 보기"처럼 쓰고, 보통 섹션 제목 옆에 둡니다.
+- 번호가 매겨진 긴 결과를 넘겨 본다면 `Pagination`을 씁니다.
+- 글 한 덩어리를 펼친다면 더보기 / 접기가 들어 있는 `ExpandableText`를 씁니다.
+- 첨부 파일을 더 보여 준다면 `FileList`가 자체 컨트롤을 그립니다.
+- 전체 개수를 모른다면 라벨을 직접 쓰는 `subtle`이나 `ghost` `Button`을 씁니다.
+  SeeMoreButton은 언제나 개수를 함께 표시하기 때문입니다.
+
+## 속성
+
+SeeMoreButton에는 `variant`가 없습니다. 언제나 위쪽 구분선을 더한 `ghost` Button
+레시피로 그려지고, 담긴 영역의 너비를 다 차지하며, Button의 나머지 속성(`onClick`,
+`disabled`, `loading`, `size` 등)을 받습니다.
+
+</Ko>
+
+<ArgTypes of={SeeMoreButtonStories} include={['currentCount', 'maxCount']} />
+
+<En>
+
+The component does not disable or hide itself when `currentCount` reaches
+`maxCount`; that is up to you (see Do / Don't).
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+`currentCount`가 `maxCount`에 닿아도 컴포넌트가 스스로 비활성이 되거나 사라지지
+않습니다. 그 처리는 호출하는 쪽에서 합니다(아래 예시 참고).
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SeeMoreButtonStories.DoGrowTheList} />
+<Verdict
+  kind="do"
+  en="Put it right under the list, let each click add items in place, and remove it once everything is shown. FactChat renders it only while there is a next page."
+  ko="목록 바로 아래에 두고, 누를 때마다 그 자리에 항목을 더하며, 모두 보여 준 뒤에는 버튼을 없앱니다. FactChat도 다음 페이지가 있을 때만 버튼을 그립니다."
+/>
+
+<Canvas of={SeeMoreButtonStories.DontNavigate} />
+<Verdict
+  kind="dont"
+  en="Use it to send the reader to a different page with all 128 reviews. It promises more of this list, here."
+  ko="리뷰 128개가 있는 다른 화면으로 보내는 데 쓰지 마세요. 이 버튼은 지금 이 목록을 이 자리에서 더 보여 주겠다는 뜻입니다."
+/>
+
+<Canvas of={SeeMoreButtonStories.DoLinkToFullPage} />
+<Verdict
+  kind="do"
+  en="To open the full list elsewhere, use a link-shaped ghost Button next to the heading."
+  ko="다른 화면에서 전체 목록을 연다면 제목 옆에 링크 모양의 ghost Button을 둡니다."
+/>
+
+<En>
+
+## Content
+
+- The label is fixed: `더보기 (currentCount/maxCount)` and a chevron.
+  Children are ignored. The text comes from the library's own `see_more`
+  string, which today always resolves to Korean, so an English screen still
+  shows 더보기.
+- Keep the numbers honest. `maxCount` is the real total; if the server only
+  tells you "there is more", use a `Button` instead.
+
+## Accessibility
+
+What SeeMoreButton does for you:
+
+- It is a Button: a native `<button>`, Tab and Enter / Space (WCAG 2.1.1), and
+  the keyboard focus ring (WCAG 2.4.7).
+- The count is part of the visible label, so the accessible name is
+  "더보기 (3/10)" and matches what is on screen (WCAG 2.5.3).
+
+What you still have to do:
+
+- **Keep the keyboard user's place.** When the last click removes the button,
+  focus would fall back to the page. Move focus to the first newly shown item
+  (WCAG 2.4.3).
+- **New items are not announced.** The component has no live region. If the
+  added items are not obvious from the focus move, announce the new count
+  yourself.
+- **Loading.** While the next page loads, pass `loading` with a
+  `loadingText` (불러오는 중) so the button cannot be pressed twice and still
+  has words. Without `loadingText` the label is hidden behind the spinner.
+
+## Tokens
+
+The table is generated from `SeeMoreButton.styles.ts` and the ghost Button
+recipe it renders.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨은 정해져 있습니다. `더보기 (currentCount/maxCount)`와 아래 화살표이며,
+  children은 무시됩니다. 문구는 라이브러리의 `see_more` 문자열에서 오는데 지금은
+  언제나 한국어로 풀리므로, 영어 화면에도 "더보기"가 나옵니다.
+- 숫자는 사실이어야 합니다. `maxCount`는 실제 전체 개수입니다. 서버가 "더 있다"는
+  것만 알려 준다면 `Button`을 씁니다.
+
+## 접근성
+
+SeeMoreButton이 알아서 하는 일
+
+- Button 그대로입니다. 기본 `<button>`이며 Tab, Enter와 Space로 다루고(WCAG 2.1.1),
+  키보드 초점 링을 그립니다(WCAG 2.4.7).
+- 개수가 보이는 라벨에 들어 있어서, 접근 가능한 이름이 화면에 보이는 그대로
+  "더보기 (3/10)"입니다(WCAG 2.5.3).
+
+직접 챙겨야 하는 일
+
+- **키보드 사용자의 위치를 지킵니다.** 마지막으로 눌렀을 때 버튼이 사라지면 초점이
+  페이지 처음으로 돌아갈 수 있습니다. 새로 나온 첫 항목으로 초점을 옮깁니다(WCAG
+  2.4.3).
+- **새 항목은 알려 주지 않습니다.** 컴포넌트에 라이브 영역이 없습니다. 초점을 옮기는
+  것만으로 새 항목이 분명하지 않다면 늘어난 개수를 직접 알립니다.
+- **불러오는 중.** 다음 페이지를 불러오는 동안 `loading`과 `loadingText`(불러오는 중)를
+  함께 주어 두 번 눌리지 않게 하고 글자도 남깁니다. `loadingText`가 없으면 라벨이
+  스피너 뒤로 숨습니다.
+
+## 토큰
+
+아래 표는 `SeeMoreButton.styles.ts`와 이 컴포넌트가 그리는 ghost Button 레시피에서
+자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={SeeMoreButtonStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Button**: a link-shaped `ghost` Button for 전체 보기, or your own label
+  when the total is unknown.
+- **Pagination**: numbered pages.
+- **ExpandableText**: 더보기 / 접기 for one block of text.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Button**: 전체 보기에 쓰는 링크 모양의 `ghost` Button, 또는 전체 개수를 모를 때
+  라벨을 직접 쓰는 버튼.
+- **Pagination**: 번호가 있는 페이지.
+- **ExpandableText**: 글 한 덩어리의 더보기 / 접기.
+
+</Ko>

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

@@ -3,6 +3,8 @@ import { Meta, StoryObj } from '@storybook/react';
 import React, { useState } from 'react';
 import { FiHome, FiSettings, FiUser } from 'react-icons/fi';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { SegmentedControl } from './SegmentedControl';
 
 const meta = {
@@ -202,3 +204,70 @@ export const WithCustomContent = {
     ],
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `SegmentedControl.usage.mdx` with <Canvas of={…} />. Hidden from
+// the sidebar (`!dev`).
+
+export const DoChangeTheView: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: change how the same data is shown',
+  render: () => (
+    <VStack align="start" gap={3}>
+      <Text fontWeight="600">크레딧 사용량</Text>
+      <SegmentedControl
+        aria-label="집계 단위"
+        size="sm"
+        defaultValue="week"
+        options={[
+          { label: '일', value: 'day' },
+          { label: '주', value: 'week' },
+          { label: '월', value: 'month' },
+        ]}
+      />
+    </VStack>
+  ),
+};
+
+export const DontSectionsAsSegments: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: switch between unrelated sections",
+  render: () => (
+    <SegmentedControl
+      defaultValue="credit"
+      options={[
+        { label: '크레딧', value: 'credit' },
+        { label: '보안', value: 'security' },
+        { label: '공지', value: 'notice' },
+        { label: '멤버', value: 'members' },
+        { label: '감사 로그', value: 'audit' },
+      ]}
+    />
+  ),
+};
+
+/** Tokens the track, thumb and labels read, as set in `SegmentedControl.tsx`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.subtle', use: <T en="Track" ko="트랙" /> },
+        {
+          token: 'border.default',
+          use: <T en="Track ring (light)" ko="트랙 테두리(라이트)" />,
+        },
+        { token: 'bg.raised', use: <T en="Selected thumb" ko="선택된 칸" /> },
+        { token: 'fg.muted', use: <T en="Label" ko="라벨" /> },
+        {
+          token: 'fg.default',
+          use: <T en="Selected label" ko="선택된 라벨" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/SegmentedControl/SegmentedControl.tsx

@@ -67,18 +67,17 @@ export const SegmentedControl = forwardRef<
         }
       }}
       size={size}
-      // Track is bg.subtle (gray.50 light) and the selected indicator rides on
-      // `bg.raised` — a raised neutral surface that resolves white in light and
-      // the lightest neutral (gray.1100) in dark, so the thumb reads as lifted
-      // above the track in both modes (`bg.surface` could not: its dark value is
-      // darker than the track). The indicator also gains a shadow: an md drop
+      // Track is bg.subtle and the selected indicator rides on `bg.raised` — a
+      // raised neutral surface that resolves white in light and a lighter
+      // neutral than the track in dark, so the thumb reads as lifted
+      // above the track in both modes. The indicator also gains a shadow: an md drop
       // shadow in light, and in dark — where a drop shadow is invisible on a
       // dark canvas — a soft ambient shadow + a translucent-white hairline edge.
       //
       // The track itself only contrasts where the page wash is darker (light) or
       // lighter (dark) than the fill. It vanishes when the page matches the
-      // track: a `bg.sunken` list/overview page is gray.50 in light — identical
-      // to the bg.subtle track — and a `bg.surface` card is lighter than the
+      // track: a `bg.sunken` list/overview page has the same light value as
+      // the bg.subtle track — and a `bg.surface` card is lighter than the
       // track in dark. In either case the control would read as floating text,
       // so a hairline ring defines its bounds on *any* background: a neutral
       // `border.default` ring in light, a translucent-white ring in dark. (The

package/src/components/SegmentedControl/SegmentedControl.usage.mdx

@@ -0,0 +1,209 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SegmentedControlStories from './SegmentedControl.stories';
+
+<Meta of={SegmentedControlStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# SegmentedControl
+
+A row of two to five mutually exclusive options in one track. Choosing one
+changes how the content next to it is shown, or which setting applies.
+
+## When to use
+
+- To change the unit or view of the same data: 일 / 주 / 월, chart / table.
+- To filter one list by a small, fixed set: all models, chat models, image
+  models.
+- For a setting with a few named values that all fit on screen, such as
+  상위 설정 따름 / 허용 / 차단.
+- To switch the language of a field being edited (한국어 / English).
+
+## When not to use
+
+- To switch between different sections with their own content → `Tabs`.
+- For more than five options, or options that do not fit on one line →
+  `Select` or `Radio`.
+- For on / off → `Switch`.
+- For actions (저장, 삭제) → `Button`s. A segment holds a value; it does not
+  do something when pressed.
+- To pick several at once → `Checkbox` or `Tag` with `selected`.
+
+## Variants and what they mean
+
+SegmentedControl has one look: the selected option sits on a raised thumb in a
+`bg.subtle` track. `size` matches the height of the `Button` of the same size,
+so a control and a button line up in one row.
+
+</En>
+
+<Ko>
+
+# SegmentedControl
+
+한 트랙 안에 둘에서 다섯 개의 선택지를 나란히 두고 하나만 고르게 합니다. 하나를 고르면
+옆 내용을 보는 방식이나 적용되는 설정이 바뀝니다.
+
+## 언제 쓰나요
+
+- 같은 데이터의 단위나 보기를 바꿀 때: 일 / 주 / 월, 차트 / 표.
+- 적고 정해진 기준으로 목록 하나를 거를 때: 전체 모델, 대화 모델, 이미지 모델.
+- 이름 붙은 값 몇 개가 화면에 다 들어가는 설정: 상위 설정 따름 / 허용 / 차단.
+- 편집 중인 입력란의 언어를 바꿀 때(한국어 / English).
+
+## 언제 쓰지 않나요
+
+- 내용이 따로 있는 서로 다른 구역을 오갈 때는 `Tabs`를 씁니다.
+- 선택지가 다섯 개보다 많거나 한 줄에 들어가지 않으면 `Select`나 `Radio`를 씁니다.
+- 켜고 끄는 것은 `Switch`를 씁니다.
+- 저장, 삭제 같은 동작은 `Button`으로 둡니다. 세그먼트는 값을 고르는 것이지 누르면 무언가를
+  하는 것이 아닙니다.
+- 여러 개를 함께 고르게 하려면 `Checkbox`나 `selected`를 쓰는 `Tag`를 씁니다.
+
+## 변형과 뜻
+
+SegmentedControl의 모양은 하나입니다. `bg.subtle` 트랙 위에 선택된 칸이 떠 있는 판으로
+올라옵니다. `size`는 같은 크기의 `Button`과 높이가 같아서 한 줄에 나란히 두면 맞아떨어집니다.
+
+</Ko>
+
+<ArgTypes of={SegmentedControlStories} include={['options', 'value', 'defaultValue', 'onSelect', 'size']} />
+
+<En>
+
+| `size` | Height | Next to |
+| --- | --- | --- |
+| `xs` | 32px | A `Button size="xs"`, a dense field header |
+| `sm` | 36px | Settings rows and filters in admin tables |
+| `md` (default) | 40px | Page-level view switches |
+| `lg` | 44px | A `Button size="lg"` |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| `size` | 높이 | 함께 두는 것 |
+| --- | --- | --- |
+| `xs` | 32px | `Button size="xs"`, 촘촘한 입력란 머리 |
+| `sm` | 36px | 관리 화면 표의 설정 줄과 필터 |
+| `md` (기본) | 40px | 페이지 전체의 보기 전환 |
+| `lg` | 44px | `Button size="lg"` |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SegmentedControlStories.DoChangeTheView} />
+<Verdict
+  kind="do"
+  en="Use it to change the unit of the data beside it, and name the group with aria-label ('집계 단위')."
+  ko="옆 데이터의 단위를 바꾸는 데 쓰고, 묶음에 aria-label('집계 단위')로 이름을 붙입니다."
+/>
+
+<Canvas of={SegmentedControlStories.DontSectionsAsSegments} />
+<Verdict
+  kind="dont"
+  en="Use it to switch between unrelated sections. That is Tabs: it gives each section a panel and the tab roles."
+  ko="서로 다른 구역을 오가는 데 쓰지 마세요. 그것은 Tabs의 일입니다. Tabs는 구역마다 패널과 탭 역할을 줍니다."
+/>
+
+<En>
+
+## Content
+
+- One or two words per option, nouns or short adjectives. No full stop.
+- Keep options parallel: 일 / 주 / 월, not 일별 / 이번 주 / 월.
+- Keep the order fixed across screens. When the same choice appears in several
+  places, users find it by position.
+
+## Accessibility
+
+What SegmentedControl does for you:
+
+- It is a radio group: the root is `role="radiogroup"` and each option is a
+  radio with a hidden native input, so `Tab` reaches the group and the arrow
+  keys change the selection (WCAG 2.1.1, 4.1.2).
+- The selected option is shown by the raised thumb and by a heavier, darker
+  label, not by colour alone (WCAG 1.4.1). The bold width is reserved in
+  advance, so the labels do not shift when the selection moves.
+- A hairline ring keeps the track visible on any page colour.
+
+What you still have to do:
+
+- **Name the group.** Pass `aria-label` (or `aria-labelledby` pointing at the
+  visible label) on `SegmentedControl`. Without it, a screen reader announces
+  the options with no question.
+- Give icon-only options a text alternative inside the label.
+- A disabled option (`disabled: true` in `options`) cannot be chosen; say why
+  nearby if the reason is not obvious.
+
+## Tokens
+
+The table lists the tokens set in `SegmentedControl.tsx`. In dark mode the
+ring and the thumb's edge are translucent white, not tokens.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 선택지마다 한두 단어의 명사나 짧은 형용사를 씁니다. 마침표를 찍지 않습니다.
+- 선택지를 같은 꼴로 맞춥니다. "일별 / 이번 주 / 월"이 아니라 "일 / 주 / 월"처럼 씁니다.
+- 화면이 달라도 순서를 바꾸지 않습니다. 같은 선택이 여러 곳에 나오면 사용자는 위치로
+  찾습니다.
+
+## 접근성
+
+SegmentedControl이 알아서 하는 일
+
+- 라디오 묶음입니다. 루트는 `role="radiogroup"`이고 각 선택지는 숨은 기본 입력이 있는
+  라디오라서, `Tab`으로 묶음에 닿고 방향키로 선택을 바꿉니다(WCAG 2.1.1, 4.1.2).
+- 선택된 칸은 떠 있는 판과 더 굵고 진한 라벨로 보이며, 색만으로 알리지 않습니다
+  (WCAG 1.4.1). 굵은 글자의 너비를 미리 잡아 두므로 선택이 옮겨 가도 라벨이 흔들리지
+  않습니다.
+- 가는 테두리가 있어 어떤 페이지 색 위에서도 트랙이 보입니다.
+
+직접 챙겨야 하는 일
+
+- **묶음에 이름을 붙입니다.** `SegmentedControl`에 `aria-label`을 넘기거나, 보이는
+  라벨을 가리키는 `aria-labelledby`를 넘깁니다. 이름이 없으면 화면 낭독기는 무엇을 고르는지
+  모른 채 선택지만 읽습니다.
+- 아이콘만 있는 선택지에는 라벨 안에 대체 텍스트를 넣습니다.
+- 비활성 선택지(`options`의 `disabled: true`)는 고를 수 없습니다. 이유가 분명하지 않다면
+  가까이에 이유를 적습니다.
+
+## 토큰
+
+아래 표는 `SegmentedControl.tsx`에서 정한 토큰입니다. 다크 모드의 테두리와 판 가장자리는
+토큰이 아니라 반투명한 흰색입니다.
+
+</Ko>
+
+<Canvas of={SegmentedControlStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Tabs**: different sections with their own content.
+- **Select** / **Radio**: more options, or options in a form.
+- **Switch**: on / off.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Tabs**: 내용이 따로 있는 서로 다른 구역.
+- **Select** / **Radio**: 선택지가 많거나 양식 안의 선택지.
+- **Switch**: 켜기 / 끄기.
+
+</Ko>

package/src/components/SegmentedProgressBar/SegmentedProgressBar.stories.tsx

@@ -1,6 +1,8 @@
 import { Box, Flex, Text, VStack } from '@chakra-ui/react';
 import { Meta, StoryObj } from '@storybook/react';
 
+import { T } from '../../guidelines/_components/Lang';
+import { TokenTable } from '../../guidelines/_components/TokenTable';
 import { ProgressSegment, SegmentedProgressBar } from './';
 
 const meta = {
@@ -274,3 +276,55 @@ export const CustomColors: Story = {
     </VStack>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `SegmentedProgressBar.usage.mdx` with <Canvas of={…} />. Hidden
+// from the sidebar (`!dev`).
+
+export const DoCountsInText: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: counts in words next to the bar',
+  render: () => (
+    <Box width="400px">
+      <SegmentedProgressBar max={100} height="8px" aria-hidden>
+        <ProgressSegment value={42} filledTrackColor="success.solid" />
+        <ProgressSegment value={3} filledTrackColor="danger.solid" />
+      </SegmentedProgressBar>
+      <Flex gap={4} mt={2} textStyle="subtext" color="fg.muted">
+        <Text>보냄 42</Text>
+        <Text color="danger.fg">실패 3</Text>
+        <Text>남음 55</Text>
+      </Flex>
+    </Box>
+  ),
+};
+
+export const DontColourOnly: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: segments with no words",
+  render: () => (
+    <Box width="400px">
+      <SegmentedProgressBar max={100} height="8px">
+        <ProgressSegment value={42} filledTrackColor="success.solid" />
+        <ProgressSegment value={3} filledTrackColor="danger.solid" />
+      </SegmentedProgressBar>
+    </Box>
+  ),
+};
+
+/** Tokens the bar reads, from `SegmentedProgressBar.tsx` and the theme. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        { token: 'bg.track', use: <T en="remainder behind the segments" ko="세그먼트 뒤의 남은 부분" /> },
+        { token: 'primary.main', use: <T en="segment fill (default)" ko="세그먼트 채움(기본)" /> },
+      ]}
+    />
+  ),
+};

package/src/components/SegmentedProgressBar/SegmentedProgressBar.types.ts

@@ -3,9 +3,11 @@ import { BoxProps } from '@chakra-ui/react';
 import { ProgressBarProps } from '../ProgressBar/ProgressBar.types';
 
 export type SegmentedProgressBarProps = BoxProps & {
+  /** The whole; each segment's width is `value / max`. */
   max: number;
 };
 
 export type ProgressSegmentProps = ProgressBarProps & {
+  /** This part's amount, in the same unit as the bar's `max`. */
   value: number;
 };