@design-ai/cli 4.55.0

package/examples/component-accordion.md

@@ -0,0 +1,229 @@
+# `Accordion` (Collapse) — spec
+
+> Citing Ant Design `Collapse`, MUI `Accordion`, shadcn-ui `accordion`
+
+## Purpose
+
+A vertically stacked set of expandable sections. User clicks a header to reveal/hide the body. Optimized for content that's organized into named sections but doesn't all need to be visible at once.
+
+## When Accordion vs Tabs vs always-visible
+
+| Use Accordion | Use Tabs | Always visible |
+| --- | --- | --- |
+| Content sections that don't need parallel comparison | Sections that user switches between | Critical info that must always be visible |
+| FAQ, settings groups, expandable details | Profile / Activity / Settings (mutually exclusive views) | Hero, primary data |
+
+Don't use accordion for navigation between distinct screens — that's tabs or pages.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│ ▾  Section 1 title                               │  ← Header (button)
+├──────────────────────────────────────────────────┤
+│    Section 1 content...                          │  ← Body (revealed when expanded)
+│                                                   │
+└──────────────────────────────────────────────────┘
+┌──────────────────────────────────────────────────┐
+│ ▸  Section 2 title                               │  ← Collapsed
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Trigger (header) | yes | Clickable; title + chevron. |
+| Body | yes | Hidden when collapsed. |
+| Chevron | yes (visual) | Rotates 90° on expand. |
+| Icon (leading) | optional | Per-section icon. |
+| Description (in header) | optional | Subtitle on header. |
+
+## API
+
+```tsx
+<Accordion type="single" defaultValue="section-1" collapsible>
+  <Accordion.Item value="section-1">
+    <Accordion.Trigger>Section 1 title</Accordion.Trigger>
+    <Accordion.Content>
+      Body content for section 1.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="section-2">
+    <Accordion.Trigger>Section 2 title</Accordion.Trigger>
+    <Accordion.Content>
+      Body content for section 2.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `type` | `"single" \| "multiple"` | `"single"` | Single: only one section open at a time. Multiple: any combination. |
+| `value` / `defaultValue` | `string` (single) / `string[]` (multiple) | — | Open section(s) |
+| `onValueChange` | `(value) => void` | — | |
+| `collapsible` | `boolean` | `true` | When `single`: allow closing the open section (vs. always one open) |
+| `disabled` | `boolean` | `false` | Disables all sections |
+
+| Prop (Item) | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | Required. Unique key. |
+| `disabled` | `boolean` | Disables this section |
+
+## Variants
+
+| Variant | Use |
+| --- | --- |
+| `bordered` (default) | 1px border around each item |
+| `borderless` | No borders, hairline divider between items only |
+| `card` | Each item is a card with shadow + radius |
+| `flush` | Edge-to-edge, no border, divider between items (mobile-friendly) |
+
+For settings-list patterns: `flush` is most common.
+
+## States
+
+| State | Trigger | Body | Chevron |
+| --- | --- | --- | --- |
+| Collapsed | resting | hidden, height 0 | →/▸ |
+| Expanding | click on trigger | animating to natural height (200ms) | rotating |
+| Expanded | settled | natural height | ↓/▾ |
+| Collapsing | click on open trigger | animating to 0 (200ms) | rotating |
+| Disabled | `disabled={true}` | hidden | muted |
+| Hover | mouse-over header | bg slightly darker | — |
+| Focus-visible | keyboard tab | 2px ring on header | — |
+
+### Animating height
+
+Use `grid-template-rows: 0fr → 1fr` (CSS-only, modern):
+
+```css
+.accordion-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 200ms ease-out;
+}
+.accordion-content[data-state="open"] {
+  grid-template-rows: 1fr;
+}
+.accordion-content > * {
+  overflow: hidden;
+}
+```
+
+Or animate `max-height` (but it's CSS-hostile for variable content).
+
+Radix's accordion uses CSS variables `--radix-collapsible-content-height` for the natural height — paste-ready.
+
+## Sizes
+
+| Size | Header height | Font | Padding |
+| --- | --- | --- | --- |
+| `sm` | 40px | 14px | 12px |
+| `md` (default) | 48px | 15px | 16px |
+| `lg` | 56px | 16px | 20px |
+
+For mobile-touch: `md` minimum.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle           (header hover, body bg in some variants)
+--color-bg-elevated         (card variant)
+--color-text-primary
+--color-text-secondary
+--color-border-default
+--color-focus-ring
+--space-md, --space-base
+--radius-md
+--motion-default            (200ms expand/collapse)
+--easing-in-out
+--shadow-card               (card variant)
+```
+
+## Accessibility — WAI-ARIA Disclosure / Accordion pattern
+
+- Each header is a `<button>` with `aria-expanded="true|false"`.
+- Header has `aria-controls={bodyId}` linking to the body element.
+- Body has `id={bodyId}`, `role="region"`, `aria-labelledby={headerId}`.
+- For `type="single"`: this is the canonical Disclosure pattern.
+- For `type="multiple"`: same pattern, just multiple `aria-expanded="true"` allowed.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Move focus through headers (skip hidden body) |
+| `Enter` / `Space` | Toggle the focused section |
+| `↑` / `↓` | Move focus between accordion headers (Radix convention; some implementations use Tab only) |
+| `Home` / `End` | First / last header |
+
+### Reduced motion
+
+Disable height transition. Toggle is instant (no 200ms).
+
+## Code example
+
+```tsx
+// FAQ pattern
+<Accordion type="single" collapsible>
+  <Accordion.Item value="how-to-cancel">
+    <Accordion.Trigger>구독을 어떻게 해지하나요?</Accordion.Trigger>
+    <Accordion.Content>
+      설정 → 구독 관리 → 해지하기에서 언제든 해지할 수 있습니다.
+    </Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="refund">
+    <Accordion.Trigger>환불은 어떻게 받나요?</Accordion.Trigger>
+    <Accordion.Content>
+      디지털 콘텐츠 7일 이내 환불 가능합니다. 고객센터로 문의해 주세요.
+    </Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+
+// Settings sections (multiple)
+<Accordion type="multiple" defaultValue={["account", "notifications"]}>
+  <Accordion.Item value="account">
+    <Accordion.Trigger>계정</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="notifications">
+    <Accordion.Trigger>알림</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+  <Accordion.Item value="security">
+    <Accordion.Trigger>보안</Accordion.Trigger>
+    <Accordion.Content>...</Accordion.Content>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Edge cases
+
+- **Long body content scrolls into view as it expands**: scrolling the new content into view on expand is helpful for long sections — but only if it's currently below the fold.
+- **Animating height with content that loads async**: as content arrives, the body re-animates if user is watching. Consider rendering all content (display:none) if heights need to be exact.
+- **Nested accordions**: avoid. Re-design the hierarchy.
+- **Accordion inside a modal**: works, but ensure the modal's max-height accommodates the expanded content.
+- **One section open by default**: `defaultValue="..."` for type="single". Useful for FAQ where the most-asked question is open.
+- **Close-all when scrolling**: anti-pattern. User-driven open/close should persist.
+
+## Don't
+
+- Don't use Accordion for primary navigation.
+- Don't put critical CTAs only inside accordions — users won't expand to find them.
+- Don't auto-collapse a section while user is reading.
+- Don't show > 8 accordion items at once. Use sections + headings or a different layout.
+- Don't render accordion bodies as `display: none` if they have form state — state is lost. Use `hidden` attribute or keep mounted with `aria-hidden` + visibility.
+- Don't combine controlled + uncontrolled modes — pick one.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/collapse/`](../refs/ant-design/components/collapse/) — `Collapse` + `Collapse.Panel`. `accordion` prop forces single. Has nice `expandIcon` customization.
+- MUI: [`refs/mui/packages/mui-material/src/Accordion/`](../refs/mui/packages/mui-material/src/Accordion/) — `Accordion`, `AccordionSummary`, `AccordionDetails`, `AccordionActions`. Solid composition.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx) — Radix Accordion primitive. Cleanest a11y. **Default for new projects.**
+
+## Cross-reference
+
+- [examples/component-tabs.md](component-tabs.md) — alternative for non-stackable view-switching
+- [WAI-ARIA Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+- [WAI-ARIA Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)

package/examples/component-account-card.md

@@ -0,0 +1,284 @@
+# `AccountCard` (custom — Korean banking / fintech) — spec
+
+> Custom component pattern. Korean banking apps universally render bank accounts as branded cards. KakaoBank, Toss, traditional bank apps all converge on this design.
+
+## Purpose
+
+Displays a bank account as a card: bank logo + nickname + masked account number + balance. Tappable to open transaction history.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────────────┐
+│ [bank logo]  국민 입출금                          │  ← bank brand + nickname
+│              123-45-6789-012                     │  ← masked account number
+│                                                  │
+│  ₩2,847,500                                      │  ← balance (prominent)
+│                                                  │
+│  [송금] [QR 결제] [입금]                          │  ← optional quick actions
+└─────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Bank logo | yes | Official asset; provides instant recognition |
+| Nickname | yes | User-editable label (default: "통장 이름") |
+| Account number | yes | Masked except last 4 digits |
+| Balance | yes | Display tier, tabular numerals, prominent |
+| Quick actions | optional | 송금 / 결제 / 입금 |
+| Trailing chevron | optional | If tappable to navigate |
+| Status badge | optional | "정지", "주거래" |
+
+## API
+
+```tsx
+<AccountCard
+  bank="KB국민은행"
+  bankLogo="/banks/kb.png"
+  nickname="국민 입출금"
+  accountNumber="123-45-6789-012"
+  balance={2847500}
+  variant="hero"
+  onClick={() => navigate(`/accounts/${id}`)}
+  actions={[
+    { label: "송금", onClick: openTransfer },
+    { label: "QR 결제", onClick: openQrPay },
+    { label: "입금", onClick: openDeposit },
+  ]}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `bank` | `string` | — | Bank name (Korean) |
+| `bankLogo` | `string \| ReactNode` | — | Logo asset |
+| `bankColor` | `string` | derived from bank | Brand color for accent |
+| `nickname` | `string` | — | User-editable label |
+| `accountNumber` | `string` | — | Full or masked |
+| `mask` | `boolean` | `true` | Auto-mask account number |
+| `balance` | `number` | — | In smallest unit (won) |
+| `currency` | `"KRW" \| ...` | `"KRW"` | |
+| `variant` | `"compact" \| "default" \| "hero"` | `"default"` | |
+| `actions` | `Action[]` | — | Quick actions row |
+| `onClick` | `() => void` | — | Tap to drill in |
+| `status` | `"active" \| "frozen" \| "primary"` | `"active"` | Optional badge |
+| `loading` | `boolean` | `false` | Skeleton state |
+
+## Variants
+
+### Compact
+
+For a list of accounts (account selector):
+```
+┌──────────────────────────────────────┐
+│ [logo]  국민 입출금         ₩2,847,500│
+│         ****-012                     │
+└──────────────────────────────────────┘
+```
+
+Single row, minimal padding.
+
+### Default
+
+Standard card with balance prominent and actions:
+```
+┌─────────────────────────────────────┐
+│ [logo]  국민 입출금                    │
+│         ****-012                     │
+│                                      │
+│  ₩2,847,500                          │
+│                                      │
+│  [송금] [결제]                        │
+└─────────────────────────────────────┘
+```
+
+### Hero
+
+For the home screen / primary account:
+```
+┌─────────────────────────────────────────────┐
+│  국민 입출금                                  │
+│  ****-012                                    │
+│                                              │
+│  ₩2,847,500                                  │  ← extra large
+│  ↑ 12,500원 이번 달                            │
+│                                              │
+│  [송금] [QR 결제] [입금]                      │
+└─────────────────────────────────────────────┘
+```
+
+Larger amount, optional delta indicator, and full quick actions.
+
+## Account number masking
+
+| Format | Display | Use |
+| --- | --- | --- |
+| Full | `123-45-6789-012` | Detail screen with extra security |
+| Last 4 only | `****-012` | List view, default |
+| Hidden | `****-****` | When user has masking turned on |
+
+The `mask` prop controls which. Mid-text mask uses asterisks per Korean banking convention (not bullets).
+
+## Bank brand integration
+
+Korean banks have official logos + brand colors. Don't restyle — use vendor assets:
+
+| Bank | Brand color |
+| --- | --- |
+| KakaoBank | Yellow `#FFEB00` |
+| KB국민은행 | Yellow + black |
+| 신한은행 | Blue `#0046ff` |
+| 우리은행 | Blue (different shade) |
+| 하나은행 | Green |
+| NH농협 | Green |
+| Toss | Blue `#3182F6` |
+| Naver Bank | Green |
+
+Use brand color for:
+- Card border accent
+- Bank logo bg
+- Subtle background tint (low-saturation)
+
+Don't use for:
+- Balance text (always neutral or money-positive/negative)
+- Action button bg
+
+## Sizes / variants → tokens
+
+| Variant | Card padding | Balance font | Balance weight |
+| --- | --- | --- | --- |
+| `compact` | 12px | 16px | 600 |
+| `default` | 16px | 24px | 600 |
+| `hero` | 24px | 36px | 700 |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Hover (interactive) | Subtle bg shift |
+| Pressed | Slight scale 0.98 (mobile feedback) |
+| Focus-visible | 2px ring |
+| Loading | Skeleton: logo + text bars + balance bar |
+| Frozen / 정지 | Gray bg + "정지" badge |
+| Primary / 주거래 | "주거래" badge with star icon |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-elevated         (card surface)
+--color-bg-subtle           (hover)
+--color-text-primary        (balance, nickname)
+--color-text-secondary       (account number, bank name)
+--color-money-positive       (delta indicator if positive)
+--color-money-negative
+--color-money-neutral
+--color-primary-default     (action button bg if appropriate)
+--color-warning              ("정지" status)
+--color-success              ("주거래" badge)
+--color-border-default
+--color-focus-ring
+--space-sm, --space-md, --space-lg
+--radius-lg                  (card corners)
+--shadow-card                 (subtle elevation)
+--font-feature-amount: 'tnum' 1
+--font-size-sm, --font-size-base, --font-size-2xl
+```
+
+## Accessibility
+
+- Render as `<button>` if interactive, `<article>` if static.
+- Bank logo: `<img alt="KB국민은행 로고">`.
+- Account number: render with semantic markup so screen readers don't read each digit ("일이삼"); use `aria-label`:
+  ```html
+  <span aria-label="계좌번호 마지막 네 자리, 영영일이">****-012</span>
+  ```
+- Balance: also include aria-label that's friendlier than the raw digits:
+  ```html
+  <span aria-label="잔액 290만 원">₩2,847,500</span>
+  ```
+- Action buttons: standard accessibility.
+
+## Code example
+
+```tsx
+function AccountsScreen() {
+  const accounts = useAccounts();
+
+  return (
+    <Page>
+      <PageHeader>내 계좌</PageHeader>
+
+      {/* Hero variant for primary */}
+      {accounts.primary && (
+        <AccountCard
+          variant="hero"
+          {...accounts.primary}
+          actions={[
+            { label: "송금", onClick: () => openTransfer(accounts.primary.id) },
+            { label: "QR 결제", onClick: () => openQrPay(accounts.primary.id) },
+            { label: "입금", onClick: () => openDeposit(accounts.primary.id) },
+          ]}
+        />
+      )}
+
+      {/* Compact for list */}
+      <Section title="다른 계좌">
+        {accounts.others.map(account => (
+          <AccountCard
+            key={account.id}
+            variant="compact"
+            {...account}
+            onClick={() => navigate(`/accounts/${account.id}`)}
+          />
+        ))}
+      </Section>
+    </Page>
+  );
+}
+```
+
+## Edge cases
+
+- **Negative balance** (overdraft): show with `--color-money-negative` + small "-" prefix or "(₩50,000)" parens. Clarify with subtitle "마이너스 통장".
+- **Foreign currency account**: switch currency symbol; consider showing KRW conversion below.
+- **Hidden balance** (user turned on privacy mode): show `***` instead of digits, with toggle.
+- **Stale balance** (last sync > 1hr): show timestamp, prompt to refresh.
+- **Loading**: skeleton matching the card shape — don't blank out.
+- **Network error fetching balance**: show "잔액 불러오기 실패" with retry.
+- **Empty bank logo**: render bank initial in a colored circle (use bankColor).
+
+## Don't
+
+- Don't show full account number by default. Mask except last 4.
+- Don't omit bank logo — brand recognition is the entire point of the card.
+- Don't restyle bank logos / brand colors.
+- Don't use `--color-error` for negative balance — use `--color-money-negative`.
+- Don't omit tabular numerals — balance won't align.
+- Don't auto-refresh balance every second; respect bank API rate limits.
+- Don't make actions invisible without tap. Show visible buttons.
+
+## Korean considerations
+
+- Account nickname is **user-editable** — letting users rename "통장이름" is a key Korean banking app feature.
+- "주거래" (primary account) is a Korean banking concept; mark with badge.
+- "송금 / 입금 / QR 결제 / 자동이체" are the canonical action labels.
+- For business accounts (사업자 계좌): subtitle may include 사업자등록번호.
+- For 외화 계좌 (foreign currency): clearly show currency symbol + KRW equivalent.
+
+## API rationale
+
+- **`balance: number`**: source of truth. Formatting via tabular numeric output.
+- **`bankLogo` accepts both string (URL) and ReactNode**: flexibility for asset pipelines.
+- **Three variants** capture the most common usage shapes; more is over-flexibility.
+- **Quick actions as array**: each card might have different actions based on account type.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — currency display, money color
+- [`knowledge/i18n/korean-payments.md`](../knowledge/i18n/korean-payments.md) — Korean banking conventions
+- [`knowledge/i18n/korean-product-conventions.md`](../knowledge/i18n/korean-product-conventions.md) — broader KR app conventions
+- [`examples/component-card.md`](component-card.md) — base card pattern
+- [`examples/component-statistic.md`](component-statistic.md) — balance display style
+- [`examples/component-transaction-list-item.md`](component-transaction-list-item.md) — drill-in target