@design-ai/cli 4.55.0

package/examples/component-item.md

@@ -0,0 +1,243 @@
+# `Item` — spec
+
+> Synthesized from shadcn-ui `item` (a flexible list-item primitive). The "Item family" — `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, `ItemActions`, `ItemSeparator`, `ItemHeader`, `ItemFooter`. The atomic building block for lists, tables-of-things, settings rows, account rows, search results.
+
+## When to use
+
+- **Settings rows** (with leading icon, title, description, trailing chevron / switch).
+- **Account / profile rows** (avatar + name + role + actions).
+- **Search results** (icon / image + title + meta + actions).
+- **List rows** in any list-of-entities surface (mail inbox, notifications, files).
+
+When NOT to use:
+- Data-grid rows — use `Table`.
+- Card-style entities — use `Card`.
+- Pure text list — use `<ul>` / `<ol>`.
+
+## Anatomy
+
+```
+┌────────────────────────────────────┐
+│ [icon] [title]              [⋮]    │   ← single-line, with action
+│        [description]                 │
+└────────────────────────────────────┘
+
+┌────────────────────────────────────┐
+│ [avatar 40px]  Sungjin Park         │  ← list / contact pattern
+│                Senior Designer       │
+│                                  ▶  │
+└────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Item>
+  <ItemMedia>
+    <Avatar src={user.avatar} />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>{user.name}</ItemTitle>
+    <ItemDescription>{user.role}</ItemDescription>
+  </ItemContent>
+  <ItemActions>
+    <Button variant="ghost" size="icon">
+      <ChevronRightIcon />
+    </Button>
+  </ItemActions>
+</Item>
+```
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Item` | Outer row wrapper |
+| `ItemMedia` | Leading visual (icon, avatar, image) |
+| `ItemContent` | Middle text region (Title + Description) |
+| `ItemTitle` | Primary text |
+| `ItemDescription` | Secondary muted text |
+| `ItemActions` | Trailing action(s) (button, switch, count, chevron) |
+| `ItemHeader` | Above-content metadata (date, author) |
+| `ItemFooter` | Below-content secondary content |
+| `ItemSeparator` | Divider between consecutive Items |
+
+## Variants
+
+### Density
+
+| Density | Padding | Typical Title size |
+| --- | --- | --- |
+| `comfortable` (default) | `--space-md` | 14-16px |
+| `compact` | `--space-sm` | 13-14px |
+| `relaxed` | `--space-lg` | 16-18px |
+
+### Interactive
+
+```tsx
+<Item asChild>
+  <a href={`/users/${user.id}`}>...</a>
+</Item>
+
+<Item interactive onClick={onClick}>...</Item>
+```
+
+When interactive, the entire row is the click target (block link pattern).
+
+### Selectable
+
+```tsx
+<Item selected={isSelected} onSelect={handleSelect}>
+  ...
+</Item>
+```
+
+Used in selection lists (mail, files). Selected state has highlight bg + persistent indicator.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Hover (interactive) | Subtle bg shift |
+| Pressed | Deeper bg (touch) or stable (mouse) |
+| Focus-visible | 2px focus ring on the entire row |
+| Selected | Persistent bg highlight + brand-color indicator |
+| Disabled | Reduced opacity, no events, `aria-disabled` |
+
+## Tokens consumed
+
+```
+--item-bg                          (default; transparent)
+--item-bg-hover                    (interactive hover)
+--item-bg-selected                 (selected state)
+--item-fg                          (Title)
+--item-fg-muted                    (Description)
+--item-padding-y                   (varies by density)
+--item-padding-x                   (typically --space-md)
+--item-gap                         (between Media / Content / Actions)
+--item-divider                     (Separator color)
+--space-sm, --space-md, --space-lg
+--radius-md                        (rounded item highlight)
+--motion-fast                      (hover transition)
+```
+
+## Accessibility
+
+- `Item`:
+  - If interactive (clickable row): use real `<a>` or `<button>`. Apply `block` styles. Focus goes to the wrapper.
+  - If non-interactive: plain `<li>` inside parent `<ul>` / `<ol>`.
+  - For multi-action items (selectable + has trailing actions): outer is `<button>` for select, but Trailing buttons inside can't be nested. Use a different pattern (separate select + actions, or label-for-checkbox pattern).
+- `ItemTitle`: typically `<h3>` or `<h4>` if list is a section's content, or just text in a list of homogenous items.
+- `ItemActions`: each action is an independent button with its own `aria-label`.
+- Touch target: ≥ 44pt for the row OR the action(s).
+- Selected state: `aria-selected="true"` (in selection list) or `aria-checked` if checkbox-style.
+
+## Korean apps
+
+Korean list patterns:
+- **Account row**: avatar + name + role / phone + "더보기" arrow
+- **Settings row**: icon + label + value (e.g., "언어 — 한국어 ▶") + chevron
+- **Notification row**: icon + title (bold) + body (muted) + timestamp + unread dot
+- **Transaction row** (fintech): merchant logo + name + amount (right) + date below — see [`examples/component-transaction-list-item.md`](component-transaction-list-item.md) for KR fintech specifics.
+
+Common labels:
+- 더보기 (more)
+- 설정 (settings)
+- 알림 (notifications)
+- 자세히 (details)
+
+## Code example — settings list
+
+```tsx
+function SettingsList() {
+  return (
+    <div role="list">
+      <Item asChild interactive>
+        <Link href="/settings/profile">
+          <ItemMedia><UserIcon /></ItemMedia>
+          <ItemContent>
+            <ItemTitle>프로필</ItemTitle>
+            <ItemDescription>이름, 사진, 자기소개</ItemDescription>
+          </ItemContent>
+          <ItemActions>
+            <ChevronRightIcon className="text-muted" />
+          </ItemActions>
+        </Link>
+      </Item>
+
+      <ItemSeparator />
+
+      <Item asChild interactive>
+        <Link href="/settings/notifications">
+          <ItemMedia><BellIcon /></ItemMedia>
+          <ItemContent>
+            <ItemTitle>알림</ItemTitle>
+            <ItemDescription>이메일, 푸시, SMS 설정</ItemDescription>
+          </ItemContent>
+          <ItemActions>
+            <ChevronRightIcon className="text-muted" />
+          </ItemActions>
+        </Link>
+      </Item>
+
+      <ItemSeparator />
+
+      <Item>
+        <ItemMedia><MoonIcon /></ItemMedia>
+        <ItemContent>
+          <ItemTitle>다크 모드</ItemTitle>
+        </ItemContent>
+        <ItemActions>
+          <Switch checked={isDark} onCheckedChange={setIsDark} />
+        </ItemActions>
+      </Item>
+
+      <ItemSeparator />
+
+      <Item asChild interactive>
+        <Link href="/help">
+          <ItemMedia><QuestionIcon /></ItemMedia>
+          <ItemContent>
+            <ItemTitle>도움말</ItemTitle>
+          </ItemContent>
+          <ItemActions>
+            <ChevronRightIcon className="text-muted" />
+          </ItemActions>
+        </Link>
+      </Item>
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Long Title**: truncate with ellipsis (`overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). Don't wrap unless ItemDescription expects to wrap too.
+- **Long Description**: typically 1-2 lines; truncate with `-webkit-line-clamp`.
+- **Multiple actions in ItemActions**: tightest is 2-3; if more, group into "More" menu.
+- **Toggle / Switch in row**: the whole row clickable also toggles? Decide; consistency matters.
+- **Selectable + interactive conflict**: can't have entire row as `<a>` AND `<button>` for select. Pattern: row is `<a>`, leading checkbox handles select.
+- **RTL**: Media and Actions positions flip.
+- **Reduced motion**: skip hover bg transition.
+
+## Don't
+
+- Don't pile up 4+ actions in ItemActions. Use overflow menu.
+- Don't make Title and Description the same weight / size — hierarchy matters.
+- Don't auto-truncate Description without showing user the rest is hidden (line-clamp + ellipsis OK; silent crop bad).
+- Don't put inputs (text fields) inside ItemActions. Use a different pattern (or Field row).
+- Don't omit `aria-label` on icon-only Action buttons.
+- Don't make rows shorter than 44pt on mobile primary surfaces.
+
+## References
+
+- shadcn-ui: [`item`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/item.tsx)
+- iOS UITableViewCell; Material 3 List item
+
+## Cross-reference
+
+- [`examples/component-transaction-list-item.md`](component-transaction-list-item.md) — KR fintech specialization
+- [`examples/component-card.md`](component-card.md) — for richer / card-style entities
+- [`examples/component-table.md`](component-table.md) — for tabular data
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md)

