@design-ai/cli 4.55.0

package/examples/component-backdrop.md

@@ -0,0 +1,148 @@
+# `Backdrop` — spec
+
+> Synthesized from MUI `Backdrop`. A semi-opaque overlay that dims the page behind a foreground element. Used by `Modal`, `Drawer`, `Sheet`, `AlertDialog` internally — and standalone for full-page loading screens.
+
+## When to use
+
+- **Standalone**: full-page loading state ("Saving... please wait").
+- **Inside other components**: as the scrim behind Modal / Drawer / Sheet (usually internal to those components).
+- **Focus / attention**: dim everything else to point at one task.
+
+When NOT to use:
+- Modal-like UI — use `Modal` (it includes Backdrop).
+- Loading inside a card — use Skeleton or Spinner inline.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────┐
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ ░░░░ (dimmed page content) ░░░░░░░░░ │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ ░░░░░░░░░░░ [spinner] ░░░░░░░░░░░░░░ │
+│ ░░░░░░░░░ Loading...  ░░░░░░░░░░░░░░ │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+│ ░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░░ │
+└─────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Backdrop open={loading}>
+  <CircularProgress />
+</Backdrop>
+
+<Backdrop open={open} onClick={() => setOpen(false)}>
+  <p>Click anywhere to dismiss</p>
+</Backdrop>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Visibility |
+| `onClick` | `() => void` | — | Click handler (often dismisses) |
+| `transitionDuration` | `number` | `300` | Fade ms |
+| `invisible` | `boolean` | `false` | Backdrop is transparent (still blocks clicks) |
+| `children` | `ReactNode` | — | Foreground content (centered by default) |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | `display: none` |
+| Opening | Fade in from 0 to opacity (300ms) |
+| Open | Fully visible |
+| Closing | Reverse |
+
+## Tokens consumed
+
+```
+--backdrop-bg                      (rgba(0,0,0,0.5) typical)
+--backdrop-bg-light                (lighter for dark themes)
+--motion-medium                    (fade duration)
+--ease-out
+--z-backdrop                       (above content, below modals/dialogs)
+```
+
+## CSS
+
+```css
+.backdrop {
+  position: fixed;
+  inset: 0;
+  background: var(--backdrop-bg);
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  z-index: var(--z-backdrop);
+  opacity: 0;
+  transition: opacity var(--motion-medium) var(--ease-out);
+  pointer-events: none;
+}
+
+.backdrop[data-state="open"] {
+  opacity: 1;
+  pointer-events: auto;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .backdrop { transition: opacity 0ms; }
+}
+```
+
+## Accessibility
+
+- Backdrop with content: usually wrap content in `<div role="status" aria-live="polite">` (for loading) or `<div role="alertdialog">` (for confirmations).
+- Standalone Backdrop is a focus trap when modal — keyboard can't escape until Backdrop closes.
+- Esc to close (when dismissible).
+- Click-outside to close (configurable).
+- `aria-busy="true"` on the entire affected page region during loading.
+
+## Code example — full-page loading
+
+```tsx
+function App() {
+  const { isAuthenticating } = useAuth();
+
+  return (
+    <>
+      <Backdrop open={isAuthenticating}>
+        <Stack align="center" gap={4}>
+          <Spinner size="lg" color="white" />
+          <Text color="white">로그인 중...</Text>
+        </Stack>
+      </Backdrop>
+
+      <main>{/* main content */}</main>
+    </>
+  );
+}
+```
+
+## Edge cases
+
+- **Multiple Backdrops at once**: stack via z-index but visually messy. Avoid; use one at a time.
+- **Backdrop doesn't cover virtual keyboard on mobile**: position: fixed handles most, but iOS Safari has quirks with input focus.
+- **Backdrop above modals**: usually wrong — modals own their Backdrop. Don't double-stack.
+- **Reduced motion**: skip fade; instant.
+- **Print**: hide via `@media print`.
+
+## Don't
+
+- Don't use Backdrop where Modal / Drawer / Sheet handles it for you.
+- Don't make Backdrop too transparent — should clearly signal "background is inactive".
+- Don't make Backdrop too opaque (>0.7) — feels suffocating.
+- Don't disable Esc / click-outside without a clear dismiss button.
+- Don't pile multiple Backdrops.
+
+## References
+
+- MUI: [`Backdrop`](../refs/mui/packages/mui-material/src/Backdrop)
+- Used internally by: Modal, Drawer, Sheet, AlertDialog
+
+## Cross-reference
+
+- [`examples/component-modal.md`](component-modal.md) — uses Backdrop internally
+- [`examples/component-spinner.md`](component-spinner.md) — common Backdrop child
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — fade timing

