@design-ai/cli 4.55.0

package/examples/component-calendar.md

@@ -0,0 +1,280 @@
+# `Calendar` (full month view) — spec
+
+> Citing Ant Design `Calendar`, MUI (no dedicated — `DateCalendar` from x-date-pickers is similar), shadcn-ui `calendar` (react-day-picker)
+>
+> Different from `DatePicker` ([`component-date-picker.md`](component-date-picker.md)) — Calendar is a **full-page month view**; DatePicker is a popover for picking a date.
+
+## Purpose
+
+A full-month or full-year calendar view used as a primary UI surface — for scheduling apps, event listings, attendance trackers, or any view where the calendar IS the page.
+
+## When Calendar vs DatePicker
+
+| Pattern | Use |
+| --- | --- |
+| **Calendar** (this spec) | Calendar is the primary content of the screen. User browses dates, views events, clicks days. |
+| **DatePicker** | User picks a date as form input. Calendar appears in a popover. |
+
+If your screen's main job is "view this month", use Calendar. If picking a date is incidental, use DatePicker.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────────────────────┐
+│  ◀  2026년 5월  ▶               [월] [주] [년]   [+ 이벤트] │  ← header: nav + view + actions
+├────────────────────────────────────────────────────────────┤
+│  일  월  화  수  목  금  토                                  │  ← weekday headers
+├────────────────────────────────────────────────────────────┤
+│       1   2                                                  │
+│       ●           [event chip]                              │  ← cell: number + indicator + events
+│  3   4   5   6   7   8   9                                   │
+│           ●                                                  │
+│ 10  11  12  13  14  15  16                                   │
+│ ...                                                           │
+└────────────────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Header | yes | Month nav, view toggle, "today" button |
+| Weekday row | yes | 일–토 (or Sun–Sat) |
+| Date cells | yes | One per day; shows day number + events |
+| Event indicators | optional | Dots, chips, or full event blocks |
+| Today highlight | yes | Current date visually marked |
+| Selected highlight | when applicable | Currently-selected date |
+
+## API
+
+```tsx
+<Calendar
+  value={selectedDate}
+  onValueChange={setSelectedDate}
+  view="month"
+  events={events}
+  renderCell={(date) => <CustomCellContent date={date} />}
+  onDateClick={(date) => openDayDetail(date)}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Date` | `today()` | Selected / focused date |
+| `onValueChange` | `(date: Date) => void` | — | |
+| `view` | `"month" \| "week" \| "year" \| "day"` | `"month"` | Time scale |
+| `onViewChange` | `(view) => void` | — | |
+| `events` | `Event[]` | `[]` | Events to render in cells |
+| `renderCell` | `(date) => ReactNode` | default | Custom cell rendering |
+| `onDateClick` | `(date) => void` | — | Cell click |
+| `onEventClick` | `(event) => void` | — | Event chip click |
+| `weekStartsOn` | `0..6` | `0` (Sun for KR/US) | |
+| `locale` | `string` | `"ko-KR"` | |
+| `holidays` | `{ date: Date, name: string }[]` | `[]` | Korean 공휴일, etc. |
+| `disabledDates` | `(date) => boolean` | — | |
+| `minDate` / `maxDate` | `Date` | — | |
+| `density` | `"compact" \| "comfortable"` | `"comfortable"` | Cell height |
+
+```ts
+type Event = {
+  id: string;
+  date: Date;
+  endDate?: Date;          // For multi-day events
+  title: string;
+  color?: string;
+  data?: unknown;
+};
+```
+
+## Views
+
+### Month view (default)
+
+7 columns × 5–6 rows. Each cell shows:
+- Day number
+- Events as small chips/dots (max 2–3 visible; "+N more" for overflow)
+- Today highlighted
+- Other-month days muted
+
+### Week view
+
+7 columns × 1 column of hours. Used for hour-by-hour schedule (calendar apps).
+
+### Day view
+
+Single column with hour rows. Detail view for one day.
+
+### Year view
+
+12 month thumbnails. Click any month to drill into Month view.
+
+## Cell rendering — events
+
+```
+┌──────────────┐
+│ 7        ●   │  ← day number + indicator
+│              │
+│ 10:00 회의   │  ← event chips (max 2-3)
+│ 14:00 점심   │
+│ + 2 more     │  ← overflow
+└──────────────┘
+```
+
+| Indicator pattern | Use |
+| --- | --- |
+| Single dot | "Has events" — minimal, used in compact view |
+| Color dots | "Multiple event types" — one per event |
+| Event chips | Short title visible — full event titles, truncated |
+
+For compact density (mobile): dots. For comfortable density (desktop): chips.
+
+## States — per cell
+
+| State | Visual |
+| --- | --- |
+| Default | Day number, events |
+| Today | Bold day number, light bg or ring |
+| Selected | Filled bg `--color-primary-default`, white number |
+| Hover | Bg `--color-bg-subtle` |
+| Other-month | Muted day number |
+| Disabled | No events, muted, no click |
+| Holiday | Day number in red (Korean convention for 공휴일) |
+| Weekend | Day number subtly different (often blue for Saturday, red for Sunday in KR) |
+
+### Korean holiday/weekend conventions
+
+- 일요일 (Sunday): red
+- 토요일 (Saturday): blue
+- 공휴일 (national holidays): red
+- 평일 (weekdays): default text color
+
+```css
+.calendar-cell[data-day="0"] { color: var(--color-error); }    /* Sunday */
+.calendar-cell[data-day="6"] { color: var(--color-info); }     /* Saturday */
+.calendar-cell[data-holiday="true"] { color: var(--color-error); }
+```
+
+## Sizes / density
+
+| Density | Cell min-height | Padding | Use |
+| --- | --- | --- | --- |
+| `compact` | 60px | 4px | Mobile, dense schedule |
+| `comfortable` (default) | 100px | 8px | Standard desktop |
+
+For event-heavy calendars (Google Calendar style): cells expand to fit events with internal scroll.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (cell bg)
+--color-bg-subtle           (hover)
+--color-primary-default     (today highlight, selected)
+--color-primary-subtle-bg
+--color-on-primary
+--color-text-primary
+--color-text-secondary       (other-month)
+--color-text-tertiary        (weekday headers)
+--color-error                (Sunday, holidays)
+--color-info                 (Saturday)
+--color-border-default
+--space-xs, --space-sm
+--radius-md
+--font-size-sm, --font-size-base
+```
+
+## Accessibility — WAI-ARIA Calendar pattern
+
+- Container: `role="grid"`, `aria-label="달력 2026년 5월"`.
+- Weekday headers: `role="columnheader"`, `aria-label` for the full day name.
+- Each row: `role="row"`.
+- Each cell: `role="gridcell"`, `aria-selected`, `aria-current="date"` for today.
+- Disabled: `aria-disabled="true"`.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reach grid (single tab stop into the cells) |
+| `←` / `→` | Move 1 day |
+| `↑` / `↓` | Move 1 week |
+| `PageUp` / `PageDown` | Previous / next month |
+| `Shift+PageUp/Down` | Previous / next year |
+| `Home` / `End` | First / last day of week |
+| `Enter` / `Space` | Select / activate cell |
+
+This is the WAI-ARIA APG datepicker pattern. Same as DatePicker.
+
+### Screen reader
+
+- Announce date on focus change: "May 7, 2026, Wednesday"
+- Announce events: "7 events on this day" or names if few
+- Announce holidays: "Buddha's Birthday"
+
+## Code example
+
+```tsx
+function MonthlyScheduleScreen() {
+  const [selected, setSelected] = useState(new Date());
+  const events = useEvents(selected);
+
+  return (
+    <div>
+      <Calendar
+        value={selected}
+        onValueChange={setSelected}
+        events={events}
+        holidays={koreanHolidays}
+        onDateClick={(date) => openDayDetail(date)}
+        onEventClick={(event) => openEventDetail(event)}
+        renderCell={(date) => (
+          <DefaultCell
+            date={date}
+            isToday={isToday(date)}
+            isHoliday={isHoliday(date)}
+            events={events.filter(e => isSameDay(e.date, date))}
+          />
+        )}
+      />
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Many events on a single day**: render first 2–3 + "+N more". Click day to open day-detail screen.
+- **Multi-day event**: render as a horizontal bar spanning multiple cells (visual challenge — usually a separate library handles).
+- **Cell content overflow**: ellipsis truncation; provide tooltip or detail-on-click.
+- **Daylight saving** (not in Korea): handle correctly; display dates per local TZ.
+- **Korean lunar calendar (음력)**: rare in product UIs. Some apps annotate Korean lunar date in cell (small, secondary).
+- **Year boundary**: December → January transition shows partial rows from both.
+- **Empty month**: render the grid normally; cells just have no events.
+- **Mobile portrait**: month view's 7 columns crunch. Switch to compact density or week view by default.
+
+## Don't
+
+- Don't render Calendar without events when the screen's purpose is event display. Show empty state instead.
+- Don't shrink cells below readable size. Switch view (week, day) instead.
+- Don't combine 5+ event colors per day. Use neutral chips or fewer event types.
+- Don't auto-redirect to day detail on click — let user opt in via explicit action.
+- Don't use Calendar where DatePicker fits (form input).
+- Don't forget keyboard navigation. Calendar without arrow keys is broken.
+- Don't ship without locale support for the user's date/week conventions.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/calendar/`](../refs/ant-design/components/calendar/) — `Calendar` with `mode="month" | "year"`, `dateCellRender`, `monthCellRender`. Most exhaustive.
+- MUI: `@mui/x-date-pickers` `DateCalendar` — focused on date selection within a calendar grid; not full-month event-display.
+- 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`. Use as date selector or full calendar via `mode="default"` + `numberOfMonths`.
+
+For event-heavy calendar apps (Google Calendar style), consider:
+- `react-big-calendar` — month/week/day views with events
+- `fullcalendar` — feature-rich, all views
+
+This spec covers the **simpler full-month-with-event-indicators** case. For full event-management UIs, layer this with a calendar-specific library.
+
+## Cross-reference
+
+- [`examples/component-date-picker.md`](component-date-picker.md) — for form-input use
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — Korean date formats
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — holiday + weekend color conventions
+- [WAI-ARIA Date Picker pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/examples/datepicker-dialog/)

package/examples/component-callout.md

@@ -0,0 +1,131 @@
+# `Callout` (info/warning/note in docs) — spec
+
+> Doc-specific component. Highlights important asides in long-form content. Distinct from `Alert` (which is for product UI feedback) — Callout is for **documentation prose**.
+
+## Purpose
+
+Marks a passage as important info, warning, tip, or note. Visually distinct from body text but doesn't break reading flow.
+
+## When Callout vs Alert vs Blockquote
+
+| Use Callout | Use Alert | Use Blockquote |
+| --- | --- | --- |
+| Long-form docs | Product UI feedback | Quote from another source |
+| Tip, note, warning, danger inside reading | Real-time notification | Attribution matters |
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────┐
+│ ℹ Note                                                │  ← icon + label header
+│                                                       │
+│ The body text of the callout. May span multiple       │
+│ paragraphs and contain code, lists, links.            │
+└──────────────────────────────────────────────────────┘
+   subtle bg, accent left-border
+```
+
+## API
+
+```mdx
+<Callout type="note">
+  This is an important note.
+</Callout>
+
+<Callout type="warning" title="Custom title">
+  Be careful — this can lose data.
+</Callout>
+
+<Callout type="tip">
+  💡 You can also use the keyboard shortcut.
+</Callout>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"note" \| "tip" \| "info" \| "warning" \| "danger" \| "success"` | `"note"` | Visual + icon |
+| `title` | `string` | derived from type | Header text (override) |
+| `children` | `ReactNode` | — | Body |
+| `compact` | `boolean` | `false` | Single-line variant |
+
+## Type → visual mapping
+
+| Type | Icon | Border | Bg tint | Use |
+| --- | --- | --- | --- | --- |
+| `note` | ℹ | `--color-info` | `--color-info-subtle-bg` | Side commentary |
+| `tip` | 💡 | `--color-success` | `--color-success-subtle-bg` | Useful trick / shortcut |
+| `info` | ℹ | `--color-info` | `--color-info-subtle-bg` | Background context |
+| `warning` | ⚠ | `--color-warning` | `--color-warning-subtle-bg` | Pay attention; potentially problematic |
+| `danger` | 🛑 | `--color-error` | `--color-error-subtle-bg` | Will cause harm if ignored |
+| `success` | ✓ | `--color-success` | `--color-success-subtle-bg` | Confirmation / "this worked" |
+
+## Tokens consumed
+
+```
+--color-info-subtle-bg, --color-info
+--color-warning-subtle-bg, --color-warning
+--color-error-subtle-bg, --color-error
+--color-success-subtle-bg, --color-success
+--color-text-primary
+--color-text-secondary
+--space-md, --space-base
+--radius-md
+--font-size-base
+```
+
+## Sizes
+
+Body 16–18px (matches surrounding doc body). Title slightly bolder (semibold).
+
+For compact variant: 14px, single-line, useful for inline tips.
+
+## Korean callouts
+
+| Type | Korean header |
+| --- | --- |
+| note | 참고 |
+| tip | 팁 |
+| info | 안내 |
+| warning | 주의 |
+| danger | 위험 / 경고 |
+| success | 완료 |
+
+For Korean docs: per [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md), use formal tone (`~합니다 / 입니다`).
+
+```mdx
+<Callout type="warning" title="주의">
+  이 작업은 되돌릴 수 없습니다. 신중히 진행해 주세요.
+</Callout>
+```
+
+## Accessibility
+
+- Render as `<aside>` with `aria-label="Note"` (or appropriate per type).
+- For `danger` / `warning`: `role="alert"` if the callout's appearance should interrupt reading flow.
+- For passive types (note, tip, info): no role needed — just an `<aside>`.
+- Icon: `aria-hidden="true"` (header label conveys meaning).
+
+## Don't
+
+- Don't overuse — every paragraph as callout = noise.
+- Don't nest callouts (callout inside callout).
+- Don't use `danger` for non-destructive info.
+- Don't put primary CTAs in callouts.
+- Don't use color alone to convey type — icon + label do the work.
+
+## References
+
+Most documentation tools (Docusaurus, Notion, GitBook, MDX-based sites) ship a Callout component. The variation is mostly in `type` naming.
+
+- Docusaurus: `:::note`, `:::tip`, `:::info`, `:::warning`, `:::danger`
+- GitBook: `<hint type="info|warning|danger|success">...</hint>`
+- Notion: built-in callout block with icon
+
+For design-ai's docs: MDX-based callout matching this spec.
+
+## Cross-reference
+
+- [`examples/component-alert.md`](component-alert.md) — for product UI feedback (different)
+- [`examples/component-blockquote.md`](component-blockquote.md) — for quotations
+- [`knowledge/patterns/document-typography.md`](../knowledge/patterns/document-typography.md)
+- [`knowledge/i18n/korean-document-style.md`](../knowledge/i18n/korean-document-style.md) — Korean callout headers

package/examples/component-card-actions.md

@@ -0,0 +1,101 @@
+# `CardActions` — spec
+
+> Synthesized from MUI `CardActions`. The action row at the bottom of a `Card`. Left-aligns by default (unlike `DialogActions` which is right-aligned).
+
+## When to use
+
+- Inside `Card` for inline actions ("자세히", "공유", "저장").
+- For destructive or modal-triggering actions, use a Dialog instead.
+
+## Anatomy
+
+```
+┌────────────────────────────┐
+│ [CardContent]              │
+├────────────────────────────┤
+│ [Action] [Action]          │
+└────────────────────────────┘
+```
+
+Left-aligned by default. The convention differs from `DialogActions` (right-aligned) because cards are scanning surfaces — the eye reads left-to-right, sees the headline, then the action without backtracking.
+
+## API
+
+```tsx
+<Card>
+  <CardContent>...</CardContent>
+  <CardActions>
+    <Button size="small">자세히</Button>
+    <Button size="small">공유</Button>
+  </CardActions>
+</Card>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Action buttons (typically `size="small"`) |
+| `disableSpacing` | `boolean` | `false` | Remove default 8px gap between buttons |
+
+## Button conventions
+
+- Use `size="small"` (matches Card's compact reading rhythm).
+- Use `variant="text"` or `variant="outlined"` — `contained` is too heavy for a card action.
+- Maximum 2-3 actions per card. More = the card is doing too much.
+
+## Tokens consumed
+
+```
+--space-sm     /* gap */
+--space-md     /* horizontal padding */
+--space-sm-y   /* vertical padding (lighter than DialogActions) */
+```
+
+## Accessibility
+
+- Each button needs an accessible name — for icon-only buttons inside `CardActions`, provide `aria-label`.
+- Tab order: matches visual order (left → right).
+- For "expandable card" patterns where a `CardActions` button reveals more content, use `aria-expanded` on that button.
+
+## Edge cases
+
+- **Mobile narrow widths** — `CardActions` can right-align by setting `sx={{ justifyContent: 'flex-end' }}` if your Card design calls for it.
+- **Long button labels in Korean** — Hangul labels run wider; consider icon-only buttons with `aria-label` for compact card grids.
+- **Single primary action** — still wrap in `CardActions` for consistent padding.
+
+## Code example
+
+```tsx
+<Card>
+  <CardMedia component="img" image="/post.jpg" alt="" />
+  <CardContent>
+    <Typography variant="h6">{post.title}</Typography>
+    <Typography variant="body2">{post.excerpt}</Typography>
+  </CardContent>
+  <CardActions>
+    <Button size="small" startIcon={<ReadIcon />}>읽기</Button>
+    <Button size="small" startIcon={<ShareIcon />}>공유</Button>
+    <Box sx={{ ml: 'auto' }}>
+      <IconButton aria-label="좋아요">
+        <FavoriteIcon />
+      </IconButton>
+    </Box>
+  </CardActions>
+</Card>
+```
+
+## Don't
+
+- Don't put 4+ actions — overflow into a menu.
+- Don't use `variant="contained"` — too heavy for a card.
+- Don't right-align without a reason — left-aligned is the cross-product expected pattern.
+
+## References
+
+- MUI: [`CardActions.d.ts`](../refs/mui/packages/mui-material/src/CardActions/CardActions.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-card.md`](component-card.md)
+- [`component-card-content.md`](component-card-content.md)
+- [`component-button.md`](component-button.md)

package/examples/component-card-content.md

@@ -0,0 +1,90 @@
+# `CardContent` — spec
+
+> Synthesized from MUI `CardContent`. The body region of a `Card`. Provides the default padding so card body content aligns with the card's grid.
+
+## When to use
+
+- Inside every `Card` that has body content beyond a hero image.
+- For media-only cards (`CardMedia` only), skip `CardContent`.
+
+## Anatomy
+
+```
+┌────────────────────────────┐
+│ [CardMedia / image]        │
+├────────────────────────────┤
+│ CardContent                │
+│   - Title                  │
+│   - Body text              │
+│   - Tags / metadata        │
+├────────────────────────────┤
+│ CardActions                │
+└────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Card>
+  <CardContent>
+    <Typography variant="h5">제목</Typography>
+    <Typography variant="body2">본문 텍스트</Typography>
+  </CardContent>
+</Card>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Body content |
+
+## Tokens consumed
+
+```
+--card-content-padding   /* default 16px / dense 8px */
+--space-md
+--space-sm
+```
+
+## Accessibility
+
+`CardContent` is structural (a `<div>`); it doesn't add semantics. The Card's role is determined by its surrounding context — wrap interactive cards in `<a>` or `<button>` higher in the tree, not at `CardContent` level.
+
+## Edge cases
+
+- **Card with no media** — `CardContent` becomes the only child; ensure padding still feels right (default 16px works).
+- **Korean text density** — Hangul reads ~10% wider; consider 20-24px padding for body-heavy cards.
+- **Bottom padding** — when `CardActions` follows, MUI removes the bottom padding of `CardContent` so the action row hugs the bottom. Don't override this without reason.
+
+## Code example
+
+```tsx
+<Card sx={{ maxWidth: 360 }}>
+  <CardMedia component="img" image="/cover.jpg" alt="" />
+  <CardContent>
+    <Typography variant="h6">제목</Typography>
+    <Typography variant="body2" color="text.secondary">
+      본문 요약 텍스트.
+    </Typography>
+  </CardContent>
+  <CardActions>
+    <Button size="small">자세히</Button>
+  </CardActions>
+</Card>
+```
+
+## Don't
+
+- Don't override the bottom padding when followed by `CardActions` — MUI handles this.
+- Don't put `Card`-level interactive surfaces (link, click handler) on `CardContent` — they belong on the Card or on `CardActionArea`.
+
+## References
+
+- MUI: [`CardContent.d.ts`](../refs/mui/packages/mui-material/src/CardContent/CardContent.d.ts)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-card.md`](component-card.md)
+- [`component-card-actions.md`](component-card-actions.md)
+- [`component-card-media.md`](component-card-media.md)
+- [`component-card-header.md`](component-card-header.md)