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

package/src/components/Banner/Banner.types.ts

@@ -2,8 +2,37 @@ import { BoxProps } from '@chakra-ui/react';
 
 export type BannerSize = 'sm' | 'md' | 'lg';
 
+/**
+ * Banner variants (5.0).
+ *
+ * - `info` (default): a system fact the reader should know before acting
+ *   (a setting that is locked, where a value comes from). Nothing is wrong.
+ * - `success`: something finished and the result stays relevant on this
+ *   screen.
+ * - `warning`: it still works, but read this first (irreversible step,
+ *   something expiring).
+ * - `danger`: it failed or is blocked, and the reader has to do something.
+ * - `neutral`: a brand notice with no status (`primary.main` accent bar).
+ */
+export type BannerVariant =
+  | 'info'
+  | 'success'
+  | 'warning'
+  | 'danger'
+  | 'neutral';
+
 export interface BannerProps extends BoxProps {
-  variant?: 'info' | 'success' | 'warning' | 'danger' | 'neutral';
+  /**
+   * Meaning of the message. Status variants only for a status every reader
+   * shares; `neutral` for a notice with none.
+   * @default 'info'
+   */
+  variant?: BannerVariant;
+  /** Hide the leading status icon. The text must still say the status. */
   hideIcon?: boolean;
+  /**
+   * `sm` = subtext, `md` = body text, `lg` = h5 text style.
+   * @default 'md'
+   */
   size?: BannerSize;
 }

package/src/components/Banner/Banner.usage.mdx