package/examples/component-kbd.md

@@ -0,0 +1,197 @@
+# `Kbd` — spec
+
+> Synthesized from shadcn-ui `kbd` and the HTML5 `<kbd>` element. Renders a keyboard shortcut as a small key cap. Used in tooltips, command palettes, dropdown menu shortcuts, documentation.
+
+## When to use
+
+- **Inline keyboard shortcut** in tooltips: "⌘ S to save".
+- **Command palette / dropdown menu shortcuts**: right-aligned shortcut hint.
+- **Documentation**: "Press ⌘ K to open the command palette".
+- **Help overlays**: keyboard shortcut cheatsheets.
+
+## Anatomy
+
+```
+[ ⌘ ] [ K ]    or    [ Ctrl ] [ K ]    or    [ ⇧ ] [ ⌘ ] [ P ]
+```
+
+A small bordered + shadowed key cap with the key label inside.
+
+## API
+
+```tsx
+<Kbd>⌘</Kbd> <Kbd>K</Kbd>
+
+<Kbd combo>
+  <Kbd.Key>⇧</Kbd.Key>
+  <Kbd.Key>⌘</Kbd.Key>
+  <Kbd.Key>P</Kbd.Key>
+</Kbd>
+
+<Kbd shortcut="cmd+k" />  {/* Helper that auto-renders cmd / ctrl based on platform */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `size` | `"sm" \| "md"` | `"sm"` | Size of the key cap |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style |
+| `shortcut` | `string` | — | Convenience: parses "cmd+k" → renders ⌘ K |
+| `children` | `ReactNode` | — | Manual content (one key or multiple `<Kbd.Key>`) |
+
+## Platform-aware shortcut parser
+
+```tsx
+function Kbd({ shortcut }: { shortcut?: string }) {
+  if (!shortcut) return /* manual */;
+
+  const isMac = /Mac/.test(navigator.platform);
+  const keys = shortcut.split("+").map(k => {
+    const lower = k.toLowerCase();
+    if (lower === "cmd" || lower === "meta") return isMac ? "⌘" : "Ctrl";
+    if (lower === "ctrl") return "Ctrl";
+    if (lower === "shift") return "⇧";
+    if (lower === "alt" || lower === "option") return isMac ? "⌥" : "Alt";
+    if (lower === "enter") return "↵";
+    if (lower === "esc") return "Esc";
+    if (lower === "tab") return "⇥";
+    if (lower === "space") return "␣";
+    if (lower === "backspace") return "⌫";
+    return k.toUpperCase();
+  });
+
+  return <kbd>{keys.map((k, i) => <span key={i}>{k}</span>)}</kbd>;
+}
+```
+
+## Symbols (Mac convention)
+
+| Key | Symbol |
+| --- | --- |
+| Cmd / Meta | ⌘ (U+2318) |
+| Shift | ⇧ (U+21E7) |
+| Option / Alt | ⌥ (U+2325) |
+| Control | ⌃ (U+2303) |
+| Enter / Return | ↵ (U+21B5) or ⏎ (U+23CE) |
+| Escape | Esc |
+| Tab | ⇥ (U+21E5) |
+| Space | ␣ (U+2423) |
+| Backspace | ⌫ (U+232B) |
+| Delete | ⌦ (U+2326) |
+| Up / Down / Left / Right | ↑ ↓ ← → |
+| Caps Lock | ⇪ (U+21EA) |
+| Function | Fn |
+
+For Windows / Linux: use text labels — "Ctrl", "Alt", "Shift", "Win".
+
+## States
+
+Stateless. `<kbd>` is presentational.
+
+## Tokens consumed
+
+```
+--kbd-bg               (key cap bg, slightly different from page bg)
+--kbd-fg               (text on key)
+--kbd-border           (key border)
+--kbd-shadow           (subtle inset shadow for "cap" effect)
+--radius-sm            (key corners)
+--font-family-mono     (typically monospace for the key label)
+--font-size-xs
+--space-xxs            (key padding)
+```
+
+## CSS
+
+```css
+kbd, .kbd {
+  display: inline-flex;
+  align-items: center;
+  padding: 1px 6px;
+  font-family: var(--font-family-mono);
+  font-size: var(--font-size-xs);
+  line-height: 1.4;
+  background: var(--kbd-bg);
+  color: var(--kbd-fg);
+  border: 1px solid var(--kbd-border);
+  border-radius: var(--radius-sm);
+  box-shadow: 0 1px 0 var(--kbd-border), 0 1px 0 inset rgba(255, 255, 255, 0.5);
+  min-width: 1.5em;
+  justify-content: center;
+}
+
+kbd + kbd {
+  margin-left: 2px;
+}
+```
+
+## Accessibility
+
+- Use the semantic `<kbd>` element. Screen readers announce as "keyboard input".
+- For complex shortcuts: wrap in a `<span>` with `aria-label` describing the shortcut, since reading individual symbols may be confusing.
+
+```html
+<span aria-label="Command K">
+  <kbd>⌘</kbd><kbd>K</kbd>
+</span>
+```
+
+- Don't rely on visual symbols alone for non-Mac users; provide text fallback.
+
+## Code example
+
+```tsx
+function ShortcutTooltip({ children, shortcut }: Props) {
+  return (
+    <Tooltip>
+      <Tooltip.Trigger asChild>{children}</Tooltip.Trigger>
+      <Tooltip.Content>
+        Save  <Kbd shortcut="cmd+s" />
+      </Tooltip.Content>
+    </Tooltip>
+  );
+}
+
+function CommandList() {
+  return (
+    <DropdownMenu>
+      <DropdownMenu.Trigger>Actions</DropdownMenu.Trigger>
+      <DropdownMenu.Content>
+        <DropdownMenu.Item>
+          New file <DropdownMenu.Shortcut><Kbd shortcut="cmd+n" /></DropdownMenu.Shortcut>
+        </DropdownMenu.Item>
+        <DropdownMenu.Item>
+          Open <DropdownMenu.Shortcut><Kbd shortcut="cmd+o" /></DropdownMenu.Shortcut>
+        </DropdownMenu.Item>
+      </DropdownMenu.Content>
+    </DropdownMenu>
+  );
+}
+```
+
+## Edge cases
+
+- **Korean keyboard mapping**: 한영 toggle uses dedicated key; can render as "한/영". Most app shortcuts use Latin characters even on Korean keyboards.
+- **Ctrl + Cmd ambiguity**: prefer one canonical name per platform. Don't say "Cmd / Ctrl" — render the platform-correct symbol.
+- **Mobile**: shortcut display rare on touch (no keyboard); hide or replace with alternative gesture description.
+- **Multi-key combos**: render each key in its own `<kbd>`; combine with small gap.
+- **Very long key labels** (e.g., "Backspace"): use the label not symbol in such cases.
+
+## Don't
+
+- Don't render shortcut as plain text. The boxed appearance is the affordance.
+- Don't use Mac symbols on Windows users (or vice-versa). Detect platform.
+- Don't make the cap so small the label is unreadable.
+- Don't put non-keyboard things in `<kbd>` (it's specifically for keys).
+
+## References
+
+- HTML5 `<kbd>` element
+- shadcn-ui: `kbd` component
+- Apple HIG: keyboard shortcut conventions
+
+## Cross-reference
+
+- [`examples/component-tooltip.md`](component-tooltip.md) — common consumer
+- [`examples/component-dropdown.md`](component-dropdown.md) — Shortcut sub-component
+- [`examples/component-command.md`](component-command.md) — heavy shortcut display
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)

package/examples/component-krw-amount.md

@@ -0,0 +1,219 @@
+# `KRWAmount` (custom — display-only currency formatter) — spec
+
+> Custom component pattern. Display-only counterpart to AmountInput. Renders KRW amounts consistently across the app — receipts, balances, transaction details, summaries.
+
+## Purpose
+
+Formats and displays a KRW amount with the right separator, suffix/prefix, sign, and color. Read-only. Use everywhere money is displayed but not entered.
+
+## Why a separate component (not just `formatKRW(...)`)
+
+A centralized component:
+- Consistent formatting across the entire app.
+- Single place to switch convention (suffix `원` vs prefix `₩`).
+- Tabular numerals applied consistently.
+- Color semantics consistent (money-positive / money-negative / neutral).
+- Smaller payload than AmountInput (no input wiring).
+
+## Anatomy
+
+```
+Default:                  Negative (expense):           Hero (large display):
+₩2,847,500                  -₩5,500                     ₩12,847,500
+                                                          ↑ 12,500원 이번 달
+
+Korean number format:    With sign explicit:           Foreign currency:
+1,200만원                 +₩2,500,000                 $25.00 (약 ₩33,300)
+```
+
+## API
+
+```tsx
+<KRWAmount value={2847500} />
+<KRWAmount value={-5500} type="expense" />
+<KRWAmount value={user.balance} variant="hero" delta={{ value: 12500, period: "이번 달" }} />
+<KRWAmount value={1200000} format="korean" />     // "1,200만원"
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `number` | — | Amount in won (smallest unit) |
+| `currency` | `"KRW"` (locked) | `"KRW"` | Reserved for future i18n |
+| `type` | `"income" \| "expense" \| "transfer" \| "neutral"` | inferred from sign | Drives color |
+| `variant` | `"default" \| "compact" \| "hero" \| "inline"` | `"default"` | Size + emphasis |
+| `format` | `"comma" \| "korean"` | `"comma"` | "1,200,000" vs "120만" |
+| `affixStyle` | `"prefix" \| "suffix"` | `"suffix"` | `1,200,000원` vs `₩1,200,000` |
+| `showSign` | `boolean` | `false` | Force `+` for positive |
+| `precision` | `number` | `0` | Decimals (always 0 for KRW) |
+| `delta` | `Delta` | — | Below-amount comparison |
+| `compactThreshold` | `number` | `10000` | When format=korean: only convert above this |
+
+## Variants
+
+### `default`
+
+Standard inline display. Body-size text, tabular numerals.
+
+```tsx
+<KRWAmount value={2847500} />
+```
+Renders: `₩2,847,500` or `2,847,500원` depending on convention.
+
+### `compact`
+
+Smaller text, for table cells / sidebars.
+
+```tsx
+<KRWAmount value={2847500} variant="compact" />
+```
+
+### `hero`
+
+Large display for hero amounts (account balance, total order):
+- Font: 32–48px
+- Weight: 700
+- Tabular numerals
+- Optional delta below
+
+```tsx
+<KRWAmount
+  value={user.balance}
+  variant="hero"
+  delta={{ value: 12500, period: "이번 달", goalDirection: "up" }}
+/>
+```
+
+Renders:
+```
+₩12,847,500
+↑ 12,500원 이번 달
+```
+
+### `inline`
+
+Minimal styling — fits inside a sentence:
+
+```tsx
+<p>총 결제 금액은 <KRWAmount value={45000} variant="inline" />입니다.</p>
+```
+
+## Format styles
+
+### `comma` (default)
+
+Standard thousands separator: `2,847,500원` or `₩2,847,500`.
+
+### `korean`
+
+Korean number names (만, 억) for compact display:
+- < 10,000 won: `123원`
+- 10,000–9,999,999 won: `1,234만원` (showing 만 as the unit)
+- ≥ 10,000,000 won: `1억 2,345만원`
+
+Use `korean` format for:
+- Real estate prices (massive amounts)
+- Investment account totals
+- Hero displays in casual consumer apps
+
+Don't use for transactional amounts (cart totals, transfers) — full digits required for accuracy.
+
+## Type / color mapping
+
+Per [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md):
+
+| `type` | Color | Sign default |
+| --- | --- | --- |
+| `expense` | `--color-money-negative` | `-` |
+| `income` | `--color-money-positive` | `+` (if `showSign`) |
+| `transfer` | `--color-money-neutral` | `-` or none |
+| `neutral` | `--color-text-primary` | none |
+
+Inferred from sign by default; override with `type` prop.
+
+## Tokens consumed
+
+```
+--color-text-primary
+--color-money-positive
+--color-money-negative
+--color-money-neutral
+--font-feature-amount: 'tnum' 1   (critical)
+--font-size-sm, --font-size-base, --font-size-2xl, --font-size-4xl
+--font-weight-semibold, --font-weight-bold
+```
+
+## Accessibility
+
+- Render as `<span>` with semantic-aware `aria-label`:
+  ```html
+  <span aria-label="290만 원">₩2,847,500</span>
+  ```
+- For type="expense": `aria-label="5,500원 지출"`.
+- For income: `aria-label="2,500,000원 수입"`.
+- Color is supplementary; don't encode meaning by color alone — sign + label do the work for screen readers.
+
+## Code examples
+
+```tsx
+// Transaction list cell
+<KRWAmount value={tx.amount} type={tx.type} variant="compact" />
+
+// Account balance hero
+<KRWAmount
+  value={account.balance}
+  variant="hero"
+  delta={{
+    value: account.monthlyChange,
+    period: "이번 달",
+    goalDirection: account.balanceType === "savings" ? "up" : undefined,
+  }}
+/>
+
+// Receipt total
+<KRWAmount value={order.total} variant="default" affixStyle="prefix" />
+
+// Inline in narrative
+<p>이번 달 지출: <KRWAmount value={monthlyExpense} type="expense" variant="inline" /></p>
+
+// Korean compact for property listing
+<KRWAmount value={propertyPrice} format="korean" variant="hero" />
+{/* Renders: 5억 2,000만원 */}
+
+// Foreign equivalent
+<div>
+  <span>$25.00</span>
+  <span className="text-text-secondary">
+    (약 <KRWAmount value={33300} variant="inline" />)
+  </span>
+</div>
+```
+
+## Edge cases
+
+- **Zero**: render as `0원` or `₩0` (not `-원`).
+- **Negative amount with `showSign`**: prefer `-₩5,500` not `₩-5,500`.
+- **Very large** (조 level): always full digits or with 조 unit. Don't crash.
+- **Floating-point error in input**: round to integer at the boundary (`Math.round(value)`).
+- **Currency conversion display**: pair with `KRWAmount` for the Korean half + native span for the foreign currency.
+
+## Don't
+
+- Don't show decimals for KRW. Round to integer at compute.
+- Don't omit tabular numerals. Tables with mixed widths look broken.
+- Don't auto-convert to `korean` format for transactional values — accuracy matters.
+- Don't forget signed-amount color logic — silently positive amounts colored as negative is a real bug.
+- Don't use `--color-error` for expense color. `money-negative` is its own axis.
+
+## API rationale
+
+- **`value` is a number, not a formatted string**: source of truth. KRWAmount is the single point of formatting.
+- **`type` separate from sign**: a positive transfer (e.g., +₩100,000 to your savings account) is "neutral", not "income".
+- **`format` opt-in for Korean compact**: full digits is the safer default; `korean` is the display option.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — full money-display rules
+- [`examples/component-amount-input.md`](component-amount-input.md) — editable counterpart
+- [`examples/component-statistic.md`](component-statistic.md) — for KPI hero amounts (alternative)
+- [`examples/component-transaction-list-item.md`](component-transaction-list-item.md) — uses KRWAmount internally
+- [`examples/component-account-card.md`](component-account-card.md) — uses KRWAmount internally