@design-ai/cli 4.55.0

package/examples/component-message.md

@@ -0,0 +1,162 @@
+# `Message` — spec
+
+> Synthesized from Ant Design `Message`. A top-of-page transient notification — a thin strip / pill that appears at the top center for 1.5-3 seconds, then auto-dismisses. Distinct from `Toast` (corner-anchored) and `Notification` (richer, persistent corner).
+
+## Message vs Toast vs Notification
+
+| | Message | Toast | Notification |
+| --- | --- | --- | --- |
+| Position | Top center | Bottom-right (or corner) | Top-right (corner) |
+| Size | Thin pill | Card-sized | Larger card |
+| Duration | 1.5-3s | 3-5s | 4.5s default; can be persistent |
+| Use | Result of action ("저장됨") | Action result + optional Undo | Notification with title + description |
+| Title? | No (just one line) | Optional | Yes |
+
+For **brief action confirmation** (저장됨, 복사됨): Message.
+For **action confirmation with Undo**: Toast.
+For **rich notifications with detail**: Notification.
+
+## Anatomy
+
+```
+                ✓ 저장되었어요
+              ↑ pill, top center, brief
+```
+
+## API
+
+Imperative API (Ant-style):
+
+```tsx
+import { message } from "antd";
+
+message.success("저장되었어요");
+message.error("저장에 실패했어요");
+message.info("새 버전이 있어요");
+message.warning("연결이 불안정해요");
+message.loading("처리 중...");
+
+// With config
+message.success({ content: "복사됨", duration: 1.5 });
+
+// Custom dismiss
+const hide = message.loading("Saving...", 0);  // 0 = persistent
+// later
+hide();
+```
+
+| API | Description |
+| --- | --- |
+| `message.success(content, duration?)` | Green check |
+| `message.error(content, duration?)` | Red X |
+| `message.info(content, duration?)` | Blue info |
+| `message.warning(content, duration?)` | Amber triangle |
+| `message.loading(content, duration?)` | Spinner |
+| `message.open(config)` | Full config object |
+| `message.destroy()` | Clear all messages |
+
+| Config field | Description |
+| --- | --- |
+| `content` | Text or ReactNode |
+| `duration` | Seconds (default 3); 0 = persistent |
+| `key` | Unique key (replace existing message with same key) |
+| `onClose` | Callback when dismissed |
+| `icon` | Custom icon override |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| success | Green check icon + content |
+| error | Red X icon + content |
+| info | Blue info icon |
+| warning | Amber triangle |
+| loading | Spinner + content |
+
+## Animation
+
+```
+Enter: slide down + fade in (200ms)
+Hold: full opacity for `duration` seconds
+Exit: slide up + fade out (200ms)
+```
+
+Reduced motion: skip slide; just fade.
+
+## Tokens consumed
+
+```
+--message-bg                       (white / dark surface)
+--message-fg
+--message-success-icon             (green)
+--message-error-icon               (red)
+--message-warning-icon             (amber)
+--message-info-icon                (blue)
+--message-shadow
+--radius-md
+--space-sm, --space-md
+--font-size-sm
+--motion-medium                    (slide animation)
+--ease-out
+--z-message                        (above modals)
+```
+
+## Accessibility
+
+- Container: `role="status"` (info / success) or `role="alert"` (error / warning).
+- `aria-live="polite"` for status; `assertive` for error.
+- Don't use for accessibility-critical info that user must read at length — use a Modal or persistent Banner.
+- For loading: pair with `aria-busy="true"` on the affected region.
+
+## Korean conventions
+
+| Action | Message |
+| --- | --- |
+| Save success | "저장되었어요" / "저장됐어요" |
+| Copy | "복사되었어요" |
+| Delete | "삭제됐어요" (often with Toast + Undo instead) |
+| Error | "오류가 발생했어요" |
+| Loading | "처리 중이에요..." |
+| Network error | "네트워크가 불안정해요" |
+
+해요체 default for casual brand voice.
+
+## Code example
+
+```tsx
+async function handleSave() {
+  const hide = message.loading("저장 중...");
+  try {
+    await api.save(data);
+    hide();
+    message.success("저장되었어요");
+  } catch (err) {
+    hide();
+    message.error("저장에 실패했어요. 다시 시도해 주세요.");
+  }
+}
+
+async function handleCopy() {
+  await navigator.clipboard.writeText(text);
+  message.success({ content: "복사됨", duration: 1.5 });
+}
+```
+
+## Don't
+
+- Don't use Message for actions with Undo. Use Toast (anchor in corner; allow Undo button).
+- Don't show 5 concurrent messages — they stack and confuse. Cap at 1-2 visible.
+- Don't use Message for critical errors that block the user. Use Modal / AlertDialog.
+- Don't make Message disappear in 500ms. Min 1.5s for users to read.
+- Don't translate Message content from English word-for-word — adapt to Korean phrasing.
+
+## References
+
+- Ant: [`Message`](../refs/ant-design/components/message)
+- Patterns: same family as iOS HUD, Material Snackbar (variant)
+
+## Cross-reference
+
+- [`examples/component-toast.md`](component-toast.md) — corner alternative with Undo
+- [`examples/component-notification.md`](component-notification.md) — richer card variant
+- [`examples/component-banner.md`](component-banner.md) — persistent strip variant