@@ -0,0 +1,233 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BannerStories from './Banner.stories';
+
+<Meta of={BannerStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Banner
+
+An inline message that stays on the page, next to the thing it is about, until
+the condition behind it changes.
+
+## When to use
+
+- To warn before an action the reader is about to take: an irreversible step,
+  something about to expire.
+- To state a system fact that shapes what the reader can do here: a setting
+  that is locked, a limit, where a value comes from.
+- To report a failure that blocks the form or section, with what to do next.
+
+## When not to use
+
+- The message only confirms that something just happened ("Saved") → `Toast`.
+- A short status attached to one item → `Badge`.
+- An error about one field → the field's own error text (`FormControl`).
+- The whole page failed to render → `ErrorFallback`.
+- An explanation the reader asks for → `InfoSprinkle` or `Tooltip`.
+
+## Variants and what they mean
+
+</En>
+
+<Ko>
+
+# Banner
+
+관련된 내용 바로 옆에 붙어서, 원인이 해결될 때까지 화면에 남아 있는 안내
+문구입니다.
+
+## 언제 쓰나요
+
+- 되돌릴 수 없는 작업이나 곧 만료되는 항목처럼, 사용자가 하려는 일 앞에서 주의를
+  줄 때.
+- 잠긴 설정, 한도, 값의 출처처럼 이 화면에서 할 수 있는 일을 정하는 시스템 사실을
+  알릴 때.
+- 폼이나 영역 전체를 막는 실패를 알리고, 다음에 할 일을 함께 적을 때.
+
+## 언제 쓰지 않나요
+
+- 방금 끝난 일을 확인만 해 준다면("저장했습니다") `Toast`를 씁니다.
+- 항목 하나에 붙는 짧은 상태는 `Badge`를 씁니다.
+- 입력란 하나의 오류는 그 입력란의 오류 문구(`FormControl`)로 알립니다.
+- 페이지 전체를 그리지 못했다면 `ErrorFallback`을 씁니다.
+- 사용자가 찾아보는 설명은 `InfoSprinkle`이나 `Tooltip`을 씁니다.
+
+## 변형과 뜻
+
+</Ko>
+
+<ArgTypes of={BannerStories} include={['variant', 'size', 'hideIcon']} />
+
+<En>
+
+| Variant | Means | Use for |
+| --- | --- | --- |
+| `info` (default) | A system fact to know before acting; nothing is wrong | Locked setting, scope, where a value comes from |
+| `success` | Finished, and the result stays relevant on this screen | A connection that is now live |
+| `warning` | Still works, but read this first | Irreversible step, expiring credit |
+| `danger` | Failed or blocked; the reader has to act | Load failure, over a limit, submit error |
+| `neutral` | A brand notice with no status | Announcements |
+
+Use `size="sm"` inside cards, dialogs and forms; `md` (default) at the top of a
+page section. Banner adds `my={2}`; pass `my={0}` when the parent already sets
+the gap.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 변형 | 뜻 | 예 |
+| --- | --- | --- |
+| `info` (기본) | 작업 전에 알아야 할 시스템 사실이며, 문제가 있다는 뜻은 아님 | 잠긴 설정, 적용 범위, 값의 출처 |
+| `success` | 끝났고, 그 결과가 이 화면에서 계속 의미가 있음 | 연결이 활성화됨 |
+| `warning` | 동작은 하지만 먼저 읽어야 함 | 되돌릴 수 없는 작업, 만료 임박 크레딧 |
+| `danger` | 실패했거나 막혔고, 사용자가 무언가 해야 함 | 불러오기 실패, 한도 초과, 저장 오류 |
+| `neutral` | 상태가 없는 브랜드 공지 | 공지 |
+
+카드, 대화상자, 폼 안에서는 `size="sm"`을, 페이지 영역 맨 위에서는 기본값 `md`를
+씁니다. Banner에는 `my={2}`가 들어 있으니, 부모가 이미 간격을 정한다면
+`my={0}`을 넘깁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BannerStories.DoWarningBeforeAction} />
+<Verdict
+  kind="do"
+  en="Put a warning right above the action it is about, inside the same panel."
+  ko="주의 문구는 관련된 버튼 바로 위, 같은 패널 안에 둡니다."
+/>
+
+<Canvas of={BannerStories.DontBannerForTransientSuccess} />
+<Verdict
+  kind="dont"
+  en="Leave a success banner on the page after a save. It is out of date the moment the reader edits again. Confirm with a Toast."
+  ko="저장한 뒤 성공 배너를 화면에 남겨 두지 마세요. 다시 고치는 순간 맞지 않는 말이 됩니다. 확인은 Toast로 합니다."
+/>
+
+<Canvas of={BannerStories.DoInfoForLockedSetting} />
+<Verdict
+  kind="do"
+  en="Use info to explain why a setting cannot change. Nothing is wrong, so it is not a warning."
+  ko="설정을 바꿀 수 없는 이유는 info로 알립니다. 문제가 생긴 것이 아니므로 warning이 아닙니다."
+/>
+
+<Canvas of={BannerStories.DontStackBanners} />
+<Verdict
+  kind="dont"
+  en="Stack several banners. The reader stops reading after the first. Keep the one that blocks the next step and move the rest to where they apply."
+  ko="배너를 여러 개 쌓지 마세요. 사용자는 첫 번째 배너만 읽습니다. 다음 단계를 막는 배너 하나만 남기고, 나머지는 해당하는 자리로 옮기세요."
+/>
+
+<Canvas of={BannerStories.DoDangerWithAlert} />
+<Verdict
+  kind="do"
+  en='When a danger banner appears in response to a submit, give it role="alert" so screen readers announce it. Say what happened and what to do next.'
+  ko='저장 같은 동작의 결과로 나타나는 danger 배너에는 role="alert"를 붙여 화면 낭독기가 바로 읽게 합니다. 무슨 일이 있었는지와 다음에 할 일을 함께 적습니다.'
+/>
+
+<En>
+
+## Content
+
+- One or two sentences. Lead with what happened or what is true, then what to
+  do: "저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요."
+- Full sentences end with a full stop. Sentence case in English.
+- Numbers and dates the reader needs go in the text, not only in a link.
+- Do not repeat the icon's meaning as a prefix ("경고:", "Error:"). The variant
+  already says it, and the words say the rest.
+
+## Accessibility
+
+What Banner does for you:
+
+- A string child renders as body text in the variant's `{status}.fg` colour,
+  which the contrast audit checks against `{status}.bg` in both modes
+  (WCAG 1.4.3).
+- The icon is a decoration next to the words; the status is in the text.
+
+What you still have to do:
+
+- **Banner has no live-region role.** A banner that is on the page when it
+  loads needs none. One that appears after an action does: pass
+  `role="alert"` for an error, `role="status"` for anything else
+  (WCAG 4.1.3).
+- **Words, not colour alone** (WCAG 1.4.1). If you set `hideIcon`, the text
+  still has to say it is a warning or an error when that matters.
+- A link or button inside the banner needs a name that makes sense on its own
+  (WCAG 2.4.4).
+
+## Tokens
+
+The table is generated from `Banner.styles.ts` and the theme.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 한두 문장으로 씁니다. 무슨 일이 있었는지 또는 무엇이 사실인지 먼저 쓰고, 다음에 할
+  일을 씁니다. 예: "저장하지 못했습니다. 네트워크 연결을 확인한 뒤 다시 시도해 주세요."
+- 완전한 문장은 마침표로 끝냅니다. 영어는 문장형 대소문자를 씁니다.
+- 사용자에게 필요한 숫자와 날짜는 링크 안에만 두지 말고 본문에 씁니다.
+- 아이콘의 뜻을 "경고:", "오류:" 같은 머리말로 반복하지 않습니다. 변형이 이미 알려
+  주고, 나머지는 문장이 전합니다.
+
+## 접근성
+
+Banner가 알아서 하는 일
+
+- 문자열을 넘기면 변형의 `{status}.fg` 색으로 본문 글자를 그립니다. 이 색은 대비
+  감사에서 라이트·다크 모두 `{status}.bg` 위에서 검사합니다(WCAG 1.4.3).
+- 아이콘은 문구 옆의 장식이고, 상태는 문구가 전합니다.
+
+직접 챙겨야 하는 일
+
+- **Banner에는 라이브 영역 역할이 없습니다.** 페이지를 열 때부터 있는 배너는 역할이
+  필요 없습니다. 어떤 동작 뒤에 나타나는 배너는 다릅니다. 오류라면 `role="alert"`,
+  그 밖에는 `role="status"`를 넘깁니다(WCAG 4.1.3).
+- **색만으로 알리지 않습니다**(WCAG 1.4.1). `hideIcon`을 쓴다면, 주의나 오류라는
+  사실이 중요할 때 문구가 그것을 말해야 합니다.
+- 배너 안의 링크나 버튼에는 그것만 읽어도 뜻이 통하는 이름을 붙입니다(WCAG 2.4.4).
+
+## 토큰
+
+아래 표는 `Banner.styles.ts`와 테마에서 자동으로 만듭니다.
+
+</Ko>
+
+<Canvas of={BannerStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Toast**: a passing confirmation or a result with one follow-up action.
+- **Badge**: a one-to-three-word status on one item.
+- **ErrorFallback**: the page or section failed to render.
+- **Guidelines/Actions in feedback surfaces**: buttons and links inside a
+  banner.
+- **Foundations/Brand & colour usage**: status colours mean status.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Toast**: 잠깐 보이는 확인 메시지, 또는 후속 동작이 하나 있는 결과 안내.
+- **Badge**: 항목 하나에 붙는 한두 단어의 상태.
+- **ErrorFallback**: 페이지나 영역을 그리지 못했을 때.
+- **Guidelines/Actions in feedback surfaces**: 배너 안의 버튼과 링크.
+- **Foundations/Brand & colour usage**: 상태색은 상태를 뜻합니다.
+
+</Ko>

package/src/components/BottomSheet/BottomSheet.stories.tsx

@@ -7,10 +7,12 @@
  * emulation) to try the gestures; with a mouse the same drags work by
  * pointer.
  */
