@design-ai/cli 4.55.0

package/examples/component-popper.md

@@ -0,0 +1,129 @@
+# `Popper` — spec
+
+> Synthesized from MUI `Popper`. Low-level positioning primitive that handles floating element placement with collision detection. Used internally by Tooltip / Popover / Menu / Autocomplete / Combobox.
+
+## When to use
+
+- As a primitive for custom floating UI when Tooltip / Popover / Menu don't fit.
+- Building custom dropdowns / pickers / overlays.
+
+When NOT to use:
+- Standard menus (use `DropdownMenu`).
+- Tooltips (use `Tooltip`).
+- Click-triggered floating content (use `Popover`).
+- For shadcn-based projects: use Radix Popover under the hood (which uses `@floating-ui/react`).
+
+## API
+
+```tsx
+<Popper
+  open={open}
+  anchorEl={anchorEl}
+  placement="bottom-start"
+  modifiers={[
+    { name: "offset", options: { offset: [0, 8] } },
+    { name: "preventOverflow", options: { padding: 8 } },
+  ]}
+>
+  <div className="custom-floating-content">
+    {/* whatever */}
+  </div>
+</Popper>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Visibility |
+| `anchorEl` | `HTMLElement \| null` | — | Element to anchor to |
+| `placement` | `"top" \| "bottom" \| "left" \| "right"` (+ -start / -end) | `"bottom"` | Preferred placement |
+| `modifiers` | `Modifier[]` | — | Popper.js modifiers (offset, flip, preventOverflow, etc.) |
+| `transition` | `boolean` | `false` | Enable animation hooks |
+| `disablePortal` | `boolean` | `false` | Render in-place vs Portal to body |
+| `keepMounted` | `boolean` | `false` | Keep DOM when closed (for CSS transitions) |
+
+## Behaviors
+
+| Capability | How |
+| --- | --- |
+| **Collision detection** | `flip` modifier flips placement when off-screen |
+| **Boundary clamping** | `preventOverflow` clamps to viewport |
+| **Offset** | Distance from anchor (8-12px typical) |
+| **Arrow** | Optional `arrow` modifier shows caret pointing at anchor |
+| **Portal** | Render in document body to escape parent overflow / z-index issues |
+
+## Modifier examples
+
+```ts
+[
+  { name: "offset", options: { offset: [0, 8] } },          // 8px gap
+  { name: "flip", options: { fallbackPlacements: ["top", "right"] } },
+  { name: "preventOverflow", options: { padding: 8 } },
+  { name: "arrow", options: { element: arrowEl } },
+]
+```
+
+For modern projects: use [`@floating-ui/react`](https://floating-ui.com/) directly. Popper.js is largely superseded; MUI v6+ uses floating-ui internally.
+
+## States
+
+Stateless from Popper's POV — visibility is controlled via `open`. Animations / transitions are layered separately.
+
+## Tokens consumed
+
+Popper itself doesn't theme. Tokens go on the children content.
+
+## Accessibility
+
+- Popper is positioning only. Accessibility comes from the wrapping component:
+  - Tooltip uses `role="tooltip"`.
+  - Menu uses `role="menu"`.
+  - Popover uses `role="dialog"`.
+- Focus management is up to the consumer.
+
+## Code example — custom date hover preview
+
+```tsx
+function DateHoverPreview({ date }: Props) {
+  const [anchor, setAnchor] = useState<HTMLElement | null>(null);
+
+  return (
+    <>
+      <span
+        onMouseEnter={(e) => setAnchor(e.currentTarget)}
+        onMouseLeave={() => setAnchor(null)}
+      >
+        {date.toLocaleDateString()}
+      </span>
+      <Popper
+        open={!!anchor}
+        anchorEl={anchor}
+        placement="top"
+        modifiers={[{ name: "offset", options: { offset: [0, 8] } }]}
+      >
+        <div className="date-preview">
+          {date.toLocaleString("ko-KR", { dateStyle: "full", timeStyle: "short" })}
+        </div>
+      </Popper>
+    </>
+  );
+}
+```
+
+## Don't
+
+- Don't use Popper when a higher-level primitive fits (Tooltip / Popover / DropdownMenu).
+- Don't anchor to a transient element (mutates / unmounts) without cleanup.
+- Don't rely on Popper for accessibility — wrap with proper roles + focus management.
+- Don't skip `disablePortal` consideration — default Portal behavior may break z-index in some layouts.
+
+## References
+
+- MUI: [`Popper`](../refs/mui/packages/mui-material/src/Popper)
+- Popper.js (deprecated; use @floating-ui)
+- @floating-ui/react — modern replacement
+
+## Cross-reference
+
+- [`examples/component-tooltip.md`](component-tooltip.md) — uses Popper internally
+- [`examples/component-popover.md`](component-popover.md) — uses Popper internally
+- [`examples/component-dropdown.md`](component-dropdown.md) — uses Popper internally

package/examples/component-pricing-cards.md

@@ -0,0 +1,247 @@
+# `PricingCards` — spec
+
+> Marketing primitive. Renders 2–4 pricing tiers in a comparison grid. The single most-iterated section of any SaaS landing page after the hero.
+
+## Purpose
+
+Communicate pricing tiers + features per tier + CTA per tier. Used on `/pricing`, in landing pages, and in upgrade modals.
+
+## When PricingCards vs PricingTable
+
+| Pattern | Use |
+| --- | --- |
+| **PricingCards** | 2–4 tiers; mobile-friendly; consumer-coded |
+| **PricingTable** (full feature matrix) | 4+ tiers OR detailed feature comparison; desktop-first; B2B-coded |
+
+Most SaaS: cards on landing, full table on dedicated `/pricing` page.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────────────────┐
+│ ┌──────────┐  ┌──────────────┐  ┌──────────┐                │
+│ │ Free     │  │ ⭐ Pro       │  │ Business │                │
+│ │          │  │ ‹ 추천 ›       │  │          │                │
+│ │ ₩0       │  │ ₩9,900/월    │  │ ₩29,000  │                │
+│ │ /월      │  │              │  │ /월       │                │
+│ │          │  │              │  │          │                │
+│ │ ✓ 기능1  │  │ ✓ 기능1      │  │ ✓ 기능1  │                │
+│ │ ✓ 기능2  │  │ ✓ 기능2      │  │ ✓ 기능2  │                │
+│ │   기능3 ✕ │  │ ✓ 기능3      │  │ ✓ 기능3  │                │
+│ │   기능4 ✕ │  │   기능4 ✕    │  │ ✓ 기능4  │                │
+│ │          │  │              │  │          │                │
+│ │ [무료 시작]│  │ [Pro 시작]   │  │ [상담 요청]│                │
+│ └──────────┘  └──────────────┘  └──────────┘                │
+└──────────────────────────────────────────────────────────────┘
+
+Highlighted "추천" tier: visual emphasis (border, scale-up, accent background).
+```
+
+## API
+
+```tsx
+<PricingCards
+  tiers={[
+    {
+      id: "free",
+      name: "Free",
+      price: { amount: 0, period: "month", currency: "KRW" },
+      description: "개인 사용자용",
+      features: [
+        { included: true, label: "거래내역 저장 (90일)" },
+        { included: true, label: "기본 카테고리" },
+        { included: false, label: "AI 자동 분류" },
+        { included: false, label: "은행 자동 연동" },
+      ],
+      cta: { label: "무료 시작", onClick: signupFree },
+    },
+    {
+      id: "pro",
+      name: "Pro",
+      price: { amount: 9900, period: "month", currency: "KRW" },
+      description: "개인 사용자용",
+      features: [
+        { included: true, label: "거래내역 저장 (무제한)" },
+        { included: true, label: "사용자 정의 카테고리" },
+        { included: true, label: "AI 자동 분류" },
+        { included: false, label: "팀 공유" },
+      ],
+      cta: { label: "Pro 시작", onClick: signupPro, intent: "primary" },
+      highlighted: true,
+      badge: "추천",
+    },
+    {
+      id: "business",
+      name: "Business",
+      price: { amount: 29000, period: "month", currency: "KRW" },
+      description: "팀 / 사업자용",
+      features: [
+        { included: true, label: "Pro 모든 기능" },
+        { included: true, label: "팀 공유 (최대 10명)" },
+        { included: true, label: "사업자 영수증 처리" },
+        { included: true, label: "전담 고객센터" },
+      ],
+      cta: { label: "상담 요청", onClick: contact },
+    },
+  ]}
+  billingPeriod="monthly"
+  onBillingPeriodChange={setBillingPeriod}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `tiers` | `Tier[]` | — | Pricing tiers (2–4 typical) |
+| `billingPeriod` | `"monthly" \| "yearly"` | `"monthly"` | |
+| `onBillingPeriodChange` | `(period) => void` | — | Toggle handler |
+| `yearlyDiscount` | `number` | — | "월 결제 대비 N% 할인" badge |
+| `currency` | `"KRW" \| ...` | `"KRW"` | Display currency |
+
+```ts
+type Tier = {
+  id: string;
+  name: string;             // "Free" / "Pro" / "Business"
+  price: { amount: number, period: "month" | "year", currency: string };
+  description?: string;
+  features: Feature[];
+  cta: { label: string, onClick: () => void, intent?: "primary" | "secondary" };
+  highlighted?: boolean;     // visual emphasis
+  badge?: string;            // "추천" / "인기"
+};
+
+type Feature = {
+  included: boolean;
+  label: string;
+  hint?: string;             // tooltip detail
+};
+```
+
+## Tier visual
+
+### Default tier (non-highlighted)
+
+- Card with neutral border
+- Standard padding
+- Outline button CTA
+
+### Highlighted tier ("recommended")
+
+- Border in `--color-primary-default`
+- Slightly bigger scale (`transform: scale(1.05)` desktop)
+- Solid primary CTA
+- "추천" badge above the card
+
+The highlighted tier is the **default conversion target**. Be explicit about which tier you want users to pick.
+
+## Feature display
+
+```
+✓ 기능 (included)
+○ 기능 (not included)  — gray, muted
+✓ 기능1 ⓘ              — with tooltip
+```
+
+| Approach | Use |
+| --- | --- |
+| Show all features in every tier (with ✓/○) | Full transparency, easy comparison |
+| Show only included features per tier | Cleaner but harder comparison |
+| Differentials only ("Everything in Free, plus...") | Hierarchical pricing — hides scope |
+
+For most consumer fintech: show all features with ✓/○ per tier. Tooltip for explanation.
+
+## Billing period toggle
+
+Common: monthly vs yearly toggle above the tiers, with "save 20%" badge:
+
+```
+[월간] [연간 -20%]
+```
+
+Yearly discount must be **honest**:
+- Monthly tier × 12 vs yearly: show the actual savings.
+- "20% 할인" only if math checks out.
+
+## Korean conventions
+
+- **Currency**: ₩9,900 / 월 (prefix) or 9,900원/월 (suffix). Pick one. Most Korean SaaS uses 원/월.
+- **Free tier name**: "무료" or "Free" — both work. KakaoBank-style products use "무료".
+- **Recommended tier badge**: "추천" / "가장 인기" / "베스트셀러".
+- **CTA verbs**: "시작" / "가입" / "결제" — short, action-led.
+- **Yearly discount label**: "연간 결제 시 20% 할인" or "월 N원 (연 결제)".
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (highlighted tier)
+--color-bg-subtle           (alternating rows in features list)
+--color-primary-default     (highlighted border, primary CTA)
+--color-primary-subtle-bg   (highlighted bg tint)
+--color-text-primary
+--color-text-secondary
+--color-text-tertiary       (un-included features)
+--color-success             (included checkmarks)
+--color-border-default
+--space-md, --space-lg, --space-xl
+--radius-lg
+--shadow-card               (highlighted tier elevation)
+```
+
+## Accessibility
+
+- Render as `<section>` with `<h2>` for "Pricing".
+- Each tier: `<article>` with `<h3>` for tier name.
+- Price: prominent, with `aria-label="9,900원 매월"`.
+- Feature list: `<ul>` with `<li>`. ✓/○ as `aria-hidden="true"`; "포함" / "미포함" prefix on each `<li>`'s screen-reader text.
+- Highlighted tier: `aria-label="추천 요금제"`.
+- Billing toggle: `<fieldset>` with radio buttons.
+
+## Korean / English label mapping
+
+| English | Korean |
+| --- | --- |
+| Free | 무료 |
+| Pro | Pro |
+| Business / Enterprise | Business / 비즈니스 / 엔터프라이즈 |
+| Recommended | 추천 |
+| Most popular | 가장 인기 |
+| Best seller | 베스트셀러 |
+| Get started | 시작하기 |
+| Contact sales | 상담 요청 |
+| Save N% | N% 할인 |
+| / month | / 월 |
+| / year | / 연 |
+
+## Code example
+
+(See API example above — fully fleshed out.)
+
+## Edge cases
+
+- **Custom pricing tier** ("Enterprise — Contact us"): no number, just "상담 후 결정". CTA opens contact form.
+- **Free trial** for paid tier: indicate prominently — "14일 무료 체험" near price.
+- **Annual-only / monthly-only**: hide the toggle if not applicable.
+- **Multiple currencies**: detect locale, show appropriate. Fallback USD.
+- **Per-seat pricing**: "₩9,900 / 사용자 / 월". Make explicit.
+
+## Don't
+
+- Don't have 5+ tiers — analysis paralysis.
+- Don't hide the "free" tier if it exists.
+- Don't auto-select a tier; let users click.
+- Don't show "원래는 비싼" pricing without honest discount math.
+- Don't make the highlighted tier look identical to others — defeats purpose.
+- Don't use "Most popular" for a tier with no actual popularity data.
+- Don't omit "월" / "연" suffix on prices — confusion follows.
+
+## References
+
+No upstream component matches exactly. Each marketing-builder (Webflow, Framer) has variants. Stripe's pricing page is canonical Western reference. Toss / KakaoBank are canonical Korean.
+
+## Cross-reference
+
+- [`knowledge/patterns/pricing-page-design.md`](../knowledge/patterns/pricing-page-design.md) — pricing strategy + design
+- [`examples/component-card.md`](component-card.md) — base card primitive
+- [`examples/component-button.md`](component-button.md) — CTA primitive
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — currency display
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — pricing in KR market

