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

package/src/components/Select/Select.styles.ts

@@ -37,9 +37,27 @@ const fieldBase = {
   },
 };
 
+/**
+ * Room for the × and its divider at the end of the value, while the × shows.
+ *
+ * The indicator group overlays the value. Chakra keeps the value off the
+ * chevron with `maxW: 80%` on a Select (too little in a narrow filter) and a
+ * 1.5× height padding on a Combobox, and neither counts the × with its
+ * divider. This reserves the whole group instead: padding on both sides, the
+ * × (`8`) with its `me` (`3`), the group `gap` (`1`) and the chevron (`1em`),
+ * so a long value ends in an ellipsis before the ×.
+ */
+const clearTriggerRoom = (paddingVar: string) => ({
+  '[data-part=control]:has([data-part=clear-trigger]:not([hidden])) > &': {
+    pe: `calc(var(${paddingVar}) * 2 + 4em)`,
+    '& [data-part=value-text]': { maxW: 'none' },
+  },
+});
+
 /** Select trigger — the clickable control. */
 export const triggerStyles = {
   ...fieldBase,
+  ...clearTriggerRoom('--select-trigger-padding-x'),
   cursor: 'pointer',
   _open: {
     borderColor: 'primary.main',
@@ -67,6 +85,11 @@ export const ghostTriggerStyles = {
   _hover: { borderColor: 'border.control' },
   _disabled: {
     ...disabledText,
+    // A field, not a ghost button: the value text stays readable at
+    // `disabled.fg` (well apart from the resting `fg.default` already).
+    // `disabled.fgGhost` is for fill-less buttons whose resting glyph is
+    // `fg.icon`.
+    color: 'disabled.fg',
     cursor: 'not-allowed',
     fontWeight: 'semibold',
   },
@@ -75,6 +98,7 @@ export const ghostTriggerStyles = {
 /** Combobox text input — the typeable control. */
 export const inputStyles = {
   ...fieldBase,
+  ...clearTriggerRoom('--combobox-input-padding-x'),
 };
 
 /** Dropdown panel for both Select and Combobox. */
@@ -115,3 +139,68 @@ export const itemStyles = {
 export const indicatorStyles = {
   color: 'fg.muted',
 };
+
+/**
+ * Clear (×) button for both Select and Combobox.
+ *
+ * Chakra's recipe gives this part a colour and no size, and its default icon
+ * is `1em`, so a bare `ClearTrigger` drew a 21px × next to a 14px chevron. The
+ * × is the secondary action, so it is smaller (`3.5`, 12px at 14px text) and
+ * lighter (`fg.icon`) than the chevron, on an `8` box. `& svg` rather than
+ * `_icon` so the size also wins over an icon passed with its own `boxSize`.
+ *
+ * On a touch screen the hit area widens to 44px, toward the value only: the
+ * chevron sits to the right and has to keep opening the list. The height stays
+ * the control's own height (`heightVar`), so the area never reaches the field
+ * above or below. Every control height is over the 24px KWCAG minimum.
+ */
+const clearTriggerStyles = (heightVar: string) => ({
+  position: 'relative',
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  boxSize: '8',
+  // The divider sits `1` past the box. `3` leaves the same space between the
+  // divider and the chevron glyph as between the × glyph and the divider
+  // (about 13px at 14px text).
+  me: '3',
+  color: 'fg.icon',
+  cursor: 'pointer',
+  _hover: { color: 'fg.default' },
+  // The divider marks where opening starts: it sits in the `me` gap, takes no
+  // clicks, and everything right of it belongs to the chevron.
+  _after: {
+    content: '""',
+    position: 'absolute',
+    insetEnd: '-1',
+    top: '50%',
+    transform: 'translateY(-50%)',
+    h: '4',
+    borderEndWidth: '1px',
+    borderColor: 'border.subtle',
+    pointerEvents: 'none',
+  },
+  // zag hides the × with the `hidden` attribute while nothing is selected,
+  // and the `display` above would otherwise override it.
+  _hidden: { display: 'none' },
+  '& svg': { width: '3.5', height: '3.5' },
+  '@media (pointer: coarse)': {
+    '&::before': {
+      content: '""',
+      position: 'absolute',
+      insetEnd: 0,
+      top: '50%',
+      transform: 'translateY(-50%)',
+      width: '44px',
+      height: `var(${heightVar})`,
+    },
+  },
+});
+
+export const selectClearTriggerStyles = clearTriggerStyles(
+  '--select-trigger-height'
+);
+
+export const comboboxClearTriggerStyles = clearTriggerStyles(
+  '--combobox-input-height'
+);

package/src/components/Select/Select.tsx

@@ -1,13 +1,16 @@
 import { forwardRef } from 'react';
 import { Select as ChakraSelect } from '@chakra-ui/react';
 
+import { useTranslate } from '@/hooks/useTranslate';
 import { mergeCss } from '@/utils/mergeCss';
 
+import { CloseIcon } from '../Icon';
 import {
   contentStyles,
   ghostTriggerStyles,
   indicatorStyles,
   itemStyles,
+  selectClearTriggerStyles,
   triggerStyles,
 } from './Select.styles';
 import type { SelectVariant } from './Select.types';
@@ -67,10 +70,33 @@ const Indicator = forwardRef<HTMLDivElement, ChakraSelect.IndicatorProps>(
   }
 );
 
+/**
+ * The × that empties the selection. Draws `CloseIcon` when no children are
+ * passed, and names itself in the provider's language: Chakra's own name is
+ * the English "Clear value" in every locale. Pass `aria-label` to say what is
+ * being cleared ("조직 선택 지우기").
+ */
+const ClearTrigger = forwardRef<
+  HTMLButtonElement,
+  ChakraSelect.ClearTriggerProps
+>(function SelectClearTrigger({ css, children, ...props }, ref) {
+  const translate = useTranslate();
+  return (
+    <ChakraSelect.ClearTrigger
+      ref={ref}
+      aria-label={translate('clear_selection') as string}
+      {...props}
+      css={mergeCss(selectClearTriggerStyles, css)}
+    >
+      {children ?? <CloseIcon aria-hidden />}
+    </ChakraSelect.ClearTrigger>
+  );
+});
+
 /**
  * Compound Select primitives — Chakra's `Select` namespace with the Logician
  * design-system styling baked into the visual parts (`Trigger`, `Content`,
- * `Item`, `Indicator`). Use these directly for full compositional control
+ * `Item`, `Indicator`, `ClearTrigger`). Use these directly for full compositional control
  * (multi-select, grouped options, custom layouts); use `SelectField` for the
  * common single-select case.
  */
@@ -84,7 +110,7 @@ export const Select = {
   ValueText: ChakraSelect.ValueText,
   IndicatorGroup: ChakraSelect.IndicatorGroup,
   Indicator,
-  ClearTrigger: ChakraSelect.ClearTrigger,
+  ClearTrigger,
   HiddenSelect: ChakraSelect.HiddenSelect,
   Positioner: ChakraSelect.Positioner,
   Content,

package/src/components/Select/Select.usage.mdx

@@ -0,0 +1,341 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as SelectStories from './Select.stories';
+import { SelectField } from './SelectField';
+
+<Meta of={SelectStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Select, SelectField, Combobox, ComboboxField
+
+Pick one value from a list that is too long to show in full. `SelectField` and
+`ComboboxField` are ready-made fields; `Select` and `Combobox` are the styled
+parts for building your own.
+
+| Component       | Use it for                                                                           |
+| --------------- | ------------------------------------------------------------------------------------ |
+| `SelectField`   | One value from a short, fixed list. Pass `options`, `value`, `onChange`.             |
+| `ComboboxField` | One value from a long list the user would rather search than scroll.                 |
+| `Select.*`      | Multi-select, grouped options, options with icons or descriptions, a custom trigger. |
+| `Combobox.*`    | A searchable list with groups or custom rows.                                        |
+
+## When to use
+
+- Five or more options, or options that would crowd the page if shown at once:
+  a language, a model, a role.
+- A setting in a dense list where each row ends in a choice: `SelectField`
+  with `variant="ghost"`.
+- A list the user searches by name, such as groups or members:
+  `ComboboxField`.
+
+## When not to use
+
+- Two to four options that fit on screen → `Radio`, so the user sees every
+  option without opening anything. A single on/off → `Switch` or `Checkbox`.
+- Switching the view of the same content → `SegmentedControl` or `Tabs`.
+- Running an action (Rename, Delete) → `Menu`. A select holds a value; a menu
+  does something.
+- Free text with suggestions the user may ignore → `Input`.
+
+## Variants and props
+
+</En>
+
+<Ko>
+
+# Select, SelectField, Combobox, ComboboxField
+
+다 펼쳐 보이기에는 긴 목록에서 값 하나를 고르게 합니다. `SelectField`와
+`ComboboxField`는 바로 쓰는 필드이고, `Select`와 `Combobox`는 직접 조합할 때 쓰는
+스타일이 입혀진 부품입니다.
+
+| 컴포넌트        | 쓰는 곳                                                                  |
+| --------------- | ------------------------------------------------------------------------ |
+| `SelectField`   | 짧고 정해진 목록에서 값 하나. `options`, `value`, `onChange`를 넘깁니다. |
+| `ComboboxField` | 스크롤보다 검색이 편한 긴 목록에서 값 하나.                              |
+| `Select.*`      | 여러 개 선택, 묶은 항목, 아이콘이나 설명이 붙은 항목, 직접 만든 트리거.  |
+| `Combobox.*`    | 묶음이나 직접 만든 행이 있는 검색 목록.                                  |
+
+## 언제 쓰나요
+
+- 선택지가 다섯 개 이상이거나, 한꺼번에 보이면 화면이 복잡해질 때: 언어, 모델, 역할.
+- 행마다 끝에 선택이 하나씩 있는 촘촘한 설정 목록: `variant="ghost"`인 `SelectField`.
+- 이름으로 찾는 목록(그룹, 멤버): `ComboboxField`.
+
+## 언제 쓰지 않나요
+
+- 화면에 다 들어가는 두세 개의 선택지는 `Radio`를 씁니다. 아무것도 열지 않고 모든
+  선택지를 볼 수 있습니다. 켜고 끄는 값 하나는 `Switch`나 `Checkbox`를 씁니다.
+- 같은 내용의 보기 방식을 바꿀 때는 `SegmentedControl`이나 `Tabs`를 씁니다.
+- 이름 바꾸기, 삭제 같은 동작은 `Menu`를 씁니다. 셀렉트는 값을 담고, 메뉴는 일을
+  합니다.
+- 제안을 무시하고 자유롭게 써도 되는 텍스트는 `Input`을 씁니다.
+
+## 변형과 속성
+
+</Ko>
+
+<ArgTypes
+  of={SelectField}
+  include={['variant', 'label', 'ariaLabel', 'placeholder', 'stagger']}
+/>
+
+<En>
+
+| Variant             | Means                                                                                      | Use for                                                                                            |
+| ------------------- | ------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
+| `outline` (default) | A bordered field, the same as `Input`. Width defaults to `full`.                           | Forms, modals, filters                                                                             |
+| `ghost`             | No border until hover or focus; sized to its value. An invalid field keeps its red border. | The trailing choice in a settings row, where a column of bordered triggers would outweigh the card |
+
+Other props: `size` (`xs`–`lg`, default `md`), `invalid`, `disabled`,
+`readOnly`, `required`, `name`, `width`. `onChange` receives the value, or
+`null` when the selection is cleared. `ComboboxField` adds `emptyText`; it has
+no `variant` or `stagger`.
+
+## Clearing the value
+
+When "nothing chosen" is a valid value, let the user empty the field again: a
+filter, or a form field that is not required. Do not offer it on a required
+field.
+
+`ComboboxField` already has the button. `SelectField` has none, so a
+clearable select is composed from `Select.*`. With `Select.*` or
+`Combobox.*`, put `ClearTrigger` in the indicator group, before the chevron:
+
+```tsx
+<Select.IndicatorGroup>
+  <Select.ClearTrigger aria-label="조직 선택 지우기" />
+  <Select.Indicator />
+</Select.IndicatorGroup>
+```
+
+The part does the rest. It shows only while something is selected. It draws
+its own icon, smaller and lighter than the chevron, with a divider between
+them. While it shows, the value ends in an ellipsis before it. On a touch
+screen its hit area widens to 44px toward the value, at the field's own
+height. Do not pass a size, a colour or your own divider.
+
+`onValueChange` receives an empty value when it is pressed;
+`ComboboxField` passes `null` to `onChange`.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형             | 뜻                                                                                                                            | 쓰는 곳                                                                              |
+| ---------------- | ----------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `outline` (기본) | `Input`과 같은 테두리가 있는 필드. 너비 기본값은 `full`입니다.                                                                | 폼, 모달, 필터                                                                       |
+| `ghost`          | 마우스를 올리거나 초점을 받기 전에는 테두리가 없고, 값 길이에 맞춰 너비가 정해집니다. 오류 상태에서는 빨간 테두리가 남습니다. | 설정 목록의 행 끝 선택. 테두리 있는 트리거가 줄지어 있으면 카드보다 무거워 보이는 곳 |
+
+그 밖의 속성: `size`(`xs`~`lg`, 기본 `md`), `invalid`, `disabled`, `readOnly`,
+`required`, `name`, `width`. `onChange`는 고른 값을 받고, 선택을 지우면 `null`을
+받습니다. `ComboboxField`에는 `emptyText`가 더 있고, `variant`와 `stagger`는
+없습니다.
+
+## 선택 지우기
+
+"아무것도 고르지 않음"도 올바른 값일 때는 사용자가 필드를 다시 비울 수 있게 합니다.
+필터나 필수가 아닌 폼 필드가 그렇습니다. 필수 필드에는 두지 않습니다.
+
+`ComboboxField`에는 이미 들어 있습니다. `SelectField`에는 없으므로, 지울 수 있는
+셀렉트는 `Select.*`로 조합합니다. `Select.*`나 `Combobox.*`로 조합할 때는
+`ClearTrigger`를 indicator group 안, 화살표 앞에 둡니다.
+
+```tsx
+<Select.IndicatorGroup>
+  <Select.ClearTrigger aria-label="조직 선택 지우기" />
+  <Select.Indicator />
+</Select.IndicatorGroup>
+```
+
+나머지는 부품이 처리합니다. 무언가 골라져 있을 때만 보입니다. 아이콘을 직접 그리고,
+화살표보다 작고 옅게 그리며, 화살표와의 사이에 구분선을 둡니다. 보이는 동안 값은
+버튼 앞에서 말줄임으로 끝납니다. 터치 화면에서는 누르는 영역이 값 쪽으로 44px까지
+넓어지고, 높이는 필드 높이를 따릅니다. 크기, 색, 구분선을 따로 넘기지 마세요.
+
+누르면 `onValueChange`가 빈 값을 받습니다. `ComboboxField`는 `onChange`에
+`null`을 넘깁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={SelectStories.DoLabelled} />
+<Verdict
+  kind="do"
+  en="Give the field a visible label with the label prop. It is rendered as the part the trigger is named by."
+  ko="label 속성으로 보이는 라벨을 붙입니다. 라벨은 트리거의 이름이 되는 부품으로 그려집니다."
+/>
+
+<Canvas of={SelectStories.DontNameless} />
+<Verdict
+  kind="dont"
+  en="Leave out label, ariaLabel and placeholder. The text next to it is not connected, so a screen reader announces a bare 'button', whatever the value says (KWCAG 5.3.4.1)."
+  ko="label, ariaLabel, placeholder를 모두 빼지 마세요. 옆에 있는 글자는 연결되지 않으므로, 화면 낭독기는 값이 무엇이든 그냥 '버튼'이라고만 읽습니다(KWCAG 5.3.4.1)."
+/>
+
+<Canvas of={SelectStories.Ghost} />
+<Verdict
+  kind="do"
+  en="In a settings list, use the ghost variant and pass the row title as ariaLabel."
+  ko="설정 목록에서는 ghost 변형을 쓰고, 행 제목을 ariaLabel로 넘깁니다."
+/>
+
+<Canvas of={SelectStories.DoComboboxForLongList} />
+<Verdict
+  kind="do"
+  en="Use ComboboxField when the user knows the name and the list is long. Translate emptyText; the default is English."
+  ko="사용자가 이름을 알고 목록이 길다면 ComboboxField를 씁니다. emptyText의 기본값은 영어이므로 번역해서 넘깁니다."
+/>
+
+<Canvas of={SelectStories.Clearable} />
+<Verdict
+  kind="do"
+  en="On an optional field, put ClearTrigger before the chevron and pass an aria-label that says what is cleared. Without one it is named 'Clear selection' in the provider language."
+  ko="필수가 아닌 필드에는 화살표 앞에 ClearTrigger를 두고, 무엇을 지우는지 aria-label로 넘깁니다. 넘기지 않으면 provider 언어의 '선택 지우기'로 읽힙니다."
+/>
+
+<Canvas of={SelectStories.DontSelectForTwo} />
+<Verdict
+  kind="dont"
+  en="Hide two options behind a dropdown. The user has to open it to learn there is only one alternative."
+  ko="선택지 두 개를 드롭다운 안에 숨기지 마세요. 다른 선택지가 하나뿐이라는 것을 열어 봐야 압니다."
+/>
+
+<Canvas of={SelectStories.DoRadioForTwo} />
+<Verdict
+  kind="do"
+  en="Show a few options as Radio, so the choice is visible at a glance."
+  ko="선택지가 몇 개뿐이면 Radio로 펼쳐서 한눈에 보이게 합니다."
+/>
+
+<En>
+
+## Content
+
+- Label: a noun for what is chosen (답변 언어, 역할), not an instruction (언어를
+  선택하세요).
+- Placeholder: only when "nothing chosen yet" is a real state. It also becomes
+  the hidden name if there is no label, so make it meaningful, but prefer
+  `label` or `ariaLabel`.
+- Options: short, parallel, sentence case, sorted in a predictable order
+  (frequency, size, or alphabetical). Do not repeat the label in each option.
+- `emptyText` on `ComboboxField`: say what was not found (일치하는 그룹이
+  없습니다).
+
+## Accessibility
+
+What these components do for you:
+
+- **A name, if you give one.** `SelectField` and `ComboboxField` always render
+  the label part the trigger points at: visibly for `label`, visually hidden
+  for `ariaLabel` (or `placeholder` as a fallback). The name is in the server
+  markup, not added after hydration (KWCAG 5.3.4.1 레이블 제공).
+- **Keyboard.** The Chakra / Zag listbox handles it: Enter, Space or the arrow
+  keys open the list; arrows move; Enter selects; Escape closes and returns
+  focus to the trigger. In `ComboboxField` typing filters the list.
+- **A name for the clear button.** `ClearTrigger` is named 「선택 지우기」 /
+  "Clear selection" in the provider language, instead of Chakra's English
+  "Clear value" in every locale. A caller's `aria-label` wins.
+- **Focus and states.** The trigger shows a `primary.main` border and ring on
+  focus and while open (WCAG 2.4.7). The selected option is bold on
+  `primary.selected` and carries a check mark, so it does not rely on colour
+  alone (WCAG 1.4.1).
+
+What you still have to do:
+
+- **Always pass `label` or `ariaLabel`.** Inside `FieldRow`, the row's label
+  does not reach the trigger: pass the same text as `ariaLabel`. The type does
+  not stop you from leaving all three out.
+- **Compose `Select.*` / `Combobox.*` with a `Label` part.** Leave it out and
+  the trigger has no name. When the label is elsewhere on screen, render
+  `<Select.Label srOnly>`.
+- Put errors in words (`FieldRow` `error`) as well as `invalid` (WCAG 3.3.1).
+
+## Tokens
+
+Generated from `Select.styles.ts`. Select and Combobox share these.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 라벨: 고르는 대상을 명사로 씁니다(답변 언어, 역할). "언어를 선택하세요" 같은 지시문은
+  쓰지 않습니다.
+- 플레이스홀더: "아직 고르지 않음"이 실제로 있는 상태일 때만 씁니다. 라벨이 없으면
+  숨은 이름으로도 쓰이므로 뜻이 통하게 쓰되, 되도록 `label`이나 `ariaLabel`을 씁니다.
+- 선택지: 짧고 같은 형식으로 쓰며, 자주 쓰는 순, 크기순, 가나다순처럼 예측할 수 있는
+  순서로 둡니다. 선택지마다 라벨을 되풀이하지 않습니다.
+- `ComboboxField`의 `emptyText`: 무엇을 찾지 못했는지 씁니다(일치하는 그룹이
+  없습니다).
+
+## 접근성
+
+이 컴포넌트들이 알아서 하는 일
+
+- **이름을 주면 그대로 씁니다.** `SelectField`와 `ComboboxField`는 트리거가 가리키는
+  라벨 부품을 항상 그립니다. `label`이면 보이게, `ariaLabel`(없으면 `placeholder`)이면
+  시각적으로 숨겨서 그립니다. 이름은 하이드레이션 뒤에 붙는 것이 아니라 서버가 보낸
+  마크업 안에 있습니다(KWCAG 5.3.4.1 레이블 제공).
+- **키보드.** Chakra와 Zag의 목록 상자가 처리합니다. Enter, Space, 방향키로 목록을
+  열고, 방향키로 옮기고, Enter로 고르며, Escape로 닫으면 초점이 트리거로 돌아갑니다.
+  `ComboboxField`에서는 입력하면 목록이 걸러집니다.
+- **지우기 버튼의 이름.** `ClearTrigger`는 provider 언어로 「선택 지우기」
+  ("Clear selection")라는 이름을 가집니다. Chakra 기본값은 어느 언어에서나 영어
+  "Clear value"였습니다. 호출부에서 넘긴 `aria-label`이 우선합니다.
+- **초점과 상태.** 트리거는 초점을 받거나 열려 있는 동안 `primary.main` 테두리와 링을
+  보여 줍니다(WCAG 2.4.7). 선택된 항목은 `primary.selected` 위에 굵은 글자와 체크
+  표시로 나타나므로 색에만 기대지 않습니다(WCAG 1.4.1).
+
+직접 챙겨야 하는 일
+
+- **`label`이나 `ariaLabel`을 반드시 넘깁니다.** `FieldRow` 안에서는 행의 라벨이
+  트리거까지 닿지 않으므로 같은 글자를 `ariaLabel`로 넘깁니다. 셋 다 빠뜨려도 타입
+  검사에서 걸리지 않습니다.
+- **`Select.*`나 `Combobox.*`로 조합할 때는 `Label` 부품을 넣습니다.** 빼면 트리거에
+  이름이 없습니다. 라벨이 화면의 다른 곳에 있다면 `<Select.Label srOnly>`를 씁니다.
+- 오류는 `invalid`와 함께 `FieldRow`의 `error`로 문구를 보여 줍니다(WCAG 3.3.1).
+
+## 토큰
+
+`Select.styles.ts`에서 자동으로 만듭니다. Select와 Combobox가 함께 씁니다.
+
+</Ko>
+
+<Canvas of={SelectStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Radio**: a few options, all visible.
+- **Switch** / **Checkbox**: on or off.
+- **SegmentedControl** / **Tabs**: switching views.
+- **Menu**: actions, not values.
+- **FieldRow**: label, helper and error around the field.
+- More compositions: the _Multi Select_, _Grouped Options_ and _Custom Items_
+  stories under Components/Select and Components/Combobox.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Radio**: 몇 개 안 되는 선택지를 모두 보여 줄 때.
+- **Switch** / **Checkbox**: 켜고 끄는 값.
+- **SegmentedControl** / **Tabs**: 보기 전환.
+- **Menu**: 값이 아니라 동작.
+- **FieldRow**: 필드를 둘러싼 라벨, 도움말, 오류 문구.
+- 조합 예시: Components/Select와 Components/Combobox 아래의 _Multi Select_,
+  _Grouped Options_, _Custom Items_ 스토리.
+
+</Ko>

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']} />