package/examples/component-mobile-stepper.md

@@ -0,0 +1,155 @@
+# `MobileStepper` — spec
+
+> Synthesized from MUI `MobileStepper`. Compact step indicator for mobile-first flows — shows progress as dots, text, or a progress bar. Used in onboarding, image carousels, multi-step bottom sheets.
+
+## When to use
+
+- Mobile onboarding flow (3-7 steps).
+- Carousel position indicator.
+- Multi-step bottom sheet.
+
+## When NOT to use
+
+- Desktop multi-step form → use `Stepper` (horizontal, labeled).
+- Single-step → no indicator needed.
+- Long flows (10+ steps) → use a percentage progress instead.
+
+## Anatomy
+
+```
+Variant = "dots":
+┌──────────────────────────────────────────┐
+│  [Back]    ● ○ ○ ○ ○             [Next] │
+└──────────────────────────────────────────┘
+
+Variant = "progress":
+┌──────────────────────────────────────────┐
+│  [Back]    ▓▓▓▓░░░░░░░░░░         [Next] │
+└──────────────────────────────────────────┘
+
+Variant = "text":
+┌──────────────────────────────────────────┐
+│  [Back]         3 / 7             [Next] │
+└──────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<MobileStepper
+  variant="dots"
+  steps={5}
+  position="bottom"
+  activeStep={step}
+  nextButton={
+    <Button onClick={handleNext} disabled={step === 4}>
+      다음 <KeyboardArrowRight />
+    </Button>
+  }
+  backButton={
+    <Button onClick={handleBack} disabled={step === 0}>
+      <KeyboardArrowLeft /> 이전
+    </Button>
+  }
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `'dots' \| 'progress' \| 'text'` | `'dots'` | Indicator style |
+| `steps` | `number` | required | Total steps |
+| `activeStep` | `number` | `0` | Current step (0-indexed) |
+| `position` | `'bottom' \| 'top' \| 'static'` | `'bottom'` | Sticky position |
+| `nextButton` | `ReactNode` | required | Next button element |
+| `backButton` | `ReactNode` | required | Back button element |
+| `LinearProgressProps` | `LinearProgressProps` | — | Customize progress variant |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Step N active | Nth dot filled / progress bar at N/total / "N / total" text |
+| First step | Back button disabled |
+| Last step | Next button label often changes ("완료" / "Done") |
+
+## Tokens consumed
+
+```
+--space-md                 /* horizontal padding */
+--dot-size-8               /* dot diameter */
+--dot-color-active         /* brand */
+--dot-color-inactive       /* fg-subtle */
+--mobile-stepper-height-48
+```
+
+## Accessibility
+
+- The buttons own their accessible names. The stepper itself has no implicit role.
+- For screen-reader announcement of progress, add live region: `aria-live="polite"` on the step text.
+- Don't disable navigation buttons — MUI does it; but ensure focus moves elsewhere when disabled (e.g., to the form below).
+
+## Edge cases
+
+- **Too many steps** — 8+ dots become unreadable. Switch to `progress` or `text` variant.
+- **Korean step labels** — use "다음" / "이전" / "완료" / "건너뛰기". Cite [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md).
+- **Last-step Next button** — label change to "완료" + change `onClick` to submit. Pair with optimistic UI for snappy feel.
+- **Position="static"** — embeds inline (good inside cards/sheets); `bottom` floats to viewport bottom.
+
+## Code example
+
+```tsx
+function OnboardingFlow() {
+  const [step, setStep] = useState(0);
+  const totalSteps = 4;
+  const isLast = step === totalSteps - 1;
+
+  return (
+    <Box sx={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      <Box sx={{ flex: 1, p: 2, overflowY: 'auto' }}>
+        {step === 0 && <WelcomeStep />}
+        {step === 1 && <ProfileStep />}
+        {step === 2 && <PreferencesStep />}
+        {step === 3 && <SummaryStep />}
+      </Box>
+      <MobileStepper
+        variant="dots"
+        steps={totalSteps}
+        position="static"
+        activeStep={step}
+        nextButton={
+          <Button
+            onClick={isLast ? handleSubmit : () => setStep(step + 1)}
+            variant={isLast ? 'contained' : 'text'}
+          >
+            {isLast ? '완료' : '다음'}
+            {!isLast && <KeyboardArrowRight />}
+          </Button>
+        }
+        backButton={
+          <Button onClick={() => setStep(step - 1)} disabled={step === 0}>
+            <KeyboardArrowLeft />
+            이전
+          </Button>
+        }
+      />
+    </Box>
+  );
+}
+```
+
+## Don't
+
+- Don't use without `nextButton` + `backButton` — required props.
+- Don't use on desktop — too small / sparse for desktop scale; use `Stepper`.
+- Don't change the indicator type mid-flow.
+
+## References
+
+- MUI: [`MobileStepper`](../refs/mui/packages/mui-material/src/MobileStepper/)
+
+## Cross-reference
+
+- [`component-step.md`](component-step.md) — desktop equivalent
+- [`component-step.md`](component-step.md)
+- [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md)
+- [`knowledge/patterns/b2b-onboarding-flows.md`](../knowledge/patterns/b2b-onboarding-flows.md)

package/examples/component-modal.md

@@ -0,0 +1,220 @@
+# `Modal` (Dialog) — spec
+
+> Status: example artifact for `component-spec-writer` skill
+> Generated by: `skills/component-spec-writer`, citing Ant Design `Modal`, MUI `Dialog`, shadcn-ui `dialog`/`alert-dialog`/`sheet`
+
+## Purpose
+
+A modal interrupts the user to capture a decision or focused interaction. It blocks page interaction until dismissed. Use sparingly — every modal is a small attention tax.
+
+This spec covers **dialog** (centered, decision/form), **alert-dialog** (destructive confirm), and **sheet** (edge-anchored, browse/edit) as variants of one component.
+
+## When to use which variant
+
+| Variant | Use when | Reference |
+| --- | --- | --- |
+| `dialog` | Decision or focused form that interrupts the current page | shadcn `dialog`, MUI `Dialog`, Ant `Modal` |
+| `alert-dialog` | Destructive confirm or important alert; requires explicit acknowledgement | shadcn `alert-dialog`, Ant `Modal.confirm` |
+| `sheet` | Browse or edit content too long for centered modal; mobile-native pattern | shadcn `sheet`, MUI `Drawer` |
+| `popover` (not modal) | Lightweight, non-blocking | use `Popover` instead |
+| `toast` (not modal) | Transient feedback | use `Toast` instead |
+
+## Anatomy
+
+```
+Modal (root, portal-mounted)
+├── Backdrop                  (click-dismiss + visual scrim)
+└── Surface                   (the box)
+    ├── Header
+    │   ├── Title
+    │   ├── [Description?]
+    │   └── [CloseButton?]
+    ├── Body                  (scrollable if content overflows)
+    └── Footer                (action buttons, right-aligned LTR)
+```
+
+| Part | Required | Notes |
+| --- | --- | --- |
+| Backdrop | yes | semi-opaque overlay; click dismisses (configurable) |
+| Title | yes | accessible name source — `aria-labelledby` points here |
+| Description | optional | `aria-describedby` if present |
+| CloseButton | yes (`dialog`), optional (`alert-dialog`) | top-right ✕ |
+| Body | yes | content; scrollable if tall |
+| Footer | usual | right-aligned action buttons; primary on the right (LTR) |
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | — | Controlled open state. |
+| `onOpenChange` | `(open: boolean) => void` | — | Fires on open/close (backdrop click, escape, button click). |
+| `title` | `string \| ReactNode` | — | Accessible name. **Required**. |
+| `description` | `string \| ReactNode` | — | Subtitle, sets `aria-describedby`. |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| "full"` | `"md"` | Max-width tier. |
+| `dismissible` | `boolean` | `true` for `dialog` / `false` for `alert-dialog` | If false, backdrop click and Escape do not close. |
+| `showCloseButton` | `boolean` | `true` | Renders top-right ✕. |
+| `initialFocus` | `RefObject<HTMLElement>` | first focusable inside | Element to focus on open. |
+| `restoreFocus` | `boolean` | `true` | Return focus to opener on close. |
+| `position` | `"center" \| "top"` (dialog) / `"top" \| "right" \| "bottom" \| "left"` (sheet) | `"center"` / `"right"` | Edge for sheet variant. |
+| `children` | `ReactNode` | — | Body content. |
+| `footer` | `ReactNode` | — | Footer slot for actions. |
+| `loading` | `boolean` | `false` | Disables footer actions, shows spinner. |
+
+For composition-style API (shadcn pattern):
+
+```tsx
+<Modal open={open} onOpenChange={setOpen}>
+  <Modal.Header>
+    <Modal.Title>...</Modal.Title>
+    <Modal.Description>...</Modal.Description>
+  </Modal.Header>
+  <Modal.Body>...</Modal.Body>
+  <Modal.Footer>...</Modal.Footer>
+</Modal>
+```
+
+## States
+
+| State | Trigger | Behavior |
+| --- | --- | --- |
+| Closed | `open={false}` | Unmounted from DOM (or kept with `display:none` for performance). |
+| Opening | transition 200ms | Backdrop fade-in 0→0.5; surface fade+scale 0.96→1 with translateY(8px)→0. |
+| Open | settled | Focus inside surface, page scroll locked, page inert. |
+| Closing | transition 150ms | Reverse of opening. |
+
+Animation timing references: [knowledge/motion/principles.md](../knowledge/motion/principles.md) — modal fade-in is the canonical 200ms `ease-out` pattern.
+
+## Sizes
+
+| Size | Max-width | Use |
+| --- | --- | --- |
+| `sm` | 400px | confirmation, simple input |
+| `md` | 560px | default; form, info |
+| `lg` | 720px | content-heavy; multi-step |
+| `xl` | 960px | data table, complex form |
+| `full` | viewport-100% with margin | mobile, image gallery |
+
+On mobile, all sizes collapse to `width: 100% - 32px margin` regardless of size prop.
+
+## Tokens consumed
+
+```
+--color-bg-elevated         (surface)
+--color-bg-overlay          (backdrop, often rgba(0,0,0,0.5))
+--color-border-default
+--color-text-primary
+--color-text-secondary
+--space-md
+--space-lg
+--space-xl
+--radius-lg
+--shadow-3                  (elevation)
+--motion-default            (200ms)
+--easing-out
+--z-modal                   (typically 1000+)
+```
+
+## Accessibility — required behaviors
+
+This is the most a11y-sensitive component in the system. Get the WAI-ARIA dialog pattern exactly right.
+
+- **Role**: `role="dialog"` (or `role="alertdialog"` for destructive confirm).
+- **`aria-modal="true"`** to indicate the rest of the page is inert.
+- **`aria-labelledby={titleId}`** pointing at the Title element.
+- **`aria-describedby={descId}`** if Description is present.
+- **Focus trap**: while open, `Tab` and `Shift+Tab` cycle within the modal. The last element loops back to the first.
+- **Initial focus**: on open, focus moves into the modal. Default to first focusable element (or the close button if no focusable content). For destructive `alert-dialog`, focus the **non-destructive** action by default ("Cancel"), not the destructive one.
+- **Restore focus**: on close, focus returns to the element that opened the modal.
+- **Escape closes** (unless `dismissible={false}`).
+- **Backdrop click closes** (unless `dismissible={false}`).
+- **Page scroll lock**: prevent body scroll while open. iOS needs `position: fixed; top: -<scrollY>px`. CSS `overflow: hidden` on body alone breaks iOS.
+- **Page inert**: set `inert` attribute on the root app container while modal is open (modern browsers 2023+). Or use `aria-hidden="true"` on background and trap focus within modal (older approach).
+- **Announce on open**: the title is read because focus moves to / inside the labeled dialog. Don't add extra announcements — that double-announces.
+- **Z-index**: above everything except notifications/toasts. Stacking multiple modals: prefer to refactor; if necessary, each higher modal needs +1 z-index and its own backdrop.
+
+## Code example
+
+```tsx
+// Standard form dialog
+const [open, setOpen] = useState(false);
+
+<Modal open={open} onOpenChange={setOpen} title="Invite member">
+  <Modal.Body>
+    <Input label="Email" type="email" value={email} onChange={setEmail} />
+    <Input label="Role" type="text" value={role} onChange={setRole} />
+  </Modal.Body>
+  <Modal.Footer>
+    <Button variant="outline" onClick={() => setOpen(false)}>Cancel</Button>
+    <Button onClick={handleInvite} loading={isPending}>Send invite</Button>
+  </Modal.Footer>
+</Modal>
+
+// Destructive confirm
+<AlertModal
+  open={confirmOpen}
+  onOpenChange={setConfirmOpen}
+  title="Delete project?"
+  description="This permanently deletes the project and all its data. This cannot be undone."
+>
+  <AlertModal.Footer>
+    <Button variant="outline" onClick={() => setConfirmOpen(false)}>Cancel</Button>
+    <Button intent="danger" onClick={handleDelete}>Delete project</Button>
+  </AlertModal.Footer>
+</AlertModal>
+
+// Sheet (mobile-friendly edit panel)
+<Sheet open={editOpen} onOpenChange={setEditOpen} position="right" size="md">
+  <Sheet.Header>
+    <Sheet.Title>Edit profile</Sheet.Title>
+  </Sheet.Header>
+  <Sheet.Body>
+    <ProfileForm />
+  </Sheet.Body>
+  <Sheet.Footer>
+    <Button variant="outline" onClick={() => setEditOpen(false)}>Cancel</Button>
+    <Button onClick={handleSave}>Save</Button>
+  </Sheet.Footer>
+</Sheet>
+```
+
+## Edge cases
+
+- **Long content**: body scrolls; header and footer stay fixed.
+- **Nested modal**: avoid. Refactor into wizard or pass-through navigation. If unavoidable, the inner modal's backdrop is fully opaque or significantly darker.
+- **Keyboard user lands on close button as first focus**: jarring. Default to first interactive content; `aria-label="Close"` makes the ✕ usable but not the focus target.
+- **Mobile: keyboard appears, modal jumps**: use `viewport-fit=cover` and `100dvh` for height. Avoid `100vh` on iOS Safari.
+- **Form inside modal, Enter key submits**: that's correct. Make sure the primary footer button is `type="submit"` or wire `onKeyDown` for Enter.
+- **Animations + reduced motion**: respect `prefers-reduced-motion`. Replace fade+scale with opacity-only.
+- **RTL**: `sheet position="right"` becomes left in RTL automatically with logical CSS.
+- **Print**: hide all modals (`@media print { .modal { display: none; } }`).
+
+## Don't
+
+- **Don't** put critical content only in modals — search engines can't index, browser back doesn't work intuitively.
+- **Don't** disable the backdrop click + Escape **and** hide the close button. Always provide at least one dismiss path (unless it's a wizard with required steps — then a clear "Save & Close" or progress indicator).
+- **Don't** open modals on page load without user action. Auto-open is hostile.
+- **Don't** chain modals (modal opens another modal). Refactor.
+- **Don't** put primary actions in the header — footer is the convention. Top-right is for close.
+- **Don't** show the close button AND a "Cancel" button — they do the same thing. Pick one.
+- **Don't** use modal for transient feedback (success message, info). Use a toast.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/modal/`](../refs/ant-design/components/modal/) — exhaustive: `Modal`, `Modal.confirm`, `Modal.info`, `Modal.success`, `Modal.error`, `Modal.warning`. Imperative API via `Modal.confirm({...})` is convenient but harder to test. The static methods are an Ant idiom worth knowing about.
+- MUI: [`refs/mui/packages/mui-material/src/Dialog/Dialog.tsx`](../refs/mui/packages/mui-material/src/Dialog/) — composition-first: `<Dialog>`, `<DialogTitle>`, `<DialogContent>`, `<DialogActions>`. Cleanest base API.
+- shadcn-ui:
+  - [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/dialog.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/dialog.tsx) — Radix Dialog primitive, all a11y handled upstream.
+  - [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/alert-dialog.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/alert-dialog.tsx) — separate primitive for confirms; difference is `role="alertdialog"` and modal cannot be dismissed via Escape/backdrop unless code-driven.
+  - [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sheet.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/sheet.tsx) — edge-anchored variant.
+
+API choices made:
+- **Three variants in one spec** (`dialog`/`alert-dialog`/`sheet`) — same focus-management contract, same a11y pattern, same composition. Fewer concepts to learn than three separate components with overlapping concerns.
+- **Composition over imperative**: prefer `<Modal>...</Modal>` to Ant's `Modal.confirm({...})`. Imperative is fine as a wrapper for one-off confirms; composition is the foundation.
+- **`title` prop required + `<Modal.Title>` slot supported**: prop is the 80% case (consistent a11y), slot for layouts that need custom title rendering.
+
+## Cross-reference
+
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — focus trap rules
+- [knowledge/motion/principles.md](../knowledge/motion/principles.md) — modal animation timing
+- [WAI-ARIA Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/)
+- [WAI-ARIA Alert Dialog Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)