@highpixel-co/palda-design-system 0.6.0 → 0.8.0

package/dist/guide/docs/TOKEN_POLICY.md

@@ -7,7 +7,7 @@
 - 이름은 실제 값이 아니라 역할을 표현한다. 예: `color.action.primary.background`.
 - 컴포넌트 CSS에는 `var(--token)` 참조만 쓴다. 시안에 적힌 리터럴 값(`#54B336`, `36px`)을 그대로 옮기지 않는다.
 - 필요한 token이 없으면 추가하지 말고 먼저 확인받는다. 값을 지어내지 않는다. 과거에 있던 token이라도 복원은 확인 대상이다.
-- **값이 어긋나면 코드가 옳다.** 저장소가 SSOT이고([`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0001-design-system-ssot.md), 자산별 경계는 [`decisions/0016`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0016-asset-ssot-boundary.md)), Figma와 다른 자리는 코드를 고치지 않고 [`FIGMA_ALIGNMENT_DELTA.md`](FIGMA_ALIGNMENT_DELTA.md)에 Figma가 바뀌어야 할 목록으로 적는다. 이름이 어긋나는 자리는 [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 있다.
+- **값이 어긋나면 코드가 옳다.** 저장소가 SSOT이고([`decisions/0001`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/docs/decisions/0001-design-system-ssot.md), 자산별 경계는 [`decisions/0016`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/docs/decisions/0016-asset-ssot-boundary.md)), Figma와 다른 자리는 코드를 고치지 않고 [`FIGMA_ALIGNMENT_DELTA.md`](FIGMA_ALIGNMENT_DELTA.md)에 Figma가 바뀌어야 할 목록으로 적는다. 이름이 어긋나는 자리는 [`FIGMA_NAME_MAPPING.md`](FIGMA_NAME_MAPPING.md)에 있다.
 - 저장소의 token 값은 확정치로 취급한다. 명도 대비 미달처럼 품질 문제를 발견하면 보고하되, 컴포넌트에서 다른 색으로 바꾸거나 값 변경을 반복해서 제안하지 않는다.
 - 보더 두께는 예외다. 시스템 전체가 항상 `1px`이며 token으로 만들지 않고 CSS에 직접 쓴다.
 - `tokens/generated/`는 직접 수정하지 않는다. `tokens/*.tokens.json`을 고치고 `pnpm tokens:build`로 다시 만든 뒤, 소스와 생성 파일을 함께 커밋한다. 생성 파일이 빠지면 `pnpm check:generated`가 실패한다.
@@ -178,7 +178,7 @@ focus에서 `border/focus`로 구분한다.
 `Card`·`ListRow`) 화면이 다시 고르는 것은 페이지 제목과 **본문 목록 여부** 둘이다.
 
 **행은 두 칸이고 그 목록이 화면의 본문인지가 고른다**
-([`decisions/0034`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0034-the-body-list-lifts-one-step.md)). 곁·요약·참조 나열은 제목
+([`decisions/0034`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/docs/decisions/0034-the-body-list-lifts-one-step.md)). 곁·요약·참조 나열은 제목
 `body2`(14) + 설명 `label`(12) 그대로이고, 선언서의 본문 문장이 가리키는 목록만 한 칸씩 올라가
 제목 `body1`(16) + 설명 `body2`(14)가 된다. `ListRow`의 `emphasis`가 그것이고 기본값은 올리지
 않는 쪽이다. **한 화면에 올린 목록은 하나다.**
@@ -227,11 +227,11 @@ DropdownButton은 `medium`이다.
 
 컨트롤은 `sm`, 컨테이너는 `md`, 큰 면은 `lg`가 기준이다. **목록의 행은 컨트롤이 아니라 `md`다** —
 행은 눌리는 컨트롤이 아니라 읽는 줄이고, 제목이 `line-height/100`이라 `sm`으로는 디바이더가 글자에
-붙는다([`decisions/0019`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0019-list-row-vertical-inset.md)).
+붙는다([`decisions/0019`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/docs/decisions/0019-list-row-vertical-inset.md)).
 
 **페이지를 조립하는 여백과 폭은 이 스케일이 아니라 `--layout-*`이다.** 컴포넌트 안쪽을 재는
 `--space-*`와 이름 공간이 갈라져 있다. 고르는 규칙은 [`LAYOUT.md`](LAYOUT.md), 근거는
-[`decisions/0008`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/docs/decisions/0008-layout-scale-separate-from-component-scale.md)에 있다.
+[`decisions/0008`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/docs/decisions/0008-layout-scale-separate-from-component-scale.md)에 있다.
 `gap/xl`이 layout이 아니라 여기 있는 것은 성격이 "요소 사이"로 같고 값도 이미 primitive에 있어서다.
 
 primitive를 직접 쓰는 자리가 둘 있다. focus 링의 `outline-offset`은 `space/1`을 쓴다. 안쪽도
@@ -259,7 +259,7 @@ primitive를 직접 쓰는 자리가 둘 있다. focus 링의 `outline-offset`
 
 `pnpm check:css`가 막는 것은 정의되지 않은 token 참조, `1px`이 아닌 보더·아웃라인 두께,
 `:focus-visible` 대신 쓴 `:focus` 셋이다. 위 표의 선택 규칙 자체는 검사하지 않으므로 사람과
-에이전트가 지킨다. 같은 실수가 반복되면 [`AGENTS.md`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/AGENTS.md) §항상의 "반복되는 오류는
+에이전트가 지킨다. 같은 실수가 반복되면 [`AGENTS.md`](https://github.com/highpixel-co/palda-design-system/blob/abee826d0afda16bd3776f015931e0a820a8876e/AGENTS.md) §항상의 "반복되는 오류는
 검사로 승격한다"에 따라 검사로 올린다.
 
 시안에 없는 값은 임의로 정하지 않고 확인받는다. 위 표에서 아직 쓰는 곳이 없다고 적힌 항목은

package/dist/harness/check.mjs

@@ -1,8 +1,8 @@
 import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs';
-import { dirname, isAbsolute, join, relative, resolve } from 'node:path';
+import { basename, dirname, isAbsolute, join, relative, resolve } from 'node:path';
 import yaml from 'js-yaml';
 import ts from 'typescript';
-import { validateScreenHtml } from '../scripts/check-examples.mjs';
+import { siblingIndex, validateScreenHtml } from '../scripts/check-examples.mjs';
 
 const PACKAGE = '@highpixel-co/palda-design-system';
 const EXCEPTION_RULES = ['primitive-import', 'icon-import', 'opaque-import'];
@@ -316,15 +316,21 @@ export function checkScreens(projectRoot, config) {
   const root = resolve(projectRoot);
   validateConfig(root, config);
   const scan = collect(root, config.screens ?? ['preview'], (name) => name.endsWith('.html'));
-  const problems = scan.files.flatMap((fullPath) => {
-    const file = normalize(relative(root, fullPath));
-    return validateScreenHtml(readFileSync(fullPath, 'utf8'), file, true).map((message) => ({
+  // 자매 대조는 짝이 필요해서 전부 읽어 색인을 만든 뒤에 검사한다.
+  const screens = scan.files.map((fullPath) => ({
+    name: basename(fullPath, '.html'),
+    source: readFileSync(fullPath, 'utf8'),
+    file: normalize(relative(root, fullPath)),
+  }));
+  const siblings = siblingIndex(screens);
+  const problems = screens.flatMap(({ source, file }) =>
+    validateScreenHtml(source, file, true, siblings).map((message) => ({
       file,
       line: 1,
       rule: 'screen',
       symbol: '',
       message,
-    }));
-  });
+    })),
+  );
   return { files: scan.files.length, excluded: scan.excluded, exceptions: 0, drafts: [], problems };
 }

package/dist/harness/metadata.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
-  "packageVersion": "0.6.0",
-  "sourceRevision": "ad23980481cd81dcf09a1044504d2295f0e4a0f3",
+  "packageVersion": "0.8.0",
+  "sourceRevision": "abee826d0afda16bd3776f015931e0a820a8876e",
   "exports": {
     ".": {
       "values": [
@@ -73,6 +73,7 @@
         "SearchIcon",
         "SendIcon",
         "ShieldCheckIcon",
+        "Skeleton",
         "SlidersIcon",
         "SmartphoneIcon",
         "SparklesIcon",
@@ -82,6 +83,7 @@
         "Switch",
         "Tab",
         "TextField",
+        "Thumbnail",
         "ThumbsUpIcon",
         "TimerIcon",
         "Toaster",
@@ -130,14 +132,21 @@
         "ModalActionsProps",
         "ModalProps",
         "NavigationButtonProps",
+        "NavigationButtonSize",
         "ProgressBarProps",
         "RadioProps",
+        "SkeletonProps",
+        "SkeletonShape",
+        "SkeletonText",
+        "SkeletonWidth",
         "SwitchProps",
         "SwitchSize",
         "TabProps",
         "TextFieldProps",
         "TextFieldSize",
         "TextFieldVariant",
+        "ThumbnailProps",
+        "ThumbnailSize",
         "ToastOptions",
         "ToastVariant",
         "ToasterPlacement",
@@ -161,9 +170,11 @@
         "NavigationButton",
         "ProgressBar",
         "Radio",
+        "Skeleton",
         "Switch",
         "Tab",
         "TextField",
+        "Thumbnail",
         "Toaster",
         "Tooltip",
         "toast"
@@ -194,14 +205,21 @@
         "ModalActionsProps",
         "ModalProps",
         "NavigationButtonProps",
+        "NavigationButtonSize",
         "ProgressBarProps",
         "RadioProps",
+        "SkeletonProps",
+        "SkeletonShape",
+        "SkeletonText",
+        "SkeletonWidth",
         "SwitchProps",
         "SwitchSize",
         "TabProps",
         "TextFieldProps",
         "TextFieldSize",
         "TextFieldVariant",
+        "ThumbnailProps",
+        "ThumbnailSize",
         "ToastOptions",
         "ToastVariant",
         "ToasterPlacement",
@@ -589,6 +607,14 @@
         "Radio"
       ]
     },
+    {
+      "key": "skeleton",
+      "kind": "ui",
+      "status": "draft",
+      "exports": [
+        "Skeleton"
+      ]
+    },
     {
       "key": "switch",
       "kind": "ui",
@@ -613,6 +639,14 @@
         "TextField"
       ]
     },
+    {
+      "key": "thumbnail",
+      "kind": "ui",
+      "status": "draft",
+      "exports": [
+        "Thumbnail"
+      ]
+    },
     {
       "key": "toast",
       "kind": "ui",

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 export { AlarmIcon, AlertIcon, ArrowLeftIcon, ArrowRightIcon, BlankIcon, CableIcon, CameraIcon, CardIcon, CheckIcon, ChevronDownIcon, ChevronLeftIcon, ChevronRightIcon, ChevronUpIcon, CloseIcon, CopyIcon, DashboardIcon, ExternalLinkIcon, EyeIcon, EyeOffIcon, FilterIcon, GiftIcon, HelpIcon, HistoryIcon, HomeIcon, ImageIcon, InfoIcon, KeyIcon, LightbulbIcon, LinkIcon, LoadingIcon, LockIcon, LogoutIcon, MenuIcon, MessageIcon, MonitorIcon, MoreVerticalIcon, MousePointerClickIcon, PauseIcon, PencilIcon, PersonIcon, PhoneIcon, PlusIcon, ProductIcon, RefreshIcon, ReportIcon, SearchIcon, SendIcon, ShieldCheckIcon, SlidersIcon, SmartphoneIcon, SparklesIcon, StarIcon, StoreIcon, SuccessIcon, ThumbsUpIcon, TimerIcon, TrashIcon, TrendingUpIcon, TruckIcon, TypeIcon, UnplugIcon, UploadIcon } from './icons.js';
 export { AppShell, AppShellProps, BottomBar, BottomBarProps, Card, CardProps, CardTone, EmptyState, EmptyStateProps, FormSection, FormSectionProps, ListRow, ListRowEmphasis, ListRowProps, LivePreview, LivePreviewProps, LivePreviewStatus } from './patterns.js';
-export { Alert, AlertProps, AlertVariant, Badge, BadgeProps, BadgeSize, BadgeVariant, Button, ButtonProps, ButtonSize, ButtonVariant, Checkbox, CheckboxProps, Chip, ChipProps, ChipSize, ChipVariant, DropdownButton, DropdownButtonAlign, DropdownButtonItem, DropdownButtonProps, DropdownButtonVariant, IconButton, IconButtonProps, IconButtonSize, IconButtonVariant, Link, LinkProps, LinkSize, LinkVariant, Modal, ModalActions, ModalActionsProps, ModalProps, NavigationButton, NavigationButtonProps, ProgressBar, ProgressBarProps, Radio, RadioProps, Switch, SwitchProps, SwitchSize, Tab, TabProps, TextField, TextFieldProps, TextFieldSize, TextFieldVariant, ToastOptions, ToastVariant, Toaster, ToasterPlacement, ToasterProps, Tooltip, TooltipPlacement, TooltipProps, toast } from './ui.js';
+export { Alert, AlertProps, AlertVariant, Badge, BadgeProps, BadgeSize, BadgeVariant, Button, ButtonProps, ButtonSize, ButtonVariant, Checkbox, CheckboxProps, Chip, ChipProps, ChipSize, ChipVariant, DropdownButton, DropdownButtonAlign, DropdownButtonItem, DropdownButtonProps, DropdownButtonVariant, IconButton, IconButtonProps, IconButtonSize, IconButtonVariant, Link, LinkProps, LinkSize, LinkVariant, Modal, ModalActions, ModalActionsProps, ModalProps, NavigationButton, NavigationButtonProps, NavigationButtonSize, ProgressBar, ProgressBarProps, Radio, RadioProps, Skeleton, SkeletonProps, SkeletonShape, SkeletonText, SkeletonWidth, Switch, SwitchProps, SwitchSize, Tab, TabProps, TextField, TextFieldProps, TextFieldSize, TextFieldVariant, Thumbnail, ThumbnailProps, ThumbnailSize, ToastOptions, ToastVariant, Toaster, ToasterPlacement, ToasterProps, Tooltip, TooltipPlacement, TooltipProps, toast } from './ui.js';
 import 'react';

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   FormSection,
   ListRow,
   LivePreview
-} from "./chunk-QW2SD3XV.js";
+} from "./chunk-3OXUONDZ.js";
 import "./chunk-EYFL232L.js";
 import {
   Alert,
@@ -23,13 +23,15 @@ import {
   NavigationButton,
   ProgressBar,
   Radio,
+  Skeleton,
   Switch,
   Tab,
   TextField,
+  Thumbnail,
   Toaster,
   Tooltip,
   toast
-} from "./chunk-6JZPK2W5.js";
+} from "./chunk-PWAQFOM3.js";
 import {
   AlarmIcon,
   AlertIcon,
@@ -163,6 +165,7 @@ export {
   SearchIcon,
   SendIcon,
   ShieldCheckIcon,
+  Skeleton,
   SlidersIcon,
   SmartphoneIcon,
   SparklesIcon,
@@ -172,6 +175,7 @@ export {
   Switch,
   Tab,
   TextField,
+  Thumbnail,
   ThumbsUpIcon,
   TimerIcon,
   Toaster,

package/dist/patterns.d.ts

@@ -95,6 +95,7 @@ interface EmptyStateProps {
 }
 declare function EmptyState({ actionLabel, description, icon, onAction, title }: EmptyStateProps): react.JSX.Element;
 
+type FormSectionTone = 'plain' | 'filled';
 interface FormSectionProps {
     children: ReactNode;
     description?: ReactNode;
@@ -103,14 +104,24 @@ interface FormSectionProps {
     /** 섹션 아래 액션. 저장·초기화 버튼을 넣는다. */
     footer?: ReactNode;
     title: ReactNode;
+    /**
+     * 섹션 내용의 채움. `Card`·`ListRow`의 `tone`과 같은 축이고 같은 값이다.
+     * - `plain`(기본) — 면이 없다. 제목과 여백만으로 갈린다.
+     * - `filled` — **내용(`children`)만** 옅은 회색 필에 담는다. 제목·설명·오류·footer는 캔버스에
+     *   남는다. 섹션이 여럿 쌓여 제목과 여백만으로 묶음이 안 갈릴 때 쓴다.
+     */
+    tone?: FormSectionTone;
 }
 /**
  * 입력 필드를 제목 아래로 묶는 폼의 한 덩어리다.
  *
  * 필드 사이 간격만 잡고 필드 자체는 그리지 않는다. 라벨과 컨트롤의 간격은 `TextField`가 갖고
  * 있으므로 여기서 다시 주지 않는다.
+ *
+ * `tone="filled"`은 내용만 면에 담고 제목은 캔버스에 남긴다. 제목까지 담으면 곁(0032)과 같은
+ * 모양이 되어 곁이 본문에 흡수되기 때문이다. 갈래 셋의 비교는 `preview/section-fill.html`에 있다.
  */
-declare function FormSection({ children, description, error, footer, title }: FormSectionProps): react.JSX.Element;
+declare function FormSection({ children, description, error, footer, title, tone, }: FormSectionProps): react.JSX.Element;
 
 type ListRowEmphasis = 'default' | 'strong';
 interface ListRowProps {

package/dist/patterns.js

@@ -6,8 +6,8 @@ import {
   FormSection,
   ListRow,
   LivePreview
-} from "./chunk-QW2SD3XV.js";
-import "./chunk-6JZPK2W5.js";
+} from "./chunk-3OXUONDZ.js";
+import "./chunk-PWAQFOM3.js";
 import "./chunk-TWYJ2UTC.js";
 export {
   AppShell,

package/dist/scripts/check-examples.mjs

@@ -31,7 +31,7 @@
  * (`docs/DESIGN_GRAMMAR.md` §자리는 시스템이 정하지 않는다).
  */
 import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { basename, dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 const DEFAULT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
@@ -94,6 +94,46 @@ const FORM_SECTION_CLASS = 'palda-form-section';
 const SECTION_FAILURE_CLASS = 'palda-form-section__error';
 const ROW_FAILURE_CLASS = 'palda-badge--danger';
 
+/**
+ * 본문을 여러 묶음으로 가르는 축 (`decisions/0023`·`0037`). 선언서가 밝히고 마크업이 따라온다.
+ *
+ * 같은 종류가 여러 갈래로 나뉘면 `탭`이고, 서로 다른 종류가 나열되면 `섹션`이다. 판정은 사람이
+ * 하지만 **고른 결과와 마크업이 어긋나는 것**은 셀 수 있다 — 갈래를 제목 여러 개로 세워 놓고
+ * 탭이라 적거나, 탭을 그려 놓고 섹션이라 적는 경우다.
+ */
+const GROUPING_LABEL = '갈래';
+const GROUPING_VALUES = ['탭', '섹션', '탭+섹션', '없음'];
+const TABLIST = /role\s*=\s*"tablist"/;
+/** 섹션 하나를 여는 자리. `--plain`·`--filled`가 붙어도 한 번만 센다. */
+const SECTION_OPEN = /class="palda-form-section[\s"]/g;
+
+/**
+ * 섹션의 채움 (`decisions/0037`). 면은 갈라야 할 형제가 있을 때만 켜고, 면 위에 다른 면을
+ * 얹지 않는다. 요약 행(`ListRow tone="filled"`)은 컴포넌트가 스스로 한 단계 올리므로 여기서
+ * 세지 않는다 — 세는 것은 **면이 스스로 못 피하는 겹침**뿐이다.
+ */
+const SECTION_FILLED_CLASS = 'palda-form-section--filled';
+const NESTED_SURFACE_CLASS = 'palda-card';
+
+/**
+ * 면을 켜야 하는데 안 켠 자리 (`decisions/0037`).
+ *
+ * 0037은 "제목과 여백만으로 안 갈릴 때"를 조건으로 두고, §적용에서 그 갈림을 못 센다고 남겨
+ * 뒀다. 몇 px 차이부터 안 갈리는지 수치가 없어서다. **다만 차이가 0인 경우는 셀 수 있다** —
+ * 섹션 제목과 그 안 행 제목이 같은 텍스트 스타일 클래스를 그대로 쓰고 있으면, 갈릴 여지가
+ * 애초에 없다.
+ *
+ * 0034를 적용해 본문 목록을 한 칸 올린 화면(`emphasis="strong"` → 제목 `body1`)이 전부 이
+ * 상태가 된다. 섹션 제목도 `body1`이라 두 글자가 문자열까지 같아진다. 2026-09-06 연동 도우미
+ * 시안이 그렇게 나왔고, 0037이 예로 든 내 계정 화면(16 대 14)보다 심한 판이라 승격했다.
+ *
+ * 2px 차이는 여전히 못 센다. 그것은 리뷰가 본다.
+ */
+const TYPOGRAPHY_CLASS = /\bpalda-text-[a-z0-9-]+\b/;
+const SECTION_HEADING_CLASS = /palda-form-section__header[\s\S]*?<h2[^>]*\bclass="([^"]*)"/;
+const SECTION_FIELDS_CLASS = 'palda-form-section__fields';
+const SECTION_FOOTER_CLASS = 'palda-form-section__footer';
+
 /** 닫는 태그가 없는 요소. 깊이를 올리지 않는다. */
 const VOID_ELEMENTS = new Set([
   'area',
@@ -144,18 +184,36 @@ function checkDeclaration(rows, where, problems) {
     problems.push(`${where}: 주 액션이 ${primary.length}개다 — 자리는 하나다`);
   } else if (!PRIMARY_ACTION_PLACES.has(primary[0].value)) {
     problems.push(
-      `${where}: 주 액션 자리가 \`${primary[0].value}\`다 — ${[...PRIMARY_ACTION_PLACES]
+      `${where}: 주 액션 자리가 \`${primary[0].value}\`이다 — ${[...PRIMARY_ACTION_PLACES]
         .map((place) => `\`${place}\``)
         .join(' 또는 ')} 중 하나여야 한다`,
     );
   }
 
+  /** 본문을 무엇으로 가르는지. 적는 행위가 탭이냐 섹션이냐의 판단을 남긴다 (0023). */
+  const grouping = rows.filter((row) => row.label === GROUPING_LABEL);
+  if (grouping.length === 0) {
+    problems.push(
+      `${where}: 선언서에 \`${GROUPING_LABEL}\` 행이 없다 — ${GROUPING_VALUES.map((value) => `\`${value}\``).join('·')} 중 하나를 밝힌다`,
+    );
+  } else if (grouping.length > 1) {
+    problems.push(`${where}: ${GROUPING_LABEL}가 ${grouping.length}개다 — 축은 하나다`);
+  } else if (!GROUPING_VALUES.includes(grouping[0].value)) {
+    problems.push(
+      `${where}: ${GROUPING_LABEL}가 \`${grouping[0].value}\`이다 — ${GROUPING_VALUES.map((value) => `\`${value}\``).join('·')} 중 하나여야 한다`,
+    );
+  }
+
   /** `곁` 행에 `없음`이라고 적으면 곁이 0개라는 뜻이다. */
   const asides = rows
     .filter((row) => row.label === '곁')
     .filter((row) => row.value !== '' && row.value !== '없음');
 
-  return { declared: body.length > 0, asides: asides.length };
+  return {
+    declared: body.length > 0,
+    asides: asides.length,
+    grouping: grouping.length === 1 ? grouping[0].value : null,
+  };
 }
 
 /** 주석을 같은 길이의 공백으로 지운다. 주석 안의 예시 마크업이 태그로 세지지 않게 한다. */
@@ -270,7 +328,7 @@ function checkBlocks(blocks, declaredAsides, where, problems) {
     }
     if (!ROLES.includes(role)) {
       problems.push(
-        `${where}: 바디 ${index + 1}번째 블록의 data-screen-role이 \`${role}\`다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나여야 한다`,
+        `${where}: 바디 ${index + 1}번째 블록의 data-screen-role이 \`${role}\`이다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나여야 한다`,
       );
       roles.push(null);
       continue;
