@design-ai/cli 4.55.0

package/examples/component-date-picker.md

@@ -0,0 +1,249 @@
+# `DatePicker` — spec
+
+> Citing Ant Design `DatePicker`, MUI `DatePicker` (X package), shadcn-ui `calendar` + `date-picker` (react-day-picker)
+
+## Purpose
+
+A DatePicker lets users pick a date or date range. Two distinct use cases drive different optimal UI:
+
+| Use case | Recommended UI |
+| --- | --- |
+| Pick a date the user **knows** (DOB, expiry, settled appointment) | Text input with format hint, OR three dropdowns (Y/M/D) |
+| Pick a date the user is **choosing** (booking, scheduling, filtering) | Calendar grid (popover or sheet) |
+
+Implementing the wrong UI for the use case is the most common bug. Don't make users navigate a calendar to enter their birthday.
+
+## Variants
+
+### `single` — pick one date
+
+```
+┌──────────────────────┐
+│ 📅  2026.05.07       │   ← compact input (month+day visible)
+└──────────────────────┘
+        │
+        ▼ (on click, opens popover)
+┌────────────────────────────────────┐
+│       ◀  May 2026  ▶               │
+│ Su Mo Tu We Th Fr Sa               │
+│              1  2                  │
+│  3  4  5  6  7  8  9               │
+│ 10 11 12 13 14 15 16               │
+│ ...                                │
+└────────────────────────────────────┘
+```
+
+### `range` — pick a start + end
+
+Same UI; calendar shows both selections highlighted with the days between styled as range fill.
+
+```
+┌──────────────────────────────────┐
+│ 📅  2026.05.07 — 2026.05.14      │
+└──────────────────────────────────┘
+```
+
+### `dateTime` — date + time
+
+```
+┌──────────────────────────────────────────┐
+│ 📅  2026.05.07  14:30                    │
+└──────────────────────────────────────────┘
+```
+
+Calendar above, time picker below. Time as separate scrollable wheels (mobile native), dropdowns (desktop), or two number inputs.
+
+### `quickRange` — preset range pills
+
+For dashboards / analytics:
+
+```
+[오늘]  [7일]  [30일]  [이번 달]  [지난 달]  [사용자 지정 ▾]
+```
+
+Clicking "사용자 지정" opens the full range picker. Pre-defined ranges cover ~80% of analytics use cases.
+
+## API
+
+```tsx
+<DatePicker
+  value={date}
+  onValueChange={setDate}
+  mode="single"          // "single" | "range" | "dateTime" | "quickRange"
+  format="yyyy.MM.dd"     // display format
+  placeholder="날짜 선택"
+  minDate={new Date()}
+  maxDate={addYears(new Date(), 1)}
+  disabledDates={(d) => isWeekend(d)}
+  locale="ko-KR"
+  showTime={false}
+  weekStartsOn={0}        // 0=Sun, 1=Mon
+  presets={[
+    { label: "오늘", value: today() },
+    { label: "이번 주", value: thisWeek() },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Date \| { from: Date, to: Date } \| null` | — | Controlled value |
+| `defaultValue` | same | — | Uncontrolled default |
+| `onValueChange` | `(value) => void` | — | Fires on selection |
+| `mode` | `"single" \| "range" \| "dateTime" \| "quickRange"` | `"single"` | |
+| `format` | `string` | locale default | Display format (date-fns or dayjs syntax) |
+| `placeholder` | `string` | locale default | When no value |
+| `minDate` / `maxDate` | `Date` | — | Bounds |
+| `disabledDates` | `(date) => boolean` | — | Disable specific dates (weekends, holidays) |
+| `locale` | `string` | `"ko-KR"` (KR builds) | |
+| `weekStartsOn` | `0..6` | `0` (Sunday) for KR/US | Korean and US start on Sun; EU on Mon |
+| `presets` | `{ label, value }[]` | — | Quick-pick buttons in popover |
+| `disabled` / `readOnly` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | Validation state |
+
+## Korean format conventions
+
+Per [knowledge/i18n/korean-typography.md](../knowledge/i18n/korean-typography.md):
+
+| Format | Example | Use |
+| --- | --- | --- |
+| `yyyy.MM.dd` | `2026.05.07` | Compact — default for most product UIs |
+| `yyyy년 M월 d일` | `2026년 5월 7일` | Formal — invoices, legal docs |
+| `yyyy-MM-dd` | `2026-05-07` | Technical / ISO — admin tools |
+| `M월 d일 (E)` | `5월 7일 (목)` | Casual — "이번 주", "오늘" relative contexts |
+
+Korean weekday short forms: 일 월 화 수 목 금 토 (single character).
+
+Do **not** use US format `MM/dd/yyyy` in Korean apps.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty (no value) | Placeholder text, calendar icon |
+| Filled | Selected date in input format |
+| Hover (input) | Border emphasis |
+| Focus-visible | 2px ring (matches Input spec) |
+| Open (popover visible) | Border emphasis, panel positioned below or above per viewport |
+| Disabled date in calendar | Muted text, no events, `aria-disabled` |
+| Today | Subtle highlight (border or bold) |
+| Selected date | Filled bg `--color-primary-default`, white text |
+| In-range dates | Subtle bg `--color-primary-subtle-bg` |
+| Range start/end | Filled bg, rounded only on the appropriate side |
+
+## Calendar grid
+
+```
+┌────────────────────────────────────────────┐
+│  ◀     2026년 5월     ▶     [오늘로]        │
+├────────────────────────────────────────────┤
+│ 일  월  화  수  목  금  토                   │
+├────────────────────────────────────────────┤
+│              1   2                          │  ← month-prev days muted
+│  3   4   5   6  ●7   8   9                  │  ● = today
+│ 10  11  12  13  14  15  16                  │
+│ ...                                         │
+└────────────────────────────────────────────┘
+[       ✕ Cancel       ✓ Confirm  ]   ← (mobile only, on sheet variant)
+```
+
+| Cell size | Use |
+| --- | --- |
+| 32×32 | Compact desktop |
+| 40×40 | Default desktop |
+| 48×48 | Mobile (touch target) |
+
+## Mobile presentation
+
+| Width | Presentation |
+| --- | --- |
+| Desktop (> md) | Popover anchored to input |
+| Tablet | Popover, larger cells |
+| Mobile (< md) | **Bottom sheet** with confirm/cancel buttons |
+
+On mobile, **don't try to fit a popover under the input** — use a bottom sheet that takes ~70% of viewport height. Cells are 48×48 minimum.
+
+The native `<input type="date">` on mobile uses the OS-native picker (iOS scrolling wheels, Android calendar). For Korean apps with custom branding, prefer a custom picker over native — but accept that custom picker has more bugs than native.
+
+## Accessibility
+
+- **Combobox pattern**: input has `role="combobox"`, `aria-expanded`, `aria-controls` pointing at the calendar's id.
+- **Calendar grid**: `role="grid"`, each cell `role="gridcell"`. Day-of-week headers `role="columnheader"`.
+- **Selected cell**: `aria-selected="true"`.
+- **Disabled cell**: `aria-disabled="true"`.
+- **Today**: `aria-current="date"`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reaches input. Pressing again leaves the picker. |
+| `↓` (on input) | Opens calendar, focus moves to today (or selected date). |
+| `Esc` | Closes calendar. |
+| `←` `→` | Move 1 day |
+| `↑` `↓` | Move 1 week |
+| `PageUp` / `PageDown` | Move 1 month |
+| `Shift+PageUp` / `Shift+PageDown` | Move 1 year |
+| `Home` / `End` | First / last day of week |
+| `Enter` / `Space` | Select focused date |
+
+This is the WAI-ARIA APG date picker pattern. Required for AAA compliance.
+
+### Screen reader
+
+Announce on date selection: "May 7, 2026 selected" (or KR "2026년 5월 7일 선택됨").
+
+## Tokens consumed
+
+```
+--color-bg-default          (calendar bg)
+--color-bg-subtle           (current month days hover)
+--color-text-primary
+--color-text-secondary      (other-month days)
+--color-text-tertiary       (weekday headers)
+--color-primary-default     (selected day)
+--color-primary-subtle-bg   (in-range days)
+--color-on-primary          (selected day text)
+--color-border-default
+--space-sm, --space-md
+--radius-md                  (calendar cells)
+--motion-fast, --easing-out
+```
+
+## Edge cases
+
+- **Range start before end after re-pick**: if user picks a date before current `from`, swap automatically (it becomes the new `from`).
+- **Time zone**: store dates as ISO 8601 with TZ. KST is UTC+9, no DST. For multi-region apps, display in user's local TZ; store in UTC.
+- **Korean lunar calendar (음력)**: rare in product UIs but present in tradition/festival apps. Don't try to support both in one component — make it a separate `LunarDatePicker` if needed.
+- **Disabled dates that include the current value**: when min/max changes and current value falls outside, clear the value or clamp to the new bound. Surface to user.
+- **Far-past dates** (DOB year picker): scrolling 80 years in monthly steps is hostile. Provide a year-jump dropdown in the calendar header.
+- **Far-future dates** (lease end, project deadline): same — year jump.
+- **Holidays / 공휴일**: Korean apps often highlight holidays in red. Pass `holidays={[...]}` and style at the cell level.
+- **Quick presets vs calendar**: when both are present, picking a preset highlights the date(s) on the calendar but stays in the popover. User can adjust manually after.
+
+## Don't
+
+- Don't ship date picker for birthday / DOB in calendar mode. Use 3-dropdown (Y/M/D) or text input with format hint. The user **knows** their DOB.
+- Don't disable confirm-button until both range dates are picked — let user click the same date twice (single-day range) or pick non-contiguous if `mode="multi"` is supported.
+- Don't auto-close popover after picking start of range. Wait for end.
+- Don't use 12-hour time with AM/PM in Korean apps. Default 24-hour.
+- Don't use month names "January" in Korean app. Use `1월`.
+- Don't put DatePicker inside a Modal — both want focus management. Use a non-modal popover anchored to the input.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/date-picker/`](../refs/ant-design/components/date-picker/) — most variants (`DatePicker`, `RangePicker`, `MonthPicker`, `YearPicker`, `WeekPicker`, `QuarterPicker`). Heavy but covers everything.
+- MUI: `@mui/x-date-pickers` (separate package) — `DatePicker`, `DateTimePicker`, `DateRangePicker`. Excellent locale support; pairs with date-fns / dayjs / luxon adapters.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/calendar.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/calendar.tsx) — wraps `react-day-picker`. Compose with `Popover` for the picker pattern.
+
+API choices made:
+- **`mode` axis** (single / range / dateTime / quickRange) over Ant's separate components — fewer top-level imports.
+- **`presets` first-class**: most product UIs eventually want them; building a wrapper to add them is more friction than necessary.
+- **`weekStartsOn` exposed**: locale-driven default (KR/US: Sunday; EU: Monday).
+- **No "lunar calendar" mode**: niche. Spec a separate `LunarDatePicker` if needed; don't bloat this.
+
+## Cross-reference
+
+- [knowledge/i18n/korean-typography.md](../knowledge/i18n/korean-typography.md) — Korean date formats
+- [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md) — when to use vs three-dropdown
+- [WAI-ARIA Date Picker pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)

