@design-ai/cli 4.55.0

package/examples/component-hero-block.md

@@ -0,0 +1,252 @@
+# `HeroBlock` (landing hero) — spec
+
+> Marketing-page primitive. The first thing visitors see. Cite [`knowledge/patterns/landing-hero-design.md`](../knowledge/patterns/landing-hero-design.md) for variants and rationale.
+
+## Purpose
+
+The top of a landing page. Headline, supporting text, primary CTA, and supporting visual. The single most-iterated element on any product website.
+
+## Anatomy
+
+```
+Pattern A (text-led, image right):
+┌────────────────────────────────────────────────────────────┐
+│                                                              │
+│ Headline — what you do (40-60pt)                             │
+│                                                              │
+│ Sub-headline / problem-solution (16-20pt, ~25 words)         │
+│                                                              │
+│ [Primary CTA]    [Secondary CTA]                             │
+│                                                              │
+│ Trust signal (logos / "1,000+ 사용자")                       │
+│                                                              │
+└────────────────────────────────────────────────────────────┘
+                        ┌──────────────────────────────────┐
+                        │                                    │
+                        │    [Hero visual]                  │
+                        │    (product screenshot, photo,    │
+                        │    illustration)                   │
+                        │                                    │
+                        └──────────────────────────────────┘
+
+Pattern B (centered, image below):
+              Headline
+              Sub-headline
+            [Primary] [Secondary]
+              Trust signal
+            ┌────────────────┐
+            │  Hero visual   │
+            └────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Headline | yes | The thing you do, in user words |
+| Sub-headline | yes | One sentence that explains the headline |
+| Primary CTA | yes | One clear action |
+| Secondary CTA | optional | "Learn more" / "View demo" / "Login" |
+| Trust signal | optional | Customer logos, user count, awards |
+| Visual | optional | Image, video, illustration |
+
+## API
+
+```tsx
+<HeroBlock
+  headline="가계부, 자동으로 채워줘요"
+  subheadline="은행 30곳 자동 연동. 첫 달 무료. 카드 등록 불필요."
+  primaryCta={{ label: "무료 시작하기", onClick: signup }}
+  secondaryCta={{ label: "데모 보기", onClick: demo }}
+  trustSignal={{ type: "userCount", count: 1247000 }}
+  visual={<ProductScreenshot />}
+  layout="text-left"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `headline` | `string \| ReactNode` | — | Required. ≤ 12 words ideal. |
+| `subheadline` | `string \| ReactNode` | — | One sentence (~25 words). |
+| `primaryCta` | `CTA` | — | Required. |
+| `secondaryCta` | `CTA` | — | Optional. |
+| `trustSignal` | `TrustSignal` | — | Below CTAs |
+| `visual` | `ReactNode` | — | Image / video / illustration |
+| `layout` | `"text-left" \| "text-right" \| "centered" \| "split"` | `"text-left"` | |
+| `background` | `"default" \| "tinted" \| "image" \| "video"` | `"default"` | |
+| `backgroundImage` | `string` | — | When `background="image"` |
+| `videoSrc` | `string` | — | When `background="video"` |
+
+## Layout variants
+
+| Layout | Use |
+| --- | --- |
+| `text-left` (most common) | Reading order LTR; image-led visual on right |
+| `text-right` | RTL languages; or to vary template across landing pages |
+| `centered` | Highest-conversion for B2C consumer; minimal layout |
+| `split` | 50-50 image and text; demos product prominently |
+
+## Headline rules
+
+| Bad | Good |
+| --- | --- |
+| "Welcome to [Company Name]" | "가계부, 자동으로 채워줘요" |
+| "Revolutionary platform" | "은행 30곳 자동 연동" |
+| "Your finance, simplified" | "[concrete what]: [concrete how]" |
+
+The headline answers "what does this do?" in user words.
+
+For Korean: short, declarative. Verb-led when possible. ~합니다 too formal for marketing — use ~해요 OR colloquial-imperative.
+
+## Sub-headline rules
+
+| Pattern | Example |
+| --- | --- |
+| Problem + solution | "은행 앱을 30번씩 보지 않아도 가계부가 자동으로 채워집니다." |
+| Differentiation | "수동 입력 없이, 첫 달 무료로 시작." |
+| Social proof + result | "100만 명이 매달 평균 12만 원을 절약했어요." |
+
+## CTA rules
+
+- **Primary**: action-specific verb. "무료 시작" beats "시작하기". "지금 가입" beats "Sign up".
+- **Secondary**: lower-commitment. "데모 보기" / "기능 살펴보기" / "로그인".
+- **One primary**. Two competing primaries dilute.
+- **Contrast**: primary CTA must have brand color + ≥ 7:1 contrast.
+
+## Trust signals
+
+5 patterns:
+
+| Type | Example | When |
+| --- | --- | --- |
+| Customer logos | "Used by 토스, KakaoBank, ..." | B2B; logos must be permission-cleared |
+| User count | "100만 명이 사용 중" | Consumer; needs to be honest |
+| Awards | "App Store '오늘의 앱' 선정" | When awarded by reputable source |
+| Reviews | "★★★★★ 평점 4.8" | Consumer; show star count |
+| Press mentions | "TechCrunch에 소개됨" | Press mentions matter (rare to have) |
+
+Below the CTA, small (smaller than sub-headline). Don't lead with trust signal — lead with the value proposition.
+
+## Visual choices
+
+| Visual | Use |
+| --- | --- |
+| Product screenshot | Most B2C / B2B; shows what the product looks like |
+| Phone mockup | Mobile-first products |
+| Illustration | When product is abstract or service-based |
+| Photo (people using product) | Lifestyle products; risks looking generic |
+| Animated GIF / video loop | Demonstrates interaction |
+| Live interactive demo | Sophisticated; rare |
+
+For Korean fintech landing pages: phone mockup with product screenshot is dominant pattern (Toss / KakaoBank style).
+
+## Sizes / typography
+
+| Element | Desktop | Mobile |
+| --- | --- | --- |
+| Headline font | 48–60px | 32–40px |
+| Sub-headline | 18–22px | 16–18px |
+| CTA button height | 56px | 48px |
+| Hero visual width | ~50% column | full-width below |
+| Total hero height | 70–90% viewport | scrollable |
+
+## Background variants
+
+### `default`
+
+Solid `--color-bg-default` (white or near-white). Cleanest, fastest perceived load.
+
+### `tinted`
+
+Subtle brand-color background (`--color-primary-subtle-bg`). Adds brand personality without overwhelming.
+
+### `image`
+
+Full-bleed image with overlay scrim for text legibility (`linear-gradient(to right, rgba(0,0,0,0.6), transparent)` typical).
+
+### `video`
+
+Hero video (autoplay muted loop). Heavy bandwidth — use sparingly.
+- `prefers-reduced-motion`: still poster image instead.
+- File optimization: H.264 < 5MB, fallback poster always.
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-tinted              (when tinted)
+--color-text-primary           (headline)
+--color-text-secondary         (sub-headline)
+--color-primary-default        (primary CTA)
+--color-on-primary
+--space-lg, --space-xl, --space-2xl, --space-3xl
+--font-size-3xl, --font-size-4xl, --font-size-5xl  (headline)
+--font-size-lg, --font-size-xl                      (sub-headline)
+--font-weight-bold, --font-weight-medium
+--motion-default
+```
+
+## Accessibility
+
+- Render as `<section role="banner">` or `<header>` for the page.
+- Headline is `<h1>`.
+- Sub-headline is `<p>` (not `<h2>` — that's the next section).
+- Primary CTA is `<button>` or `<a href>` per action type.
+- Background video: `<video>` with `aria-hidden="true"` (decorative).
+- Alt text on hero image describes meaning, not "hero image".
+
+## Korean considerations
+
+- **Voice**: ~해요 (friendly, consumer) or ~합니다 (formal, B2B). Pick one.
+- **Headline style**: declarative or colloquial-imperative. "가계부, 자동으로!" / "30초 만에 가입".
+- **CTAs**: short. "무료 시작" / "지금 가입" / "체험하기" / "데모 보기".
+- **Trust signals**: Korean star pattern (`★★★★★`) + count. "1,247,000명이 사용 중".
+
+## Code example
+
+```tsx
+function LandingPage() {
+  return (
+    <main>
+      <HeroBlock
+        headline="가계부, 자동으로 채워줘요"
+        subheadline="은행 30곳 자동 연동. 첫 달 무료. 카드 등록 불필요."
+        primaryCta={{ label: "무료 시작", onClick: () => navigate("/signup") }}
+        secondaryCta={{ label: "데모 보기", onClick: () => navigate("/demo") }}
+        trustSignal={{
+          type: "userCount",
+          count: 1247000,
+          label: "명이 매달 평균 12만 원 절약 중",
+        }}
+        visual={<PhoneMockup screen="dashboard" />}
+        layout="text-left"
+        background="tinted"
+      />
+
+      <FeatureGrid />
+      <TestimonialCarousel />
+      <PricingCards />
+    </main>
+  );
+}
+```
+
+## Don't
+
+- Don't use marketing prose ("revolutionary", "synergy") in the headline.
+- Don't show 4+ buttons in the hero — clarity dies.
+- Don't autoplay videos with sound.
+- Don't ship a hero without `prefers-reduced-motion` handling for video / animations.
+- Don't put critical info only in the hero image.
+- Don't truncate the headline to fit the design — re-write the headline shorter.
+- Don't make the primary CTA visually weaker than the secondary.
+
+## References
+
+- No upstream component is exactly this. Each landing-page builder (Webflow, Framer, Astro Themes) ships their own variant.
+- Cite [`knowledge/patterns/landing-page-patterns.md`](../knowledge/patterns/landing-page-patterns.md) and [`knowledge/patterns/landing-hero-design.md`](../knowledge/patterns/landing-hero-design.md).
+
+## Cross-reference
+
+- [`knowledge/patterns/landing-hero-design.md`](../knowledge/patterns/landing-hero-design.md) — hero variants
+- [`knowledge/patterns/landing-page-patterns.md`](../knowledge/patterns/landing-page-patterns.md) — full landing structure
+- [`examples/component-button.md`](component-button.md) — CTA primitive
+- [`knowledge/patterns/brand-identity.md`](../knowledge/patterns/brand-identity.md) — voice in marketing

package/examples/component-hover-card.md

@@ -0,0 +1,211 @@
+# `HoverCard` — spec
+
+> Synthesized from shadcn-ui `hover-card` (Radix). Hover-triggered floating card showing rich preview content. Distinct from Tooltip (text only) and Popover (click-triggered).
+
+## When to use
+
+- **User profile preview** on @-mention hover.
+- **Link preview** before navigation.
+- **Glossary** — hover term, see definition.
+- **Card-style metadata** — hover an entity, see image + summary + actions.
+
+When NOT to use:
+- Mobile-primary contexts — hover doesn't exist on touch (long-press feels heavy).
+- Critical info — hover is supplemental; user must be able to access without it.
+- Quick text only — use Tooltip (lighter, faster).
+- User-initiated content — use Popover (click-triggered).
+
+## Anatomy
+
+```
+[hover trigger]
+        ↓
+        ┌──────────────────────┐
+        │ [avatar]             │
+        │ User Name            │
+        │ @username            │
+        │                      │
+        │ Joined 2024          │
+        │ Following 234        │
+        │                      │
+        │ [Follow]  [Message]  │
+        └──────────────────────┘
+```
+
+## API
+
+```tsx
+<HoverCard openDelay={400} closeDelay={300}>
+  <HoverCard.Trigger asChild>
+    <a href={`/users/${user.id}`}>@{user.username}</a>
+  </HoverCard.Trigger>
+  <HoverCard.Content>
+    <div className="hover-card-content">
+      <Avatar src={user.avatar} />
+      <h4>{user.name}</h4>
+      <p>@{user.username}</p>
+      <p>{user.bio}</p>
+      <div className="actions">
+        <button>Follow</button>
+        <button>Message</button>
+      </div>
+    </div>
+  </HoverCard.Content>
+</HoverCard>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `openDelay` | `number` | `700` | Ms hover before opening (don't trigger on glancing-pass) |
+| `closeDelay` | `number` | `300` | Ms after leave before closing (allows mouse to enter card) |
+| `defaultOpen` | `boolean` | `false` | Open initially (rare) |
+| `open` | `boolean` | controlled | Controlled state |
+| `onOpenChange` | `(open: boolean) => void` | — | State callback |
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Trigger` | Hover target |
+| `Content` | The floating card |
+| `Arrow` (optional) | Caret pointing at trigger |
+| `Portal` | Render outside parent (default behavior) |
+
+Free-form children inside Content — no enforced sub-parts (unlike DropdownMenu).
+
+## Open / close behavior
+
+```
+User hovers trigger
+  ↓ wait openDelay (700ms default)
+Card opens with fade + scale (200ms)
+User mouses out of trigger
+  ↓ wait closeDelay (300ms)
+  ↓ during delay, if mouse enters Card, cancel close
+Card closes if mouse hasn't entered Card
+User mouses out of Card
+  ↓ wait closeDelay
+Card closes
+```
+
+The closeDelay + Card-as-hover-target pattern is critical. Without it, users can't reach the card content.
+
+## Positioning
+
+Same as DropdownMenu:
+- Default: `bottom-start`.
+- `align`, `side` configurable.
+- Auto-flip on collision.
+- 8px collision padding.
+
+For inline triggers (within paragraphs of text): consider `align="start"` to anchor to the trigger's left edge.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Trigger visible; card hidden |
+| Hover (within openDelay) | Trigger styled (e.g., underline) but card still hidden |
+| Opening | Card fades + scales in (200ms) |
+| Open | Card visible |
+| Closing | Reverse (150ms) |
+
+No focus management — HoverCard is hover-only. For keyboard / focus equivalent, use Tooltip OR pair with a Popover triggered by focus.
+
+## Tokens consumed
+
+```
+--color-bg-overlay
+--color-fg-on-overlay
+--color-border-overlay
+--radius-md
+--shadow-overlay
+--space-md, --space-lg
+--font-size-sm, --font-size-base
+--motion-medium                (200ms open/close)
+--ease-out
+--z-overlay
+```
+
+## Accessibility
+
+- HoverCard is **decorative / supplemental**. The same content must be reachable elsewhere (linked profile page, accessible label, etc.).
+- Trigger remains a normal interactive element (link, button) — its activation must work without hover.
+- Don't put critical actions ONLY in the HoverCard. Buttons inside should also exist on the destination page.
+- For keyboard users: hovering doesn't fire on `focus` by default. If you need focus-equivalent, use `Popover` or add a dedicated keyboard shortcut.
+- For touch: hover doesn't exist; HoverCard is silently no-op on mobile. Don't ship critical info inside.
+- `aria-label` on Trigger should describe the destination, not "show preview" (hover is internal mechanic).
+
+## Mobile behavior
+
+By default, HoverCard does nothing on touch devices. Options:
+- **Tap once = preview, tap again = navigate** (pattern used by some social apps; confusing).
+- **Long-press = preview** (similar to ContextMenu; non-obvious).
+- **Don't show on mobile** — fall back to direct navigation.
+
+Default and recommended: **don't show on mobile**. Style the trigger so users see it's tappable, navigate them to a full page on tap.
+
+## Code example
+
+```tsx
+function MentionLink({ user }: { user: User }) {
+  return (
+    <HoverCard openDelay={500} closeDelay={300}>
+      <HoverCard.Trigger asChild>
+        <a href={`/users/${user.id}`} className="mention">
+          @{user.username}
+        </a>
+      </HoverCard.Trigger>
+      <HoverCard.Content className="mention-preview">
+        <div className="header">
+          <Avatar src={user.avatar} size="lg" />
+          <div>
+            <h4>{user.name}</h4>
+            <p className="username">@{user.username}</p>
+          </div>
+        </div>
+        <p className="bio">{user.bio}</p>
+        <dl className="stats">
+          <dt>Following</dt><dd>{user.following}</dd>
+          <dt>Followers</dt><dd>{user.followers}</dd>
+        </dl>
+        <div className="actions">
+          <FollowButton userId={user.id} />
+        </div>
+      </HoverCard.Content>
+    </HoverCard>
+  );
+}
+```
+
+## Edge cases
+
+- **Trigger inside scrollable container**: card may scroll out of view; `Portal` keeps it visible.
+- **Async content** (fetch user data on hover): show skeleton inside card while loading.
+- **Trigger removed during open**: card auto-closes.
+- **Multiple hover-cards in close proximity**: respect `openDelay` so glancing through doesn't open a chain.
+- **Card content larger than viewport**: cap height; scroll inside card OR truncate.
+- **Right-to-left**: positioning flips automatically.
+- **Reduced motion**: skip fade + scale; instant show / hide.
+
+## Don't
+
+- Don't put critical info or actions only inside HoverCard.
+- Don't trigger on click — that's Popover.
+- Don't trigger on focus — use Tooltip for that, or pair with Popover.
+- Don't make HoverCard the only way to view a profile — link the trigger to the full page.
+- Don't ship without `openDelay` — mouse-passing through triggers an avalanche of cards.
+- Don't disable on mobile silently without a fallback path.
+- Don't autofocus inside HoverCard — content is non-interactive aside from links.
+
+## References
+
+- shadcn-ui: [`hover-card`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/hover-card.tsx) (Radix)
+- Patterns: Twitter / X profile previews on @mention hover
+- Patterns: GitHub PR review preview on commit hash hover
+
+## Cross-reference
+
+- [`examples/component-tooltip.md`](component-tooltip.md) — text-only hover hint
+- [`examples/component-popover.md`](component-popover.md) — click-triggered floating content
+- [`examples/component-dropdown.md`](component-dropdown.md) — menu-style overlay

package/examples/component-icon-button.md

@@ -0,0 +1,142 @@
+# `IconButton` — spec
+
+> Synthesized from MUI `IconButton` and Material 3 icon button patterns. A button that contains only an icon. Distinct from `Button` (text+icon) and `Toggle` (persistent state).
+
+## When to use
+
+- Toolbar actions where space is tight (search, settings, more).
+- Card / item trailing actions.
+- Mobile primary action affordances.
+
+When NOT to use:
+- The icon's meaning isn't universally recognized — use text Button.
+- The action is the primary CTA — use Button with text.
+
+## Anatomy
+
+```
+[ ⚙ ]    [ × ]    [ ⋮ ]
+ settings close   more
+```
+
+A circular or rounded-square button with one icon centered. ≥ 44pt touch target on mobile (44x44 min); ≥ 32x32 desktop.
+
+## API
+
+```tsx
+<IconButton aria-label="설정" onClick={openSettings}>
+  <SettingsIcon />
+</IconButton>
+
+<IconButton variant="outline" size="sm" aria-label="닫기">
+  <CloseIcon />
+</IconButton>
+
+<IconButton variant="filled" color="destructive" aria-label="삭제">
+  <TrashIcon />
+</IconButton>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `aria-label` | `string` | required | Accessible label (icon-only buttons MUST have this) |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Touch target size |
+| `variant` | `"ghost" \| "outline" \| "filled" \| "tonal"` | `"ghost"` | Visual treatment |
+| `color` | `"default" \| "brand" \| "destructive"` | `"default"` | Color token |
+| `disabled` | `boolean` | `false` | — |
+| `loading` | `boolean` | `false` | Replaces icon with spinner |
+
+## Variants
+
+| Variant | Look |
+| --- | --- |
+| `ghost` (default) | No bg until hover; subtle |
+| `outline` | Border, no fill |
+| `filled` | Solid bg (brand or destructive) |
+| `tonal` | Soft tinted bg (Material 3 style) |
+
+## Sizes
+
+| Size | Touch target | Icon size |
+| --- | --- | --- |
+| `sm` | 32x32 | 16-18px |
+| `md` (default) | 40x40 | 20-24px |
+| `lg` | 48x48 | 24-28px |
+
+For mobile primary: ≥ 44pt minimum. Desktop secondary: 32px ok.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Per variant |
+| Hover | Subtle bg shift (ghost) or darker fill (filled) |
+| Focus-visible | Visible 2px ring around the button |
+| Active (press) | Deeper bg |
+| Disabled | Reduced opacity, no events, `aria-disabled` |
+| Loading | Spinner replaces icon; `aria-busy="true"` |
+
+## Tokens consumed
+
+```
+--icon-button-size-sm / -md / -lg
+--icon-button-bg-default
+--icon-button-bg-hover
+--icon-button-bg-pressed
+--icon-button-bg-filled              (filled variant)
+--icon-button-bg-destructive
+--icon-button-fg-default
+--icon-button-fg-on-filled
+--icon-button-border                 (outline variant)
+--radius-md                          (rounded-square) or --radius-full (circular)
+--motion-fast
+--ease-out
+```
+
+## Accessibility
+
+- **`aria-label` mandatory**. Icon-only buttons without label fail accessibility.
+- Focus-visible ring required.
+- Touch target ≥ 44pt mobile primary.
+- For Korean: `aria-label` in Korean ("설정", "닫기", "삭제") for KR audiences.
+
+## Code example
+
+```tsx
+function ToolbarActions() {
+  return (
+    <div className="toolbar">
+      <IconButton aria-label="이전">
+        <ChevronLeftIcon />
+      </IconButton>
+      <IconButton aria-label="다음">
+        <ChevronRightIcon />
+      </IconButton>
+      <IconButton aria-label="새로고침" loading={refreshing}>
+        <RefreshIcon />
+      </IconButton>
+      <IconButton aria-label="더보기">
+        <MoreIcon />
+      </IconButton>
+    </div>
+  );
+}
+```
+
+## Don't
+
+- Don't omit `aria-label`.
+- Don't make IconButton smaller than 32x32 on desktop, 44pt on mobile.
+- Don't use IconButton for primary CTAs. Use text Button.
+- Don't pair IconButton with Tooltip text on mobile (no hover) — `aria-label` is the spoken label.
+
+## References
+
+- MUI: [`IconButton`](../refs/mui/packages/mui-material/src/IconButton)
+- Material 3: Icon button variants
+
+## Cross-reference
+
+- [`examples/component-button.md`](component-button.md) — text+icon variant
+- [`examples/component-icon.md`](component-icon.md)
+- [`examples/component-tooltip.md`](component-tooltip.md) — pairs with IconButton on desktop