@design-ai/cli 4.55.0

package/examples/component-tag-badge.md

@@ -0,0 +1,309 @@
+# `Tag` + `Badge` — combined spec
+
+> Two sibling status indicators. Same family, distinct purposes — speccing together avoids duplicate decisions.
+>
+> Citing Ant Design `Tag` + `Badge`, MUI `Chip` + `Badge`, shadcn-ui `badge`
+
+## Semantic difference
+
+| Component | Use | Interactive? |
+| --- | --- | --- |
+| **Tag** | Inline label or pill — categorize content, attribute, filter | Often (closable, clickable) |
+| **Badge** | Small dot or count overlaid on another element (icon, avatar) | No (decorative status indicator) |
+
+Picking the wrong one is common. A "3 new messages" indicator on a notification icon = **Badge**. A "Premium" label inline with a username = **Tag**.
+
+## Tag
+
+### Anatomy
+
+```
+Static:        ┌──────────┐
+              │  Premium │
+              └──────────┘
+
+With icon:    ┌──────────────┐
+              │ ★ Featured   │
+              └──────────────┘
+
+Closable:     ┌──────────────┐
+              │ tag1      ✕  │
+              └──────────────┘
+
+Color tag:    ●━━━━━━━━━━●  Critical    [colored dot + text]
+```
+
+### API
+
+```tsx
+<Tag>Premium</Tag>
+<Tag color="success">Completed</Tag>
+<Tag closable onClose={() => removeTag(id)}>{tagText}</Tag>
+<Tag iconStart={<StarIcon />} variant="solid">Featured</Tag>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Tag label |
+| `variant` | `"subtle" \| "outlined" \| "solid"` | `"subtle"` | Visual emphasis |
+| `color` | `"default" \| "primary" \| "success" \| "warning" \| "error" \| "info"` or hex | `"default"` | Semantic color |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+| `closable` | `boolean` | `false` | Show ✕ |
+| `onClose` | `(e) => void` | — | |
+| `onClick` | `(e) => void` | — | If set, makes tag clickable (cursor + hover) |
+| `iconStart` / `iconEnd` | `ReactNode` | — | |
+| `disabled` | `boolean` | `false` | |
+
+### Sizes
+
+| Size | Height | Font | Padding-x |
+| --- | --- | --- | --- |
+| `sm` | 20px | 11px | 6px |
+| `md` (default) | 24px | 12px | 8px |
+| `lg` | 28px | 13px | 10px |
+
+### Variants
+
+| Variant | Subtle | Outlined | Solid |
+| --- | --- | --- | --- |
+| Background | `--color-<color>-subtle-bg` | transparent | `--color-<color>` |
+| Border | none | `1px --color-<color>` | none |
+| Text | `--color-text-primary` (or color-specific) | `--color-<color>` | `--color-on-<color>` |
+
+`subtle` is the default — least visually noisy. Use `outlined` for important categorization. Use `solid` for "Premium" / "Featured" / status that needs to dominate.
+
+### When to use Tag
+
+- Category labels: "디자인", "엔지니어링", "마케팅"
+- Status: "Active", "Archived", "Pending"
+- Filter chips (in a filter bar): "Color: Red ✕", "Size: M ✕"
+- Premium / status indicators: "Pro", "Enterprise"
+- Multi-select selected values inside a Combobox
+
+### When NOT to use Tag
+
+- For interactive primary actions — that's a Button.
+- For navigation — that's a Link or Breadcrumb item.
+- For a container — that's a Card or Box.
+
+## Badge
+
+### Anatomy
+
+```
+Dot indicator:               Count badge:                Standalone:
+
+   📨 ●                          📨 (3)                    [New]
+                              max 99+: 📨 (99+)
+
+Status dot on avatar:         New indicator on tab:
+   ● 김민지                     설정 ●
+```
+
+### API
+
+```tsx
+<Badge variant="dot" color="success" />               {/* dot only */}
+<Badge count={3}>{<NotificationIcon />}</Badge>        {/* count overlay */}
+<Badge count={142} max={99} showZero={false} />        {/* shows "99+" */}
+<Badge content="NEW" color="primary" />                {/* text content */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `count` | `number` | — | Numeric value to show |
+| `max` | `number` | `99` | Above this, show "max+" (e.g., "99+") |
+| `showZero` | `boolean` | `false` | Render even when count is 0 |
+| `content` | `ReactNode` | — | Text/element instead of count (e.g., "NEW") |
+| `variant` | `"dot" \| "count"` | inferred | Dot if no count/content; otherwise count |
+| `color` | `"primary" \| "success" \| "warning" \| "error" \| "info"` | `"error"` | |
+| `size` | `"sm" \| "md"` | `"md"` | |
+| `placement` | `"top-right" \| "top-left" \| "bottom-right" \| "bottom-left"` | `"top-right"` | When wrapping a child |
+| `offset` | `[number, number]` | `[0, 0]` | Fine-tune placement |
+| `children` | `ReactElement` | — | The element being badged |
+
+### Sizes
+
+| Size | Dot | Count badge height |
+| --- | --- | --- |
+| `sm` | 6px | 16px |
+| `md` (default) | 8px | 18px |
+
+The count badge wraps tightly around 1–2 digits. For 3-digit + show "99+".
+
+### Placement
+
+When `<Badge>` wraps a child element, it positions absolutely relative to the child:
+
+```
+┌──────────┐
+│   📨   ● │   ← top-right (default)
+└──────────┘
+```
+
+Use `offset` to fine-tune (badges often need -4px / -4px to overlap nicely).
+
+### When to use Badge
+
+- Notification count on icons (mail, bell)
+- Online status dot on avatars
+- "New" indicator on tabs / menu items
+- Cart count
+- Unread count on chat list items
+
+### When NOT to use Badge
+
+- Inline text labels — use Tag
+- Standalone status — use Tag
+- Long text (4+ chars) — use Tag
+
+## States
+
+### Tag states
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Hover (clickable) | Slight bg darken |
+| Focus-visible (clickable) | 2px ring |
+| Closing | Optional fade-out 100ms |
+| Disabled | 50% opacity |
+
+### Badge states
+
+| State | Visual |
+| --- | --- |
+| Default | Always visible (with count > 0 or dot) |
+| Animating in | 150ms scale 0.7 → 1 + opacity |
+| Hidden | When count = 0 and `!showZero`, badge unmounts |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-text-primary
+--color-text-secondary
+--color-on-primary, --color-on-success, etc.
+--color-primary-default, --color-primary-subtle-bg
+--color-success, --color-success-subtle-bg
+--color-warning, --color-warning-subtle-bg
+--color-error, --color-error-subtle-bg
+--color-info, --color-info-subtle-bg
+--color-border-default
+--color-focus-ring
+--space-xs, --space-sm
+--radius-md (Tag)
+--radius-full (Badge dot, Badge count)
+--font-size-xs, --font-size-sm
+--font-weight-medium
+--motion-fast
+```
+
+## Accessibility
+
+### Tag
+
+- If purely decorative (e.g., category label): regular `<span>`, no special role.
+- If clickable: `<button>` semantics.
+- If closable: the close button has its own `aria-label="<tag content> 제거"`.
+- Color is not the only signal — pair with text or icon. (e.g., "Critical" tag should have icon AND red color.)
+
+### Badge
+
+- For count badges: include screen-reader text. The visual count can be `aria-hidden`; the actual announcement should be richer.
+
+```html
+<button aria-label="알림, 새 알림 3개">
+  <BellIcon aria-hidden="true" />
+  <span class="badge" aria-hidden="true">3</span>
+</button>
+```
+
+- For dot indicators: `aria-label` on the parent describes the status.
+- Don't put critical info only in a badge — visually small, easily missed.
+
+## Code examples
+
+```tsx
+// Multi-select tags inside a Combobox
+<div className="tags-input">
+  {selectedTags.map(tag => (
+    <Tag key={tag} closable onClose={() => removeTag(tag)}>{tag}</Tag>
+  ))}
+  <input ... />
+</div>
+
+// Filter bar
+<div className="filter-bar">
+  Active filters:
+  {activeFilters.map(f => (
+    <Tag key={f.key} variant="outlined" closable onClose={() => clearFilter(f.key)}>
+      {f.label}: {f.value}
+    </Tag>
+  ))}
+</div>
+
+// Status tag in a list
+<TableCell>
+  {row.status === "active" && <Tag color="success">활성</Tag>}
+  {row.status === "pending" && <Tag color="warning">대기 중</Tag>}
+  {row.status === "archived" && <Tag color="default">보관됨</Tag>}
+</TableCell>
+
+// Notification count on bell icon
+<Badge count={notificationCount} max={99}>
+  <button aria-label={`알림 ${notificationCount}개`}>
+    <BellIcon />
+  </button>
+</Badge>
+
+// Online dot on avatar
+<Badge variant="dot" color="success" placement="bottom-right">
+  <Avatar src={user.photoUrl} alt={user.name} />
+</Badge>
+
+// "NEW" indicator on a menu item
+<MenuItem>
+  새 기능
+  <Badge content="NEW" color="primary" size="sm" />
+</MenuItem>
+```
+
+## Edge cases
+
+- **Tag with very long text**: cap with `max-width` + `text-overflow: ellipsis`. Provide `title` for full text.
+- **Badge count flickering** (count changes rapidly): debounce updates to avoid visual jitter.
+- **Badge over a clickable child**: badge should be `pointer-events: none` so clicks reach the child.
+- **Tag click + close button click**: stop propagation on close button so tag's onClick doesn't fire.
+- **Many tags wrapping**: use flex with gap, allow wrapping. Don't truncate the row of tags.
+- **Korean tag text**: typically short (1–4 syllables) — fits easily.
+
+## Don't
+
+- Don't use Tag for buttons.
+- Don't use Badge for decorative effect — meaning required.
+- Don't combine 4+ colors of tags in one row — picks one or two semantic colors.
+- Don't show "0" count badge unless `showZero` (visual noise).
+- Don't put images / videos in a Tag. Text + small icon only.
+- Don't use Badge as the only indicator for critical info.
+- Don't omit screen reader text for count badges.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/tag/`](../refs/ant-design/components/tag/) (Tag) + [`refs/ant-design/components/badge/`](../refs/ant-design/components/badge/) (Badge). Both well-developed; Tag has `Tag.CheckableTag` for filter-style.
+- MUI: `Chip` (closest to Tag) + `Badge`. MUI Chip has `clickable`, `deletable`, `avatar` slot — most flexible.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/badge.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/badge.tsx) — minimal Tag-equivalent. shadcn doesn't have a separate Tag/Badge distinction; user composes.
+
+API choices made:
+- **Tag and Badge as separate components**: matches Ant + MUI; clearer than a single "Pill" with a `mode` flag.
+- **Tag's `color` accepts hex** in addition to semantic names — for category-colored tags (e.g., a project color).
+- **Badge's `count` + `max`**: matches Ant convention. `99+` is the universal display.
+- **Combined spec**: shared visual language and tokens; avoids triplicate maintenance for nearly-identical pieces.
+
+## Cross-reference
+
+- [`examples/component-button.md`](component-button.md) — when interactive emphasis matters more than category
+- [`examples/component-avatar.md`](component-avatar.md) — Badge on Avatar pattern
+- [`examples/component-form-controls.md`](component-form-controls.md) — Tag in multi-select
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md) — color tags must clear AA

