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

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>
+  ),
+};

package/src/components/FormControl/FormControl.usage.mdx

@@ -0,0 +1,128 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormControlStories from './FormControl.stories';
+
+<Meta of={FormControlStories} name="Usage" />
+
+<LangToggle />
+
+<En>
+
+# FormControl
+
+Chakra's `Field.Root` under the design-system name: the wrapper that shares one
+field's id and state with its label, control, helper and error.
+
+## When to use
+
+- A field layout `FieldRow` does not cover, built from `FormLabel`, a control,
+  `FieldHelp` and `FieldError`.
+- Wrapping a control so a parent can set `required`, `invalid`, `disabled` or
+  `readOnly` once.
+
+## When not to use
+
+- A standard field → `FieldRow`, which is `FormControl` with the label, helper
+  and error already laid out.
+
+## Props
+
+`required`, `invalid`, `disabled` and `readOnly` (plus every `Field.Root`
+prop). The state reaches `Input`, `Textarea` and `PasswordInput` through
+Chakra's field context, together with the id the label points at and the
+`aria-describedby` for helper and error text. Composed controls (`SelectField`,
+`ComboboxField`, `Slider`) take their name from their own label part, so give
+them `label` or `ariaLabel` and pass `invalid` / `disabled` to them directly.
+
+## Do / Don't
+
+</En>
+
+<Ko>
+
+# FormControl
+
+Chakra `Field.Root`를 디자인 시스템 이름으로 내보낸 것입니다. 필드 하나의 id와 상태를
+라벨, 컨트롤, 도움말, 오류 문구에 나눠 주는 래퍼입니다.
+
+## 언제 쓰나요
+
+- `FieldRow`로 안 되는 필드 배치를 `FormLabel`, 컨트롤, `FieldHelp`, `FieldError`로
+  직접 짤 때.
+- 상위에서 `required`, `invalid`, `disabled`, `readOnly`를 한 번에 정하려고 컨트롤을
+  감쌀 때.
+
+## 언제 쓰지 않나요
+
+- 일반적인 필드는 `FieldRow`를 씁니다. 라벨, 도움말, 오류 문구가 이미 배치된
+  `FormControl`입니다.
+
+## 속성
+
+`required`, `invalid`, `disabled`, `readOnly`(그리고 `Field.Root`의 모든 속성)를
+받습니다. 이 상태는 Chakra의 필드 컨텍스트를 타고 `Input`, `Textarea`,
+`PasswordInput`에 전달되며, 라벨이 가리키는 id와 도움말·오류 문구용
+`aria-describedby`도 함께 전달됩니다. 부품을 조합한 컨트롤(`SelectField`,
+`ComboboxField`, `Slider`)은 자기 라벨 부품에서 이름을 가져오므로 `label`이나
+`ariaLabel`을 주고, `invalid`·`disabled`도 컨트롤에 직접 넘깁니다.
+
+## 이렇게 하세요 / 이렇게 하지 마세요
+
+</Ko>
+
+<Canvas of={FormControlStories.DoFieldRowFirst} />
+<Verdict
+  kind="do"
+  en="Reach for FieldRow first. It is FormControl with the label, help and error placed for you."
+  ko="먼저 FieldRow를 씁니다. 라벨, 도움말, 오류 문구를 알아서 배치한 FormControl입니다."
+/>
+
+<Canvas of={FormControlStories.DoInvalidOnTheField} />
+<Verdict
+  kind="do"
+  en="When you compose by hand, set invalid on FormControl, not on the Input, and add a FieldError with the reason."
+  ko="직접 조합할 때는 invalid를 Input이 아니라 FormControl에 주고, 이유를 적은 FieldError를 함께 둡니다."
+/>
+
+<En>
+
+## Accessibility
+
+- `invalid` on `FormControl` sets `aria-invalid` on the input; `invalid` on
+  `Input` only paints the border (WCAG 3.3.1, 4.1.2).
+- `required` marks the input required and shows the asterisk in `FormLabel`.
+  Say "required" in words somewhere on the form too; an asterisk alone is a
+  symbol not everyone knows (WCAG 3.3.2).
+
+## Tokens
+
+None. FormControl draws nothing; the label colours are on the FormLabel page.
+
+## Related
+
+- **FieldRow**: the laid-out field.
+- **FormLabel**, **FieldHelp**, **FieldError**: the parts.
+
+</En>
+
+<Ko>
+
+## 접근성
+
+- `FormControl`의 `invalid`는 입력란에 `aria-invalid`를 붙이고, `Input`의 `invalid`는
+  테두리만 칠합니다(WCAG 3.3.1, 4.1.2).
+- `required`는 입력란을 필수로 표시하고 `FormLabel`에 별표를 보여 줍니다. 별표는 모두가
+  아는 기호가 아니므로 폼 어딘가에 "필수"라고 글자로도 적습니다(WCAG 3.3.2).
+
+## 토큰
+
+없습니다. FormControl은 아무것도 그리지 않습니다. 라벨 색은 FormLabel 페이지에
+있습니다.
+
+## 관련 컴포넌트
+
+- **FieldRow**: 배치까지 된 필드.
+- **FormLabel**, **FieldHelp**, **FieldError**: 부품.
+
+</Ko>

