@design-ai/cli 4.55.0

package/examples/component-address-input.md

@@ -0,0 +1,260 @@
+# `AddressInput` (custom — Korean) — spec
+
+> Status: example artifact for **custom components**. Korean addresses require Daum Postcode lookup and a two-line structure that doesn't exist in any upstream design system.
+>
+> Cited knowledge: [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md), [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md)
+
+## Purpose
+
+Captures a Korean address. Uses **Daum Postcode API** (the universal standard) to look up postal codes + main address; user adds detail line manually.
+
+**Never accept Korean addresses as free text.** Address validation is a real problem; Daum solves it for free; users expect it.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│ 우편번호                                  │
+│ ┌──────────────┐  ┌─────────────────┐   │
+│ │  06234       │  │  주소 검색       │   │   ← read-only zip + lookup button
+│ └──────────────┘  └─────────────────┘   │
+│                                          │
+│ 기본 주소                                 │
+│ ┌──────────────────────────────────────┐ │
+│ │ 서울특별시 강남구 테헤란로 123        │ │   ← read-only, populated by lookup
+│ └──────────────────────────────────────┘ │
+│                                          │
+│ 상세 주소 (선택)                          │
+│ ┌──────────────────────────────────────┐ │
+│ │ 5층 501호                              │ │   ← user-editable
+│ └──────────────────────────────────────┘ │
+└─────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Zip code field | yes | Read-only, populated by Daum lookup |
+| Lookup button | yes | "주소 검색" — opens Daum Postcode |
+| Main address | yes | Read-only, from Daum (도로명 or 지번 — choose) |
+| Detail line | optional | User-typed (apt #, suite, instructions) |
+| Address-type toggle | optional | 도로명 vs 지번 (street name vs lot number) |
+
+## API
+
+```tsx
+<AddressInput
+  value={address}
+  onValueChange={setAddress}
+  required
+  onLookupClick={openDaumPostcode}
+/>
+
+// where address is:
+type Address = {
+  postalCode: string;     // "06234"
+  mainAddress: string;    // "서울특별시 강남구 테헤란로 123"
+  detailAddress: string;  // "5층 501호"
+  addressType: "road" | "lot";   // 도로명 (road) | 지번 (lot)
+  englishAddress?: string; // "123 Teheran-ro, Gangnam-gu, Seoul" — for international
+}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Address \| null` | — | The full address object |
+| `onValueChange` | `(address: Address) => void` | — | |
+| `required` | `boolean` | `false` | All three fields required (typically just zip + main) |
+| `onLookupClick` | `() => void` | — | Triggers Daum Postcode UI; required to wire up |
+| `disabled` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | Validation state |
+| `addressTypeToggle` | `boolean` | `false` | Allow user to switch between 도로명 / 지번 |
+| `requireDetail` | `boolean` | `false` | If detail address is mandatory (e.g., apartment # required) |
+| `country` | `"KR"` | `"KR"` | Reserved for future i18n support |
+
+## Daum Postcode integration
+
+Daum (Kakao) provides a free embedded postcode lookup:
+
+```ts
+// In a real implementation, load the script:
+// <script src="//t1.daumcdn.net/mapjsapi/bundle/postcode/prod/postcode.v2.js"></script>
+
+const openDaumPostcode = () => {
+  new window.daum.Postcode({
+    oncomplete: (data) => {
+      const newAddress: Partial<Address> = {
+        postalCode: data.zonecode,
+        mainAddress: data.address,        // 도로명 by default
+        addressType: data.userSelectedType === "R" ? "road" : "lot",
+        englishAddress: data.addressEnglish,
+      };
+      // Detail address is left for the user to fill
+      setAddress({ ...address, ...newAddress, detailAddress: "" });
+
+      // Focus the detail input next
+      detailInputRef.current?.focus();
+    },
+  }).open();
+};
+```
+
+The Daum widget opens a modal/popup with its own UI (search field, results list). Returns the selected address.
+
+For React Native / non-web: use a webview to embed the Daum widget OR a vendor's wrapper (e.g., `react-native-daum-postcode`).
+
+## Behavior
+
+### Lookup flow
+
+1. User clicks "주소 검색" button.
+2. Daum Postcode modal opens.
+3. User searches by keyword (`강남역`, `테헤란로 123`, `청담동 100-1`).
+4. User picks a result from the list.
+5. Modal closes; zip + main address populate.
+6. Focus moves to the detail address input (best practice).
+7. User types apartment / suite / instructions.
+
+### Editing existing address
+
+If `value` is already populated and user clicks "주소 검색" again:
+- All three fields are **replaced** with the new lookup.
+- Confirm with user if detail was already filled (toast: "상세 주소가 초기화됩니다").
+
+### Address type (도로명 vs 지번)
+
+도로명 (road name): "서울특별시 강남구 테헤란로 123" — modern, since 2014.
+지번 (lot number): "서울특별시 강남구 역삼동 821-1" — legacy, still common in older systems and rural areas.
+
+Daum lookup returns both. Default to 도로명 unless the user prefers 지번. Provide a toggle if your form needs both displayed.
+
+### Detail address rules
+
+- Free-text, max ~50 chars.
+- Common formats:
+  - "5층 501호" (5th floor, room 501)
+  - "302호" (room 302 — for 빌라 / villa-style buildings)
+  - "B동 1502호" (building B, room 1502)
+- Optional unless your business requires it.
+- Don't validate beyond character length — variations are too many.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | All fields empty, "주소 검색" button prominent |
+| Looking up | Daum modal is open (this component's UI is mostly inactive) |
+| Populated | Fields filled, "주소 검색" button still available for re-lookup |
+| Disabled | All fields and button disabled |
+| Error | Red border on whichever field failed validation |
+| Read-only (existing user) | All fields show, no edit affordances, no lookup button |
+
+## Tokens consumed
+
+Inherited from Input + Button. No new tokens.
+
+## Accessibility
+
+- Each field is a labeled input. Group with `<fieldset><legend>주소</legend>`.
+- "주소 검색" is a `<button>` with clear label.
+- Daum's modal is its own dialog — focus management is handled by Daum (not by this component).
+- After lookup completes, focus moves to detail input via `ref.focus()` — improves keyboard flow.
+- `aria-required="true"` on required fields.
+- Error: `aria-invalid="true"` + `aria-describedby` to error text.
+- Postal code field: `aria-readonly="true"` (don't let users guess they can type).
+
+## Korean considerations
+
+Per [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md):
+
+- Always use Daum Postcode. Korean users expect it; free-form is broken.
+- Address-type defaults to 도로명 for modern apps (matches government standardization).
+- Display labels: "우편번호" / "기본 주소" / "상세 주소" — these are conventional. Don't translate.
+- For international shipments: optionally include `englishAddress` from Daum.
+- Server-side: store the full structured address (all 4 fields), not just the formatted string. Lets you re-display in different formats later.
+
+## Mobile patterns
+
+- The lookup button: full-width on mobile, alongside the zip field on desktop.
+- Daum's modal is responsive — trust it.
+- After lookup, scroll the detail input into view (it's the next thing user types in).
+
+## Code example
+
+```tsx
+function CheckoutForm() {
+  const [address, setAddress] = useState<Address | null>(null);
+  const detailRef = useRef<HTMLInputElement>(null);
+
+  const openLookup = () => {
+    new window.daum.Postcode({
+      oncomplete: (data) => {
+        setAddress({
+          postalCode: data.zonecode,
+          mainAddress: data.address,
+          detailAddress: "",
+          addressType: data.userSelectedType === "R" ? "road" : "lot",
+          englishAddress: data.addressEnglish,
+        });
+        setTimeout(() => detailRef.current?.focus(), 100);
+      },
+    }).open();
+  };
+
+  return (
+    <Form>
+      <AddressInput
+        label="배송지"
+        value={address}
+        onValueChange={setAddress}
+        onLookupClick={openLookup}
+        detailInputRef={detailRef}
+        required
+        errorText={address && !address.postalCode ? "주소를 검색해 주세요" : undefined}
+      />
+
+      <Form.Field name="recipient">
+        <Form.Label>받는 사람</Form.Label>
+        <Form.Control><Input /></Form.Control>
+      </Form.Field>
+
+      <Form.Field name="phone">
+        <Form.Label>연락처</Form.Label>
+        <Form.Control><Input type="tel" /></Form.Control>
+      </Form.Field>
+    </Form>
+  );
+}
+```
+
+## Edge cases
+
+- **No internet**: Daum widget can't load. Show error + retry button. Don't allow free-form fallback.
+- **Daum API fails / banned**: rare, but vendors do change. Have a backup vendor (Naver Maps geocoding, juso.go.kr official API).
+- **Address that Daum doesn't recognize**: rare for residential. For very new construction, Daum might lag — let user note in detail address.
+- **PO Box / virtual addresses**: Korean PO Boxes use a separate system; out of scope for residential AddressInput. Different field.
+- **Multi-tenant address** (e.g., apartment complex with multiple buildings): Daum returns the building-level address; user adds 동 (building) and 호 (unit) in detail.
+- **International orders**: AddressInput is KR-only here. For multi-country: separate `InternationalAddressInput` component with country dropdown.
+- **Server-side normalization**: even with Daum's clean output, server should normalize whitespace and casing.
+
+## Don't
+
+- Don't accept Korean addresses as free text.
+- Don't roll your own postal-code database.
+- Don't make all three fields free-form (zip + main + detail). Zip and main come from lookup.
+- Don't auto-validate detail address against a real-world database (impossible).
+- Don't ship without a lookup button — there's no other way to get the right zip.
+- Don't store only the formatted string — store all 4 components for future flexibility.
+- Don't use `<input type="text">` for postal code with `pattern` regex as the only validation. Use Daum.
+
+## API rationale
+
+- **`value: Address` (structured object)**: matches what Daum returns; frees the consumer from re-parsing.
+- **`onLookupClick: () => void`**: lookup is side-effectful (DOM manipulation, script load). Consumer wires it; component doesn't bake in Daum dependency.
+- **No "free-form" mode**: forcing the lookup is the point. If a consumer wants free-form, they shouldn't use this component.
+
+## Cross-reference
+
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — Daum Postcode, address conventions
+- [`knowledge/patterns/form-design.md`](../knowledge/patterns/form-design.md) — address-field pattern
+- [`examples/component-input.md`](component-input.md) — base Input
+- [Daum Postcode Service](https://postcode.map.daum.net/guide) — official documentation

package/examples/component-affix.md

@@ -0,0 +1,190 @@
+# `Affix` (sticky positioning) — spec
+
+> Citing Ant Design `Affix`, MUI (no dedicated — use CSS `position: sticky`), shadcn-ui (CSS only)
+>
+> Mostly **a CSS pattern** in modern browsers. The Affix component wraps that pattern with React-friendly props (target scroll container, offset, callbacks).
+
+## Purpose
+
+Makes an element stick to a position (top of viewport, scroll container) as the user scrolls past it. Used for: sticky table headers, sticky CTAs, side panels that lock to top, sub-navigation bars.
+
+## When Affix vs CSS `position: sticky`
+
+| Scenario | Use |
+| --- | --- |
+| Element follows viewport on scroll | CSS `position: sticky` (native, no JS) |
+| Element follows viewport with **callback** when sticky toggles | Affix component (or write custom IntersectionObserver) |
+| Element sticks within a **specific container** (not page) | Affix or scoped sticky |
+| Sticky inside a Modal that has its own scroll | Affix with `target` prop |
+
+For 80% of cases, native CSS is the right answer:
+
+```css
+.sticky-header {
+  position: sticky;
+  top: 0;
+  background: var(--color-bg-default);
+  z-index: 10;
+}
+```
+
+This works in all modern browsers, no JavaScript, no perf cost. **Reach for the Affix component only when** you need:
+- Container-scoped sticky (not page-scroll)
+- Callbacks on stick / unstick
+- Programmatic offset adjustment
+
+## Anatomy
+
+The Affix wraps a child element. It positions normally until the user scrolls past a threshold, then it sticks to the configured position.
+
+```
+[normal scroll position]
+  ┌───────────────────────┐
+  │ Affixed element       │  ← scrolls naturally with page
+  └───────────────────────┘
+  [content below]
+
+[user scrolls down]
+  ┌───────────────────────┐
+  │ Affixed element       │  ← stays at top of viewport (or container)
+  └───────────────────────┘
+  [content scrolls behind]
+```
+
+## API
+
+```tsx
+<Affix offsetTop={0} onChange={(affixed) => setIsSticky(affixed)}>
+  <SubNavBar />
+</Affix>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | The element to affix |
+| `offsetTop` | `number` | `0` | Px from top when sticky |
+| `offsetBottom` | `number` | — | Alternative: stick to bottom |
+| `target` | `() => HTMLElement` | window | Scroll container (for inner scroll cases) |
+| `onChange` | `(affixed: boolean) => void` | — | Fires on stick/unstick |
+
+## Behavior
+
+- Element renders in flow normally.
+- As user scrolls, Affix watches the scroll position.
+- When the element's natural top reaches `offsetTop`, it switches to `position: fixed` (or `sticky`) at that offset.
+- When user scrolls back up past the threshold, it returns to flow.
+
+In practice: Ant's Affix uses `position: sticky` under the hood for modern browsers, falling back to `position: fixed` + scroll listener for older.
+
+## Use cases
+
+### 1. Sticky sub-navigation
+
+```tsx
+<Affix offsetTop={64}>  {/* Below a 64px main nav */}
+  <SubNav />
+</Affix>
+```
+
+The sub-nav scrolls with the page until it hits the main nav, then sticks below.
+
+### 2. Sticky table header
+
+For long tables, the header should stay visible:
+
+```tsx
+<table className="sticky-header">
+  <thead>...</thead>
+  <tbody>...</tbody>
+</table>
+
+/* Or in CSS: */
+table thead { position: sticky; top: 0; z-index: 1; }
+```
+
+CSS-only is preferred here.
+
+### 3. Sticky form CTA on mobile
+
+```tsx
+<Affix offsetBottom={0}>
+  <div className="footer-cta">
+    <Button fullWidth>저장</Button>
+  </div>
+</Affix>
+```
+
+The CTA sticks to the bottom of viewport. On mobile, this is the canonical pattern for primary form actions.
+
+### 4. Sticky filter sidebar in scrollable container
+
+```tsx
+<div ref={containerRef} className="overflow-auto h-screen">
+  <Affix target={() => containerRef.current!}>
+    <FilterPanel />
+  </Affix>
+  <Results />
+</div>
+```
+
+The filter sticks within the container (not viewport).
+
+## Sizes / states
+
+Affix doesn't have its own visual states — it transparently relays the wrapped element. Visual decisions (shadow, background, border) belong to the wrapped element when it becomes sticky.
+
+A common pattern: add a subtle border/shadow only when sticky:
+
+```tsx
+<Affix onChange={setIsSticky}>
+  <div className={isSticky ? "sticky-with-shadow" : ""}>
+    <SubNav />
+  </div>
+</Affix>
+```
+
+```css
+.sticky-with-shadow {
+  box-shadow: 0 1px 0 var(--color-border-default), 0 4px 12px rgba(0,0,0,0.04);
+}
+```
+
+This hints "I've moved; you scrolled" without screaming.
+
+## Tokens consumed
+
+Affix itself doesn't consume tokens. The wrapped element does. For sticky-specific styling:
+
+```
+--color-bg-default          (sticky element bg, often opaque to hide content behind)
+--color-border-default      (subtle separator when sticky)
+--shadow-card                (subtle shadow when sticky)
+--z-sticky                   (z-index above page content)
+```
+
+## Accessibility
+
+Affix is purely visual — no a11y implications beyond what the wrapped element provides. Keyboard navigation continues normally.
+
+If the affixed element is interactive (buttons in a sticky CTA bar): standard focus rules apply.
+
+For sticky **alerts / banners**: respect `prefers-reduced-motion` and don't animate the stick transition. The position change itself (relative to the viewport) doesn't violate motion preferences, but added animations should be optional.
+
+## Don't
+
+- Don't reach for Affix when CSS `position: sticky` works. Native is faster, lighter, and supported everywhere modern.
+- Don't stick large blocks (>50% viewport height). They eat scroll space.
+- Don't stack 3+ sticky elements (header + sub-nav + filter bar). The visible viewport shrinks.
+- Don't forget background color on sticky elements — content scrolls behind, transparency = visual chaos.
+- Don't auto-show sticky alerts that don't have a dismiss action — user is stuck with them.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/affix/`](../refs/ant-design/components/affix/) — `Affix`. Wraps native sticky with React-friendly callbacks.
+- MUI / shadcn-ui: no dedicated component. Use CSS `position: sticky`.
+
+## Cross-reference
+
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md) — broader layout patterns
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md) — sticky bottom-tab-bar (similar pattern)
+- [`examples/component-table.md`](component-table.md) — sticky table headers

package/examples/component-alert-dialog.md

@@ -0,0 +1,210 @@
+# `AlertDialog` — spec
+
+> Synthesized from shadcn-ui `alert-dialog` (Radix). Modal confirmation dialog for actions that require explicit user acknowledgment. Distinct from `Modal` (general-purpose) and `Toast` (transient).
+
+## When to use
+
+- **Destructive actions** that can't be undone: "Delete account?", "Discard unsaved changes?"
+- **Significant state changes**: "Cancel subscription?", "Sign out everywhere?"
+- **Critical confirmations** in payment / financial flows.
+
+When NOT to use:
+- Routine confirmations (use Toast with undo instead).
+- Form submissions (let the form's submit button speak for itself).
+- Loading / progress (use Modal or Toast).
+
+## AlertDialog vs Modal vs Toast
+
+| | AlertDialog | Modal | Toast |
+| --- | --- | --- | --- |
+| Cancellable via Esc / outside-click | **Yes for cancel; no destructive default** | Yes | n/a |
+| Default focus | Cancel button | First focusable | n/a |
+| Use | Destructive confirmation | Forms, settings, content | Transient feedback |
+| Backdrop click | Closes (= cancel) | Closes (= dismiss) | n/a |
+
+The key behavioral difference: AlertDialog defaults focus to **Cancel** so accidental Enter doesn't fire a destructive action.
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│                                  │
+│  ⚠  Delete this project?          │   ← title with icon
+│                                  │
+│  This will permanently delete    │   ← description
+│  the project and all its data.   │
+│  This action cannot be undone.   │
+│                                  │
+│       [Cancel] [Delete]          │   ← Cancel default focus
+│        ↑                         │
+│   default focus                  │
+└──────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<AlertDialog>
+  <AlertDialog.Trigger asChild>
+    <Button variant="destructive">Delete project</Button>
+  </AlertDialog.Trigger>
+  <AlertDialog.Content>
+    <AlertDialog.Header>
+      <AlertDialog.Title>Delete this project?</AlertDialog.Title>
+      <AlertDialog.Description>
+        This will permanently delete the project and all its data.
+        This action cannot be undone.
+      </AlertDialog.Description>
+    </AlertDialog.Header>
+    <AlertDialog.Footer>
+      <AlertDialog.Cancel>Cancel</AlertDialog.Cancel>
+      <AlertDialog.Action onClick={handleDelete}>
+        Delete
+      </AlertDialog.Action>
+    </AlertDialog.Footer>
+  </AlertDialog.Content>
+</AlertDialog>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Trigger` | Element that opens the dialog |
+| `Content` | The modal panel |
+| `Header` | Title + description region |
+| `Title` | Heading; identifies the question |
+| `Description` | Explanation of consequences |
+| `Footer` | Action row |
+| `Cancel` | Safe / dismissive action (default focus) |
+| `Action` | Confirming / destructive action |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Hidden |
+| Opening | Backdrop fade + content scale (200ms) |
+| Open | Visible, focus on Cancel, body scroll locked |
+| Action loading | Action button shows spinner; both buttons disabled |
+| Closing | Reverse |
+
+## Tokens consumed
+
+```
+--color-bg-overlay-scrim           (backdrop)
+--color-bg-default                 (dialog bg)
+--color-fg-default
+--color-error-default              (destructive variant title icon + Action)
+--color-warning-default            (warning variant)
+--shadow-overlay
+--radius-lg
+--space-md, --space-lg
+--motion-medium
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- `Content`: `role="alertdialog"` (NOT `dialog`) — interrupts screen readers.
+- `aria-labelledby` references `Title`.
+- `aria-describedby` references `Description`.
+- **Focus trap on open**; focus defaults to `Cancel` (the safe option).
+- `Esc` triggers `Cancel` (not `Action`).
+- Backdrop click triggers `Cancel`.
+- `Enter` on focused button activates that button (default = Cancel = safe).
+- Touch target ≥ 44pt for both buttons.
+
+## Korean conventions
+
+```
+삭제하시겠습니까?
+
+이 프로젝트와 관련된 모든 데이터가 영구적으로 삭제되며,
+복구할 수 없습니다.
+
+[취소]  [삭제]
+```
+
+- 합쇼체 typical for destructive confirmations ("...하시겠습니까?")
+- 해요체 OK for casual brand voice ("...할까요?")
+- "취소" for Cancel; "삭제" / "확인" / "동의" for Action
+- Avoid "OK" / "예" alone — use a verb that names the action
+
+## Code example
+
+```tsx
+function DeleteProjectButton({ project }: Props) {
+  const [loading, setLoading] = useState(false);
+
+  const handleDelete = async () => {
+    setLoading(true);
+    try {
+      await api.deleteProject(project.id);
+      toast.success("프로젝트가 삭제되었습니다");
+    } finally {
+      setLoading(false);
+    }
+  };
+
+  return (
+    <AlertDialog>
+      <AlertDialog.Trigger asChild>
+        <Button variant="destructive">
+          <TrashIcon /> 프로젝트 삭제
+        </Button>
+      </AlertDialog.Trigger>
+      <AlertDialog.Content>
+        <AlertDialog.Header>
+          <AlertDialog.Title>이 프로젝트를 삭제하시겠습니까?</AlertDialog.Title>
+          <AlertDialog.Description>
+            <strong>{project.name}</strong> 및 관련된 모든 데이터가
+            영구적으로 삭제되며, 복구할 수 없습니다.
+          </AlertDialog.Description>
+        </AlertDialog.Header>
+        <AlertDialog.Footer>
+          <AlertDialog.Cancel disabled={loading}>취소</AlertDialog.Cancel>
+          <AlertDialog.Action
+            onClick={handleDelete}
+            disabled={loading}
+            className="bg-destructive"
+          >
+            {loading ? "삭제 중..." : "삭제"}
+          </AlertDialog.Action>
+        </AlertDialog.Footer>
+      </AlertDialog.Content>
+    </AlertDialog>
+  );
+}
+```
+
+## Edge cases
+
+- **Async action with error**: keep dialog open after error; show inline error message; let user retry or cancel.
+- **Action requires more context**: pre-fill Description with consequence detail (file count, last edit date, undoable for X days).
+- **Multi-step destructive flow**: chain AlertDialogs OR convert to a wizard with summary at end.
+- **Type-to-confirm pattern** (delete repo on GitHub): replace simple Cancel/Action with a text input requiring exact name match.
+- **Stacking**: avoid AlertDialog inside AlertDialog. Sequence them or rethink flow.
+- **RTL**: button order reverses (Action left, Cancel right) per RTL convention.
+- **Reduced motion**: skip scale animation; instant.
+
+## Don't
+
+- Don't use AlertDialog for routine confirmations — use Toast with Undo for delete-with-undo flows.
+- Don't make Action the default-focused button. Cancel is safer.
+- Don't omit the Description for destructive actions. Users need consequence info.
+- Don't use vague labels like "OK / Cancel". Name the action ("Delete project").
+- Don't auto-close after Action without showing success feedback (Toast / inline).
+- Don't disable Esc — accessibility requires it.
+
+## References
+
+- shadcn-ui: [`alert-dialog`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/alert-dialog.tsx) (Radix)
+- WAI-ARIA: [`alertdialog`](https://www.w3.org/WAI/ARIA/apg/patterns/alertdialog/)
+
+## Cross-reference
+
+- [`examples/component-modal.md`](component-modal.md) — general-purpose modal
+- [`examples/component-toast.md`](component-toast.md) — transient feedback (with Undo)
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)