package/examples/component-progress.md

@@ -0,0 +1,195 @@
+# `Progress` — spec
+
+> Citing Ant Design `Progress`, MUI `LinearProgress`/`CircularProgress`, shadcn-ui `progress`
+
+## Purpose
+
+Visualizes the completion of a task. Two variants:
+
+| Variant | Use |
+| --- | --- |
+| **Linear** (bar) | Long, sequential operations: file upload, multi-step form, page-load progress |
+| **Circular** (ring) | Compact: button loading, profile completion percentage, score display |
+
+## Determinate vs Indeterminate
+
+| Mode | Use |
+| --- | --- |
+| **Determinate** (knows %) | Upload of known file size, multi-step wizard (3/5), survey progress |
+| **Indeterminate** (doesn't know %) | API call with unknown duration, "thinking" states |
+
+For indeterminate operations < 2 seconds, prefer a Spinner (not a Progress component). Progress implies multi-step.
+
+## Anatomy — Linear
+
+```
+Determinate:     ▰▰▰▰▰▰▰▱▱▱  60%
+Indeterminate:   ▱▱▰▰▰▰▱▱▱▱  (animated sweep)
+```
+
+```tsx
+<Progress value={60} />                 {/* determinate */}
+<Progress />                            {/* indeterminate (no value) */}
+<Progress value={60} max={100} />       {/* explicit max */}
+```
+
+## Anatomy — Circular
+
+```
+   ⌒⌒
+  ⟨ 60% ⟩    ← ring with arc filled to 60%, label centered
+   ⌣⌣
+```
+
+```tsx
+<Progress variant="circular" value={60} size={48} showLabel />
+<Progress variant="circular" />          {/* indeterminate spinner */}
+```
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` | — | 0–100 (or 0–`max`). Omit for indeterminate. |
+| `max` | `number` | `100` | Upper bound |
+| `variant` | `"linear" \| "circular"` | `"linear"` | |
+| `intent` | `"primary" \| "success" \| "warning" \| "error"` | `"primary"` | Bar color |
+| `size` | `"sm" \| "md" \| "lg"` (linear) / `number` (circular, px) | `"md"` / `40` | |
+| `thickness` | `number` | derived | Bar height (linear) or ring stroke (circular) |
+| `showLabel` | `boolean` | `false` | Render the % value |
+| `label` | `ReactNode` | `${value}%` | Custom label |
+| `striped` | `boolean` | `false` | Animated diagonal stripes (linear, indicates active progress) |
+
+## Linear sizes
+
+| Size | Height | Use |
+| --- | --- | --- |
+| `sm` | 4px | Subtle, beneath nav bars |
+| `md` (default) | 8px | Standard upload/download |
+| `lg` | 12px | Hero / dashboard prominence |
+
+## Circular sizes
+
+| Size | Diameter | Stroke | Use |
+| --- | --- | --- | --- |
+| `sm` (16) | 16px | 2px | Inside a button (loading) |
+| `md` (24) | 24px | 3px | Inline loading indicator |
+| `lg` (40, default) | 40px | 4px | Page/section loader |
+| `xl` (64+) | 64px | 5px | Hero / score display |
+
+## States
+
+| State | Linear | Circular |
+| --- | --- | --- |
+| Determinate, value > 0 | Bar fills `value`% | Ring arc to `value`° |
+| Determinate, value = 100 | Full bar, optional success color shift | Full ring |
+| Indeterminate | Animated sweep (1500ms loop, ease-in-out) | Spinning arc (1000ms loop, linear) |
+| Striped (linear active) | Bar fills + diagonal stripes animate | N/A |
+
+## Tokens consumed
+
+```
+--color-bg-subtle           (track)
+--color-primary-default     (bar fill, default intent)
+--color-success
+--color-warning
+--color-error
+--color-text-secondary       (label)
+--space-xs, --space-sm
+--radius-full                (rounded bar/ring ends)
+--motion-default             (transitions on value change)
+--easing-out
+```
+
+For dark mode, ensure track is visible against bg — typically `--color-bg-subtle` works in both modes.
+
+## Behavior
+
+### Determinate value transitions
+
+- Animate value changes over 200–400ms with `ease-out`.
+- For very small changes (< 5%), instant transition is fine.
+- Don't animate every frame on continuous progress (e.g., upload at 47.3% → 47.4%) — let the visual update lag for smoother perception.
+
+### Indeterminate animation
+
+Linear: 0% → 100% sweep, 1500ms loop. The "wave" travels left to right.
+
+Circular: full rotation, 1000ms loop, linear easing. The arc itself can also pulse in length (10–80% arc) for the Material-style "growing/shrinking" spinner.
+
+## Accessibility
+
+- **Determinate**: `role="progressbar"`, `aria-valuenow`, `aria-valuemin`, `aria-valuemax`, `aria-label` (or `aria-labelledby`).
+  ```html
+  <div role="progressbar" aria-valuenow="60" aria-valuemin="0" aria-valuemax="100" aria-label="Upload progress">
+  ```
+- **Indeterminate**: `role="progressbar"` with no `aria-valuenow` (omit, don't set to 0).
+- **Don't update aria-valuenow on every frame** — debounce to ~5–10% steps, or update on percentage milestones.
+- **Reduced motion**: indeterminate animation should be replaced with a static "loading" indicator. Determinate value transitions should be instant (no 300ms animation).
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .progress { transition: none; }
+  .progress-indeterminate { animation: none; }
+}
+```
+
+## Code example
+
+```tsx
+// File upload progress
+<div>
+  <p>uploading.pdf — {bytesFormatted}</p>
+  <Progress value={uploadPct} aria-label="Upload progress" />
+</div>
+
+// Multi-step form
+<Progress value={(currentStep / totalSteps) * 100} aria-label={`Step ${currentStep} of ${totalSteps}`} showLabel />
+
+// Indeterminate while waiting
+<Progress aria-label="Loading account data" />
+
+// Profile completion (circular hero)
+<Progress
+  variant="circular"
+  value={profileCompletion}
+  size={120}
+  showLabel
+  label={`${profileCompletion}% 완료`}
+/>
+
+// Inside a Button (replaces button's children with circular)
+<Button loading><Progress variant="circular" size={16} /></Button>
+```
+
+## Edge cases
+
+- **Value > max**: clamp to max. Don't render at 110%.
+- **Negative value**: clamp to 0.
+- **Value transitions backwards** (e.g., 80% → 30%, retrying upload): animate, but communicate the rollback in copy ("재시도 중…").
+- **Stuck progress** (no movement for 30s+): show a "still working…" indicator alongside, or escalate to error.
+- **0% determinate**: show empty track. Don't fall back to indeterminate animation.
+- **100% determinate**: optionally shift to success color + checkmark when done. Otherwise, unmount the progress.
+- **Multiple concurrent**: stack vertically, each labeled. Don't sum into one combined progress.
+- **Reduced motion + indeterminate**: still need to communicate "in progress" — show a text label, e.g., "처리 중…".
+
+## Don't
+
+- Don't use indeterminate for operations under 1 second. Just don't show a progress component.
+- Don't fake progress (e.g., always show 0 → 100% over 3s while actual completion time is unknown). Fails when reality differs.
+- Don't combine multiple unrelated tasks into one progress bar.
+- Don't show progress for irreversible / consequential actions without a way to cancel.
+- Don't omit aria-label.
+- Don't use a Progress for a Skeleton's job — Skeleton is for content shape, Progress is for completion %.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/progress/`](../refs/ant-design/components/progress/) — `Progress` with `type="line" | "circle" | "dashboard"` (3/4 ring), `steps` (segmented), `success` (overlay).
+- MUI: separate `LinearProgress` and `CircularProgress` components. `variant="determinate" | "indeterminate" | "buffer" | "query"`. Buffer mode for media playback.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/progress.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/progress.tsx) — Radix primitive. Linear only. Circular requires a different primitive.
+
+## Cross-reference
+
+- [examples/component-skeleton.md](component-skeleton.md) — for "loading shape", not "progress %"
+- [examples/component-button.md](component-button.md) — uses circular Progress for `loading` state
+- [knowledge/motion/principles.md](../knowledge/motion/principles.md) — animation timing