-import { useState } from 'react';
+import { type ReactNode, useState } from 'react';
 import { Box, 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 { Button } from '../Button';
 import {
   BoltIcon,
@@ -30,6 +32,8 @@ import {
   BottomSheetContent,
   BottomSheetFooter,
   BottomSheetHeader,
+  BottomSheetOverlay,
+  bottomSheetSlotRecipe,
 } from '.';
 
 const meta = {
@@ -202,3 +206,166 @@ export const LongScrollingList: Story = {
     );
   },
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `BottomSheet.usage.mdx` with <Canvas of={…} />. Hidden from the
+// sidebar (`!dev`). Each is a real, open sheet held inside a phone-sized frame
+// on the docs page: the portal is disabled, the frame's transform makes it the
+// containing block for the fixed positioner and scrim, and `modal={false}`
+// keeps the specimen from trapping focus or locking the page's scroll (the
+// scrim is drawn with `BottomSheetOverlay` so it still looks modal).
+
+const PhoneFrame = ({ children }: { children: ReactNode }) => (
+  <Box
+    position="relative"
+    w="360px"
+    maxW="100%"
+    h="420px"
+    mx="auto"
+    overflow="hidden"
+    borderRadius="l3"
+    borderWidth="1px"
+    borderColor="border.subtle"
+    bg="bg.canvas"
+    transform="translateZ(0)"
+    css={{
+      '& [data-scope=drawer][data-part=positioner], & [data-scope=drawer][data-part=backdrop]':
+        { width: '100%', height: '100%' },
+    }}
+  >
+    {children}
+  </Box>
+);
+
+const OpenSheet = ({ children }: { children: ReactNode }) => (
+  <PhoneFrame>
+    <BottomSheet
+      open
+      modal={false}
+      closeOnInteractOutside={false}
+      closeOnEscape={false}
+      portalProps={{ disabled: true }}
+    >
+      <BottomSheetOverlay />
+      <BottomSheetContent>{children}</BottomSheetContent>
+    </BottomSheet>
+  </PhoneFrame>
+);
+
+const SHORT_PALETTE = PALETTE.slice(0, 4);
+
+export const DoPickFromList: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a titled list to pick from',
+  render: () => (
+    <OpenSheet>
+      <BottomSheetHeader>노드 추가</BottomSheetHeader>
+      <BottomSheetCloseButton />
+      <BottomSheetBody>
+        {/* Inline: the docs page's `.sbdocs-content ul` marker rule
+            outranks a style prop. */}
+        <Stack as="ul" gap="1" style={{ listStyle: 'none' }} m="0" p="0">
+          {SHORT_PALETTE.map(({ icon: Icon, label, hint }) => (
+            <Box as="li" key={label}>
+              <HStack
+                as="button"
+                w="full"
+                gap="3"
+                px="3"
+                py="2.5"
+                borderRadius="l2"
+                textAlign="start"
+              >
+                <Icon boxSize="sm" aria-hidden />
+                <Stack gap="0">
+                  <Text fontWeight="semibold">{label}</Text>
+                  <Subtext color="fg.muted">{hint}</Subtext>
+                </Stack>
+              </HStack>
+            </Box>
+          ))}
+        </Stack>
+      </BottomSheetBody>
+    </OpenSheet>
+  ),
+};
+
+export const DontNoHeader: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: a sheet with no header",
+  render: () => (
+    <OpenSheet>
+      <BottomSheetBody>
+        <Stack gap="2" pt="2">
+          {SHORT_PALETTE.map(({ label }) => (
+            <Text key={label}>{label}</Text>
+          ))}
+        </Stack>
+      </BottomSheetBody>
+    </OpenSheet>
+  ),
+};
+
+export const DoFooterToApply: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: a footer when choices apply together',
+  render: () => (
+    <OpenSheet>
+      <BottomSheetHeader>필터</BottomSheetHeader>
+      <BottomSheetCloseButton />
+      <BottomSheetBody>
+        <Stack gap="2">
+          <Text>모델: 전체</Text>
+          <Text>기간: 최근 7일</Text>
+          <Text>상태: 완료</Text>
+        </Stack>
+      </BottomSheetBody>
+      <BottomSheetFooter>
+        <Button variant="secondary">초기화</Button>
+        <Button variant="primary">적용</Button>
+      </BottomSheetFooter>
+    </OpenSheet>
+  ),
+};
+
+const sheet = bottomSheetSlotRecipe.base ?? {};
+
+/** Tokens each sheet part reads, from `bottomSheetSlotRecipe` in `BottomSheet.styles.ts`. */
+export const UsageTokens: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Tokens',
+  render: () => (
+    <TokenTable
+      rows={[
+        {
+          token: String(sheet.content?.bg),
+          use: <T en="Sheet · background" ko="시트 · 배경" />,
+        },
+        {
+          token: String(sheet.content?.color),
+          use: <T en="Sheet · text" ko="시트 · 글자" />,
+        },
+        {
+          token: String(sheet.content?.borderColor),
+          use: <T en="Sheet · top edge" ko="시트 · 위 테두리" />,
+        },
+        {
+          token: String(sheet.grabberIndicator?.bg),
+          use: <T en="Grabber" ko="손잡이" />,
+        },
+        {
+          token: String(sheet.description?.color),
+          use: <T en="Description" ko="설명" />,
+        },
+        {
+          token: String(sheet.footer?.borderColor),
+          use: <T en="Footer · top rule" ko="푸터 · 위 선" />,
+        },
+      ]}
+    />
+  ),
+};