package/examples/component-tag.md

@@ -0,0 +1,102 @@
+# `Tag` — spec
+
+> Synthesized from Ant Design `Tag`. Closeable label / chip for filters, attributes, or selected items. See [`component-tag-badge.md`](component-tag-badge.md) for Tag + Badge comparison.
+
+## Tag vs Badge
+
+> Tag = removable / interactive. Badge = passive indicator.
+
+- Filter chips ("Marketing × Sales × ×"): Tag.
+- Notification count: Badge.
+- Selected items in multi-select: Tag.
+- Status indicator on a parent: Badge.
+
+## Anatomy
+
+```
+[ React ×]   [ TypeScript ×]   [ + Add tag ]
+   ↑ closeable
+```
+
+## API
+
+```tsx
+<Tag>React</Tag>
+<Tag closable onClose={() => removeTag("react")}>React</Tag>
+<Tag color="error">Failed</Tag>
+<Tag color="success">Active</Tag>
+<Tag icon={<CheckIcon />}>Verified</Tag>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `closable` | `boolean` | `false` | Show × button |
+| `onClose` | `() => void` | — | Close callback |
+| `color` | `"default" \| "brand" \| "success" \| "warning" \| "error" \| "info"` | `"default"` | Color preset |
+| `icon` | `ReactNode` | — | Leading icon |
+| `bordered` | `boolean` | `true` | Border style |
+| `size` | `"sm" \| "md"` | `"md"` | — |
+| `disabled` | `boolean` | `false` | — |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Filled / outlined per variant |
+| Hover (closable) | Subtle shift |
+| Close button hover | Distinct hover on × |
+| Disabled | Reduced opacity, no events |
+
+## Tokens consumed
+
+```
+--tag-bg-default / -brand / -success / -warning / -error / -info
+--tag-fg-default / ...
+--tag-border-default / ...
+--radius-sm                       (slightly less rounded than chips)
+--space-xxs                       (icon gap)
+--font-size-sm
+```
+
+## Accessibility
+
+- For removable: `<button aria-label="Remove {label}">×</button>` inside the tag.
+- For non-interactive: just `<span>`; no role needed.
+- If tags are filterable: wrap group in `<div role="group" aria-label="Active filters">`.
+
+## Code example — filter chips
+
+```tsx
+<div role="group" aria-label="활성 필터">
+  {filters.map(f => (
+    <Tag
+      key={f.id}
+      closable
+      onClose={() => removeFilter(f.id)}
+      color="brand"
+    >
+      {f.label}
+    </Tag>
+  ))}
+</div>
+```
+
+## Korean conventions
+
+- 태그 / 필터: 합쇼체 / 해요체 either; tag labels are usually nouns.
+- Status colors same as global conventions.
+
+## Don't
+
+- Don't use Tag for primary CTAs.
+- Don't pile up 20+ tags inline. Wrap or paginate.
+- Don't omit `aria-label` on close button.
+
+## References
+
+- Ant: [`Tag`](../refs/ant-design/components/tag)
+
+## Cross-reference
+
+- [`examples/component-tag-badge.md`](component-tag-badge.md) — combined spec
+- [`examples/component-badge.md`](component-badge.md) — passive indicator

package/examples/component-testimonial-carousel.md

@@ -0,0 +1,218 @@
+# `TestimonialCarousel` — spec
+
+> Marketing primitive. Rotates customer testimonials. Most-skipped section on landing pages — get it right or skip it entirely.
+
+## Purpose
+
+Display customer quotes / case studies / reviews. Used as social proof between feature display and pricing.
+
+## When TestimonialCarousel vs static testimonials
+
+| Pattern | Use |
+| --- | --- |
+| **Carousel** | Many testimonials (5+); horizontal screen real estate matters |
+| **Static 3-up grid** | 3 strong testimonials; landing page already short |
+| **No testimonials** | < 3 strong quotes, or audience won't care (developer tools rarely care about user testimonials) |
+
+If you can't find 3 strong testimonials, **don't fake it**. Skip the section.
+
+## Anatomy
+
+```
+┌────────────────────────────────────────────────────────────┐
+│ Section title (optional)                                    │
+│                                                              │
+│ ┌────────────────────────────────────────────────────────┐ │
+│ │ ★★★★★                                                   │ │
+│ │                                                          │ │
+│ │ "은행 앱을 30번씩 보지 않아도 되니 너무 편해요.            │ │
+│ │  처음엔 이게 정말 자동으로 분류될까 의심했는데              │ │
+│ │  3주 쓰니 90% 이상 맞춰주네요."                          │ │
+│ │                                                          │ │
+│ │ ┌──┐ 김민지 · 마케터                                      │ │
+│ │ └──┘ 사용 6개월                                           │ │
+│ └────────────────────────────────────────────────────────┘ │
+│                                                              │
+│ ●  ○  ○  ○  ○                                              │
+└────────────────────────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<TestimonialCarousel
+  title="실제 사용자 후기"
+  testimonials={[
+    {
+      quote: "은행 앱을 30번씩 보지 않아도 되니 너무 편해요.",
+      authorName: "김민지",
+      authorRole: "마케터",
+      authorPhotoUrl: "/users/minji.jpg",
+      authorBadge: "사용 6개월",
+      rating: 5,
+    },
+    // ...
+  ]}
+  variant="single-large"
+  autoplay={false}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | — | Section heading |
+| `testimonials` | `Testimonial[]` | — | Array of quotes |
+| `variant` | `"single-large" \| "3-up-grid" \| "auto-scroll"` | `"single-large"` | Display layout |
+| `autoplay` | `boolean` | `false` | (Default off — see deck-design rules) |
+| `autoplayInterval` | `number` | `8000` | ms |
+| `showNavigation` | `boolean` | `true` | Arrows + dots |
+| `showRating` | `boolean` | `true` | Stars per testimonial |
+
+```ts
+type Testimonial = {
+  quote: string;
+  authorName: string;
+  authorRole?: string;
+  authorPhotoUrl?: string;
+  authorBadge?: string;       // "사용 6개월", "Pro 회원"
+  rating?: 1 | 2 | 3 | 4 | 5;
+  source?: string;             // "App Store 리뷰" / "사용자 인터뷰"
+};
+```
+
+## Variants
+
+### `single-large` (default)
+
+One testimonial visible at a time, large. Carousel moves to next on click / swipe.
+
+```
+"Quote text — large, focal."
+— Author photo + name + role
+```
+
+Best for **hero quotes** that deserve full attention.
+
+### `3-up-grid` (no carousel)
+
+Three testimonials in a row. No rotation. Static.
+
+Better when you want all 3 testimonials seen without interaction.
+
+### `auto-scroll`
+
+Continuous horizontal scroll (right-to-left), slow speed (~30 px/sec). Mimics infinite-marquee. Used for "logo wall" feel — many short quotes scrolling past.
+
+Pause on hover. Respect `prefers-reduced-motion`.
+
+## Quote rules
+
+| Rule | Why |
+| --- | --- |
+| **Quote real customers**, with their permission. | Legal + trust. |
+| **Use full names** (or initials with permission). | "JS, Seoul" reads as fake. |
+| **Photos help** — match to name. | Real-people photos > stock photos. |
+| **Specific quote** beats generic. | "Saves 4 hours / week" > "Great product!" |
+| **Edit minimally** — typos OK to fix. | Don't reword to fit your marketing voice. |
+| **Date or duration** matters. | "Used for 6 months" > undated. |
+
+## Korean testimonial conventions
+
+- Author name: 한국 이름 + 직책. "김민지 · 마케터".
+- Photo: optional, but commonly included.
+- Voice: ~해요 (casual) is most common in consumer testimonials. Don't overly formalize.
+- "★★★★★ + 평점 4.8" — pair with overall rating if available.
+- Source: "App Store 리뷰", "사용자 인터뷰", "Twitter" — adds legitimacy.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | One quote visible (single-large) |
+| Auto-pause on hover | All variants |
+| Reduced motion | Auto-scroll → static; auto-play → off |
+| Loading | Skeleton matching quote shape |
+| No testimonials | Render nothing (don't show empty section) |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle          (alternate row in grid)
+--color-text-primary        (quote text)
+--color-text-secondary      (author name + role)
+--color-text-tertiary       (date, source)
+--color-warning             (star rating)
+--space-lg, --space-xl
+--radius-lg
+--font-size-lg, --font-size-xl  (quote text — larger than body)
+--font-weight-medium
+--motion-default
+```
+
+## Sizes
+
+| Element | Mobile | Desktop |
+| --- | --- | --- |
+| Quote font | 18px | 24–28px |
+| Author name | 14px | 16px |
+| Avatar | 40px | 48–56px |
+
+## Accessibility
+
+- Wrap in `<section>` with `<h2>` for section title.
+- Each testimonial: `<blockquote>` with `<cite>` for attribution.
+- Stars: `aria-label="평점 4점 / 5점"` (don't read each star separately).
+- Carousel arrows: `aria-label="다음" / "이전"`.
+- Auto-play: provide pause button (WCAG 2.2.2).
+- For dot indicators: `aria-label="2 / 5번째"`.
+
+## Code example
+
+```tsx
+<TestimonialCarousel
+  title="실제 사용자 후기"
+  testimonials={[
+    {
+      quote: "은행 앱을 30번씩 보지 않아도 되니 너무 편해요. 처음엔 이게 정말 자동으로 분류될까 의심했는데 3주 쓰니 90% 이상 맞춰주네요.",
+      authorName: "김민지",
+      authorRole: "마케터",
+      authorPhotoUrl: "/users/minji.jpg",
+      authorBadge: "사용 6개월",
+      rating: 5,
+      source: "App Store 리뷰",
+    },
+    {
+      quote: "월급 받는 날 자동으로 적금에 옮겨주는 자동이체 룰이 신기해요.",
+      authorName: "박지훈",
+      authorRole: "개발자",
+      authorPhotoUrl: "/users/jihoon.jpg",
+      authorBadge: "사용 1년",
+      rating: 5,
+    },
+    // ...
+  ]}
+  variant="single-large"
+/>
+```
+
+## Don't
+
+- Don't fabricate testimonials.
+- Don't auto-play without pause control (WCAG fail).
+- Don't use stock-photo "models" — readers spot it.
+- Don't put 5-paragraph quotes in a carousel — readers won't read.
+- Don't omit names — "Anonymous user" is suspicious.
+- Don't mix testimonial format (some with stars, some without) — pick one.
+
+## References
+
+No upstream component is exactly this. Each marketing builder (Webflow, Framer) has variants.
+
+## Cross-reference
+
+- [`examples/component-carousel.md`](component-carousel.md) — base Carousel pattern
+- [`examples/component-hero-block.md`](component-hero-block.md) — comes before
+- [`examples/component-feature-grid.md`](component-feature-grid.md) — comes between
+- [`examples/component-pricing-cards.md`](component-pricing-cards.md) — comes after
+- [`knowledge/patterns/landing-page-patterns.md`](../knowledge/patterns/landing-page-patterns.md)