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

package/src/components/FileList/FileList.usage.mdx

@@ -0,0 +1,165 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FileListStories from './FileList.stories';
+
+<Meta of={FileListStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FileList
+
+A bordered list of `FileItem` rows that shows the first few files and reveals
+more on request.
+
+## When to use
+
+- The files attached to something: a chatbot's knowledge files, a project's
+  uploads, a policy's documents.
+
+## When not to use
+
+- One file → `FileItem`.
+- Hundreds of files the user searches, sorts or selects → `Table`.
+
+## Props
+
+</En>
+
+<Ko>
+
+# FileList
+
+`FileItem` 행을 테두리 안에 모아, 처음 몇 개만 보여 주고 요청하면 더 펼치는
+목록입니다.
+
+## 언제 쓰나요
+
+- 어떤 대상에 붙은 파일들: 챗봇의 지식 파일, 프로젝트에 올린 파일, 정책 문서.
+
+## 언제 쓰지 않나요
+
+- 파일이 하나라면 `FileItem`을 씁니다.
+- 검색, 정렬, 선택이 필요한 수백 개의 파일은 `Table`을 씁니다.
+
+## 속성
+
+</Ko>
+
+<ArgTypes
+  of={FileListStories}
+  include={[
+    'files',
+    'visibleCount',
+    'onFileDownload',
+    'onFileDelete',
+    'stagger',
+  ]}
+/>
+
+<En>
+
+- Shows `visibleCount` rows (default 3); the "see more" button adds three at
+  a time. With no files it renders nothing.
+- A row gets a download button only when the file has a `fileUrl` and you pass
+  `onFileDownload`.
+- `onFileDelete` may return a promise; the row shows a spinner until it
+  settles, and a second click on the same row is ignored meanwhile.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+- `visibleCount`개 행(기본 3개)을 보여 주고, "더 보기" 버튼을 누를 때마다 세 개씩
+  늘립니다. 파일이 없으면 아무것도 그리지 않습니다.
+- 내려받기 버튼은 파일에 `fileUrl`이 있고 `onFileDownload`를 넘겼을 때만 생깁니다.
+- `onFileDelete`는 프로미스를 돌려줘도 됩니다. 끝날 때까지 그 행에 스피너가 보이고, 그
+  사이 같은 행을 다시 눌러도 무시합니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FileListStories.DoDownloadAndDelete} />
+<Verdict
+  kind="do"
+  en="Pass fileUrl for files that can be downloaded and let uploads in progress show their own bar."
+  ko="내려받을 수 있는 파일에는 fileUrl을 넘기고, 올리는 중인 파일은 진행 막대가 보이게 둡니다."
+/>
+
+<En>
+
+## Content
+
+- When the list is empty, say so outside it (no files yet, and how to add
+  one); FileList renders nothing.
+- Put a heading or label above it that says whose files these are.
+
+## Accessibility
+
+What FileList does for you:
+
+- Renders a real list (`<ul>` / `<li>`), so a screen reader announces the
+  number of files (WCAG 1.3.1).
+
+Known gaps, and what to do:
+
+- **The "see more" button has no focus ring.** Its styles are reset with
+  `all: unset`, which removes the outline (WCAG 2.4.7).
+- Its count shows the initial `visibleCount`, not the number of rows on
+  screen, after the first click.
+- Rows inherit the `FileItem` gaps (errors in tooltips, English cancel
+  label).
+
+## Tokens
+
+The frame and row dividers are `border.subtle`; the "see more" text and
+chevron are `fg.subtle`. Row colours are listed on the FileItem page.
+
+## Related
+
+- **FileItem**: one row.
+- **FileInput**: adding files.
+- **Table**: large file sets.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 목록이 비면 FileList는 아무것도 그리지 않으므로, 목록 밖에서 아직 파일이 없다는 것과
+  추가하는 방법을 알려 줍니다.
+- 위에 누구의 파일인지 알려 주는 제목이나 라벨을 둡니다.
+
+## 접근성
+
+FileList가 알아서 하는 일
+
+- 실제 목록(`<ul>`·`<li>`)으로 그리므로 화면 낭독기가 파일 개수를 알려 줍니다(WCAG
+  1.3.1).
+
+알려진 한계와 대처
+
+- **"더 보기" 버튼에 초점 표시가 없습니다.** 스타일을 `all: unset`으로 지워서 윤곽선이
+  사라집니다(WCAG 2.4.7).
+- 한 번 누른 뒤에도 버튼의 숫자는 화면에 보이는 행 수가 아니라 처음 `visibleCount`를
+  보여 줍니다.
+- 각 행은 `FileItem`의 한계(툴팁 속 오류, 영어 취소 버튼 이름)를 그대로 가집니다.
+
+## 토큰
+
+테두리와 행 구분선은 `border.subtle`, "더 보기" 글자와 화살표는 `fg.subtle`입니다. 행의
+색은 FileItem 페이지에 있습니다.
+
+## 관련 컴포넌트
+
+- **FileItem**: 한 줄.
+- **FileInput**: 파일 추가.
+- **Table**: 많은 파일.
+
+</Ko>