package/examples/component-descriptions.md

@@ -0,0 +1,242 @@
+# `Descriptions` (key-value list) — spec
+
+> Citing Ant Design `Descriptions`, MUI (composition with `<dl>`), shadcn-ui (composition).
+>
+> Renders structured key-value pairs in a tidy layout. Used for: order details, account profile fields, transaction metadata, settings summaries.
+
+## When Descriptions vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Descriptions** | Static read-only labels + values, multi-row, possibly multi-column |
+| **Form** | Editable; each field has validation |
+| **Table** | Many comparable items; one row per record |
+| **Definition list** (raw `<dl>`) | When tagged HTML is enough; no styling layer needed |
+
+## Anatomy
+
+```
+Single column:
+┌────────────────────────────────────────────┐
+│ 이름        │ 김민지                           │
+│ 이메일      │ minji@example.com               │
+│ 휴대폰      │ 010-1234-5678                   │
+│ 가입일      │ 2024.03.15                      │
+└────────────────────────────────────────────┘
+
+Two columns:
+┌────────────┬───────────────┬────────────┬───────────────┐
+│ 이름        │ 김민지         │ 이메일      │ minji@...     │
+│ 휴대폰      │ 010-...        │ 가입일      │ 2024.03.15    │
+└────────────┴───────────────┴────────────┴───────────────┘
+
+With sections:
+┌────────────────────────────────────────────┐
+│ ── 계정 정보 ────────────────────           │
+│ 이름        │ 김민지                          │
+│ 이메일      │ minji@example.com              │
+│ ── 결제 ──────────────────────────          │
+│ 카드        │ KB국민 ****-1234               │
+│ 자동결제    │ 사용 중                          │
+└────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Item label | yes | Left column or above value |
+| Item value | yes | Right column or below label |
+| Title | optional | Heading for the descriptions block |
+| Section divider | optional | Group items |
+
+## API
+
+```tsx
+<Descriptions title="계정 정보" columns={1}>
+  <Descriptions.Item label="이름">김민지</Descriptions.Item>
+  <Descriptions.Item label="이메일">minji@example.com</Descriptions.Item>
+  <Descriptions.Item label="휴대폰">010-1234-5678</Descriptions.Item>
+  <Descriptions.Item label="가입일">2024.03.15</Descriptions.Item>
+</Descriptions>
+
+// Two-column on desktop, single on mobile
+<Descriptions columns={{ default: 1, md: 2 }}>
+  ...
+</Descriptions>
+
+// With sections
+<Descriptions
+  sections={[
+    {
+      title: "계정",
+      items: [
+        { label: "이름", value: "김민지" },
+        { label: "이메일", value: "minji@example.com" },
+      ],
+    },
+    {
+      title: "결제",
+      items: [
+        { label: "카드", value: "KB국민 ****-1234" },
+      ],
+    },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string \| ReactNode` | — | Heading |
+| `columns` | `number \| { default, md, lg, ... }` | `1` | How many key-value pairs per row |
+| `layout` | `"horizontal" \| "vertical"` | `"horizontal"` | Label position relative to value |
+| `bordered` | `boolean` | `false` | Renders cell borders |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `colon` | `boolean` | `false` | Append `:` to labels |
+| `labelStyle` / `valueStyle` | `CSSProperties` | — | Per-cell overrides |
+
+| Prop (Item) | Type | Description |
+| --- | --- | --- |
+| `label` | `ReactNode` | Required |
+| `children` | `ReactNode` | Value content |
+| `span` | `number` | Multi-column span (when `columns > 1`) |
+| `valueColor` | semantic color | For status / amount |
+
+## Layouts
+
+### Horizontal (default)
+
+Label on left, value on right. Most product UIs.
+
+| Property | Width |
+| --- | --- |
+| Label column | ~30% (or fixed 120–160px) |
+| Value column | rest |
+
+### Vertical
+
+Label above value. Use when:
+- Labels are long (Korean labels often need this).
+- Values are wide (long URLs, multi-line text).
+- Forms-adjacent style.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Plain text |
+| Empty value | "—" or "정보 없음" placeholder |
+| Sensitive (masked) | "****-1234" partial reveal |
+| Editable on hover | Pen icon appears, click → enters edit mode (if interactive) |
+
+## Tokens consumed
+
+```
+--color-text-primary       (value)
+--color-text-secondary      (label)
+--color-text-tertiary
+--color-bg-default
+--color-bg-subtle           (alternating rows if bordered)
+--color-border-default      (bordered variant)
+--space-xs, --space-sm, --space-md
+--font-size-sm, --font-size-base
+```
+
+## Accessibility
+
+Render as `<dl>` (definition list) for semantics:
+
+```html
+<dl>
+  <div>
+    <dt>이름</dt>
+    <dd>김민지</dd>
+  </div>
+  <div>
+    <dt>이메일</dt>
+    <dd>minji@example.com</dd>
+  </div>
+</dl>
+```
+
+Screen readers parse `<dt>` as "term", `<dd>` as "description". Keyboard users tab through interactive values only.
+
+For sensitive values (account number): provide `aria-label` on the masked rendering — "계좌번호 마지막 네 자리, 일이삼사".
+
+## Korean conventions
+
+Typical labels:
+
+| Korean | English |
+| --- | --- |
+| 이름 | Name |
+| 이메일 | Email |
+| 휴대폰 / 전화번호 | Phone |
+| 주소 | Address |
+| 가입일 | Sign-up date |
+| 결제 수단 | Payment method |
+| 자동결제 | Auto-payment |
+| 회원 등급 | Membership tier |
+| 적립금 | Points |
+
+For long Korean labels: switch to vertical layout (label above value).
+
+## Code example
+
+```tsx
+function ProfileScreen() {
+  const user = useUser();
+
+  return (
+    <Page>
+      <PageHeader>내 정보</PageHeader>
+
+      <Descriptions title="계정" columns={1} bordered>
+        <Descriptions.Item label="이름">{user.name}</Descriptions.Item>
+        <Descriptions.Item label="이메일">{user.email}</Descriptions.Item>
+        <Descriptions.Item label="휴대폰">{formatPhone(user.phone)}</Descriptions.Item>
+        <Descriptions.Item label="가입일">{formatDate(user.createdAt)}</Descriptions.Item>
+      </Descriptions>
+
+      <Descriptions title="결제" columns={1} bordered>
+        <Descriptions.Item label="카드">
+          {user.savedCard
+            ? `${user.savedCard.bank} ****-${user.savedCard.last4}`
+            : "등록된 카드 없음"}
+        </Descriptions.Item>
+        <Descriptions.Item label="자동결제">
+          <Tag color={user.autoPayment ? "success" : "default"}>
+            {user.autoPayment ? "사용 중" : "미사용"}
+          </Tag>
+        </Descriptions.Item>
+      </Descriptions>
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **Long values that wrap**: align label to top of value (`vertical-align: top`).
+- **Empty value**: render `—` or culturally-appropriate placeholder ("정보 없음").
+- **Sensitive value masked**: pair with copy-button if it's user's identifier (account number, member ID).
+- **Editable inline**: switch to Form when in edit mode; revert to Descriptions when done.
+- **Mobile**: descend to single-column regardless of `columns` prop, or use vertical layout per item.
+
+## Don't
+
+- Don't use Descriptions for editable forms. Use `Form`.
+- Don't put complex interactive widgets in values (use a different component).
+- Don't omit the label — values without labels are mystery data.
+- Don't show empty values without placeholder — looks broken.
+- Don't use `:` in labels by default (Korean convention is space). Toggle `colon` prop if needed.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/descriptions/`](../refs/ant-design/components/descriptions/) — most exhaustive (column, span, layout, bordered, sections).
+- MUI / shadcn-ui: no built-in. Compose with `<dl>` + Tailwind.
+
+## Cross-reference
+
+- [`examples/component-form.md`](component-form.md) — editable counterpart
+- [`examples/component-table.md`](component-table.md) — for many comparable items
+- [`examples/component-card.md`](component-card.md) — wraps Descriptions in detail screens
+- [`knowledge/patterns/settings-page.md`](../knowledge/patterns/settings-page.md) — Descriptions on settings pages

package/examples/component-dialog-actions.md

@@ -0,0 +1,111 @@
+# `DialogActions` — spec
+
+> Synthesized from MUI `DialogActions`. The action row at the bottom of a `Dialog`. Right-aligns buttons by default; primary action goes last (right-most) so it gets the user's reading-direction emphasis.
+
+## When to use
+
+- Inside every interactive `Dialog` — confirmation, form submission, choice prompts.
+- For non-blocking inline confirmations, prefer `Popconfirm` instead of opening a Dialog.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────┐
+│            [ Cancel ]   [ Primary ]        │
+└────────────────────────────────────────────┘
+```
+
+Korean / Western convention: cancel on the left, primary on the right. macOS / iOS native convention is reversed (primary on the right is consistent across both, but cancel position varies). Match your platform target.
+
+## API
+
+```tsx
+<DialogActions>
+  <Button onClick={handleClose}>취소</Button>
+  <Button onClick={handleConfirm} variant="contained" autoFocus>
+    삭제
+  </Button>
+</DialogActions>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Action buttons |
+| `disableSpacing` | `boolean` | `false` | Remove default 8px gap between buttons |
+
+## States
+
+Non-interactive itself. Buttons own their states.
+
+## Button order convention
+
+| Convention | Order (left → right) |
+| --- | --- |
+| Web / Material / Korean apps | Cancel · Primary |
+| iOS native (sheet style) | Cancel · Primary (primary highlighted) |
+| Windows native | Primary · Cancel |
+| Linux GNOME native | Cancel · Primary |
+
+For Korean B2C / B2B apps, use **Cancel · Primary** (matches Toss / KakaoBank / NaverPay convention).
+
+For destructive primary actions (e.g., 삭제), use `color="error"` on the primary button + place it in the same right-most position. Don't move it to the left to "discourage" — users learn one position; consistency matters more than friction.
+
+## Tokens consumed
+
+```
+--space-sm        /* gap between buttons */
+--space-md        /* container padding */
+```
+
+## Accessibility
+
+- The primary action should have `autoFocus` (so Enter activates it without keyboard nav).
+- For destructive primary actions, consider NOT auto-focusing — require explicit click. Cite [`knowledge/patterns/empty-states.md`](../knowledge/patterns/empty-states.md) (the same pattern applies to confirmation flows).
+- Tab order: cancel → primary (matches visual order).
+- Esc must trigger cancel (handled at the `Dialog` level, not here).
+
+## Edge cases
+
+- **3-button choice** — left: tertiary action ("나중에"); middle: cancel; right: primary. Avoid 4+ buttons — split into a multi-step flow.
+- **Loading primary** — disable both cancel and primary while pending; show spinner on primary. Don't allow cancel during destructive operations that can't actually be undone.
+- **Mobile narrow widths** — buttons can wrap to two rows. Test at 320px width.
+
+## Code example
+
+```tsx
+<Dialog open={open} onClose={handleClose}>
+  <DialogTitle id="delete-title">정말 삭제할까요?</DialogTitle>
+  <DialogContent>
+    <DialogContentText>이 작업은 취소할 수 없어요.</DialogContentText>
+  </DialogContent>
+  <DialogActions>
+    <Button onClick={handleClose}>취소</Button>
+    <LoadingButton
+      onClick={handleDelete}
+      loading={isPending}
+      variant="contained"
+      color="error"
+    >
+      삭제
+    </LoadingButton>
+  </DialogActions>
+</Dialog>
+```
+
+## Don't
+
+- Don't put 4+ buttons — confusing.
+- Don't reverse the order to discourage destructive actions — users learn one order; consistency matters more.
+- Don't omit a clear cancel — every dialog needs a way out (Esc + at least one button).
+
+## References
+
+- MUI: [`DialogActions.d.ts`](../refs/mui/packages/mui-material/src/DialogActions/DialogActions.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-dialog.md`](component-dialog.md)
+- [`component-dialog-title.md`](component-dialog-title.md)
+- [`component-dialog-content.md`](component-dialog-content.md)
+- [`component-button.md`](component-button.md)

package/examples/component-dialog-content-text.md

@@ -0,0 +1,76 @@
+# `DialogContentText` — spec
+
+> Synthesized from MUI `DialogContentText`. The descriptive paragraph inside `DialogContent`. Provides the accessible *description* for the dialog via `aria-describedby` association.
+
+## When to use
+
+- Inside every Dialog whose body has explanatory text.
+- Pair with `aria-describedby` on the parent Dialog.
+
+## API
+
+```tsx
+<Dialog aria-labelledby="t" aria-describedby="d">
+  <DialogTitle id="t">정말 삭제할까요?</DialogTitle>
+  <DialogContent>
+    <DialogContentText id="d">
+      이 작업은 되돌릴 수 없어요.
+    </DialogContentText>
+  </DialogContent>
+  <DialogActions>...</DialogActions>
+</Dialog>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Required for `aria-describedby` association on parent Dialog |
+| `children` | `ReactNode` | — | Description text |
+
+Extends `Typography` — all typography props work.
+
+## Tokens consumed
+
+```
+--font-size-body
+--color-fg-muted          /* slightly less prominent than primary content */
+--line-height-body
+```
+
+## Accessibility
+
+- Without matching `aria-describedby` on the parent Dialog, the description is just visual — screen readers won't connect it.
+- For dialogs with multiple paragraphs, only one needs the `id` (the most informative). Or wrap multiple paragraphs in a `<div id="d">` and put `id` on that.
+
+## Edge cases
+
+- **Long description** — wraps. For multi-paragraph, use multiple `<Typography>` children with one outer container holding the `id`.
+- **Markdown links inside** — inline links work; ensure they're keyboard-accessible (focus moves to them inside the trapped dialog).
+- **Korean honorific** — match the title's register. Confirmation: 합쇼체 ("되돌릴 수 없습니다"). Friendly: 해요체 ("되돌릴 수 없어요").
+
+## Code example
+
+```tsx
+<DialogContent>
+  <DialogContentText id="leave-desc">
+    저장하지 않은 변경사항이 있어요.{' '}
+    <Link href="/help/auto-save" target="_blank" onClick={(e) => e.stopPropagation()}>
+      자동 저장이 켜져 있나요?
+    </Link>
+  </DialogContentText>
+</DialogContent>
+```
+
+## Don't
+
+- Don't omit `id` — defeats `aria-describedby`.
+- Don't use as a generic paragraph — for non-described body text, use `<Typography>`.
+
+## References
+
+- MUI: [`DialogContentText`](../refs/mui/packages/mui-material/src/DialogContentText/)
+
+## Cross-reference
+
+- [`component-dialog.md`](component-dialog.md)
+- [`component-dialog-title.md`](component-dialog-title.md)
+- [`component-dialog-content.md`](component-dialog-content.md)