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

package/src/components/Button/Button.usage.mdx

@@ -0,0 +1,358 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as ButtonStories from './Button.stories';
+
+<Meta of={ButtonStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Button
+
+A control that does something on this screen: save, cancel, run, delete. One
+`variant` sets fill, border and label colour together.
+
+## When to use
+
+- To commit or cancel what the user is doing: the footer of a dialog, a form,
+  a settings pane (취소 · 저장).
+- To start work: 실행, 생성, 보내기 with a label.
+- To confirm a destructive step after the user has been told what it does
+  (삭제, 영구 삭제).
+- As a call to action that navigates, rendered as a link with `as="a"` or a
+  router link (전체 보기, 문서).
+
+## When not to use
+
+- The control is an icon with no visible label → `IconButton`, and give it an
+  `aria-label`.
+- The action lives inside a toast or an inline banner → a text action in the
+  surface's own colour (see **Guidelines/Actions in feedback surfaces**), not a
+  Button.
+- "Load more" at the end of a list that grows in place → `SeeMoreButton`.
+- A choice that stays on or off → `Switch` or `Checkbox`. Picking one option
+  from a few → `SegmentedControl` or `Radio`, not a row of buttons.
+- A link inside running text → a text link (`fg.link`).
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Button
+
+지금 화면에서 무언가를 실행하는 컨트롤입니다. 저장, 취소, 실행, 삭제가 여기에
+해당합니다. `variant` 하나가 바탕, 테두리, 글자 색을 함께 정합니다.
+
+## 언제 쓰나요
+
+- 사용자가 하던 일을 확정하거나 취소할 때: 대화상자, 폼, 설정 패널의 하단(취소 · 저장).
+- 작업을 시작할 때: 라벨이 있는 실행, 생성, 보내기.
+- 무슨 일이 일어나는지 알린 다음, 되돌릴 수 없는 단계를 확정할 때(삭제, 영구 삭제).
+- 다른 화면으로 이동하는 행동 유도 버튼. 이때는 `as="a"`나 라우터 링크로 렌더해
+  링크로 만듭니다(전체 보기, 문서).
+
+## 언제 쓰지 않나요
+
+- 글자 없이 아이콘만 있는 컨트롤이라면 `IconButton`을 쓰고 `aria-label`을 붙입니다.
+- 토스트나 인라인 배너 안의 동작이라면 Button 대신 그 면의 색을 따르는 텍스트
+  동작을 씁니다(**Guidelines/Actions in feedback surfaces** 참고).
+- 목록을 그 자리에서 늘리는 "더보기"라면 `SeeMoreButton`을 씁니다.
+- 켜고 끄는 상태라면 `Switch`나 `Checkbox`를 씁니다. 몇 가지 중 하나를 고르는
+  경우라면 버튼을 늘어놓지 말고 `SegmentedControl`이나 `Radio`를 씁니다.
+- 본문 문장 속 링크라면 텍스트 링크(`fg.link`)를 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={ButtonStories} include={['variant', 'isDestructive', 'lift', 'focusableWhenDisabled', 'onDisabledClick']} />
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `primary` | The one main action of the screen | 저장, 확인, 요금제 업그레이드, 결제 |
+| `action` | Run: start AI work. Black fill, coral icon | 실행, 생성 (with a leading icon) |
+| `accent` | The one coloured call to action of a landing page or hero | 시작하기, 입장하기 on marketing surfaces |
+| `secondary` | An alternative or a way out | 취소, 나중에, 필터 해제 |
+| `subtle` (default) | A low-emphasis action that still needs a shape | 필터 초기화, 다시 시도, 더보기 / 접기 |
+| `ghost` | Toolbars and inline actions next to content | 선택 해제, 닫기, 전체 보기 |
+| `danger` | Confirms a destructive step | 삭제 in a confirmation dialog, 반려 |
+
+`isDestructive` turns the label `danger.fg` on `secondary`, `subtle` and
+`ghost`; it is ignored on the filled roles. Use it for a delete that sits among
+other actions, and keep the red fill for the final confirmation.
+
+### Choosing a variant
+
+1. **Is it the step the screen exists for?** → `primary`. One per view. In
+   FactChat, `secondary` is used almost twice as often as `primary`: most
+   screens have one main action and several ways around it.
+2. **Does it start AI work?** → `action` with its icon. The coral icon is the
+   run signal; one per screen (Foundations: one run signal per screen).
+3. **Is it a marketing hero or landing CTA?** → `accent`. Product screens keep
+   `primary`; sign-up, payment and upgrade are black, not coral.
+4. **Does it delete or reject?** → in a confirmation, `danger`; anywhere else,
+   the quiet role plus `isDestructive`.
+5. **Otherwise** → `secondary` for an alternative, `ghost` in a toolbar or next
+   to content, `subtle` when a ghost would get lost on the surface.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `primary` | 화면의 주 행동 하나 | 저장, 확인, 요금제 업그레이드, 결제 |
+| `action` | AI 작업 실행. 검정 바탕에 코랄 아이콘 | 실행, 생성(앞에 아이콘) |
+| `accent` | 랜딩 페이지나 히어로 영역의 색 있는 행동 유도 버튼 하나 | 마케팅 화면의 시작하기, 입장하기 |
+| `secondary` | 다른 선택지나 빠져나가는 길 | 취소, 나중에, 필터 해제 |
+| `subtle` (기본) | 강조는 낮지만 모양은 있어야 하는 동작 | 필터 초기화, 다시 시도, 더보기 / 접기 |
+| `ghost` | 툴바, 내용 옆의 인라인 동작 | 선택 해제, 닫기, 전체 보기 |
+| `danger` | 되돌릴 수 없는 단계를 확정 | 확인 대화상자의 삭제, 반려 |
+
+`isDestructive`는 `secondary`, `subtle`, `ghost`의 글자를 `danger.fg`로 바꿉니다.
+바탕이 있는 변형에서는 무시됩니다. 다른 동작과 나란히 있는 삭제에 쓰고, 빨간
+바탕은 마지막 확인 단계에만 씁니다.
+
+### 변형 고르기
+
+1. **이 화면이 있는 이유가 되는 단계인가요?** 그렇다면 `primary`입니다. 한 화면에
+   하나만 둡니다. FactChat에서는 `secondary`가 `primary`보다 두 배 가까이 많이 쓰입니다.
+   대부분의 화면은 주 행동 하나와 여러 개의 다른 길로 이루어지기 때문입니다.
+2. **AI 작업을 시작하나요?** 그렇다면 아이콘을 넣은 `action`입니다. 코랄 아이콘이
+   실행 신호이며, 한 화면에 하나만 둡니다(Foundations의 실행 신호 규칙).
+3. **마케팅 히어로나 랜딩 페이지의 행동 유도 버튼인가요?** 그렇다면 `accent`입니다.
+   제품 화면은 `primary`를 씁니다. 가입, 결제, 업그레이드 버튼은 코랄이 아니라
+   검정입니다.
+4. **삭제하거나 반려하나요?** 확인 대화상자에서는 `danger`, 그 밖의 자리에서는 조용한
+   변형에 `isDestructive`를 붙입니다.
+5. **그 밖에는** 다른 선택지에 `secondary`, 툴바나 내용 옆에 `ghost`, 면 위에서
+   ghost가 묻힐 때 `subtle`을 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={ButtonStories.DoOnePrimary} />
+<Verdict
+  kind="do"
+  en="Give the screen one primary, with the secondary to its left."
+  ko="주 행동은 하나만 primary로 두고, secondary는 그 왼쪽에 둡니다."
+/>
+
+<Canvas of={ButtonStories.DontTwoPrimaries} />
+<Verdict
+  kind="dont"
+  en="Make both buttons primary. The reader can no longer see which one moves them forward, and 취소 looks as safe as 저장."
+  ko="두 버튼을 모두 primary로 만들지 마세요. 어느 쪽이 다음 단계인지 보이지 않고, 취소가 저장만큼 중요해 보입니다."
+/>
+
+<Canvas of={ButtonStories.DoDangerToConfirm} />
+<Verdict
+  kind="do"
+  en="Use the danger fill on the button that confirms the deletion, after the dialog has said what is lost."
+  ko="빨간 바탕은 무엇이 사라지는지 알린 대화상자에서 삭제를 확정하는 버튼에만 씁니다."
+/>
+
+<Canvas of={ButtonStories.DoQuietDestructiveInRows} />
+<Verdict
+  kind="do"
+  en="In a list, use a quiet button with isDestructive. The red label marks the risk without shouting on every row."
+  ko="목록에서는 조용한 버튼에 isDestructive를 붙입니다. 빨간 글자가 위험을 알리면서도 줄마다 눈에 띄지는 않습니다."
+/>
+
+<Canvas of={ButtonStories.DontDangerFillInRows} />
+<Verdict
+  kind="dont"
+  en="Put a red-filled button on every row. Three red blocks read as three errors, and the fill means nothing by the time the dialog asks for confirmation."
+  ko="줄마다 빨간 바탕 버튼을 두지 마세요. 빨간 덩어리 세 개는 오류 세 개로 읽히고, 확인 대화상자의 빨간 버튼도 힘을 잃습니다."
+/>
+
+<Canvas of={ButtonStories.DoPrimaryForUpgrade} />
+<Verdict
+  kind="do"
+  en="Use primary (black) for upgrade, payment and sign-up in the product."
+  ko="제품 화면의 업그레이드, 결제, 가입 버튼에는 primary(검정)를 씁니다."
+/>
+
+<Canvas of={ButtonStories.DontAccentForUpgrade} />
+<Verdict
+  kind="dont"
+  en="Use the coral accent for upgrade or payment. Coral is kept for send, run and the landing CTA, and it sits only a few degrees from the error red."
+  ko="업그레이드나 결제에 코랄 accent를 쓰지 마세요. 코랄은 보내기, 실행, 랜딩 페이지의 행동 유도 버튼에만 씁니다. 게다가 코랄은 오류 빨강과 색상이 몇 도밖에 차이 나지 않습니다."
+/>
+
+<Canvas of={ButtonStories.DoLoadingText} />
+<Verdict
+  kind="do"
+  en="While the action runs, set loading with a loadingText. The button is disabled and says what is happening."
+  ko="동작이 진행되는 동안 loading과 loadingText를 함께 줍니다. 버튼은 비활성이 되고, 무슨 일이 진행 중인지 글자로 알립니다."
+/>
+
+<Canvas of={ButtonStories.DontSpinnerOnly} />
+<Verdict
+  kind="dont"
+  en="Set loading with no loadingText. The label is hidden behind the spinner, so the button has no visible words and screen readers may get no name."
+  ko="loadingText 없이 loading만 주지 마세요. 라벨이 스피너 뒤로 숨어 눈에 보이는 글자가 없어지고, 화면 낭독기에도 이름이 전달되지 않을 수 있습니다."
+/>
+
+<Canvas of={ButtonStories.FocusableWhenDisabled} />
+<Verdict
+  kind="do"
+  en="When the reason a button is disabled can be out of view, add focusableWhenDisabled and answer onDisabledClick by moving focus to what is missing. Without it the button cannot be reached by Tab and a press does nothing."
+  ko="버튼이 비활성인 이유가 화면 밖에 있을 수 있다면 focusableWhenDisabled를 붙이고, onDisabledClick에서 빠진 항목으로 초점을 옮깁니다. 붙이지 않으면 Tab으로 닿지 않고, 눌러도 아무 반응이 없습니다."
+/>
+
+<En>
+
+## Content
+
+- Start with a verb, or a noun that names the result: 저장, 삭제, 내려받기,
+  초대 보내기. One to three words.
+- Say what will happen, not "확인" or "예" when a verb fits. In a delete
+  dialog the confirm button says 삭제, not 확인.
+- Sentence case in English ("Save changes"). No full stop, no 「」 or quotation
+  marks.
+- Keep the same word for the same action across a flow: if the dialog title
+  says 삭제, the button says 삭제, not 제거.
+- `loadingText` is a short present-tense state: 저장 중, 실행 중.
+
+## Accessibility
+
+What Button does for you:
+
+- It renders a native `<button type="button">`, so Tab reaches it and Enter
+  and Space activate it (WCAG 2.1.1). It will not submit a form by accident;
+  pass `type="submit"` when it should.
+- A keyboard focus ring (`focus.ring` with a canvas-coloured inner band) on
+  `:focus-visible` only, with no transition (WCAG 2.4.7).
+- Disabled is a fixed colour pair (`disabled.bg` / `disabled.fg`; the
+  fill-less `ghost` uses the lighter `disabled.fgGhost` label alone), not
+  opacity, and does not react to hover or press. The cursor is `not-allowed`,
+  and `progress` while `loading`.
+- `loading` disables the button and shows a spinner.
+- With `as="a"` or a router link it renders that element, so a navigating
+  button is announced as a link and keeps open-in-new-tab.
+
+What you still have to do:
+
+- **Give it words.** The visible label is the accessible name (WCAG 4.1.2).
+  An icon next to the label is decoration. With no visible label, use
+  `IconButton` with `aria-label`. If you add an `aria-label` to a Button with
+  text, it must start with the visible words (WCAG 2.5.3).
+- **Pass `loadingText`** with `loading`. Without it the label is hidden behind
+  the spinner.
+- **Say why it is disabled.** A disabled `<button>` cannot be focused, so a
+  keyboard or screen reader user may never find it. Put the reason in text
+  near it. When the reason is out of view (a consent box at the bottom of a
+  long form), add `focusableWhenDisabled`: the button stays in the Tab order
+  as `aria-disabled="true"`, looks and refuses the same, and calls
+  `onDisabledClick` instead of `onClick` when pressed — use it to move focus
+  to what is missing. Point `aria-describedby` at the reason text.
+- **Only phrasing content inside** (ACCESSIBILITY.md §5). No `<div>` or `<p>`
+  inside a Button; wrap with `as="span"` and set `display`.
+- **No button inside another control.** Don't put a Button inside a clickable
+  card or a `role="button"` wrapper (ACCESSIBILITY.md §3, axe
+  `nested-interactive`).
+- **Words, not colour alone** (WCAG 1.4.1). `danger` and `isDestructive`
+  colour the button; the label (삭제) is what tells the user.
+
+## Tokens
+
+The table is generated from `Button.styles.ts` and the theme. `transparent`
+fills and borders are left out.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 동사나 결과를 가리키는 명사로 시작합니다: 저장, 삭제, 내려받기, 초대 보내기. 한
+  단어에서 세 단어까지 씁니다.
+- 알맞은 동사가 있으면 "확인"이나 "예" 대신 무슨 일이 일어나는지 적습니다. 삭제
+  대화상자의 확정 버튼은 "확인"이 아니라 "삭제"입니다.
+- 영어는 문장형 대소문자를 씁니다("Save changes"). 마침표, 「」, 따옴표를 쓰지
+  않습니다.
+- 한 흐름 안에서 같은 동작에는 같은 말을 씁니다. 대화상자 제목이 "삭제"라면 버튼도
+  "제거"가 아니라 "삭제"입니다.
+- `loadingText`는 지금 진행 중인 상태를 짧게 씁니다: 저장 중, 실행 중.
+
+## 접근성
+
+Button이 알아서 하는 일
+
+- 기본 `<button type="button">`으로 렌더하므로 Tab으로 이동하고 Enter와 Space로
+  실행합니다(WCAG 2.1.1). 실수로 폼을 제출하지 않으며, 제출해야 할 때는
+  `type="submit"`을 줍니다.
+- 키보드 초점에만(`:focus-visible`) 초점 링을 그립니다. `focus.ring`에 바탕색 안쪽
+  띠를 더한 모양이며, 전환 효과 없이 바로 나타납니다(WCAG 2.4.7).
+- 비활성 상태는 투명도가 아니라 고정된 색 한 쌍(`disabled.bg` / `disabled.fg`)이며
+  바탕이 없는 `ghost`는 더 옅은 글자색 `disabled.fgGhost`만 씁니다.
+  마우스를 올리거나 눌러도 변하지 않습니다. 커서는 `not-allowed`이고, `loading`
+  중에는 `progress`입니다.
+- `loading`을 주면 버튼이 비활성이 되고 스피너가 나타납니다.
+- `as="a"`나 라우터 링크를 주면 그 요소로 렌더합니다. 이동하는 버튼이 링크로 읽히고
+  새 탭에서 열기도 그대로 됩니다.
+
+직접 챙겨야 하는 일
+
+- **글자를 넣습니다.** 눈에 보이는 라벨이 접근 가능한 이름입니다(WCAG 4.1.2).
+  라벨 옆의 아이콘은 장식입니다. 보이는 라벨이 없다면 `IconButton`에
+  `aria-label`을 붙여 씁니다. 글자가 있는 Button에 `aria-label`을 더한다면 보이는
+  글자로 시작해야 합니다(WCAG 2.5.3).
+- **`loading`에는 `loadingText`를 함께 줍니다.** 없으면 라벨이 스피너 뒤로 숨습니다.
+- **왜 비활성인지 알립니다.** 비활성 `<button>`은 초점을 받지 못해 키보드나 화면
+  낭독기 사용자는 버튼이 있다는 것조차 모를 수 있습니다. 가까운 곳에 이유를 글로
+  적습니다. 이유가 화면 밖에 있다면(긴 폼 맨 아래의 동의 체크박스) `focusableWhenDisabled`를
+  붙입니다. 버튼이 `aria-disabled="true"`로 Tab 순서에 남고, 모양과 막히는 동작은
+  같으며, 누르면 `onClick` 대신 `onDisabledClick`을 부릅니다. 여기서 빠진 항목으로
+  초점을 옮기고, `aria-describedby`로 이유 문구를 가리킵니다.
+- **안에는 구문 콘텐츠만 넣습니다**(ACCESSIBILITY.md 5절). Button 안에 `<div>`나
+  `<p>`를 넣지 않습니다. 감싸야 한다면 `as="span"`에 `display`를 지정합니다.
+- **컨트롤 안에 버튼을 넣지 않습니다.** 누를 수 있는 카드나 `role="button"` 래퍼 안에
+  Button을 두지 않습니다(ACCESSIBILITY.md 3절, axe `nested-interactive`).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1). `danger`와 `isDestructive`는 색을 바꿀
+  뿐이고, 뜻은 "삭제" 같은 라벨이 전합니다.
+
+## 토큰
+
+아래 표는 `Button.styles.ts`와 테마에서 자동으로 만듭니다. `transparent`인 바탕과
+테두리는 뺐습니다.
+
+</Ko>
+
+<Canvas of={ButtonStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **IconButton**: the same roles for an icon with no visible label.
+- **SeeMoreButton**: "load more" at the end of a list.
+- **Guidelines/Actions in feedback surfaces**: which control goes in a toast,
+  a banner, a pane or a dialog.
+- **Foundations/Brand & colour usage**: why button states are black, and where
+  coral may go.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **IconButton**: 보이는 라벨 없이 아이콘만 있는 버튼. 역할은 같습니다.
+- **SeeMoreButton**: 목록 끝의 "더보기".
+- **Guidelines/Actions in feedback surfaces**: 토스트, 배너, 패널, 대화상자에 어떤
+  컨트롤을 두는지.
+- **Foundations/Brand & colour usage**: 버튼 상태를 검정으로 표현하는 이유와 코랄을
+  쓰는 자리.
+
+</Ko>

package/src/components/Button/Button.variants.test.tsx

@@ -4,7 +4,10 @@ import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { system } from '../../theme';
 import { IconButton } from '../IconButton';
-import { getIconButtonStyles } from '../IconButton/IconButton.styles';
+import {
+  getIconButtonStyles,
+  iconButtonVariantStyles,
+} from '../IconButton/IconButton.styles';
 import { Button } from './Button';
 import {
   __resetLegacyButtonWarnings,
@@ -62,8 +65,17 @@ describe('Button variants (5.0)', () => {
       color: 'disabled.fg',
       opacity: 1,
     });
+    // Fill-less: no disabled.bg, so a lighter glyph/label carries the state.
     expect(buttonVariantStyles.ghost._disabled).toMatchObject({
       bg: 'transparent',
+      color: 'disabled.fgGhost',
+    });
+    expect(iconButtonVariantStyles.ghost._disabled).toMatchObject({
+      bg: 'transparent',
+      color: 'disabled.fgGhost',
+    });
+    expect(iconButtonVariantStyles.secondary._disabled).toMatchObject({
+      bg: 'disabled.bg',
       color: 'disabled.fg',
     });
   });