package/src/components/FormIntegration/FormIntegration.usage.mdx

@@ -0,0 +1,158 @@
+import { Canvas, Meta } from '@storybook/blocks';
+
+import { En, Ko, LangToggle, Verdict } from '../../guidelines/_components/Lang';
+import * as FormIntegrationStories from './FormIntegration.stories';
+
+<Meta title="Components/FormIntegration/Usage" />
+
+<LangToggle />
+
+<En>
+
+# Form integration
+
+How the form controls connect to a form library. There is no
+`FormIntegration` component: this page and the stories under
+**Examples/Form Integration** show the wiring.
+
+## The rule
+
+Put field state on the field, not on the control:
+
+1. One `FieldRow` (or `FormControl`) per field. Set `error` on it from the
+   library's error for that field; `invalid` follows, and `aria-invalid` and
+   `aria-describedby` reach the control.
+2. Pass the library's `value`, `onChange`, `onBlur` and `name` to the control.
+   `Input` re-emits change and blur events with `name` and the processed value
+   (trimmed, or digits only with `maskNumber`), so Formik's `handleChange` and
+   React Hook Form's `field.onChange` both work.
+3. Controls with their own value API take it directly: `SelectField` /
+   `ComboboxField` `onChange(value)`, `RadioGroup` `onValueChange`, `Checkbox`
+   / `Switch` `onCheckedChange`, `Slider` `onValueChange` (an array),
+   `FileInput` `onChange(files)`. With React Hook Form, wrap them in a
+   `Controller`.
+
+## When to use which library
+
+- **React Hook Form** with a `Controller` per non-text control: what FactChat
+  uses for admin and studio forms.
+- **Formik + Yup**: the first example below.
+- **Plain state**: small forms, the second example.
+
+## Examples
+
+</En>
+
+<Ko>
+
+# 폼 연동
+
+폼 컨트롤을 폼 라이브러리에 연결하는 방법입니다. `FormIntegration`이라는 컴포넌트는
+없습니다. 이 페이지와 **Examples/Form Integration** 아래 스토리가 연결 방법을 보여
+줍니다.
+
+## 원칙
+
+필드 상태는 컨트롤이 아니라 필드에 둡니다.
+
+1. 필드마다 `FieldRow`(또는 `FormControl`)를 하나씩 둡니다. 라이브러리가 그 필드에
+   대해 준 오류를 `error`에 넣으면 `invalid`도 따라 바뀌고, `aria-invalid`와
+   `aria-describedby`가 컨트롤까지 전달됩니다.
+2. 라이브러리의 `value`, `onChange`, `onBlur`, `name`을 컨트롤에 넘깁니다. `Input`은
+   변경·이탈 이벤트를 `name`과 가공한 값(공백을 정리한 값, `maskNumber`면 숫자만)으로
+   다시 만들어 보내므로 Formik의 `handleChange`와 React Hook Form의 `field.onChange`가
+   모두 동작합니다.
+3. 값을 다루는 방식이 따로 있는 컨트롤은 그 방식을 그대로 씁니다. `SelectField`·
+   `ComboboxField`는 `onChange(value)`, `RadioGroup`은 `onValueChange`, `Checkbox`·
+   `Switch`는 `onCheckedChange`, `Slider`는 `onValueChange`(배열), `FileInput`은
+   `onChange(files)`입니다. React Hook Form에서는 `Controller`로 감쌉니다.
+
+## 어떤 라이브러리를 쓰나요
+
+- **React Hook Form**과 텍스트가 아닌 컨트롤마다 `Controller`: FactChat의 관리자·
+  스튜디오 폼이 쓰는 방식입니다.
+- **Formik + Yup**: 아래 첫 번째 예시.
+- **일반 상태**: 작은 폼. 아래 두 번째 예시.
+
+## 예시
+
+</Ko>
+
+<Canvas of={FormIntegrationStories.FormikFormExample} />
+<Verdict
+  kind="do"
+  en="Formik: the error for each field goes to that field's Field.Root, and the message renders under it."
+  ko="Formik: 필드마다 오류를 그 필드의 Field.Root에 넘기고, 문구는 필드 바로 아래에 그립니다."
+/>
+
+<Canvas of={FormIntegrationStories.RegularFormExample} />
+<Verdict
+  kind="do"
+  en="Plain state: validate on submit, keep errors in state per field, and clear a field's error when it changes."
+  ko="일반 상태: 제출할 때 검사하고, 오류는 필드별로 상태에 두며, 값이 바뀌면 그 필드의 오류를 지웁니다."
+/>
+
+<En>
+
+## Pitfalls
+
+- **`trimWhiteSpace` trims on every keystroke**, so a name with a space can
+  only be pasted. Trim at submit instead.
+- **`maskNumber` needs `type="number"`** and then renders a text input; `min`
+  and `max` do nothing there. Validate the range in the schema.
+- **`SelectField` inside `FieldRow` needs `ariaLabel`** with the row's label;
+  the row's label does not name it.
+- **Don't set `invalid` on the control alone.** It paints the border without
+  telling assistive technology (WCAG 3.3.1).
+
+## Accessibility
+
+- Every field has a visible label (WCAG 3.3.2; KWCAG 5.3.4.1 레이블 제공), and
+  every error is text under its field (WCAG 3.3.1).
+- After a failed submit, move focus to the first invalid field or to an error
+  summary at the top.
+- Do not disable the submit button until the form is valid without saying
+  why; the user cannot find out what is missing. Validate on submit and show
+  the errors.
+
+## Tokens
+
+None of its own; see Input, Select and Form.
+
+## Related
+
+- **Form** (`FieldRow`, `FormSection`, footers), **FormControl**, **Input**,
+  **Select**.
+
+</En>
+
+<Ko>
+
+## 자주 하는 실수
+
+- **`trimWhiteSpace`는 입력할 때마다 공백을 지웁니다.** 그래서 공백이 든 이름은 붙여
+  넣기로만 넣을 수 있습니다. 공백 정리는 제출할 때 합니다.
+- **`maskNumber`는 `type="number"`가 있어야 동작하고**, 그때는 텍스트 입력란을 그립니다.
+  `min`과 `max`는 효과가 없으므로 범위는 스키마에서 검사합니다.
+- **`FieldRow` 안의 `SelectField`에는 행의 라벨을 `ariaLabel`로 넘깁니다.** 행의 라벨은
+  셀렉트의 이름이 되지 않습니다.
+- **컨트롤에만 `invalid`를 주지 않습니다.** 테두리만 칠하고 보조기술에는 알리지
+  않습니다(WCAG 3.3.1).
+
+## 접근성
+
+- 모든 필드에 보이는 라벨을 두고(WCAG 3.3.2, KWCAG 5.3.4.1 레이블 제공), 모든 오류는 해당
+  필드 아래에 문구로 보여 줍니다(WCAG 3.3.1).
+- 제출에 실패하면 첫 오류 필드나 위쪽의 오류 요약으로 초점을 옮깁니다.
+- 이유를 알리지 않은 채 폼이 유효해질 때까지 제출 버튼을 비활성으로 두지 않습니다.
+  무엇이 빠졌는지 알 수 없습니다. 제출할 때 검사하고 오류를 보여 줍니다.
+
+## 토큰
+
+따로 정한 토큰이 없습니다. Input, Select, Form 페이지를 보세요.
+
+## 관련 컴포넌트
+
+- **Form**(`FieldRow`, `FormSection`, 푸터), **FormControl**, **Input**, **Select**.
+
+</Ko>

