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

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, ListRowProps, LivePreview, LivePreviewProps, LivePreviewStatus } from './patterns.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';
 import 'react';

package/dist/index.js

@@ -7,7 +7,7 @@ import {
   FormSection,
   ListRow,
   LivePreview
-} from "./chunk-Q4UXASZH.js";
+} from "./chunk-QW2SD3XV.js";
 import "./chunk-EYFL232L.js";
 import {
   Alert,
@@ -29,7 +29,7 @@ import {
   Toaster,
   Tooltip,
   toast
-} from "./chunk-GPCPGABI.js";
+} from "./chunk-6JZPK2W5.js";
 import {
   AlarmIcon,
   AlertIcon,

package/dist/patterns.d.ts

@@ -112,11 +112,21 @@ interface FormSectionProps {
  */
 declare function FormSection({ children, description, error, footer, title }: FormSectionProps): react.JSX.Element;
 
+type ListRowEmphasis = 'default' | 'strong';
 interface ListRowProps {
     /** 누를 수 있는 행 오른쪽 끝의 chevron. `onClick`이 있으면 기본으로 붙는다. */
     chevron?: boolean;
     children?: ReactNode;
     description?: ReactNode;
+    /**
+     * 행이 놓인 층. 크기를 고르는 자리가 아니라 이 목록이 화면의 본문인지를 밝히는 자리다.
+     * - `default`(기본) — 제목 `body2`(14) · 설명 `label`(12). 곁·요약·참조 나열이다.
+     * - `strong` — 제목 `body1`(16) · 설명 `body2`(14). 선언서의 본문 문장이 가리키는 목록
+     *   하나에만 쓴다. 한 화면에 `strong` 목록은 하나다.
+     *
+     * `tone="filled"`와 함께 쓰지 않는다 — 곁이 본문 크기를 갖는 일이다 (0032, 0034).
+     */
+    emphasis?: ListRowEmphasis;
     /** 제목 앞 아이콘이나 썸네일. */
     leading?: ReactNode;
     /** 자리를 잡아 두는 로딩 표시. 켜면 내용 대신 뼈대를 그린다. */
@@ -140,9 +150,12 @@ interface ListRowProps {
  *
  * `onClick`을 주면 누를 수 있는 행이 되어 button으로 그려지고 오른쪽 끝에 chevron이 붙는다.
  *
+ * 이 목록이 화면의 본문이면 `emphasis="strong"`으로 제목·설명을 한 칸씩 올린다 (0034). 곁·요약
+ * 나열은 기본값 그대로 둔다.
+ *
  * 목록 전체가 비었을 때와 실패했을 때는 이 컴포넌트가 아니라 `EmptyState`를 쓴다.
  */
-declare function ListRow({ chevron, children, description, leading, loading, onClick, selected, title, tone, trailing, }: ListRowProps): react.JSX.Element;
+declare function ListRow({ chevron, children, description, emphasis, leading, loading, onClick, selected, title, tone, trailing, }: ListRowProps): react.JSX.Element;
 
 type LivePreviewStatus = 'ready' | 'loading' | 'empty' | 'error';
 interface LivePreviewProps {
@@ -159,4 +172,4 @@ interface LivePreviewProps {
  */
 declare function LivePreview({ children, message, status, title }: LivePreviewProps): react.JSX.Element;
 
-export { AppShell, type AppShellProps, BottomBar, type BottomBarProps, Card, type CardProps, type CardTone, EmptyState, type EmptyStateProps, FormSection, type FormSectionProps, ListRow, type ListRowProps, LivePreview, type LivePreviewProps, type LivePreviewStatus };
+export { AppShell, type AppShellProps, BottomBar, type BottomBarProps, Card, type CardProps, type CardTone, EmptyState, type EmptyStateProps, FormSection, type FormSectionProps, ListRow, type ListRowEmphasis, type ListRowProps, LivePreview, type LivePreviewProps, type LivePreviewStatus };

package/dist/patterns.js

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

package/dist/scripts/check-examples.mjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+/**
+ * 화면 선언서와 시안 마크업을 검사한다.
+ *
+ * 화면은 그리기 전에 본문을 한 문장으로 선언하고, 선언에 들지 않은 것은 곁으로 내린다
+ * (`docs/decisions/0022-screens-declare-their-body.md`). 선언이 산문 규칙으로만 있으면
+ * 화면을 들일 때 빠지기 쉬워서, 셀 수 있는 부분만 검사로 둔다.
+ *
+ * 대상이 둘이다.
+ *
+ * 1. 승인 화면 문서(`examples/approved/*.md`) — 선언서의 항목과 개수.
+ * 2. 시안 HTML(`preview/`·`examples/`의 `.html`) — 같은 선언서 + 바디 블록의 소속 표시.
+ *
+ * 2번은 0022 §적용이 "강제되지 않는 것"에 남겨 둔 곁의 규칙들이다. 당시 근거는 "화면 코드가
+ * 이 저장소에 없어 셀 대상이 없다"였는데, 시안 HTML이 그 대상이다 — 시안 CSS를 `check:css`로
+ * 올린 것과 같은 자리다(`docs/COMPONENT_POLICY.md` §시안은 HTML로 먼저 확정한다).
+ * `AGENTS.md` §항상("반복되는 오류는 검사로 승격한다")을 따른다.
+ *
+ * 실제로 새어 나갔다 — 스토어 알림톡 시안이 결제·구독 요약(명백한 곁)을 `곁: 없음`이라고
+ * 선언해 놓고 `Card` + 행 넷 + 버튼으로 그렸다. 규칙 셋을 전부 어겼는데 선언서만 보는 검사는
+ * 통과했다.
+ *
+ * 곁의 규칙과 별개로 **상태를 누가 드는가**도 한 가지 센다. 행 하나의 실패를 섹션 배너로 올리면
+ * 같은 사실을 두 번 말하고, 면적이 큰 배너가 본문보다 강해진다
+ * (`docs/decisions/0024-state-belongs-to-the-nearest-owner.md`). 스토어 알림톡 시안이 실제로
+ * 그렇게 그려져 목록이 눈에 안 들어왔다.
+ *
+ * 읽지 못하는 것은 그대로 리뷰가 받는다 — 본문 문장의 폭과, 곁이 폭에 밀려 접히는지다. 곁의
+ * 규칙 1(세로로 한 줄)은 마크업으로 이미 갈라 둔 경우만 잡는다. 곁의 자리도 세지 않는다 —
+ * 0022가 자리를 정하지 않고, 본문보다 먼저 오는 것도 규칙 위반이 아니다
+ * (`docs/DESIGN_GRAMMAR.md` §자리는 시스템이 정하지 않는다).
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { dirname, join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const DEFAULT_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/** 선언서는 문서 맨 위의 표다. 첫 칸이 항목 이름이고 백틱은 있어도 없어도 된다. */
+const ROW = /^\|([^|]*)\|([^|]*)\|/;
+/** 표의 구분선(`| --- | --- |`)은 항목이 아니다. */
+const DIVIDER = /^[\s:-]*$/;
+
+/**
+ * 주 액션의 자리. `없음`은 고르는 행위가 본문 안에서 끝나는 화면이다 — 목록을 훑고 행을 눌러
+ * 들어가는 화면은 행이 곧 액션이라 헤더나 하단에 세울 것이 없다
+ * (`docs/decisions/0033-a-screen-may-have-no-primary-action.md`). 행 자체는 여전히 필수라
+ * "적기를 잊은 것"과 "정말 없는 것"이 갈린다.
+ */
+const PRIMARY_ACTION_PLACES = new Set(['헤더 우측', 'BottomBar', '없음']);
+
+/** 시안을 찾는 곳. `preview/`는 untracked라 CI에서는 비어 있고 로컬에서만 걸린다. */
+const SCREEN_DIRS = ['preview', 'examples'];
+
+/** 셸의 바디 밴드. 이 안의 직계 자식이 화면의 블록이다 (`docs/LAYOUT.md` §콘텐츠 세로 순서). */
+const BODY_BAND_CLASS = 'palda-app-shell__band--body';
+
+/** 바디 직계 자식이 밝히는 소속. 순서도 이 순서다 — 헤더 → 본문 → 곁. */
+const ROLE_ATTRIBUTE = /data-screen-role\s*=\s*"([^"]*)"/;
+const ROLES = ['헤더', '본문', '곁'];
+
+/**
+ * 곁이 쓰지 않는 pattern 클래스 (0022 규칙 2 — 본문이 쓰는 pattern을 쓰지 않는다).
+ * 본문이 무엇을 쓰는지와 무관하게 pattern 자체가 "이 화면이 하는 일"을 담는 도구다.
+ * 곁에 남는 표현은 텍스트와 `Link`다(0022 §대가).
+ */
+const BODY_PATTERN_CLASSES = [
+  'palda-card',
+  'palda-form-section',
+  'palda-list-row',
+  'palda-empty-state',
+  'palda-live-preview',
+  'palda-bottom-bar',
+];
+
+/**
+ * 곁이 쓰지 않는 강조 채움 (0022 규칙 3 — 강조 예산은 본문이 갖는다).
+ * 액션의 채움만 본다. 상태 배지는 강조 예산을 쓰지 않는다
+ * (`docs/DESIGN_PRINCIPLES.md` §4의 "상태 색은 이 한도에 들어가지 않는다").
+ */
+const EMPHASIS_CLASSES = [
+  'palda-button--primary',
+  'palda-button--accent',
+  'palda-chip--primary',
+  'palda-chip--accent',
+];
+
+/**
+ * 상태를 드는 자리 (0024 — 상태는 가장 가까운 자리가 든다).
+ * 한 섹션이 둘을 같이 쓰면 행 하나의 실패를 섹션이 대신 말한 것이다. `\b`가 `_`를 경계로 보지
+ * 않아 `palda-form-section__error`는 섹션 클래스로 세지 않는다.
+ */
+const FORM_SECTION_CLASS = 'palda-form-section';
+const SECTION_FAILURE_CLASS = 'palda-form-section__error';
+const ROW_FAILURE_CLASS = 'palda-badge--danger';
+
+/** 닫는 태그가 없는 요소. 깊이를 올리지 않는다. */
+const VOID_ELEMENTS = new Set([
+  'area',
+  'base',
+  'br',
+  'col',
+  'embed',
+  'hr',
+  'img',
+  'input',
+  'link',
+  'meta',
+  'param',
+  'source',
+  'track',
+  'wbr',
+]);
+
+function cell(text) {
+  return text.replace(/`/g, '').trim();
+}
+
+/** 선언서 표의 행을 읽는다. 마크다운이든 HTML 주석 안이든 서식이 같다. */
+function declarationRows(source) {
+  const rows = [];
+  for (const line of source.split('\n')) {
+    const match = ROW.exec(line.trim());
+    if (!match || DIVIDER.test(match[1])) continue;
+    rows.push({ label: cell(match[1]), value: cell(match[2]) });
+  }
+  return rows;
+}
+
+/** 선언서의 셀 수 있는 부분 — 항목이 있는지, 본문이 하나인지, 주 액션 값이 둘 중 하나인지. */
+function checkDeclaration(rows, where, problems) {
+  const body = rows.filter((row) => row.label === '본문');
+  const primary = rows.filter((row) => row.label === '주 액션');
+
+  if (body.length === 0) {
+    problems.push(`${where}: 선언서에 \`본문\` 행이 없다`);
+  } else if (body.length > 1) {
+    problems.push(`${where}: 본문이 ${body.length}개다 — 하나여야 하고, 둘이면 화면을 쪼갠다`);
+  }
+
+  if (primary.length === 0) {
+    problems.push(`${where}: 선언서에 \`주 액션\` 행이 없다`);
+  } else if (primary.length > 1) {
+    problems.push(`${where}: 주 액션이 ${primary.length}개다 — 자리는 하나다`);
+  } else if (!PRIMARY_ACTION_PLACES.has(primary[0].value)) {
+    problems.push(
+      `${where}: 주 액션 자리가 \`${primary[0].value}\`다 — ${[...PRIMARY_ACTION_PLACES]
+        .map((place) => `\`${place}\``)
+        .join(' 또는 ')} 중 하나여야 한다`,
+    );
+  }
+
+  /** `곁` 행에 `없음`이라고 적으면 곁이 0개라는 뜻이다. */
+  const asides = rows
+    .filter((row) => row.label === '곁')
+    .filter((row) => row.value !== '' && row.value !== '없음');
+
+  return { declared: body.length > 0, asides: asides.length };
+}
+
+/** 주석을 같은 길이의 공백으로 지운다. 주석 안의 예시 마크업이 태그로 세지지 않게 한다. */
+function stripComments(html) {
+  return html.replace(/<!--[\s\S]*?-->/g, (match) => ' '.repeat(match.length));
+}
+
+function scanTags(html) {
+  const TAG = /<(\/)?([a-zA-Z][\w-]*)((?:'[^']*'|"[^"]*"|[^'">])*)>/g;
+  const tags = [];
+  let match;
+  while ((match = TAG.exec(html)) !== null) {
+    const attributes = match[3] ?? '';
+    tags.push({
+      closing: match[1] === '/',
+      name: match[2].toLowerCase(),
+      attributes,
+      selfClosing: attributes.trimEnd().endsWith('/'),
+      start: match.index,
+      end: TAG.lastIndex,
+    });
+  }
+  return tags;
+}
+
+/**
+ * 셸 바디 밴드의 직계 자식을 순서대로 돌려준다.
+ * 밴드가 없으면 `null`이다 — 컴포넌트 시안은 화면이 아니라 이 검사를 받지 않는다.
+ */
+function bodyBlocks(html) {
+  const source = stripComments(html);
+  const tags = scanTags(source);
+  const band = tags.findIndex((tag) => !tag.closing && tag.attributes.includes(BODY_BAND_CLASS));
+  if (band < 0) return null;
+
+  const blocks = [];
+  let depth = 0;
+  let open = null;
+
+  for (let index = band + 1; index < tags.length; index += 1) {
+    const tag = tags[index];
+
+    if (tag.closing) {
+      // 밴드 자신이 닫혔다.
+      if (depth === 0) break;
+      depth -= 1;
+      if (depth === 0 && open) {
+        blocks.push({ tag: open, html: source.slice(open.start, tag.end) });
+        open = null;
+      }
+      continue;
+    }
+
+    if (depth === 0) {
+      if (tag.selfClosing || VOID_ELEMENTS.has(tag.name)) {
+        blocks.push({ tag, html: source.slice(tag.start, tag.end) });
+        continue;
+      }
+      open = tag;
+    }
+    if (!tag.selfClosing && !VOID_ELEMENTS.has(tag.name)) depth += 1;
+  }
+
+  return blocks;
+}
+
+/**
+ * 블록 안의 `.palda-form-section` 요소를 HTML 조각으로 하나씩 돌려준다.
+ * 섹션은 중첩되지 않지만, 안쪽 태그의 닫는 순서에 속지 않도록 깊이를 센다.
+ */
+function formSections(html) {
+  const tags = scanTags(html);
+  const sections = [];
+  const isSection = new RegExp(`\\b${FORM_SECTION_CLASS}\\b`);
+
+  for (let index = 0; index < tags.length; index += 1) {
+    const open = tags[index];
+    if (open.closing || !isSection.test(open.attributes)) continue;
+
+    let depth = 0;
+    for (let cursor = index; cursor < tags.length; cursor += 1) {
+      const tag = tags[cursor];
+      if (tag.closing) {
+        depth -= 1;
+        if (depth === 0) {
+          sections.push(html.slice(open.start, tag.end));
+          break;
+        }
+        continue;
+      }
+      if (!tag.selfClosing && !VOID_ELEMENTS.has(tag.name)) depth += 1;
+    }
+  }
+
+  return sections;
+}
+
+/** 바디 블록의 소속 표시와 곁의 규칙을 센다. */
+function checkBlocks(blocks, declaredAsides, where, problems) {
+  const roles = [];
+
+  for (const [index, block] of blocks.entries()) {
+    const match = ROLE_ATTRIBUTE.exec(block.tag.attributes);
+    const role = match ? match[1].trim() : null;
+
+    if (!role) {
+      problems.push(
+        `${where}: 바디 ${index + 1}번째 블록(<${block.tag.name}>)에 data-screen-role이 없다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나를 밝힌다`,
+      );
+      roles.push(null);
+      continue;
+    }
+    if (!ROLES.includes(role)) {
+      problems.push(
+        `${where}: 바디 ${index + 1}번째 블록의 data-screen-role이 \`${role}\`다 — ${ROLES.map((name) => `\`${name}\``).join('·')} 중 하나여야 한다`,
+      );
+      roles.push(null);
+      continue;
+    }
+    roles.push(role);
+
+    if (role !== '곁') continue;
+
+    // 규칙 2 — 본문이 쓰는 pattern을 쓰지 않는다.
+    for (const pattern of BODY_PATTERN_CLASSES) {
+      if (new RegExp(`\\b${pattern}\\b`).test(block.html)) {
+        problems.push(
+          `${where}: 곁이 \`${pattern}\`을 쓴다 — 곁은 본문이 쓰는 pattern을 쓰지 않는다 (0022 규칙 2)`,
+        );
+      }
+    }
+
+    // 규칙 3 — 강조 예산을 쓰지 않는다.
+    for (const emphasis of EMPHASIS_CLASSES) {
+      if (new RegExp(`\\b${emphasis}\\b`).test(block.html)) {
+        problems.push(
+          `${where}: 곁이 \`${emphasis}\`를 쓴다 — 강조 예산은 본문이 갖는다 (0022 규칙 3)`,
+        );
+      }
+    }
+  }
+
+  // 상태는 가장 가까운 자리가 든다 (0024). 소속과 무관하게 바디 전체를 본다.
+  for (const block of blocks) {
+    for (const section of formSections(block.html)) {
+      if (!section.includes(SECTION_FAILURE_CLASS)) continue;
+      if (!new RegExp(`\\b${ROW_FAILURE_CLASS}\\b`).test(section)) continue;
+      problems.push(
+        `${where}: 한 섹션이 \`${SECTION_FAILURE_CLASS}\` 배너와 \`${ROW_FAILURE_CLASS}\` 배지로 같은 실패를 두 번 말한다 — 행 하나의 실패는 그 행이 든다 (0024)`,
+      );
+    }
+  }
+
+  // 헤더는 하나이고 맨 앞이다 (`docs/LAYOUT.md` §콘텐츠 세로 순서).
+  const headers = roles.filter((role) => role === '헤더').length;
+  if (headers > 1) {
+    problems.push(`${where}: 페이지 헤더가 ${headers}개다 — 하나다`);
+  } else if (headers === 1 && roles[0] !== '헤더') {
+    problems.push(`${where}: 페이지 헤더가 첫 블록이 아니다 — 바디의 맨 위다`);
+  }
+
+  // 본문은 블록 여러 개로 나뉘어도 되지만 사이가 갈리지 않는다. 선언서의 본문은 한 문장이고,
+  // 그 한 문장이 곁을 사이에 두고 두 덩어리로 읽히면 화면이 둘이다.
+  const bodyIndexes = roles.flatMap((role, index) => (role === '본문' ? [index] : []));
+  if (
+    bodyIndexes.length > 1 &&
+    bodyIndexes[bodyIndexes.length - 1] - bodyIndexes[0] + 1 !== bodyIndexes.length
+  ) {
+    problems.push(
+      `${where}: 본문 블록 사이에 다른 것이 끼어 있다 — 본문은 여러 블록이어도 붙어 있어야 한다`,
+    );
+  }
+
+  // 선언되지 않은 곁은 화면에 들어오지 못한다. 곁이 몇 개여야 하는지는 세지 않는다 — 기능이
+  // 다르면 블록도 다르고(0032 규칙 1), 개수는 기능 수가 정한다.
+  const drawn = roles.filter((role) => role === '곁').length;
+  if (drawn !== declaredAsides) {
+    problems.push(
+      `${where}: 곁이 선언서에 ${declaredAsides}개인데 화면에 ${drawn}개다 — 적히지 않은 곁은 화면에 들어오지 못한다`,
+    );
+  }
+}
+
+function htmlFiles(dir, out = []) {
+  for (const name of readdirSync(dir)) {
+    const full = join(dir, name);
+    if (statSync(full).isDirectory()) htmlFiles(full, out);
+    else if (name.endsWith('.html')) out.push(full);
+  }
+  return out;
+}
+
+export function validateScreenHtml(source, where, requireScreen = false) {
+  const problems = [];
+  const blocks = bodyBlocks(source);
+  if (blocks === null) {
+    if (requireScreen) problems.push(`${where}: DS 셸 바디가 없는 HTML은 화면 검사 대상이 아니다`);
+    return problems;
+  }
+  const rows = declarationRows(source);
+  if (rows.length === 0) {
+    problems.push(`${where}: 화면 선언 표가 없다 — 파일 맨 위 주석에 둔다`);
+    return problems;
+  }
+  const { asides } = checkDeclaration(rows, where, problems);
+  checkBlocks(blocks, asides, where, problems);
+  return problems;
+}
+
+export function validateExamples(root = DEFAULT_ROOT) {
+  const problems = [];
+
+  // 1. 승인 화면 문서 — 선언서만 본다. 화면은 시안 HTML이 갖는다.
+  const approvedDir = join(root, 'examples/approved');
+  if (existsSync(approvedDir)) {
+    for (const name of readdirSync(approvedDir)) {
+      if (!name.endsWith('.md') || name === 'README.md') continue;
+      const file = join(approvedDir, name);
+      checkDeclaration(declarationRows(readFileSync(file, 'utf8')), relative(root, file), problems);
+    }
+  }
+
+  // 2. 시안 HTML — 선언서 + 바디 블록의 소속.
+  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));
+    }
+  }
+
+  return problems;
+}
+
+function main() {
+  const problems = validateExamples(process.env.DS_ROOT ?? DEFAULT_ROOT);
+  if (problems.length > 0) {
+    console.error(`화면 선언·시안 불일치 ${problems.length}건\n`);
+    for (const problem of problems) console.error(`  ${problem}`);
+    process.exit(1);
+  }
+  console.log('화면 선언·시안 검사 통과');
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) main();