package/src/components/Card/Card.stories.tsx

@@ -1,6 +1,11 @@
+import { Flex } from '@chakra-ui/react';
 import type { Meta, StoryObj } from '@storybook/react';
 
+import { TokenTable } from '../../guidelines/_components/TokenTable';
+import { Button } from '../Button';
+import { Subtext, Text } from '../Typography';
 import { Card } from './Card';
+import { clickableStyles, variantStyles } from './Card.styles';
 
 const meta = {
   title: 'Components/Card',
@@ -9,6 +14,15 @@ const meta = {
     children: 'Default Card',
     p: 8,
   },
+  argTypes: {
+    variant: {
+      control: 'select',
+      options: ['default', 'wash', 'elevated'],
+      description:
+        '`default`: `bg.surface` + `border.subtle` hairline. `wash`: `bg.muted`, no border — a block that summarises or concludes. `elevated`: soft `sm` shadow — a standalone raised object.',
+      table: { defaultValue: { summary: 'default' } },
+    },
+  },
 } satisfies Meta<typeof Card>;
 
 export default meta;
@@ -52,3 +66,95 @@ export const AsButton: Story = {
     <Card {...args} as="button" type="button" textAlign="left" />
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Card.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`); `tags` is written out on each story because the indexer
+// reads CSF statically.
+
+const CourseBody = () => (
+  <>
+    <Text fontWeight="bold">AI 글쓰기 기초</Text>
+    <Subtext color="fg.muted">수강생 42명 · 6주 과정</Subtext>
+  </>
+);
+
+export const DoClickableIsTheLink: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a clickable card is the link',
+  render: () => (
+    <Card clickable as="a" href="#course-1" p={5} maxW="320px">
+      <CourseBody />
+    </Card>
+  ),
+};
+
+export const DontButtonInClickable: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a second control inside a clickable card",
+  render: () => (
+    <Card clickable onClick={() => {}} p={5} maxW="320px">
+      <CourseBody />
+      <Flex mt={3}>
+        <Button size="sm" variant="secondary">
+          삭제
+        </Button>
+      </Flex>
+    </Card>
+  ),
+};
+
+export const DoWashForSummary: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: wash for a summary or result',
+  render: () => (
+    <Card variant="wash" p={5} maxW="420px">
+      <Text fontWeight="bold" mb={1}>
+        요약
+      </Text>
+      <Text>다음 주까지 요금제 변경안을 정리하고, 금요일에 다시 검토합니다.</Text>
+    </Card>
+  ),
+};
+
+export const DontNestedCards: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: cards inside cards",
+  render: () => (
+    <Card p={5} maxW="420px">
+      <Text fontWeight="bold" mb={3}>
+        이번 달
+      </Text>
+      <Card p={4} mb={2}>
+        <Text>사용 크레딧 8,489</Text>
+      </Card>
+      <Card p={4}>
+        <Text>남은 크레딧 1,511</Text>
+      </Card>
+    </Card>
+  ),
+};
+
+/** Colour tokens from `Card.tsx` (base) and `Card.styles.ts`. */
+const CARD_TOKENS: { token: string; use: string }[] = [
+  { token: 'bg.surface', use: 'default · background' },
+  { token: 'fg.default', use: 'text' },
+  { token: 'border.subtle', use: 'default, elevated · border' },
+  { token: variantStyles.wash.bg, use: 'wash · background (no border)' },
+  { token: clickableStyles._hover.bg, use: 'clickable · hover background' },
+  {
+    token: clickableStyles._hover.borderColor,
+    use: 'clickable · hover border',
+  },
+];
+
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => <TokenTable rows={CARD_TOKENS} />,
+};

package/src/components/Card/Card.types.ts

@@ -7,7 +7,19 @@ import type { PolymorphicProps } from '../../types/polymorphic';
 export type CardVariant = 'default' | 'wash' | 'elevated';
 
 export type CardOwnProps = Omit<ChakraCardRootProps, 'as'> & {
+  /**
+   * The whole card is one target: pointer cursor, and on hover the ground
+   * steps to `bg.subtle` and the border to `border.strong`. Styling only —
+   * render it as the control with `as` (`as={NextLink}`, `as="button"`).
+   */
   clickable?: boolean;
+  /**
+   * `default`: `bg.surface` with a `border.subtle` hairline — most content.
+   * `wash`: `bg.muted`, no border — a block that summarises or concludes (an
+   * AI summary, a purchase total). `elevated`: a soft `sm` shadow — a
+   * standalone card that should read as a raised object.
+   * @default 'default'
+   */
   variant?: CardVariant;
 };