@@ -348,7 +406,169 @@ function htmlFiles(dir, out = []) {
   return out;
 }
 
-export function validateScreenHtml(source, where, requireScreen = false) {
+/**
+ * 화면의 섹션 이름. `FormSection`의 헤더에 있는 `h2`가 그것이다 — 화면이 무엇으로 나뉘는지를
+ * 사람이 읽는 자리와 같다. 주석 안의 예시 마크업은 세지 않으므로 주석을 먼저 지운다.
+ */
+const SECTION_HEADING = /palda-form-section__header[\s\S]*?<h2[^>]*>([^<]*)<\/h2>/g;
+
+/** 뒤에 붙는 개수 표기는 값이라 이름이 아니다 — `상품 템플릿 3/10`과 `상품 템플릿`은 같다. */
+const stripCount = (name) => name.replace(/\s*\d+\s*\/\s*\d+\s*$/, '').trim();
+
+function screenSections(source) {
+  return [...stripComments(source).matchAll(SECTION_HEADING)]
+    .map((match) => stripCount(match[1]))
+    .filter(Boolean);
+}
+
+/**
+ * 선언 주석에 등록한 자매와의 차이. `1. [섹션]` 또는 `1. [이쪽] ↔ [저쪽]` 형태다.
+ * 적는 행위가 판단을 남긴다 — 왜 갈라졌는지가 그 자리에 남아 다음에 다시 판단하지 않는다.
+ */
+const REGISTERED_DIFF = /^\s*\d+\.\s*\[([^\]]+)\](?:\s*↔\s*\[([^\]]+)\])?/gm;
+
+function registeredDiffs(source) {
+  return new Set(
+    [...source.matchAll(REGISTERED_DIFF)].flatMap((match) =>
+      [match[1], match[2]].filter(Boolean).map(stripCount),
+    ),
+  );
+}
+
+const siblingOf = (rows) => rows.find((row) => row.label === '자매')?.value || null;
+
+/**
+ * 자매로 선언한 두 화면의 섹션 집합을 비교한다 (`decisions/0036`).
+ * 차이를 금지하지 않고 **적지 않은 차이**를 막는다. 문자열 집합 비교라 판단이 들어가지 않는다.
+ */
+function checkSiblings(source, where, rows, siblings, problems) {
+  const name = siblingOf(rows);
+  if (!name) return;
+
+  const mate = siblings.get(name);
+  if (mate === undefined) {
+    problems.push(`${where}: 자매로 적은 \`${name}\`을 찾을 수 없다 — 같은 시안 디렉터리에 둔다`);
+    return;
+  }
+
+  // 짝이 맞는지는 상대의 `자매` 행이 나를 가리키는지다. 한쪽만 적으면 반대편이 모른다.
+  const self = basename(where, '.html');
+  const back = siblingOf(declarationRows(mate));
+  if (back !== self) {
+    problems.push(
+      `${where}: 자매 선언이 짝이 안 맞는다 — \`${name}\`의 자매는 \`${back ?? '없음'}\`이다. 양쪽 다 적는다`,
+    );
+    return;
+  }
+
+  const theirs = new Set(screenSections(mate));
+  const registered = registeredDiffs(source);
+  for (const section of screenSections(source)) {
+    if (theirs.has(section) || registered.has(section)) continue;
+    problems.push(
+      `${where}: 섹션 [${section}]이 자매(${name})에 없는데 선언에 등록되지 않았다 — 차이는 \`1. [${section}]\` 형태로 적는다`,
+    );
+  }
+}
+
+/**
+ * 선언한 갈래와 마크업이 맞는지 (0023). 탭 줄은 `role="tablist"`로, 섹션 나열은 형제
+ * `FormSection` 둘 이상으로 읽는다. 섹션 하나는 나누는 축이 아니라 그냥 본문이다.
+ */
+function checkGrouping(blocks, declared, where, problems) {
+  if (!declared) return;
+
+  const html = blocks.map((block) => block.html).join('\n');
+  const drawnTabs = TABLIST.test(html);
+  const drawnSections = (html.match(SECTION_OPEN) ?? []).length >= 2;
+  const expectTabs = declared.includes('탭');
+  const expectSections = declared.includes('섹션');
+
+  if (expectTabs && !drawnTabs) {
+    problems.push(
+      `${where}: ${GROUPING_LABEL}를 \`${declared}\`로 적었는데 본문에 \`role="tablist"\`가 없다 — 탭 줄은 쓰는 쪽이 만든다 (0023)`,
+    );
+  }
+  if (!expectTabs && drawnTabs) {
+    problems.push(
+      `${where}: 본문이 탭으로 갈리는데 ${GROUPING_LABEL}가 \`${declared}\`이다 — 같은 종류의 갈래를 탭이 가른다면 그렇게 적는다`,
+    );
+  }
+  if (expectSections && !drawnSections) {
+    problems.push(
+      `${where}: ${GROUPING_LABEL}를 \`${declared}\`로 적었는데 형제 섹션이 둘 미만이다 — 섹션 하나는 나누는 축이 아니다`,
+    );
+  }
+  if (!expectSections && drawnSections) {
+    problems.push(
+      `${where}: 본문이 섹션 여럿으로 나뉘는데 ${GROUPING_LABEL}가 \`${declared}\`이다 — 같은 종류의 갈래라면 제목을 여러 개 세우는 대신 탭으로 가른다 (0023)`,
+    );
+  }
+}
+
+/**
+ * 섹션의 내용 자리. `__fields`부터 `__footer` 앞까지다 — 면이 붙는 자리가 거기 하나이고,
+ * 제목·오류·footer는 면 밖에 남는다 (0037).
+ */
+function sectionFields(section) {
+  const start = section.indexOf(SECTION_FIELDS_CLASS);
+  if (start === -1) return '';
+  const footer = section.indexOf(SECTION_FOOTER_CLASS, start);
+  return section.slice(start, footer === -1 ? undefined : footer);
+}
+
+/** 섹션의 채움이 제 조건에서 켜졌는지 (0037). */
+function checkSectionFill(blocks, where, problems) {
+  const html = blocks.map((block) => block.html).join('\n');
+  const sections = formSections(html);
+  const filled = sections.filter((section) =>
+    new RegExp(`\\b${SECTION_FILLED_CLASS}\\b`).test(section.slice(0, section.indexOf('>') + 1)),
+  );
+
+  // 켜야 하는데 안 켠 자리. 형제가 있고, 제목과 내용의 텍스트 스타일이 문자열까지 같으면
+  // 여백 말고 갈릴 것이 없다. 형제가 하나뿐이면 애초에 켜지 못하므로(아래) 세지 않는다.
+  if (sections.length >= 2) {
+    for (const section of sections) {
+      const head = section.slice(0, section.indexOf('>') + 1);
+      if (new RegExp(`\\b${SECTION_FILLED_CLASS}\\b`).test(head)) continue;
+
+      const heading = SECTION_HEADING_CLASS.exec(section)?.[1] ?? '';
+      const style = TYPOGRAPHY_CLASS.exec(heading)?.[0];
+      if (!style) continue;
+
+      const fields = sectionFields(section);
+      // 내용이 이미 덩어리면 면이 할 일이 없다. 카드 그리드가 그 자리다 (0037) — 아래에서
+      // 면을 켜지 못하게 막는 것과 같은 표시를 쓴다. 결제의 `요금제`·`구매 수량`이 그렇다.
+      if (new RegExp(`\\b${NESTED_SURFACE_CLASS}\\b`).test(fields)) continue;
+
+      if (new RegExp(`\\b${style}\\b`).test(fields)) {
+        problems.push(
+          `${where}: 섹션 제목과 그 내용이 같은 \`${style}\`인데 면이 없다 — 제목과 여백만으로 갈리지 않는다 (0037)`,
+        );
+      }
+    }
+  }
+
+  if (filled.length === 0) return;
+
+  // 면은 형제를 가르는 장치다. 혼자면 가를 것이 없고 곁만 본문에 흡수된다.
+  if (sections.length < 2) {
+    problems.push(
+      `${where}: 섹션이 하나인데 \`${SECTION_FILLED_CLASS}\`이다 — 면은 갈라야 할 형제가 있을 때 켠다 (0037)`,
+    );
+  }
+
+  // 내용이 이미 덩어리면 면이 한 겹 겹친다. 카드 그리드가 그 자리다.
+  for (const section of filled) {
+    if (new RegExp(`\\b${NESTED_SURFACE_CLASS}\\b`).test(section)) {
+      problems.push(
+        `${where}: \`${SECTION_FILLED_CLASS}\` 안에 \`${NESTED_SURFACE_CLASS}\`가 있다 — 내용이 이미 덩어리면 면을 주지 않는다 (0037)`,
+      );
+    }
+  }
+}
+
+export function validateScreenHtml(source, where, requireScreen = false, siblings = null) {
   const problems = [];
   const blocks = bodyBlocks(source);
   if (blocks === null) {
@@ -360,11 +580,25 @@ export function validateScreenHtml(source, where, requireScreen = false) {
     problems.push(`${where}: 화면 선언 표가 없다 — 파일 맨 위 주석에 둔다`);
     return problems;
   }
-  const { asides } = checkDeclaration(rows, where, problems);
+  const { asides, grouping } = checkDeclaration(rows, where, problems);
   checkBlocks(blocks, asides, where, problems);
+  checkGrouping(blocks, grouping, where, problems);
+  checkSectionFill(blocks, where, problems);
+  // 자매는 짝이 있어야 셀 수 있다. 파일 하나만 주면 이 검사는 건너뛴다.
+  if (siblings) checkSiblings(source, where, rows, siblings, problems);
   return problems;
 }
 
+/**
+ * 자매를 찾는 색인. 키는 확장자를 뺀 파일 이름이고, 선언서가 그 이름으로 상대를 가리킨다.
+ * 이름이 겹치면 먼저 읽은 쪽이 남는다 — 시안 이름은 화면 하나를 가리키므로 겹치지 않는다.
+ */
+export function siblingIndex(entries) {
+  const index = new Map();
+  for (const { name, source } of entries) if (!index.has(name)) index.set(name, source);
+  return index;
+}
+
 export function validateExamples(root = DEFAULT_ROOT) {
   const problems = [];
 
@@ -378,18 +612,27 @@ export function validateExamples(root = DEFAULT_ROOT) {
     }
   }
 
-  // 2. 시안 HTML — 선언서 + 바디 블록의 소속.
+  // 2. 시안 HTML — 선언서 + 바디 블록의 소속 + 자매의 섹션 집합.
+  //    자매는 짝이 필요해서 전부 읽어 색인을 만든 뒤에 검사한다.
+  const screens = [];
   for (const dir of SCREEN_DIRS) {
     const full = join(root, dir);
     if (!existsSync(full)) continue;
 
     for (const file of htmlFiles(full)) {
-      const source = readFileSync(file, 'utf8');
-      const where = relative(root, file);
-      problems.push(...validateScreenHtml(source, where));
+      screens.push({
+        name: basename(file, '.html'),
+        source: readFileSync(file, 'utf8'),
+        where: relative(root, file),
+      });
     }
   }
 
+  const siblings = siblingIndex(screens);
+  for (const screen of screens) {
+    problems.push(...validateScreenHtml(screen.source, screen.where, false, siblings));
+  }
+
   return problems;
 }