package/dist/styles.css

@@ -1355,6 +1355,11 @@
   justify-content: center;
   width: 24px;
 }
+.palda-tab__badge {
+  align-items: center;
+  display: inline-flex;
+  flex-shrink: 0;
+}
 .palda-tab__label {
   white-space: nowrap;
 }
@@ -2112,6 +2117,12 @@ button.palda-list-row:focus-visible {
   height: var(--palda-font-size-xs);
   width: 70%;
 }
+.palda-list-row--strong .palda-list-row__skeleton--title {
+  height: var(--palda-font-size-md);
+}
+.palda-list-row--strong .palda-list-row__skeleton--description {
+  height: var(--palda-font-size-sm);
+}
 @keyframes palda-list-row-pulse {
   from {
     opacity: 1;

package/dist/ui.d.ts

@@ -174,10 +174,15 @@ interface TabProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, 'role'
     children: ReactNode;
     /** 라벨 앞 아이콘. 시안 기준 24px 고정이다. */
     icon?: ReactNode;
+    /**
+     * 라벨 뒤 배지. 그룹별 개수처럼 탭을 열지 않고도 보여야 하는 수를 싣는다.
+     * `Badge`를 넣는 자리이며 크기는 `sm`을 쓴다 — 라벨이 Body2(14px)라 md(28px)는 라벨보다 커진다.
+     */
+    badge?: ReactNode;
     /** 지금 보고 있는 탭. `aria-selected`로 함께 노출된다. */
     selected?: boolean;
 }
-declare function Tab({ children, className, icon, selected, ...props }: TabProps): react.JSX.Element;
+declare function Tab({ children, className, icon, badge, selected, ...props }: TabProps): react.JSX.Element;
 
 type TextFieldVariant = 'outline' | 'accent' | 'subtle';
 type TextFieldSize = 'md' | 'sm';

package/dist/ui.js

@@ -19,7 +19,7 @@ import {
   Toaster,
   Tooltip,
   toast
-} from "./chunk-GPCPGABI.js";
+} from "./chunk-6JZPK2W5.js";
 import "./chunk-TWYJ2UTC.js";
 export {
   Alert,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@highpixel-co/palda-design-system",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Palda product design tokens, icons, React components, and patterns",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,12 @@
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
+  "bin": {
+    "palda-ds": "./dist/harness/cli.mjs"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -32,7 +38,8 @@
       "types": "./dist/tokens.d.ts",
       "import": "./dist/tokens.js"
     },
-    "./styles.css": "./dist/styles.css"
+    "./styles.css": "./dist/styles.css",
+    "./catalog": "./dist/harness/metadata.json"
   },
   "sideEffects": [
     "./dist/styles.css"
@@ -52,5 +59,9 @@
   "publishConfig": {
     "registry": "https://registry.npmjs.org/",
     "access": "public"
+  },
+  "dependencies": {
+    "js-yaml": "4.3.0",
+    "typescript": "6.0.3"
   }
 }