package/examples/component-badge.md

@@ -0,0 +1,181 @@
+# `Badge` — spec
+
+> Synthesized from Ant Design `Badge`, MUI `Badge`, shadcn-ui `badge`. A small status / count indicator anchored to another element OR used standalone as a label.
+
+## Two modes
+
+| Mode | Use |
+| --- | --- |
+| **Standalone label** (shadcn-style) | Status pill rendered inline as text content ("New", "Beta", "Sale 30%") |
+| **Indicator** (Ant + MUI style) | Small dot or count anchored to a parent — typically an avatar or icon (notification count, online status) |
+
+These are conceptually different and often shipped as different components in larger systems. shadcn ships only the standalone form; Ant + MUI ship both. Pick one mental model per system.
+
+## Standalone Badge — anatomy
+
+```
+[● New]    [Beta]    [Sale 30%]    [PRO]
+```
+
+A pill with optional icon + text, brand-colored.
+
+## Indicator Badge — anatomy
+
+```
+┌────────┐
+│ Inbox  │● 3       ← positioned top-right of the parent
+└────────┘
+```
+
+A wrapper around a child element, with a count or dot floating at a corner.
+
+## API — Standalone
+
+```tsx
+<Badge variant="default">New</Badge>
+<Badge variant="secondary">Beta</Badge>
+<Badge variant="destructive">Failed</Badge>
+<Badge variant="outline">Draft</Badge>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"default" \| "secondary" \| "destructive" \| "outline" \| "success" \| "warning"` | `"default"` | Visual style |
+| `size` | `"sm" \| "md"` | `"md"` | Dense vs default |
+| `asChild` | `boolean` | `false` | Render as child element (Slot pattern) |
+| `children` | `ReactNode` | — | Content (text, optional icon) |
+
+## API — Indicator
+
+```tsx
+<IndicatorBadge count={3} max={99}>
+  <BellIcon />
+</IndicatorBadge>
+
+<IndicatorBadge variant="dot" status="online">
+  <Avatar src={url} />
+</IndicatorBadge>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` | `number \| undefined` | — | Number to display; `undefined` = no count |
+| `max` | `number` | `99` | Cap; `count > max` displays as `max+` |
+| `variant` | `"count" \| "dot"` | `"count"` | Number vs solid dot |
+| `status` | `"online" \| "offline" \| "away" \| "busy" \| "default"` | `"default"` | Color preset |
+| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | Anchor corner |
+| `offset` | `[x, y]` | `[0, 0]` | Pixel offset from corner |
+| `showZero` | `boolean` | `false` | Show count when `count === 0` |
+| `children` | `ReactNode` | — | Element being decorated |
+
+## Variants
+
+| Variant | Visual | Use |
+| --- | --- | --- |
+| `default` | Brand-color filled | Primary badges (New, Featured) |
+| `secondary` | Muted bg | Neutral status (Beta, Draft) |
+| `destructive` | Red filled | Error, blocked |
+| `outline` | Bordered transparent | Subtle (Optional, Coming soon) |
+| `success` | Green | Success markers |
+| `warning` | Amber | Caution markers |
+
+## Status colors (Indicator)
+
+```
+online  → green
+offline → gray
+away    → yellow
+busy    → red
+default → brand
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Hover (if interactive) | Slight bg darken |
+| Active / pressed | Deeper bg |
+| Disabled | Reduced opacity, no events |
+
+Most badges are non-interactive. If clickable: render as `<button>` or wrap in `<Link>`; styles add hover + focus ring.
+
+## Tokens consumed
+
+```
+--color-bg-default                 (outline / secondary)
+--color-bg-secondary               (secondary fill)
+--color-brand-default              (default variant)
+--color-on-brand                   (text on default)
+--color-error-default              (destructive)
+--color-success-default            (success)
+--color-warning-default            (warning)
+--color-border-default             (outline)
+--radius-full                      (pill shape)
+--space-xs, --space-sm
+--font-size-xs                     (typically 11-12px)
+--font-weight-medium               (500)
+--motion-fast                      (hover transition if interactive)
+```
+
+## Accessibility
+
+- **Standalone**: `<span>` with brand styling; text reads as part of context. No special role.
+- **Indicator**:
+  - **Dot variant**: visual only; meaning conveyed via parent (`aria-label="3 unread notifications"` on the parent button).
+  - **Count variant**: include the number in `aria-label` of the wrapper; or place a hidden `<span class="sr-only">{count} new</span>` adjacent.
+- Don't rely on color alone for status (online vs busy = green vs red). Add `aria-label` describing state.
+- Touch targets: badges with click handlers need ≥ 24×24 (small badges hard to tap; consider expanding hit area).
+
+## Edge cases
+
+- **Count 0 + showZero false**: hide badge; render only children.
+- **Count > max**: render `99+` (or `${max}+`).
+- **Very long text** (Standalone): truncate with ellipsis at max-width; don't wrap to two lines.
+- **Indicator on small parent** (24px icon): badge may overflow; place outside parent's bounding box (positioning offset).
+- **RTL**: flip `top-right` / `top-left` mappings.
+- **Dark mode**: tokens cascade; verify outline variant has visible border.
+
+## Code example
+
+```tsx
+function NotificationBell({ count }: { count: number }) {
+  return (
+    <IndicatorBadge count={count} max={99}>
+      <button aria-label={`${count} unread notifications`} className="icon-button">
+        <BellIcon />
+      </button>
+    </IndicatorBadge>
+  );
+}
+
+function ProductCard({ name, isNew, isOnSale }: Props) {
+  return (
+    <article>
+      <h3>{name}</h3>
+      {isNew && <Badge variant="default">New</Badge>}
+      {isOnSale && <Badge variant="destructive">Sale</Badge>}
+    </article>
+  );
+}
+```
+
+## Don't
+
+- Don't use Badge as a primary CTA. It looks like a button but isn't.
+- Don't pile up 5+ badges next to a single item — visual noise.
+- Don't make badges so small the text is unreadable (< 10px).
+- Don't use color-only status (online/busy as just green/red without label).
+- Don't animate badge appearance (count 1 → 2 with spring) on every render — distracting; use only for meaningful state changes.
+
+## References
+
+- Ant: [`Badge`](../refs/ant-design/components/badge)
+- MUI: [`Badge`](../refs/mui/packages/mui-material/src/Badge)
+- shadcn-ui: [`badge`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/badge.tsx)
+
+## Cross-reference
+
+- [`examples/component-avatar.md`](component-avatar.md) — common Indicator parent
+- [`examples/component-tag-badge.md`](component-tag-badge.md) — closely related (filterable tags)
+- [`examples/component-alert.md`](component-alert.md) — for full alerts vs small badges

package/examples/component-banner.md

@@ -0,0 +1,237 @@
+# `Banner` — spec
+
+> A persistent in-page or app-wide notification strip. Distinct from `Alert` (page-level inline message) and `Toast` (transient floating notification). Used for upgrade prompts, system status, cookie consent, ongoing announcements.
+
+## Banner vs Alert vs Toast
+
+| | Banner | Alert | Toast |
+| --- | --- | --- | --- |
+| Position | Top of page or app-wide strip | Inline within page content | Floating, usually corner |
+| Persistence | Persistent until dismissed (or context changes) | Visible while relevant | Auto-dismisses (3-7s) |
+| Width | Full-width edge-to-edge | Constrained to content area | Card-width |
+| Use | System-level announcements | Page-level state info | Action confirmation |
+| Dismissible | Often (but persistent until dismissed) | Sometimes | Yes (auto + manual) |
+
+## Common Banner use cases
+
+- **System status**: "We're experiencing degraded performance."
+- **Cookie / consent**: "We use cookies. [Accept] [Customize]"
+- **Trial / upgrade**: "Your trial ends in 3 days. [Upgrade]"
+- **Migration / version**: "We've updated our terms. [Read more]"
+- **Maintenance window**: "Scheduled maintenance: Sunday 2am UTC."
+- **Promo / announcement**: "Save 30% on annual plans."
+- **Korean spam law (정보통신망법)**: marketing consent banner where required.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────────────┐
+│ ⚠  Your trial ends in 3 days. Upgrade now to keep access. │
+│                                            [Upgrade] [×] │
+└─────────────────────────────────────────────────────────┘
+   (above the page content; full-width)
+```
+
+## API
+
+```tsx
+<Banner
+  variant="warning"
+  icon={<ClockIcon />}
+  dismissible
+  onDismiss={handleDismiss}
+  action={
+    <Button size="sm" variant="primary" onClick={handleUpgrade}>
+      Upgrade
+    </Button>
+  }
+>
+  <strong>Your trial ends in 3 days.</strong>
+  <span>Upgrade now to keep access.</span>
+</Banner>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `variant` | `"info" \| "success" \| "warning" \| "error" \| "promo" \| "neutral"` | `"info"` | Visual treatment |
+| `icon` | `ReactNode` | per variant | Leading icon |
+| `dismissible` | `boolean` | `false` | Show dismiss × |
+| `onDismiss` | `() => void` | — | Dismiss callback |
+| `action` | `ReactNode` | — | Right-aligned action(s) |
+| `position` | `"top" \| "bottom" \| "inline"` | `"top"` | Where in the layout |
+| `sticky` | `boolean` | `false` | Stick to viewport edge |
+| `id` | `string` | — | For dismissal persistence (localStorage) |
+
+## Variants
+
+| Variant | Color | Use |
+| --- | --- | --- |
+| `info` | Blue | General announcements, info |
+| `success` | Green | Positive milestones (account verified) |
+| `warning` | Amber | Time-sensitive (trial expiring) |
+| `error` | Red | System issues (degraded service) |
+| `promo` | Brand | Marketing, discounts |
+| `neutral` | Gray | Quiet announcements |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Per variant; full-width strip |
+| Dismissing | Slide / fade out 200ms |
+| Hidden (dismissed) | Removed; remembered via `id` + localStorage |
+
+## Persistence
+
+For dismissible banners, persist dismissal across sessions:
+
+```tsx
+const [dismissed, setDismissed] = useLocalStorage(`banner-dismissed-${id}`, false);
+
+if (dismissed) return null;
+
+return <Banner id={id} dismissible onDismiss={() => setDismissed(true)}>...</Banner>;
+```
+
+Reset dismissal when the underlying content changes (new `id` for new announcement).
+
+## Position variants
+
+### `top` (default)
+
+Above all content. Typically sticky or scrolls with page top.
+
+### `bottom`
+
+Bottom of viewport. Common for cookie consent (less intrusive on first paint).
+
+### `inline`
+
+Within page content as a contextual block.
+
+## Tokens consumed
+
+```
+--banner-bg-info               (variant bgs)
+--banner-bg-success
+--banner-bg-warning
+--banner-bg-error
+--banner-bg-promo              (often brand-color)
+--banner-bg-neutral
+--banner-fg                    (text on banner)
+--banner-icon                  (icon color, slightly emphasized)
+--banner-action                (action button styling)
+--banner-dismiss               (× button color)
+--space-md                     (banner padding)
+--font-size-sm                 (typically smaller than body)
+--font-weight-medium           (slight emphasis)
+--motion-medium                (dismiss animation)
+--ease-out
+--z-banner                     (above content, below modals)
+```
+
+## Accessibility
+
+- `<div role="status">` for non-urgent (info, promo, neutral).
+- `<div role="alert">` ONLY for time-sensitive errors / warnings (avoid otherwise — interrupts screen readers).
+- Dismiss button: `<button aria-label="Dismiss banner">`.
+- Action button: standard button accessibility.
+- Don't auto-dismiss critical banners (system status). User must acknowledge or fix the issue.
+- For trial-expiring / cookie consent: don't trap focus or block interaction — banner is informational, not a modal.
+- Sufficient color contrast on all variants (WCAG AA minimum).
+
+## Korean conventions
+
+- 시스템 점검 안내 (system maintenance)
+- 무료 체험 만료 안내 (trial expiration)
+- 쿠키 / 마케팅 정보 수신 동의 (cookie / marketing consent — required by 정보통신망법)
+- "확인" / "동의" / "거부" / "닫기" — typical Korean button labels
+- 합쇼체 for formal banners ("점검을 진행합니다"); 해요체 for casual ("이벤트가 시작됐어요").
+
+For 정보통신망법 marketing consent banner:
+```
+저희는 이메일 / SMS로 마케팅 정보를 보낼 수 있도록 동의를 요청합니다.
+[동의] [거부] [자세히 보기]
+```
+
+## Code example — System status
+
+```tsx
+function SystemStatusBanner() {
+  const { status } = useSystemStatus();
+
+  if (status === "operational") return null;
+
+  return (
+    <Banner
+      variant={status === "degraded" ? "warning" : "error"}
+      icon={<AlertCircleIcon />}
+      action={
+        <a href="/status" className="link">
+          {status === "degraded" ? "자세히 보기" : "상태 페이지"}
+        </a>
+      }
+    >
+      {status === "degraded"
+        ? "일부 기능이 정상 작동하지 않고 있어요."
+        : "서비스 장애가 발생했습니다. 빠르게 복구하겠습니다."}
+    </Banner>
+  );
+}
+```
+
+## Code example — Promo banner
+
+```tsx
+function PromoBanner() {
+  return (
+    <Banner
+      id="annual-discount-2025"
+      variant="promo"
+      dismissible
+      icon={<SparklesIcon />}
+      action={
+        <Button size="sm" asChild>
+          <a href="/pricing">자세히 보기</a>
+        </Button>
+      }
+    >
+      <strong>연간 결제 30% 할인</strong>
+      {" "}
+      <span>1월 31일까지 신규 가입자 대상.</span>
+    </Banner>
+  );
+}
+```
+
+## Edge cases
+
+- **Multiple banners stacked**: prioritize one (most important first); cap at 1-2 visible at any time.
+- **Banner with action that requires modal confirmation**: action opens modal; banner stays until resolved.
+- **Banner on print**: hide via `@media print`.
+- **Mobile narrow width**: stack content (text + action) vertically; ensure action remains tappable (≥ 44pt).
+- **RTL**: swap icon position (right) and action position (left); dismiss × stays on far end.
+- **Keyboard nav**: Tab through Banner content (link, action, dismiss).
+- **Screen-reader spam**: don't make banner update per-second (every counter tick announced); update at significant intervals.
+
+## Don't
+
+- Don't use Banner for transient confirmation. That's Toast.
+- Don't put more than one primary action in a Banner.
+- Don't use Banner inside content cards. That's an Alert.
+- Don't trap focus or block interaction. Banner is informational.
+- Don't auto-show after every page navigation (annoying). Show once, persist dismissal.
+- Don't use Banner for required confirmation (terms acceptance) without a modal. Banner can dismiss too easily.
+- Don't omit dismissal for non-critical banners — users hate persistent unkillable strips.
+
+## References
+
+- Patterns: GitHub system status banner, Stripe Trial banner, Vercel deploy notifications, KR cookie consent banners
+- WAI-ARIA: `role="status"` for non-urgent, `role="alert"` for time-sensitive
+
+## Cross-reference
+
+- [`examples/component-alert.md`](component-alert.md) — inline page-level message
+- [`examples/component-toast.md`](component-toast.md) — transient floating notification
+- [`knowledge/patterns/email-design.md`](../knowledge/patterns/email-design.md) — KR 정보통신망법 marketing consent
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md)