package/src/components/FormLabel/FormLabel.stories.tsx

@@ -0,0 +1,71 @@
+import { Stack } from '@chakra-ui/react';
+import type { Meta, StoryObj } from '@storybook/react';
+
+import { FormControl } from '../FormControl';
+import { Input } from '../Input';
+import { FormLabel } from './FormLabel';
+
+const meta = {
+  title: 'Components/FormLabel',
+  component: FormLabel,
+  parameters: { layout: 'centered' },
+} satisfies Meta<typeof FormLabel>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+/** A label inside `FormControl`; it is associated with the control for you. */
+export const Basic: Story = {
+  render: () => (
+    <FormControl w="300px">
+      <FormLabel>표시 이름</FormLabel>
+      <Input placeholder="홍길동" />
+    </FormControl>
+  ),
+};
+
+/** `required` on `FormControl` adds the asterisk; nothing to pass here. */
+export const Required: Story = {
+  render: () => (
+    <FormControl required w="300px">
+      <FormLabel>업무용 이메일</FormLabel>
+      <Input type="email" />
+    </FormControl>
+  ),
+};
+
+// ───────────────────────── Usage-page specimens ─────────────────────────
+// Pulled into `FormLabel.usage.mdx` with <Canvas of={…} />. Hidden (`!dev`).
+
+export const DoNounLabels: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: 'Usage / Do: short noun labels',
+  render: () => (
+    <Stack gap={4} maxW="320px">
+      <FormControl required>
+        <FormLabel>그룹 이름</FormLabel>
+        <Input />
+      </FormControl>
+      <FormControl>
+        <FormLabel>설명</FormLabel>
+        <Input />
+      </FormControl>
+    </Stack>
+  ),
+};
+
+export const DontSentenceLabels: Story = {
+  tags: ['!dev'],
+  parameters: { layout: 'padded' },
+  name: "Usage / Don't: instructions as labels",
+  render: () => (
+    <Stack gap={4} maxW="320px">
+      <FormControl required>
+        <FormLabel>그룹 이름을 입력해 주세요 (필수):</FormLabel>
+        <Input />
+      </FormControl>
+    </Stack>
+  ),
+};