package/src/components/FlyTo/FlyTo.usage.mdx

@@ -0,0 +1,99 @@
+import { ArgTypes, Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle } from '../../guidelines/_components/Lang';
+import * as FlyToStories from './FlyTo.stories';
+
+<Meta of={FlyToStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FlyTo
+
+Sends a ghost of an element arcing from one rect to another, to say "this went
+there": a reward chip into a balance, a file into a folder.
+
+</En>
+
+<Ko>
+
+# FlyTo
+
+요소의 복제본을 한 위치에서 다른 위치로 포물선을 그리며 날려 보내, "이것이 저기로
+갔다"를 보여 줍니다. 보상 칩이 잔액으로, 파일이 폴더로 들어가는 장면에 씁니다.
+
+</Ko>
+
+<Canvas of={FlyToStories.Default} />
+
+<En>
+
+## When to use
+
+- A reward the reader just earned travels to the balance or counter it adds
+  to, and the balance updates when it lands (`onDone`).
+- An item moves to a place that is visible on screen, and seeing it go there
+  explains where it went.
+
+## When not to use
+
+- The target is not on screen, or there is no meaningful source → skip the
+  flight and `Pulse` the value that changed.
+- Only a number changed → `CountUp`, optionally inside a `Pulse`.
+- Something new appears in place → `Appear`.
+
+## Reduced motion and accessibility
+
+- With `prefers-reduced-motion: reduce` nothing flies: FlyTo renders nothing and
+  calls `onDone` right after mounting, so whatever the flight was sequencing
+  still happens.
+- The ghost is decoration. It renders into a portal at the end of the page, so
+  a screen reader can reach a copy of its text there. Pass `aria-hidden` when
+  the ghost holds text.
+- The meaning lives in the state change, not the flight. Update the target
+  value in `onDone`, and if the reader must hear it, announce it yourself
+  (WCAG 4.1.3).
+- The ghost ignores the pointer (`pointer-events: none`), so it never blocks
+  a click.
+
+## Props
+
+`from` and `to` are viewport rects, usually from `getBoundingClientRect()`.
+The caller mounts FlyTo to start a flight and unmounts it in `onDone`.
+
+</En>
+
+<Ko>
+
+## 언제 쓰나요
+
+- 사용자가 방금 받은 보상이 그것이 더해질 잔액이나 카운터로 날아가고, 도착하는 순간
+  잔액이 바뀔 때(`onDone`).
+- 항목이 화면에 보이는 다른 자리로 옮겨 가고, 날아가는 모습이 어디로 갔는지를 설명해 줄 때.
+
+## 언제 쓰지 않나요
+
+- 목적지가 화면에 없거나 출발점이 뚜렷하지 않다면 날리지 말고, 바뀐 값에 `Pulse`를
+  씁니다.
+- 숫자만 바뀌었다면 `CountUp`을 쓰고, 필요하면 `Pulse`로 감쌉니다.
+- 새 요소가 제자리에 나타난다면 `Appear`를 씁니다.
+
+## 동작 줄이기와 접근성
+
+- `prefers-reduced-motion: reduce`에서는 아무것도 날지 않습니다. FlyTo는 아무것도
+  그리지 않고 마운트 직후 `onDone`을 부르므로, 비행 뒤에 이어지던 일은 그대로 진행됩니다.
+- 복제본은 장식입니다. 페이지 끝의 포털에 그려지므로 화면 낭독기가 거기서 그 글자를 한
+  번 더 만날 수 있습니다. 복제본에 글자가 있다면 `aria-hidden`을 넘깁니다.
+- 뜻은 비행이 아니라 상태 변화에 있습니다. `onDone`에서 목적지 값을 바꾸고, 사용자가
+  들어야 하는 변화라면 직접 알립니다(WCAG 4.1.3).
+- 복제본은 포인터를 받지 않으므로(`pointer-events: none`) 클릭을 막지 않습니다.
+
+## 속성
+
+`from`과 `to`는 뷰포트 기준 사각형이며 보통 `getBoundingClientRect()`에서 얻습니다.
+비행을 시작하려면 FlyTo를 마운트하고, `onDone`에서 언마운트합니다.
+
+</Ko>
+
+<ArgTypes of={FlyToStories} include={['from', 'to', 'lift', 'onDone']} />

package/src/components/Form/Form.stories.tsx

@@ -0,0 +1,149 @@
+import { useState } from 'react';
+import { Box, Dialog } from '@chakra-ui/react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { Button } from '../Button';
+import { Input } from '../Input';
+import { SelectField } from '../Select';
+import { Switch } from '../Switch';
+import { Textarea } from '../Textarea';
+import { Subtext } from '../Typography';
+import {
+  FieldRow,
+  FormFooter,
+  FormModalFooter,
+  FormScrollArea,
+  FormSection,
+} from '.';
+
+/**
+ * The Form building blocks together: `FormSection` groups, `FieldRow` fields,
+ * a `FormFooter` pinned under a `FormScrollArea`. Each part has its own story
+ * set below this one.
+ */
+const meta = {
+  title: 'Components/Form',
+  parameters: { layout: 'padded' },
+} satisfies Meta;
+
+export default meta;
+
+type Story = StoryObj;
+
+const MODELS = [
+  { label: 'GPT-5', value: 'gpt-5' },
+  { label: 'Claude Sonnet', value: 'claude-sonnet' },
+  { label: 'Gemini Flash', value: 'gemini-flash' },
+];
+
+const SettingsPanel = ({ withErrors = false }: { withErrors?: boolean }) => {
+  const [name, setName] = useState(withErrors ? '' : '사내 규정 도우미');
+  return (
+    <Box
+      h="460px"
+      w="400px"
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderRadius="12px"
+      overflow="hidden"
+    >
+      <FormScrollArea>
+        <Box p={4} flex={1}>
+          <FormSection title="기본 정보" gap={4}>
+            <FieldRow
+              label="챗봇 이름"
+              required
+              error={
+                withErrors && !name ? '챗봇 이름을 입력해 주세요.' : undefined
+              }
+            >
+              <Input value={name} onChange={(e) => setName(e.target.value)} />
+            </FieldRow>
+            <FieldRow label="설명" helperText="목록에서 이름 아래에 보입니다.">
+              <Textarea rows={3} />
+            </FieldRow>
+          </FormSection>
+          <FormSection title="동작" divider mt={6} gap={4}>
+            <FieldRow label="기본 모델">
+              <SelectField
+                ariaLabel="기본 모델"
+                options={MODELS}
+                defaultValue="gpt-5"
+              />
+            </FieldRow>
+            <Switch display="flex" justifyContent="space-between" w="100%">
+              <Switch.Label>웹 검색 사용</Switch.Label>
+              <Switch.Control />
+            </Switch>
+          </FormSection>
+        </Box>
+        <FormFooter
+          meta={<Subtext color="fg.muted">오후 2:14에 저장됨</Subtext>}
+          action={<Button variant="primary">저장</Button>}
+        />
+      </FormScrollArea>
+    </Box>
+  );
+};
+
+/** A settings panel: two sections, a pinned footer with meta and action. */
+export const Basic: Story = {
+  render: () => <SettingsPanel />,
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `Form.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoErrorsAtTheField: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: errors at the field',
+  render: () => <SettingsPanel withErrors />,
+};
+
+export const DoModalFooter: Story = {
+  tags: ['!dev'],
+  name: 'Usage / Do: FormModalFooter in a modal form',
+  render: () => (
+    // `ModalFooter` reads the dialog's style context; a closed root provides it
+    // without opening anything.
+    <Dialog.Root>
+      <Box
+        w="480px"
+        bg="bg.surface"
+        borderWidth="1px"
+        borderColor="border.subtle"
+        borderRadius="12px"
+      >
+        <FormModalFooter
+          onDelete={() => {}}
+          deleteLabel="그룹 삭제"
+          onCancel={() => {}}
+          cancelLabel="취소"
+          submitLabel="저장"
+          onSubmit={() => {}}
+        />
+      </Box>
+    </Dialog.Root>
+  ),
+};
+
+export const DontHandRolledFooter: Story = {
+  tags: ['!dev'],
+  name: "Usage / Don't: a hand-rolled footer",
+  render: () => (
+    <Box
+      w="480px"
+      p={4}
+      display="flex"
+      gap={2}
+      bg="bg.surface"
+      borderWidth="1px"
+      borderColor="border.subtle"
+      borderRadius="12px"
+    >
+      <Button variant="primary">저장</Button>
+      <Button variant="danger">그룹 삭제</Button>
+      <Button variant="subtle">취소</Button>
+    </Box>
+  ),
+};

package/src/components/Form/Form.usage.mdx

@@ -0,0 +1,201 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormStories from './Form.stories';
+
+<Meta of={FormStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# Form
+
+The layout parts every form shares: fields, sections, a scroll area and the
+footer with the actions.
+
+| Part                                      | What it does                                                                                                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `FieldRow`                                | One field: label (with `description` and an `endAdornment` slot), the control, `helperText` and `error`. Wraps `FormControl`, so ids and ARIA are wired for you.                                       |
+| `FieldLabel` / `FieldHelp` / `FieldError` | The pieces `FieldRow` is made of, for layouts it does not cover. `FieldError` renders nothing when empty.                                                                                              |
+| `FormSection`                             | A titled group of fields with one gap (default `4`). `divider` adds a top rule; `collapsible` (with a `title`) turns it into an accordion, and `hasError` flags a collapsed section that hides errors. |
+| `FormSectionHeader`                       | The section title row (`H5`, description, `titleAdornment`, `action`) on its own.                                                                                                                      |
+| `FormScrollArea`                          | A full-height scrolling column, so a sticky footer pins to its bottom.                                                                                                                                 |
+| `FormFooter`                              | A sticky footer for panel forms: `start` on the left, `meta` (saved time, cost) and `action` on the right.                                                                                             |
+| `FormModalFooter`                         | The modal footer: optional delete on the far left, Cancel, and a primary submit with its own loading and disabled state.                                                                               |
+
+## When to use
+
+- Any settings panel, create or edit modal, or sidebar form. Start with
+  `FieldRow` for every field and `FormSection` for every group.
+- `FormFooter` in a panel that scrolls; `FormModalFooter` in a modal.
+
+## When not to use
+
+- A single search box or filter bar → the control on its own, with an
+  `ariaLabel` or visible label.
+- A confirm dialog with no fields → `Modal` with its own footer.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# Form
+
+모든 폼이 함께 쓰는 배치 부품입니다. 필드, 섹션, 스크롤 영역, 동작 버튼이 있는 푸터가
+있습니다.
+
+| 부품                                      | 하는 일                                                                                                                                                                                           |
+| ----------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `FieldRow`                                | 필드 하나. 라벨(`description`, `endAdornment` 자리 포함), 컨트롤, `helperText`, `error`. `FormControl`을 감싸므로 id와 ARIA 연결을 대신 해 줍니다.                                                |
+| `FieldLabel` / `FieldHelp` / `FieldError` | `FieldRow`를 이루는 조각. `FieldRow`로 안 되는 배치에 씁니다. `FieldError`는 비어 있으면 아무것도 그리지 않습니다.                                                                                |
+| `FormSection`                             | 제목이 있는 필드 묶음. 간격은 하나로 통일합니다(기본 `4`). `divider`는 위에 구분선을 긋고, `collapsible`(`title` 필요)은 접히는 묶음으로 바꾸며, `hasError`는 접힌 섹션에 숨은 오류를 표시합니다. |
+| `FormSectionHeader`                       | 섹션 제목 줄(`H5`, 설명, `titleAdornment`, `action`)만 따로 쓸 때.                                                                                                                                |
+| `FormScrollArea`                          | 높이를 꽉 채우고 스크롤되는 세로 영역. 붙박이 푸터가 아래에 고정됩니다.                                                                                                                           |
+| `FormFooter`                              | 패널 폼의 붙박이 푸터. 왼쪽에 `start`, 오른쪽에 `meta`(저장 시각, 비용)와 `action`.                                                                                                               |
+| `FormModalFooter`                         | 모달 푸터. 맨 왼쪽의 삭제(선택), 취소, 로딩과 비활성 상태를 스스로 가진 기본 제출 버튼.                                                                                                           |
+
+## 언제 쓰나요
+
+- 설정 패널, 만들기·수정 모달, 사이드바 폼 어디서나 씁니다. 필드마다 `FieldRow`를,
+  묶음마다 `FormSection`을 먼저 씁니다.
+- 스크롤되는 패널에는 `FormFooter`를, 모달에는 `FormModalFooter`를 씁니다.
+
+## 언제 쓰지 않나요
+
+- 검색창이나 필터 막대 하나는 컨트롤만 두고 `ariaLabel`이나 보이는 라벨을 붙입니다.
+- 입력란 없이 확인만 받는 대화상자는 `Modal`의 푸터를 씁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FormStories.Basic} />
+<Verdict
+  kind="do"
+  en="Build panels from FormSection and FieldRow, and pin the action in a FormFooter inside a FormScrollArea."
+  ko="패널은 FormSection과 FieldRow로 짜고, 동작 버튼은 FormScrollArea 안의 FormFooter에 고정합니다."
+/>
+
+<Canvas of={FormStories.DoErrorsAtTheField} />
+<Verdict
+  kind="do"
+  en="Show each error under its own field with FieldRow error. The field is marked invalid for assistive technology at the same time."
+  ko="오류는 FieldRow의 error로 해당 필드 바로 아래에 보여 줍니다. 보조기술에도 그 필드가 오류 상태라고 함께 전달됩니다."
+/>
+
+<Canvas of={FormStories.DoModalFooter} />
+<Verdict
+  kind="do"
+  en="Use FormModalFooter in modals: delete far left, Cancel, then the primary action last."
+  ko="모달에는 FormModalFooter를 씁니다. 삭제는 맨 왼쪽, 그다음 취소, 기본 동작은 맨 끝입니다."
+/>
+
+<Canvas of={FormStories.DontHandRolledFooter} />
+<Verdict
+  kind="dont"
+  en="Hand-roll the footer. The order changes from modal to modal, and the danger action ends up next to Save."
+  ko="푸터를 직접 만들지 마세요. 모달마다 순서가 달라지고, 위험한 동작이 저장 버튼 옆에 붙게 됩니다."
+/>
+
+<En>
+
+## Content
+
+- Section titles are nouns (기본 정보, 동작). Field rules are on the Input and
+  Select pages.
+- Footer labels name the result (저장, 만들기, 그룹 삭제). The design system
+  owns no copy: `cancelLabel`, `submitLabel` and `deleteLabel` come from your
+  translations.
+- `meta` is a fact, not an instruction: 오후 2:14에 저장됨, 10 크레딧.
+
+## Accessibility
+
+What these parts do for you:
+
+- `FieldRow` associates the label, sets `aria-invalid` when `error` is set,
+  and points `aria-describedby` at the helper and error text. `required`
+  shows the asterisk and marks the control required.
+- `FormModalFooter` keeps the submit a `type="submit"` button inside a
+  `<form>`, so Enter submits; pass `onSubmit` only for a portalled or
+  form-less modal. `isSubmitting` disables every button so the modal cannot be
+  dismissed mid-request.
+- A collapsed `FormSection` with `hasError` swaps its chevron for a danger
+  glyph, so hidden errors are not missed.
+
+What you still have to do:
+
+- **Name controls that `FieldRow` cannot reach.** `SelectField`,
+  `ComboboxField` and `Slider` take their name from their own label part: pass
+  the row's label as `ariaLabel` (`ACCESSIBILITY.md` §1).
+- A flat `FormSection` and `FormSectionHeader` render the title as an `<h5>`. Check
+  that the level fits the page outline; where it does not, leave `title` out
+  and put your own heading of the right level above the fields (WCAG 1.3.1;
+  KWCAG 5.2.4.2 제목 제공).
+- On submit, move focus to the first field with an error, or summarise the
+  errors at the top (WCAG 3.3.1).
+
+## Tokens
+
+Form parts are layout. `FormFooter` uses `bg.surface` with a `border.subtle`
+top rule, `FormSection` `divider` uses `border.subtle`, and `FieldError` uses
+`danger.fg`. Section descriptions and `FieldLabel` descriptions are
+`fg.muted`.
+
+## Related
+
+- **FormControl** / **FormLabel**: the primitives under `FieldRow`.
+- **FormIntegration**: wiring these to Formik or React Hook Form.
+- **Modal**: `FormModalFooter` sits in `ModalFooter`.
+
+</En>
+
+<Ko>
+
+## 문구
+
+- 섹션 제목은 명사로 씁니다(기본 정보, 동작). 필드 문구 규칙은 Input과 Select 페이지에
+  있습니다.
+- 푸터 버튼에는 결과를 씁니다(저장, 만들기, 그룹 삭제). 디자인 시스템은 문구를 가지지
+  않으므로 `cancelLabel`, `submitLabel`, `deleteLabel`은 앱의 번역에서 넘깁니다.
+- `meta`에는 지시가 아니라 사실을 씁니다. 예: 오후 2:14에 저장됨, 10 크레딧.
+
+## 접근성
+
+이 부품들이 알아서 하는 일
+
+- `FieldRow`는 라벨을 연결하고, `error`가 있으면 `aria-invalid`를 붙이며, 도움말과 오류
+  문구를 `aria-describedby`로 가리킵니다. `required`를 주면 별표가 보이고 컨트롤도 필수로
+  표시됩니다.
+- `FormModalFooter`는 `<form>` 안에서 제출 버튼을 `type="submit"`으로 두어 Enter로
+  제출되게 합니다. `onSubmit`은 포털로 그려지거나 `<form>`이 없는 모달에서만 넘깁니다.
+  `isSubmitting`이면 모든 버튼이 비활성이 되어 요청 중에 모달이 닫히지 않습니다.
+- `hasError`인 `FormSection`이 접혀 있으면 펼침 화살표 대신 위험 표시가 보여 숨은
+  오류를 놓치지 않습니다.
+
+직접 챙겨야 하는 일
+
+- **`FieldRow`가 닿지 않는 컨트롤에는 따로 이름을 줍니다.** `SelectField`,
+  `ComboboxField`, `Slider`는 자기 라벨 부품에서 이름을 가져오므로 행의 라벨을
+  `ariaLabel`로 넘깁니다(`ACCESSIBILITY.md` 1절).
+- 펼친 `FormSection`과 `FormSectionHeader`는 제목을 `<h5>`로 그립니다. 그 수준이 화면 구조에
+  맞는지 확인하고, 맞지 않으면 `title`을 비우고 필드 위에 알맞은 수준의 제목을 직접
+  둡니다(WCAG 1.3.1, KWCAG 5.2.4.2 제목 제공).
+- 제출할 때 오류가 있으면 첫 오류 필드로 초점을 옮기거나 위쪽에 오류를 모아 보여
+  줍니다(WCAG 3.3.1).
+
+## 토큰
+
+Form 부품은 배치용입니다. `FormFooter`는 `bg.surface`에 `border.subtle` 윗선을,
+`FormSection`의 `divider`는 `border.subtle`을, `FieldError`는 `danger.fg`를 씁니다.
+섹션 설명과 `FieldLabel` 설명은 `fg.muted`입니다.
+
+## 관련 컴포넌트
+
+- **FormControl** / **FormLabel**: `FieldRow` 아래의 기본 부품.
+- **FormIntegration**: Formik이나 React Hook Form과 연결하기.
+- **Modal**: `FormModalFooter`는 `ModalFooter` 안에 들어갑니다.
+
+</Ko>

package/src/components/Form/FormModalFooter/FormModalFooter.types.ts

@@ -25,7 +25,10 @@ export interface FormModalFooterProps extends Omit<
   cancelLabel: ReactNode;
   /** Primary submit button label. */
   submitLabel: ReactNode;
-  /** Palette for the primary button. Defaults to `primary`. */
+  /**
+   * @deprecated 5.0 Button has no colour palette. Only `'danger'` changes
+   * anything (a danger submit button); every other value renders `primary`.
+   */
   submitColorPalette?: ButtonColorPalette;
   /**
    * In-flight state — shows the submit spinner and disables every button so the

package/src/components/FormControl/FormControl.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from '@storybook/react';
 import { Stack } from '@chakra-ui/react';
 
+import { FieldError, FieldRow } from '../Form';
 import { FormLabel } from '../FormLabel';
 import { Input } from '../Input';
 import { FormControl } from './FormControl';
@@ -76,3 +77,37 @@ export const ReadOnly: Story = {
     </FormControl>
   ),
 };
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FormControl.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoFieldRowFirst: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: FieldRow for the common field',
+  render: () => (
+    <Stack w="320px">
+      <FieldRow
+        label="표시 이름"
+        helperText="다른 멤버에게 보이는 이름입니다."
+        error="이름을 입력해 주세요."
+        required
+      >
+        <Input />
+      </FieldRow>
+    </Stack>
+  ),
+};
+
+export const DoInvalidOnTheField: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: invalid on FormControl',
+  render: () => (
+    <FormControl invalid required w="320px">
+      <FormLabel>업무용 이메일</FormLabel>
+      <Input type="email" value="name@company" onChange={() => {}} />
+      <FieldError>이메일 주소 형식이 아닙니다.</FieldError>
+    </FormControl>
+  ),
+};