package/src/components/BottomSheet/BottomSheet.test.tsx

@@ -29,7 +29,8 @@ beforeAll(() => {
 });
 
 const Sheet = (props: Partial<BottomSheetProps>) => (
-  <LogicianProvider>
+  // Korean copy, so the built-in close label is 닫기 (it follows `language`).
+  <LogicianProvider language="ko">
     <BottomSheet {...props}>
       <BottomSheetContent data-testid="content">
         <BottomSheetHeader>노드 추가</BottomSheetHeader>

package/src/components/BottomSheet/BottomSheet.usage.mdx

@@ -0,0 +1,216 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as BottomSheetStories from './BottomSheet.stories';
+
+<Meta of={BottomSheetStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# BottomSheet
+
+A panel that rises from the bottom edge of a phone screen. The user can drag it
+between snap points or swipe it away.
+
+## When to use
+
+- On a phone, to pick one item from a list: a node palette in the workflow
+  editor, an answer to a question the assistant asks.
+- On a phone, for a few related choices the user applies together, such as
+  filters.
+- Next to a canvas the user keeps working on: a non-modal sheet
+  (`modal={false}`) resting on a snap point leaves the page usable.
+
+## When not to use
+
+- On a desktop layout → `Modal` for a task, `Menu` or `Popover` for options
+  next to their trigger.
+- To confirm something that cannot be undone → `Modal`. A swipe should never
+  be the only thing between the user and a deletion.
+- For a result or status → `Toast` or `Banner`.
+- For a long form → a page. The sheet is capped at 85% of the screen height.
+
+## Variants and what they mean
+
+The sheet has no visual variants. These props decide how it behaves:
+
+</En>
+
+<Ko>
+
+# BottomSheet
+
+휴대폰 화면 아래 가장자리에서 올라오는 패널입니다. 사용자가 끌어서 멈춤 지점 사이를
+오가거나 쓸어내려 닫을 수 있습니다.
+
+## 언제 쓰나요
+
+- 휴대폰에서 목록 중 하나를 고르게 할 때: 워크플로 편집기의 노드 팔레트, 어시스턴트가
+  묻는 질문의 답.
+- 휴대폰에서 함께 적용하는 몇 가지 선택지를 보일 때: 필터.
+- 사용자가 계속 작업하는 캔버스 옆에 둘 때: 멈춤 지점에 걸쳐 둔 비모달 시트
+  (`modal={false}`)는 뒤의 페이지를 그대로 쓸 수 있게 둡니다.
+
+## 언제 쓰지 않나요
+
+- 데스크톱 화면에서는 작업에 `Modal`을, 버튼 옆 선택지에 `Menu`나 `Popover`를 씁니다.
+- 되돌릴 수 없는 동작의 확인은 `Modal`로 받습니다. 쓸어내리는 동작 하나만으로 삭제가
+  일어나서는 안 됩니다.
+- 결과나 상태는 `Toast`나 `Banner`로 알립니다.
+- 긴 양식은 페이지에 둡니다. 시트 높이는 화면의 85%까지만 늘어납니다.
+
+## 변형과 뜻
+
+시트에는 모양 변형이 없습니다. 동작을 정하는 속성은 다음과 같습니다.
+
+</Ko>
+
+<En>
+
+| Prop | Effect | Use for |
+| --- | --- | --- |
+| `modal` (default `true`) | Scrim, focus trap and scroll lock. | Most sheets: a pick or a set of choices. |
+| `modal={false}` | No scrim, no focus trap, no scroll lock; the page behind stays usable. | A palette beside a canvas, usually with `snapPoints`. |
+| `snapPoints` / `defaultSnapPoint` | Heights the sheet rests at. Numbers up to 1 are fractions of the viewport (`[0.4, 1]`); strings take `px` or `rem`. | A sheet that opens half-way and expands. |
+| `BottomSheetContent showGrabber` (default `true`) | Draws the drag handle. | Leave it on; turn it off only when the sheet cannot be dragged. |
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+| 속성 | 효과 | 쓰는 곳 |
+| --- | --- | --- |
+| `modal` (기본 `true`) | 배경 막, 초점 가두기, 스크롤 잠금. | 대부분의 시트: 하나 고르기, 선택지 묶음. |
+| `modal={false}` | 배경 막, 초점 가두기, 스크롤 잠금이 모두 없어 뒤의 페이지를 쓸 수 있습니다. | 캔버스 옆의 팔레트. 보통 `snapPoints`와 함께 씁니다. |
+| `snapPoints` / `defaultSnapPoint` | 시트가 멈추는 높이. 1 이하의 숫자는 화면 높이의 비율(`[0.4, 1]`)이고, 문자열은 `px`나 `rem` 값입니다. | 반쯤 열렸다가 더 펼치는 시트. |
+| `BottomSheetContent`의 `showGrabber` (기본 `true`) | 끌기 손잡이를 그립니다. | 켜 둡니다. 시트를 끌 수 없을 때만 끕니다. |
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={BottomSheetStories.DoPickFromList} />
+<Verdict
+  kind="do"
+  en="Give the sheet a header and a close button, and keep each row a single button."
+  ko="시트에 헤더와 닫기 버튼을 두고, 목록의 한 줄은 버튼 하나로 만듭니다."
+/>
+
+<Canvas of={BottomSheetStories.DontNoHeader} />
+<Verdict
+  kind="dont"
+  en="Leave out the header. The header is the sheet's accessible name; without it a screen reader announces an unnamed dialog, and nobody sees what the list is for."
+  ko="헤더를 빼지 마세요. 헤더가 시트의 접근 가능한 이름입니다. 헤더가 없으면 화면 낭독기는 이름 없는 대화상자로 읽고, 보는 사람도 목록이 무엇인지 알 수 없습니다."
+/>
+
+<Canvas of={BottomSheetStories.DoFooterToApply} />
+<Verdict
+  kind="do"
+  en="Add BottomSheetFooter only when the choices apply together. For a single pick, the row itself is the action."
+  ko="선택지를 한꺼번에 적용할 때만 BottomSheetFooter를 둡니다. 하나만 고르는 시트에서는 줄을 누르는 것이 곧 동작입니다."
+/>
+
+<En>
+
+## Content
+
+- **Header:** a noun or a short task name, no full stop: "노드 추가", "필터".
+- **Rows:** a label and, if needed, one line of hint in `fg.muted`.
+- **Footer buttons:** verbs ("적용", "초기화"), at most two.
+
+## Accessibility
+
+What BottomSheet does for you:
+
+- `BottomSheetHeader` becomes the sheet's title, which the content's
+  `aria-labelledby` points at (WCAG 4.1.2).
+- When modal, it traps focus in the sheet and locks the page's scroll.
+  `Escape` closes it (WCAG 2.1.1).
+- `BottomSheetCloseButton` carries a translated `aria-label` (닫기 / Close).
+- The grabber is `aria-hidden`: it is a pointer affordance, and dragging is
+  never the only way to close the sheet (WCAG 2.5.1).
+- `BottomSheetBody` scrolls inside the sheet; a drag starts from the body only
+  when the list is scrolled to the top, so scrolling never drags the sheet.
+
+What you still have to do:
+
+- **Always render `BottomSheetHeader`.** Without it the sheet has no name.
+- **Keep a close button or a footer action.** A swipe or an outside tap is not
+  available to keyboard and switch users.
+- Put `BottomSheetCloseButton` directly inside `BottomSheetContent`, next to
+  the header, not inside it.
+- A non-modal sheet does not trap focus: `Tab` can leave it for the page
+  behind. Check that the tab order between the two still makes sense.
+
+## Tokens
+
+The table is generated from `bottomSheetSlotRecipe` in `BottomSheet.styles.ts`.
+The scrim is `blackAlpha.500`, a fixed value rather than a semantic token.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- **헤더:** 명사나 짧은 작업 이름을 쓰고 마침표를 찍지 않습니다. "노드 추가", "필터".
+- **목록 한 줄:** 라벨 하나와, 필요하면 `fg.muted`로 쓴 도움말 한 줄.
+- **푸터 버튼:** 동사("적용", "초기화")로 두 개까지 씁니다.
+
+## 접근성
+
+BottomSheet가 알아서 하는 일
+
+- `BottomSheetHeader`가 시트의 제목이 되고, 콘텐츠의 `aria-labelledby`가 이 제목을
+  가리킵니다(WCAG 4.1.2).
+- 모달일 때는 초점을 시트 안에 가두고 페이지 스크롤을 막습니다. `Escape`로 닫힙니다
+  (WCAG 2.1.1).
+- `BottomSheetCloseButton`에는 번역된 `aria-label`(닫기 / Close)이 붙어 있습니다.
+- 손잡이는 `aria-hidden`입니다. 포인터용 표시일 뿐이고, 끌기만이 시트를 닫는 유일한
+  방법이 되지 않습니다(WCAG 2.5.1).
+- `BottomSheetBody`는 시트 안에서 스크롤됩니다. 목록이 맨 위에 있을 때만 본문에서 끌기가
+  시작되므로, 목록을 스크롤하다가 시트가 끌려 내려가지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **`BottomSheetHeader`를 언제나 둡니다.** 헤더가 없으면 시트에 이름이 없습니다.
+- **닫기 버튼이나 푸터 동작을 남깁니다.** 쓸어내리기나 바깥 누르기는 키보드나 스위치
+  사용자가 쓸 수 없습니다.
+- `BottomSheetCloseButton`은 헤더 안이 아니라 헤더 옆, `BottomSheetContent`의 바로
+  아래에 둡니다.
+- 비모달 시트는 초점을 가두지 않으므로 `Tab`으로 뒤의 페이지로 나갈 수 있습니다. 시트와
+  페이지 사이의 탭 순서가 자연스러운지 확인합니다.
+
+## 토큰
+
+아래 표는 `BottomSheet.styles.ts`의 `bottomSheetSlotRecipe`에서 자동으로 만듭니다. 배경
+막은 의미 토큰이 아니라 고정값 `blackAlpha.500`입니다.
+
+</Ko>
+
+<Canvas of={BottomSheetStories.UsageTokens} sourceState="none" />
+
+<En>
+
+## Related
+
+- **Modal**: the same job on a wide screen, and every destructive confirmation.
+- **Menu**: a short list of actions next to its trigger.
+- **Popover**: a small panel of controls anchored to its trigger.
+
+</En>
+
+<Ko>
+
+## 관련 컴포넌트
+
+- **Modal**: 넓은 화면에서 같은 일을 하며, 되돌릴 수 없는 동작의 확인은 모두 Modal로
+  받습니다.
+- **Menu**: 버튼 옆에 여는 짧은 동작 목록.
+- **Popover**: 버튼에 붙어 열리는 작은 컨트롤 패널.
+
+</Ko>