@design-ai/cli 4.55.0

package/examples/component-anchor.md

@@ -0,0 +1,198 @@
+# `Anchor` (scrollspy / TOC) — spec
+
+> Citing Ant Design `Anchor`, MUI (no built-in), shadcn-ui (no built-in)
+
+## Purpose
+
+A side-rail navigation that highlights the current section as the user scrolls through long-form content. Used for: documentation pages, terms of service, long articles, settings sections.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────┐
+│                                  ┌─────┐ │
+│  Section 1 heading               │ §1  │ │
+│  Body text...                    │ §2  │ │  ← TOC sidebar
+│                                  │ §3  │ │     (active highlighted)
+│  Section 2 heading               │ §4  │ │
+│  Body text...                    └─────┘ │
+│                                          │
+│  Section 3 heading (current)             │
+│  Body text...                            │
+└──────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Anchor list | yes | TOC items with hierarchy |
+| Active indicator | yes | Highlights the section the user is reading |
+| Click to scroll | yes | Clicking an item scrolls smoothly to its target |
+
+## API
+
+```tsx
+<Anchor
+  items={[
+    { key: "intro", title: "소개", href: "#intro" },
+    { key: "install", title: "설치", href: "#install" },
+    {
+      key: "usage",
+      title: "사용법",
+      href: "#usage",
+      children: [
+        { key: "basic", title: "기본 사용", href: "#basic" },
+        { key: "advanced", title: "고급 사용", href: "#advanced" },
+      ],
+    },
+  ]}
+  affix
+  offsetTop={64}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `AnchorItem[]` | — | TOC entries (hierarchical) |
+| `affix` | `boolean` | `true` | Stick to viewport on scroll |
+| `offsetTop` | `number` | `0` | Top offset when sticky (e.g., for header) |
+| `bounds` | `number` | `5` | Threshold for active detection |
+| `targetOffset` | `number` | — | Account for sticky header on click-scroll |
+| `onChange` | `(key: string) => void` | — | Active item changes |
+| `onClick` | `(e, item) => void` | — | |
+| `direction` | `"vertical" \| "horizontal"` | `"vertical"` | |
+
+```ts
+type AnchorItem = {
+  key: string;
+  title: string;
+  href: string;          // CSS selector (e.g., "#section-1") or full URL
+  children?: AnchorItem[];
+  target?: string;       // For external links
+};
+```
+
+## Behavior
+
+### Active section detection
+
+Uses `IntersectionObserver` (modern browsers) or scroll listener:
+- Watch each target section as user scrolls.
+- The "active" section is the one currently in viewport.
+- For overlapping sections: typically the one closest to top (or above the bounds threshold).
+
+### Click to scroll
+
+Clicking an anchor item scrolls smoothly to its target:
+
+```js
+const target = document.querySelector(item.href);
+target.scrollIntoView({ behavior: "smooth", block: "start" });
+```
+
+For sticky headers: subtract the header height from scroll position via `scroll-margin-top: <headerHeight>` on target elements.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default (inactive) | Light text |
+| Active | Bold + accent color + colored left-border indicator |
+| Hover | Slightly darker text |
+| Focus-visible | 2px ring around item |
+
+## Tokens consumed
+
+```
+--color-text-secondary      (inactive items)
+--color-text-primary         (active item)
+--color-primary-default      (active indicator border)
+--color-bg-default
+--color-focus-ring
+--space-xs, --space-sm
+--font-size-sm
+--motion-fast                 (scroll behavior)
+```
+
+## Sizes
+
+Typical width: 200–280px (desktop). Each item: ~32–40px height.
+
+For dense docs with many sections: 240px width, 28px row height.
+
+## Accessibility
+
+- Container: `<nav aria-label="목차">`.
+- TOC: `<ol>` with hierarchical nesting.
+- Each item: `<a href>` (links).
+- Current section: `aria-current="location"`.
+
+```html
+<nav aria-label="목차">
+  <ol>
+    <li><a href="#intro">소개</a></li>
+    <li><a href="#install" aria-current="location">설치</a></li>
+    <li>
+      <a href="#usage">사용법</a>
+      <ol>
+        <li><a href="#basic">기본 사용</a></li>
+      </ol>
+    </li>
+  </ol>
+</nav>
+```
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Move through items |
+| `Enter` | Activate (scroll to target) |
+
+## Mobile
+
+For mobile: typically hide Anchor (long-form on mobile uses different patterns — read top-to-bottom, no jumping). If shown:
+- Render as collapsible drawer ("목차") on the side.
+- Or: button at top "목차 보기" → opens dialog with TOC.
+
+## Don't
+
+- Don't show Anchor for content that's < 1 page tall.
+- Don't auto-scroll the active item out of view in the rail (use `scroll-behavior: smooth` to keep it visible).
+- Don't break browser back/forward — use URL hash sync.
+- Don't render Anchor without unique `id`s on target sections.
+
+## Code example
+
+```tsx
+function DocsPage({ headings }: Props) {
+  return (
+    <div className="grid grid-cols-[1fr_240px] gap-8">
+      <article>
+        {headings.map(h => (
+          <section key={h.id} id={h.id} style={{ scrollMarginTop: 80 }}>
+            <h2>{h.title}</h2>
+            {h.content}
+          </section>
+        ))}
+      </article>
+      <Anchor
+        affix
+        offsetTop={64}
+        targetOffset={80}
+        items={headings.map(h => ({ key: h.id, title: h.title, href: `#${h.id}` }))}
+      />
+    </div>
+  );
+}
+```
+
+## References
+
+- Ant Design: [`refs/ant-design/components/anchor/`](../refs/ant-design/components/anchor/) — `Anchor`, `Anchor.Link`. Solid implementation.
+- MUI / shadcn-ui: no built-in. Compose with `IntersectionObserver` + custom CSS.
+
+## Cross-reference
+
+- [`examples/component-affix.md`](component-affix.md) — sticky positioning (Anchor uses)
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md) — sticky section headers
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)

package/examples/component-app-bar.md

@@ -0,0 +1,249 @@
+# `AppBar` (Top app bar / header) — spec
+
+> Citing Ant Design (no dedicated — use Layout.Header), MUI `AppBar`, shadcn-ui (composition)
+
+## Purpose
+
+The persistent top bar of an app or page. Holds navigation context (back / menu), title, and primary actions (search, notifications, profile).
+
+Applicable on web (page header) and mobile (top app bar). Different in shape but same role.
+
+## When AppBar (full spec) vs alternatives
+
+This is the more detailed primitive that the [mobile-navigation knowledge](../knowledge/patterns/mobile-navigation.md) referenced. Refer to that for **when** to use; this spec covers the **how**.
+
+## Anatomy
+
+```
+Mobile (compact):
+┌──────────────────────────────────────────┐
+│ ←   화면 제목                  🔍  ⋮     │
+└──────────────────────────────────────────┘
+
+Desktop (wider):
+┌────────────────────────────────────────────────────────────────┐
+│ [logo]  Section nav                          🔍 [avatar] ⋮     │
+└────────────────────────────────────────────────────────────────┘
+
+With tabs:
+┌──────────────────────────────────────────┐
+│ ← Project Aurora                  ⋮      │
+├──────────────────────────────────────────┤
+│ Overview │ Tasks │ Files │ Settings      │  ← in-bar tabs
+└──────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Leading | yes | Back / menu / logo |
+| Title | yes | Page title (mobile) or section nav (desktop) |
+| Trailing actions | optional | 1–3 visible icons + overflow menu |
+| Tabs row | optional | Below the bar for sub-navigation |
+| Search overlay | optional | Replaces title with search input |
+
+## API
+
+```tsx
+<AppBar
+  leading={<BackButton onClick={goBack} />}
+  title="설정"
+  actions={[
+    { icon: <SearchIcon />, label: "검색", onClick: openSearch },
+    { icon: <BellIcon />, label: "알림", onClick: openNotifications, badge: unreadCount },
+    { type: "menu", items: [...] },
+  ]}
+  variant="standard"
+/>
+
+<AppBar
+  leading={<Logo />}
+  title={<NavLinks />}
+  actions={[<Avatar src={user.photoUrl} />]}
+  variant="standard"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `leading` | `ReactNode` | — | Left slot (back/menu/logo) |
+| `title` | `string \| ReactNode` | — | Center or left content |
+| `actions` | `Action[]` | `[]` | Right-aligned actions |
+| `tabs` | `ReactNode` | — | Bottom tabs row |
+| `variant` | `"standard" \| "large" \| "compact" \| "search"` | `"standard"` | |
+| `position` | `"static" \| "sticky" \| "fixed"` | `"sticky"` | |
+| `elevation` | `0 \| 1 \| 2` | `0` | Shadow on scroll |
+| `transparent` | `boolean` | `false` | When over hero image |
+
+## Variants
+
+### `standard` (default)
+
+Single row, 56px (mobile) / 64px (desktop) tall. Title centered (mobile) or left (desktop).
+
+### `large` (iOS-native large title)
+
+Two rows: standard top + large title below. Collapses to standard on scroll. iOS-coded.
+
+```
+┌──────────────────────────────────────────┐
+│ ←                          🔍  ⋮         │
+│                                           │
+│ Settings                                  │   ← large 28px title
+│                                           │
+└──────────────────────────────────────────┘
+```
+
+On scroll: collapses to standard with the title moving up.
+
+### `compact`
+
+40px tall — for desktop dense admin tools.
+
+### `search`
+
+Title slot replaced with a search input. Common on tap of a search icon.
+
+## Sizes
+
+| Variant | Mobile height | Desktop height |
+| --- | --- | --- |
+| `compact` | 48px | 40px |
+| `standard` (default) | 56px | 64px |
+| `large` | 56px + 56px expansion | (rare on desktop) |
+
+Plus `env(safe-area-inset-top)` on iOS.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting at top |
+| Scrolled | Optional shadow appears (`elevation > 0`) |
+| Search active | Title replaced with input, search icon → close |
+| Actions overflow | When > 2 actions on mobile, collapses to `⋮` menu |
+
+## Tokens consumed
+
+```
+--color-bg-default          (header surface)
+--color-bg-elevated         (when elevated)
+--color-text-primary        (title)
+--color-text-secondary      (subtitle)
+--color-border-default      (bottom border on scroll, alternative to shadow)
+--space-md, --space-base
+--shadow-card                (elevation when scrolled)
+--motion-fast                (collapse animation)
+--z-app-bar                  (above content, below modals)
+```
+
+## Mobile-specific
+
+- **Safe area**: top inset must be respected. `padding-top: env(safe-area-inset-top)`.
+- **Status bar coordination**: `<StatusBar barStyle="dark-content" />` on iOS to match light header.
+- **Back button**: 44×44 pt minimum hit area. Icon (chevron) + optional label ("← Settings").
+- **Title truncation**: 1 line max, truncate with `…`.
+- **System back gesture**: respect Android system back. Don't override.
+
+## Tabs in app bar
+
+When the bar has secondary tabs:
+
+```
+┌──────────────────────────────────────────┐
+│ ← Project Aurora                  ⋮      │
+├──────────────────────────────────────────┤
+│ Overview │ Tasks │ Files │ Settings      │
+└──────────────────────────────────────────┘
+```
+
+Tabs are sticky too — both header + tab row stick. See [`examples/component-tabs.md`](component-tabs.md).
+
+## Accessibility
+
+- Render as `<header>` with `role="banner"` (or omit role; banner is implicit on `<header>` not nested).
+- Title: `<h1>` for page-level header, `<h2>` for sub-page headers.
+- Action buttons: `aria-label` for icon-only; tooltips on hover (desktop).
+- Back button: `aria-label="뒤로"` or "Back".
+- Skip link: provide "본문으로 건너뛰기" / "Skip to main content" before app bar for keyboard users.
+
+### Keyboard
+
+- `Tab` reaches actions in order: leading → title (if interactive) → tabs → actions.
+- `Esc` in search-active: cancels search, returns to title view.
+
+## Korean considerations
+
+Standard back button label: `←` icon, no text (most common). Some apps add "이전" text.
+
+Page titles: 1-3 words typical ("설정", "알림 설정", "프로필").
+
+For chat/conversation headers: title shows the contact's name + online status:
+```
+← 김민지 ●           [📞] [...]
+   오전 11:23 활동
+```
+
+## Code example
+
+```tsx
+// Settings screen
+<AppBar
+  leading={<BackButton aria-label="뒤로" onClick={() => navigate(-1)} />}
+  title="설정"
+  position="sticky"
+/>
+
+// Conversation screen
+<AppBar
+  leading={<BackButton onClick={() => navigate("/chats")} />}
+  title={
+    <div className="flex items-center gap-2">
+      <Avatar src={contact.photoUrl} alt={contact.name} size="sm" status={contact.online ? "online" : "offline"} />
+      <span>{contact.name}</span>
+    </div>
+  }
+  actions={[
+    { icon: <PhoneIcon />, label: "통화", onClick: callContact },
+    { icon: <VideoIcon />, label: "영상통화", onClick: videoCall },
+    { type: "menu", items: chatMenuItems },
+  ]}
+/>
+
+// Desktop with section nav
+<AppBar
+  leading={<Logo />}
+  title={
+    <nav>
+      <NavLink to="/dashboard">대시보드</NavLink>
+      <NavLink to="/transactions">거래</NavLink>
+      <NavLink to="/cards">카드</NavLink>
+    </nav>
+  }
+  actions={[
+    { icon: <SearchIcon />, onClick: openSearch },
+    { icon: <BellIcon />, badge: 3, onClick: openNotifications },
+    <Avatar src={user.photoUrl} alt={user.name} />,
+  ]}
+/>
+```
+
+## Don't
+
+- Don't put primary CTAs in the app bar (those go in body).
+- Don't hide the back button on inner screens.
+- Don't show 4+ visible action icons on mobile — overflow to ⋮ menu.
+- Don't put long titles. 1 line max.
+- Don't omit safe-area-inset on iOS — content overlaps the notch.
+- Don't make the app bar transparent without ensuring text-on-content contrast.
+
+## References
+
+- Ant Design: no dedicated AppBar — use `Layout.Header` + custom composition.
+- MUI: [`refs/mui/packages/mui-material/src/AppBar/`](../refs/mui/packages/mui-material/src/AppBar/) — `AppBar` with `position`, `color`, `elevation`. Material-aligned.
+- shadcn-ui: no built-in. Compose with custom header structure.
+
+## Cross-reference
+
+- [`knowledge/patterns/mobile-navigation.md`](../knowledge/patterns/mobile-navigation.md) — when AppBar is used in nav patterns
+- [`examples/component-tabs.md`](component-tabs.md) — sub-tabs within AppBar
+- [`examples/component-affix.md`](component-affix.md) — sticky positioning

package/examples/component-aspect-ratio.md

@@ -0,0 +1,156 @@
+# `AspectRatio` — spec
+
+> Synthesized from shadcn-ui `aspect-ratio` (Radix). A wrapper that locks its child to a specific aspect ratio. The single-purpose primitive for hero images, video embeds, card thumbnails, and any case where you need predictable proportions before content loads.
+
+## Why this exists
+
+The CSS `aspect-ratio` property handles 90% of cases natively. AspectRatio component is useful when:
+- You need a consistent React API across the codebase.
+- Browser support for `aspect-ratio` is insufficient (rare in 2024+; Safari < 15).
+- You want to compose with other behavior (loading skeleton, fade-in).
+
+For new projects targeting modern browsers: just use `aspect-ratio: 16/9` in CSS. AspectRatio component is for cross-browser / design-system consistency.
+
+## API
+
+```tsx
+<AspectRatio ratio={16 / 9}>
+  <img src="/hero.jpg" alt="" className="w-full h-full object-cover" />
+</AspectRatio>
+
+<AspectRatio ratio={1}>
+  <Avatar src={url} />
+</AspectRatio>
+
+<AspectRatio ratio={4 / 5}>
+  <ProductImage src={product.image} />
+</AspectRatio>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `ratio` | `number` | `1` | Width / height ratio (16/9 = 1.77, 4/3 = 1.33, 1/1 = 1) |
+| `children` | `ReactNode` | — | Single child; positioned absolute to fill |
+| `className` | `string` | — | Pass-through |
+| `as` | `keyof JSX.IntrinsicElements` | `"div"` | Wrapper element |
+
+## Common ratios
+
+| Ratio | Use |
+| --- | --- |
+| `16/9` (1.77) | Video, hero images, widescreen |
+| `4/3` (1.33) | Photography, classic TV |
+| `1/1` (1.0) | Avatars, product thumbnails (Instagram-style) |
+| `4/5` (0.8) | Mobile portrait product |
+| `9/16` (0.56) | Vertical video (Reels / Shorts / TikTok) |
+| `3/2` (1.5) | DSLR photos |
+| `21/9` (2.33) | Ultrawide cinema |
+| `1/2` (0.5) | Tall hero / banner |
+
+## Implementation
+
+CSS:
+```css
+.aspect-ratio {
+  position: relative;
+  width: 100%;
+  aspect-ratio: var(--ratio);  /* modern browsers */
+}
+
+/* Fallback for browsers without aspect-ratio support */
+@supports not (aspect-ratio: 1) {
+  .aspect-ratio::before {
+    content: "";
+    display: block;
+    padding-bottom: calc(100% / var(--ratio));
+  }
+  .aspect-ratio > * {
+    position: absolute;
+    inset: 0;
+  }
+}
+```
+
+React:
+```tsx
+function AspectRatio({ ratio = 1, children, className, as: Tag = "div" }: Props) {
+  return (
+    <Tag
+      className={cn("aspect-ratio", className)}
+      style={{ "--ratio": ratio } as React.CSSProperties}
+    >
+      {children}
+    </Tag>
+  );
+}
+```
+
+## Tokens consumed
+
+```
+--radius-md          (when used in cards; outer corners rounded)
+```
+
+That's it. AspectRatio is layout-only; no theming.
+
+## States
+
+Stateless. The wrapper holds proportions; children control their own visuals.
+
+## Accessibility
+
+- AspectRatio is layout-only — no role, no semantics.
+- Make sure the children have appropriate alt text / aria labels.
+- `<img>` inside should always have `alt=""` (decorative) or descriptive `alt`.
+- For `<video>` inside: same captions / accessibility as standalone video.
+
+## Edge cases
+
+- **Multiple children**: only first child is positioned absolute. Wrap in a single container if multiple needed.
+- **Content overflows ratio**: hidden by default. To allow overflow, set `overflow: visible` on the wrapper.
+- **Loading state**: pair with skeleton — skeleton itself can be the AspectRatio child during load.
+- **Object-fit**: image / video child needs `object-fit: cover` (default for filling) or `contain` (letterbox).
+- **No children**: empty wrapper still maintains ratio.
+- **Print**: `aspect-ratio` works in print; ratio preserved.
+
+## Code example
+
+```tsx
+function ProductCard({ product }: Props) {
+  const [imageLoaded, setImageLoaded] = useState(false);
+
+  return (
+    <article className="product-card">
+      <AspectRatio ratio={4 / 5} className="rounded-md overflow-hidden">
+        {!imageLoaded && <Skeleton className="absolute inset-0" />}
+        <img
+          src={product.image}
+          alt={product.name}
+          onLoad={() => setImageLoaded(true)}
+          className="w-full h-full object-cover"
+        />
+      </AspectRatio>
+      <h3>{product.name}</h3>
+      <p className="price">{product.price.toLocaleString()}원</p>
+    </article>
+  );
+}
+```
+
+## Don't
+
+- Don't use AspectRatio when CSS `aspect-ratio` alone suffices.
+- Don't put complex layouts inside — it's a single-child wrapper.
+- Don't apply `aspect-ratio` AND fixed height to the same element. Pick one.
+- Don't forget `object-fit` on images inside.
+
+## References
+
+- shadcn-ui: [`aspect-ratio`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/aspect-ratio.tsx) (Radix)
+- CSS: `aspect-ratio` property (Baseline 2021)
+
+## Cross-reference
+
+- [`examples/component-image.md`](component-image.md) — image with built-in fallback
+- [`examples/component-video-hero.md`](component-video-hero.md) — uses aspect-ratio for video
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)