@design-ai/cli 4.55.0

package/examples/component-bottom-navigation.md

@@ -0,0 +1,226 @@
+# `BottomNavigation` — spec
+
+> Synthesized from MUI `BottomNavigation` and the iOS / Android tab bar pattern. Persistent tab bar at the bottom of mobile / responsive apps. The canonical mobile primary navigation.
+
+## When to use
+
+- **Mobile primary navigation** with 3-5 top-level destinations.
+- **Touch-thumb-friendly** placement (bottom = thumb-zone).
+- **Tab-style switching** between same-level views (Home / Search / Profile).
+
+When NOT to use:
+- Desktop primary navigation (use Sidebar or NavigationMenu).
+- Hierarchical navigation (BottomNav is flat — for hierarchy use Sidebar).
+- More than 5 destinations (overcrowds; group via "More" tab).
+
+## Anatomy
+
+```
+┌─────────────────────────────────────┐
+│                                     │
+│  [content area]                     │
+│                                     │
+│                                     │
+│                                     │
+│                                     │
+├─────────────────────────────────────┤
+│   [🏠]  [🔍]  [➕]  [🔔3]  [👤]      │  ← BottomNavigation
+│   Home  Search Add  Inbox Profile   │     (5 tabs max)
+└─────────────────────────────────────┘
+            ↑
+       active tab indicated
+```
+
+## API
+
+```tsx
+<BottomNavigation value={tab} onValueChange={setTab}>
+  <BottomNavigation.Item value="home">
+    <HomeIcon />
+    <span>Home</span>
+  </BottomNavigation.Item>
+  <BottomNavigation.Item value="search">
+    <SearchIcon />
+    <span>Search</span>
+  </BottomNavigation.Item>
+  <BottomNavigation.Item value="add" elevated>
+    <PlusIcon />
+  </BottomNavigation.Item>
+  <BottomNavigation.Item value="inbox" badgeCount={3}>
+    <InboxIcon />
+    <span>Inbox</span>
+  </BottomNavigation.Item>
+  <BottomNavigation.Item value="profile">
+    <UserIcon />
+    <span>Profile</span>
+  </BottomNavigation.Item>
+</BottomNavigation>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | controlled | Active tab value |
+| `onValueChange` | `(value: string) => void` | — | Tab switch callback |
+| `showLabels` | `"always" \| "selected" \| "never"` | `"always"` | When labels are visible |
+| `safeArea` | `boolean` | `true` | Add iOS home-indicator padding |
+| `elevation` | `0 \| 1 \| 2` | `1` | Shadow above the bar |
+
+## Item
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | required | Identifies the tab |
+| `icon` | `ReactNode` | from children | Icon |
+| `label` | `string` | from children | Label text |
+| `badgeCount` | `number` | — | Notification count overlay |
+| `badge` | `ReactNode` | — | Custom badge override |
+| `disabled` | `boolean` | `false` | Disabled |
+| `elevated` | `boolean` | `false` | Center "elevated" style (FAB-like, common for primary CTA) |
+
+## Variants
+
+### `showLabels="always"` (default)
+
+All labels visible always.
+
+### `showLabels="selected"`
+
+Only the active tab shows its label; others icon-only. iOS-classic style. Common in Apple's apps.
+
+### `showLabels="never"`
+
+Icon-only across the bar. Used in dense interfaces or when labels are obvious.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Icon + label, muted color |
+| Active (selected) | Icon + label, brand color, slightly larger or bold |
+| Hover (web) | Subtle bg shift |
+| Active press (touch) | Slight scale + bg shift |
+| Disabled | Reduced opacity, no events |
+| Badge | Dot or count overlay on icon |
+
+## Tokens consumed
+
+```
+--bottom-nav-bg                    (bar bg, often slightly elevated from page)
+--bottom-nav-fg-default            (inactive icon + label)
+--bottom-nav-fg-active             (active = brand color)
+--bottom-nav-divider               (top border separating from content)
+--bottom-nav-shadow                (subtle upward shadow)
+--bottom-nav-height                (typically 56-64px + safe area)
+--bottom-nav-icon-size             (24-28px)
+--bottom-nav-label-size            (10-12px)
+--space-xs, --space-sm
+--motion-fast                      (active state transition)
+--ease-out
+--z-fixed                          (above content, below modals)
+```
+
+## Accessibility
+
+- Wrapper: `<nav aria-label="Primary navigation">` (or contextual label).
+- Items: `<button>` if state-only, `<a>` if URL-routed.
+- Active: `aria-current="page"`.
+- Icon-only items: `aria-label` required.
+- Touch target: ≥ 44×44pt per item (mobile primary).
+- Focus visible on keyboard nav.
+- Respect safe-area: `padding-bottom: env(safe-area-inset-bottom)` for iPhone home indicator.
+
+## iOS / Android conventions
+
+| Aspect | iOS | Android |
+| --- | --- | --- |
+| Position | Bottom | Bottom |
+| Height | 49pt + safe area | 56dp |
+| Icon style | Outline (inactive) / filled (active) | Filled or outlined (Material 3) |
+| Label | Below icon | Below icon (M2) or hidden if active-only (M3) |
+| Active indicator | Color shift | Color shift + pill behind icon (M3) |
+| Center FAB | Common for primary action | "Floating" elevated button common |
+
+For native-feel design: respect platform expectations (iOS = sharper; Android M3 = soft pill behind active icon).
+
+## Korean app conventions
+
+Korean B2C apps (Toss, KakaoBank, Coupang, Baemin):
+- 4-5 tabs typical.
+- 한글 labels short (2-4 chars: 홈 / 검색 / 알림 / 마이페이지).
+- Center "Add" or primary action elevated (FAB-style) common in some apps.
+- Badge count for messages / orders prominent.
+
+```
+[🏠 홈] [🔍 검색] [➕] [🔔 알림] [👤 MY]
+```
+
+For 토스-style fintech: simple, brand-color active, no decorative effects.
+For 카카오-style consumer: warmer, mascot-friendly, often with subtle animations on tap.
+
+## Code example
+
+```tsx
+function MobileAppShell() {
+  const [tab, setTab] = useState("home");
+  const [unreadCount, setUnreadCount] = useState(0);
+
+  return (
+    <div className="app">
+      <main>{renderTab(tab)}</main>
+      <BottomNavigation value={tab} onValueChange={setTab}>
+        <BottomNavigation.Item value="home">
+          <HomeIcon />
+          <span>홈</span>
+        </BottomNavigation.Item>
+        <BottomNavigation.Item value="search">
+          <SearchIcon />
+          <span>검색</span>
+        </BottomNavigation.Item>
+        <BottomNavigation.Item value="inbox" badgeCount={unreadCount}>
+          <InboxIcon />
+          <span>알림</span>
+        </BottomNavigation.Item>
+        <BottomNavigation.Item value="profile">
+          <UserIcon />
+          <span>MY</span>
+        </BottomNavigation.Item>
+      </BottomNavigation>
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Page-aware bottom nav**: hide on certain screens (camera, full-screen video). Use `display: none` OR an in-shell variant.
+- **Keyboard open** (mobile virtual keyboard): bottom nav should hide so keyboard doesn't obscure it AND doesn't push the input field below the keyboard.
+- **Long Korean label** (보관함, 즐겨찾기): truncate with ellipsis OR drop label at small viewport.
+- **5+ tabs needed**: don't expand bar; group into "More" with a Sheet menu.
+- **Tab switches modify URL**: yes, always use real URLs so back-button works.
+- **Initial route mismatch**: parse current URL → set initial `value`.
+- **Reduced motion**: skip active-state animation.
+- **Landscape orientation on phone**: hide bottom nav (rare orientation; prioritize content).
+
+## Don't
+
+- Don't use BottomNav for hierarchy navigation. Tabs at the same conceptual level.
+- Don't put 6+ tabs. 3-5 max; group rest into More.
+- Don't omit `aria-label` on icon-only items.
+- Don't make BottomNav float (transparent bg over content) — bad for legibility.
+- Don't ignore safe-area on iOS — content cuts off behind home indicator.
+- Don't auto-hide on scroll without user research; users hunt for the bar.
+- Don't omit active state visual — users need orientation.
+
+## References
+
+- MUI: [`BottomNavigation`](../refs/mui/packages/mui-material/src/BottomNavigation)
+- iOS: UITabBar; Apple HIG → "Tab Bars"
+- Material 3: NavigationBar component
+- Patterns: Toss, KakaoBank, Instagram, Twitter
+
+## Cross-reference
+
+- [`examples/component-tabs.md`](component-tabs.md) — non-mobile-first tab variant
+- [`examples/component-app-bar.md`](component-app-bar.md) — top-of-screen counterpart
+- [`examples/component-sidebar.md`](component-sidebar.md) — desktop nav
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md)

package/examples/component-box.md

@@ -0,0 +1,112 @@
+# `Box` — spec
+
+> Synthesized from MUI `Box`. The most generic layout primitive — a styled `<div>` with theme-prop access. Lower-level than `Card`, `Paper`, or `Stack`.
+
+## When to use
+
+- As a generic styled container with token access.
+- For one-off custom layouts that don't fit other primitives.
+- As a system-prop sandbox (padding, margin, color, display) when you don't want to author CSS.
+
+When NOT to use:
+- For semantic containers (use `<section>`, `<article>`, `<aside>`).
+- For interactive surfaces (use `Button`, `Card`).
+- When a more specific primitive exists (`Stack`, `Grid`, `Paper`).
+
+## API
+
+```tsx
+<Box p={4} bg="surface" rounded="md">
+  Content
+</Box>
+
+<Box as="section" display="flex" gap={2}>
+  <Box>A</Box>
+  <Box>B</Box>
+</Box>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `as` | `keyof JSX.IntrinsicElements` | `"div"` | Render element |
+| `p` / `px` / `py` / `pt` / `pr` / `pb` / `pl` | spacing-token | — | Padding shorthand |
+| `m` / `mx` / `my` / `mt` / `mr` / `mb` / `ml` | spacing-token | — | Margin shorthand |
+| `bg` | color-token | — | Background color |
+| `color` | color-token | — | Text color |
+| `display` | CSS display | — | Display mode |
+| `gap` | spacing-token | — | Gap (when display=flex/grid) |
+| `rounded` | radius-token | — | Border radius |
+| `border` | `boolean \| number` | — | Border |
+| `shadow` | shadow-token | — | Box shadow |
+| `width` / `height` / `minWidth` / `maxWidth` | CSS length | — | Sizing |
+
+## States
+
+Stateless. Box is a layout primitive.
+
+## Tokens consumed
+
+```
+--space-{0..n}                     (p, m, gap)
+--color-{semantic}                 (bg, color)
+--radius-{sm,md,lg}                (rounded)
+--shadow-{sm,md,lg}                (shadow)
+--border-default                   (border)
+```
+
+## Variants vs other primitives
+
+```
+Box       → most generic; just a styled <div>
+Stack     → flex wrapper with auto direction + gap
+Grid      → grid wrapper
+Flex      → flex wrapper
+Paper     → elevated surface
+Card      → composition slots (Header / Body / Footer)
+```
+
+Use Box when none of the above fit. If you find yourself using Box with `display="flex" direction="column" gap={2}`, you actually want `Stack`.
+
+## Accessibility
+
+- Box is presentational by default. Use `as` to render semantic elements when appropriate.
+- For accessible regions: `as="section" aria-label="..."`.
+- For decorative dividers: prefer `Separator` over Box with `borderTop`.
+
+## Code example
+
+```tsx
+{/* Decorative brand-color callout */}
+<Box bg="brand-50" p={4} rounded="md" border>
+  <Text fontWeight={600}>이벤트 진행 중</Text>
+  <Text>가입 시 30% 할인.</Text>
+</Box>
+
+{/* Custom flex layout */}
+<Box display="flex" gap={2} alignItems="center">
+  <Avatar />
+  <Box flex={1}>
+    <Text>이름</Text>
+    <Text fontSize="sm" color="muted">설명</Text>
+  </Box>
+</Box>
+```
+
+## Don't
+
+- Don't use Box where a semantic element is appropriate. Use `as` or pick a different primitive.
+- Don't use Box for interactive surfaces. Use Button / Link.
+- Don't recreate layouts that other primitives handle. `<Box display="flex" direction="column">` = `<Stack>`.
+- Don't use raw hex / px values via the system props. Use tokens.
+
+## References
+
+- MUI: [`Box`](../refs/mui/packages/mui-material/src/Box) — system-prop pioneer
+- Chakra UI Box (very similar API)
+- shadcn-ui: doesn't ship Box; uses Tailwind classes directly
+
+## Cross-reference
+
+- [`examples/component-card.md`](component-card.md) — when Box gets too generic
+- [`examples/component-paper.md`](component-paper.md) — elevated surface variant
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)

package/examples/component-breadcrumb.md

@@ -0,0 +1,222 @@
+# `Breadcrumb` — spec
+
+> Citing Ant Design `Breadcrumb`, MUI `Breadcrumbs`, shadcn-ui `breadcrumb`
+
+## Purpose
+
+Shows the user's location in a hierarchy. Each segment is a navigable ancestor, except the last (current page).
+
+## When NOT to use
+
+- Single-level apps (no hierarchy to show).
+- Mobile-first apps where the back button is the primary nav metaphor (Korean consumer apps especially — breadcrumb is rare on KR mobile).
+- Linear flows (use a stepper / progress, not breadcrumbs).
+
+Breadcrumbs are a **desktop / web-app** pattern. Use sparingly on mobile.
+
+## Anatomy
+
+```
+Home  /  Projects  /  Aurora  /  Settings
+ ↑       ↑              ↑           ↑
+ link    link           link        current (not a link, bold)
+```
+
+Or with more visual breathing room:
+
+```
+🏠 Home  ›  📁 Projects  ›  Aurora  ›  Settings
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Crumb (link) | yes (≥ 1) | Each ancestor — clickable |
+| Separator | yes | `/`, `›`, `→`, or chevron icon |
+| Current crumb | yes | Last item — not a link, marked with `aria-current="page"` |
+| Icon (per crumb) | optional | Home icon, folder icon for context |
+| Truncation indicator | optional | `…` when path is long |
+
+## API
+
+```tsx
+<Breadcrumb>
+  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+  <Breadcrumb.Item href="/projects">Projects</Breadcrumb.Item>
+  <Breadcrumb.Item href="/projects/aurora">Aurora</Breadcrumb.Item>
+  <Breadcrumb.Item current>Settings</Breadcrumb.Item>
+</Breadcrumb>
+```
+
+Or imperative:
+
+```tsx
+<Breadcrumb
+  items={[
+    { label: "Home", href: "/" },
+    { label: "Projects", href: "/projects" },
+    { label: "Aurora", href: "/projects/aurora" },
+    { label: "Settings", current: true },
+  ]}
+  separator="/"
+  maxItems={6}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `BreadcrumbItem[]` | — | (Imperative API) |
+| `separator` | `string \| ReactNode` | `"/"` | Between items |
+| `maxItems` | `number` | `8` | When exceeded, collapse middle items into `…` |
+| `itemsBeforeCollapse` | `number` | `1` | How many items to show at the start when collapsed |
+| `itemsAfterCollapse` | `number` | `1` | How many at the end |
+
+```tsx
+type BreadcrumbItem = {
+  label: string | ReactNode;
+  href?: string;
+  icon?: ReactNode;
+  onClick?: () => void;
+  current?: boolean;
+};
+```
+
+## Truncation behavior
+
+When `items.length > maxItems`:
+
+```
+Home / ... / Aurora / Settings
+```
+
+Click on `…` to expand (popover with the hidden items) or just hover to peek.
+
+For very long path with smaller `maxItems`:
+- Show first 1, ellipsis, last 2 by default.
+- `itemsBeforeCollapse=1, itemsAfterCollapse=2` for typical web app.
+
+## Sizes
+
+| Size | Font | Spacing between |
+| --- | --- | --- |
+| `sm` | 12px | 4px |
+| `md` (default) | 13–14px | 8px |
+| `lg` | 16px | 12px |
+
+Default to `md` for desktop, `sm` for dense admin tools.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default link | `--color-text-secondary`, no underline |
+| Hover | `--color-text-primary`, underline |
+| Focus-visible | 2px ring around the link |
+| Current (last item) | `--color-text-primary`, **bold** weight |
+| Disabled | Grayed out, no events (rare) |
+
+The current item is **never** a link. It's where the user is.
+
+## Tokens consumed
+
+```
+--color-text-primary
+--color-text-secondary
+--color-text-tertiary           (separator)
+--space-xs, --space-sm
+--font-size-sm, --font-size-base
+--font-weight-medium             (current item bold)
+--color-focus-ring
+```
+
+## Accessibility
+
+- Wrap in `<nav aria-label="Breadcrumb">`.
+- Render as `<ol>` (ordered list — semantically correct because the order matters).
+- Each item is `<li>`.
+- Each link is `<a>` (or router-Link). The current item is just text — **not a disabled link**.
+- Current item: `aria-current="page"`.
+- Don't put separators in the same `<a>` as the link text — separators should be `aria-hidden="true"` on the parent `<li>` or on a separate visual element.
+
+```html
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/">Home</a></li>
+    <li aria-hidden="true">/</li>
+    <li><a href="/projects">Projects</a></li>
+    <li aria-hidden="true">/</li>
+    <li aria-current="page">Settings</li>
+  </ol>
+</nav>
+```
+
+### Keyboard
+
+- `Tab` reaches each link in order.
+- `Enter` activates link.
+- Separators are not focusable.
+
+## Code example
+
+```tsx
+// Basic
+<Breadcrumb>
+  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+  <Breadcrumb.Item href="/products">Products</Breadcrumb.Item>
+  <Breadcrumb.Item current>Wireless Mouse</Breadcrumb.Item>
+</Breadcrumb>
+
+// With router (Next.js / React Router)
+<Breadcrumb>
+  <Breadcrumb.Item asChild><Link href="/">Home</Link></Breadcrumb.Item>
+  <Breadcrumb.Item asChild><Link href="/products">Products</Link></Breadcrumb.Item>
+  <Breadcrumb.Item current>Wireless Mouse</Breadcrumb.Item>
+</Breadcrumb>
+
+// With icons
+<Breadcrumb>
+  <Breadcrumb.Item href="/" icon={<HomeIcon />}>Home</Breadcrumb.Item>
+  <Breadcrumb.Item href="/projects" icon={<FolderIcon />}>Projects</Breadcrumb.Item>
+  <Breadcrumb.Item current>Aurora</Breadcrumb.Item>
+</Breadcrumb>
+
+// Truncation
+<Breadcrumb maxItems={4} itemsBeforeCollapse={1} itemsAfterCollapse={2}>
+  <Breadcrumb.Item href="/">Home</Breadcrumb.Item>
+  <Breadcrumb.Item href="/level1">Level 1</Breadcrumb.Item>
+  <Breadcrumb.Item href="/level1/level2">Level 2</Breadcrumb.Item>
+  <Breadcrumb.Item href="/level1/level2/level3">Level 3</Breadcrumb.Item>
+  <Breadcrumb.Item href="/level1/level2/level3/level4">Level 4</Breadcrumb.Item>
+  <Breadcrumb.Item current>Current</Breadcrumb.Item>
+</Breadcrumb>
+{/* Renders: Home / ... / Level 4 / Current */}
+```
+
+## Edge cases
+
+- **Long path that wraps to two lines**: don't wrap by default; truncate via `maxItems`. If wrapping is needed, it's a sign the hierarchy is too deep.
+- **Crumb labels longer than 30 chars**: truncate individual labels with `…`, full text in `title`.
+- **Dynamically loaded labels** (URL has IDs, real names load async): show ID or "Loading..." in the meantime; replace with real name. Don't shift width drastically.
+- **Mobile**: can collapse to "← Back" link on narrow screens, or hide entirely.
+- **RTL**: separator direction flips (`›` becomes `‹`). Use a directional character or two icons.
+- **Korean labels**: Korean breadcrumbs work cleanly. Common: "홈 / 프로젝트 / Aurora / 설정".
+- **No URL** (current page is not addressable): only the last item shows; previous crumbs may or may not be present.
+
+## Don't
+
+- Don't make the current page a link to itself. It's a no-op + bad a11y.
+- Don't use breadcrumbs as the only navigation. They supplement, not replace, sidebars/menus.
+- Don't show breadcrumbs on top-level pages (no hierarchy).
+- Don't include "more menus" in breadcrumb dropdowns. Keep them flat — collapsed-items popover is the only complex pattern.
+- Don't put filters or actions in breadcrumbs.
+- Don't use breadcrumbs for chronological steps (signup step 2 of 4) — that's a stepper.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/breadcrumb/`](../refs/ant-design/components/breadcrumb/) — `Breadcrumb` + `Breadcrumb.Item` + `Breadcrumb.Separator`. `itemRender` for custom rendering.
+- MUI: [`refs/mui/packages/mui-material/src/Breadcrumbs/`](../refs/mui/packages/mui-material/src/Breadcrumbs/) — `Breadcrumbs` (note plural) with `separator`, `maxItems`, `itemsBeforeCollapse`, `itemsAfterCollapse`. Built-in collapse logic.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/breadcrumb.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/breadcrumb.tsx) — primitive: `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`. Most flexible.
+
+## Cross-reference
+
+- [knowledge/patterns/mobile-navigation.md](../knowledge/patterns/mobile-navigation.md) — mobile prefers back button over breadcrumb
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md)