@design-ai/cli 4.55.0

package/examples/component-chart.md

@@ -0,0 +1,237 @@
+# `Chart` — spec
+
+> Synthesized from shadcn-ui `chart` (Recharts wrapper). Themed chart container that handles theming, tooltips, legends, and accessibility for data visualization. Pairs with [`knowledge/patterns/chart-types.md`](../knowledge/patterns/chart-types.md) for chart-type selection.
+
+## When to use
+
+- **Dashboards** with consistent chart styling.
+- **Report / analytics** views.
+- **In-product data viz** (account balance over time, usage stats).
+
+When NOT to use:
+- Single-value display (use `Statistic`).
+- Tabular data (use `Table`).
+- Maps / geographic (use a dedicated map component).
+
+`Chart` is a **wrapper / theming layer**, not a chart engine. Underlying engine is Recharts (or D3 / VisX). The wrapper gives you brand-consistent tooltips, colors, legends, accessibility.
+
+## Anatomy
+
+```
+┌─────────────────────────────────────────┐
+│ Title                              [⋮]  │
+├─────────────────────────────────────────┤
+│  10K ┤                                  │
+│      │       ╱─────╲                    │
+│   5K ┤    ╱╱        ╲                    │
+│      │ ╱╱            ╲╱╲╲                │
+│      │                                  │
+│   0K └────────────────────────────       │
+│      Jan  Feb  Mar  Apr  May  Jun        │
+│                                         │
+│  ●  Revenue   ●  Cost                   │  ← legend
+└─────────────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<Chart
+  config={{
+    revenue: { label: "Revenue", color: "var(--chart-1)" },
+    cost:    { label: "Cost", color: "var(--chart-2)" },
+  }}
+  className="h-72"
+>
+  <LineChart data={data}>
+    <CartesianGrid />
+    <XAxis dataKey="month" />
+    <YAxis />
+    <ChartTooltip content={<ChartTooltipContent />} />
+    <ChartLegend content={<ChartLegendContent />} />
+    <Line dataKey="revenue" stroke="var(--color-revenue)" />
+    <Line dataKey="cost" stroke="var(--color-cost)" />
+  </LineChart>
+</Chart>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `config` | `{ [key: string]: { label, color } }` | required | Mapping of series key → label + color |
+| `children` | `Recharts component tree` | — | The chart definition |
+| `className` | `string` | — | Style override |
+
+The `config` becomes CSS variables (`--color-{key}`) on the wrapper, so child Recharts components reference them as `stroke="var(--color-revenue)"`. Theming flows from the wrapper.
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Chart` (Container) | Wrapper; injects theme + a11y |
+| `ChartTooltip` | Themed tooltip wrapper (Recharts Tooltip + custom content) |
+| `ChartTooltipContent` | Default tooltip content with brand styling |
+| `ChartLegend` | Themed legend wrapper |
+| `ChartLegendContent` | Default legend content |
+| `ChartStyle` | Auto-injects CSS variables from `config` |
+
+User wraps Recharts primitives (`LineChart`, `BarChart`, `Line`, `Bar`, `XAxis`, etc.) inside `Chart`.
+
+## Chart types (engine-agnostic)
+
+The wrapper supports any Recharts chart type. See [`knowledge/patterns/chart-types.md`](../knowledge/patterns/chart-types.md) for selection guidance.
+
+| Chart type | Use |
+| --- | --- |
+| Line | Trend over continuous (time, scale) |
+| Area | Trend with cumulative emphasis |
+| Bar | Discrete comparison |
+| Stacked bar | Composition over discrete |
+| Pie / donut | Part-of-whole (max 5 slices) |
+| Scatter | Correlation between two variables |
+| Radar | Multi-dimensional comparison |
+| Heatmap | Density across two dimensions |
+| Treemap | Hierarchy with size encoding |
+
+Each becomes a Recharts `<XYZChart>` inside `<Chart>`.
+
+## Korean stock convention (CRITICAL)
+
+Korean stock charts use **inverted color encoding**: red = up, blue = down (opposite of Western convention).
+
+```tsx
+<Chart config={{
+  rise: { label: "상승", color: "var(--color-stock-up)" },    // red in KR
+  fall: { label: "하락", color: "var(--color-stock-down)" },  // blue in KR
+}}>
+  ...
+</Chart>
+```
+
+Tokens cascade through theme. See [`knowledge/patterns/chart-color-encoding.md`](../knowledge/patterns/chart-color-encoding.md) and [`examples/component-stock-chart.md`](component-stock-chart.md) for KR-specific stock chart spec.
+
+For non-stock data viz: use Western convention (green=up, red=down).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Loading | Skeleton showing chart shape; Recharts won't render until data arrives |
+| Empty (no data) | Empty state message in chart area |
+| Hover (data point) | Tooltip with series + value |
+| Hover (series legend) | Other series dimmed, hovered series emphasized |
+| Active selection | Persistent selected point / range |
+
+## Tokens consumed
+
+```
+--chart-1  through  --chart-N         (series color palette; typically 8-12 distinct hues)
+--chart-grid                           (background gridlines)
+--chart-axis                           (axis labels, ticks)
+--chart-tooltip-bg                     (tooltip surface)
+--chart-tooltip-border
+--chart-tooltip-fg
+--chart-legend-fg
+--color-stock-up                       (Korean: red)
+--color-stock-down                     (Korean: blue)
+```
+
+shadcn names them `--chart-1` ... `--chart-5` (5 distinct series colors). For more series, extend with `--chart-6+` or use ordinal palette generation.
+
+## Accessibility
+
+- Chart container: `<figure>` with `<figcaption>` for the chart title.
+- `role="img"` + `aria-label` describing the chart's main takeaway ("Revenue rose 30% from Jan to Jun").
+- **Provide a data table alternative** for screen reader users: hidden `<table>` adjacent OR toggleable "View as table" button.
+- Legend items: focusable; activating legend toggles series visibility.
+- Tooltip: `aria-live="polite"` so changes announce on hover / focus.
+- High contrast mode: ensure series colors are distinguishable (don't rely on hue alone — use shape encoding for points or pattern for areas).
+
+```tsx
+<Chart config={config} aria-label="월별 매출 추이">
+  ...
+</Chart>
+<details>
+  <summary>표로 보기</summary>
+  <table>{/* same data as table */}</table>
+</details>
+```
+
+## Code example — Korean fintech dashboard
+
+```tsx
+function RevenueChart({ data }: Props) {
+  return (
+    <Card>
+      <CardHeader>
+        <CardTitle>월별 매출</CardTitle>
+        <CardDescription>2025년 6월부터 11월까지</CardDescription>
+      </CardHeader>
+      <CardContent>
+        <Chart
+          config={{
+            revenue: { label: "매출", color: "var(--chart-1)" },
+            cost:    { label: "비용", color: "var(--chart-2)" },
+            profit:  { label: "이익", color: "var(--chart-3)" },
+          }}
+          className="h-72"
+        >
+          <LineChart data={data}>
+            <CartesianGrid vertical={false} />
+            <XAxis
+              dataKey="month"
+              tickFormatter={(m) => `${m}월`}
+            />
+            <YAxis tickFormatter={(v) => `${(v / 1000).toFixed(0)}K원`} />
+            <ChartTooltip content={<ChartTooltipContent />} />
+            <ChartLegend content={<ChartLegendContent />} />
+            <Line dataKey="revenue" stroke="var(--color-revenue)" strokeWidth={2} />
+            <Line dataKey="cost" stroke="var(--color-cost)" strokeWidth={2} />
+            <Line dataKey="profit" stroke="var(--color-profit)" strokeWidth={2} />
+          </LineChart>
+        </Chart>
+      </CardContent>
+    </Card>
+  );
+}
+```
+
+## Edge cases
+
+- **Empty data**: render empty state inside chart area, not a broken axis.
+- **Single data point**: line / area charts can't render lines; consider Statistic + sparkline instead.
+- **Very long X-axis** (60+ ticks): rotate labels OR aggregate (week vs day).
+- **Mixed scale** (e.g., revenue in won, count in units): use dual axis (Recharts `<YAxis yAxisId="right">`).
+- **Color-blind users**: redundant encoding — series color + line style (solid / dashed / dotted) + point shape (circle / square / triangle).
+- **RTL**: Recharts handles axis direction via `reverse` prop.
+- **Reduced motion**: disable Recharts default animations (`isAnimationActive={false}`).
+- **Dark mode**: tokens cascade; verify chart bg, gridlines, tooltip remain visible.
+
+## Performance
+
+- For large datasets (10K+ points): consider downsampling or windowing.
+- Recharts uses SVG; very large charts may slow. Canvas-based engines (Visx, Plot) faster.
+- Avoid re-rendering the whole chart on every state change; memoize data transforms.
+
+## Don't
+
+- Don't use Western color convention for Korean stock charts. Red=up.
+- Don't use 5+ series in one line/bar chart — visual noise. Split or aggregate.
+- Don't omit data table alternative for screen reader users.
+- Don't rely on color alone for series differentiation.
+- Don't auto-animate every render — disorienting; use only on initial draw.
+- Don't put title inside the chart (use Card / heading above) — better legibility.
+- Don't crop axis to make small differences look big — misleading. Start at 0 unless explicitly justified.
+
+## References
+
+- shadcn-ui: [`chart`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/chart.tsx) (Recharts wrapper)
+- Recharts: <https://recharts.org/>
+- Edward Tufte's *The Visual Display of Quantitative Information* — chart design fundamentals
+
+## Cross-reference
+
+- [`examples/component-stock-chart.md`](component-stock-chart.md) — KR stock convention specifics
+- [`knowledge/patterns/chart-types.md`](../knowledge/patterns/chart-types.md) — chart-type selection
+- [`knowledge/patterns/chart-color-encoding.md`](../knowledge/patterns/chart-color-encoding.md) — color encoding
+- [`knowledge/patterns/dashboard-composition.md`](../knowledge/patterns/dashboard-composition.md) — dashboard layout
+- [`examples/component-statistic.md`](component-statistic.md) — single-value alternative

package/examples/component-chat-interface.md

@@ -0,0 +1,399 @@
+<!-- hand-written -->
+# `ChatInterface` (custom — generic chat UI for chatbot / AI / live agent) — spec
+
+> Reusable chat shell for chatbots, AI chat (LLM), and live customer support. Handles message rendering (markdown, code, attachments), streaming, suggested chips, typing indicators, and Korean conversational conventions. Pairs with [`knowledge/conversational/chatbot-design.md`](../knowledge/conversational/chatbot-design.md) and [`knowledge/conversational/ai-chat-interfaces.md`](../knowledge/conversational/ai-chat-interfaces.md).
+
+## Purpose
+
+Chat UIs are similar across products — chatbot, AI chat, live support — but differ in details. `ChatInterface` provides:
+1. **Message list** with virtualization for long histories.
+2. **Bot / user / agent** message styling.
+3. **Markdown rendering** (for AI / rich bot messages).
+4. **Streaming response** support.
+5. **Suggested chips** (quick replies).
+6. **Typing indicator**.
+7. **Attachment** support.
+8. **Korean voice conventions** baked in.
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│ [avatar] Brand Bot          [×]  │   ← header
+├──────────────────────────────────┤
+│                                  │
+│  [Bot bubble]                    │
+│  안녕하세요! 무엇을 도와드릴까요? │
+│  ▼                               │
+│  [상품 문의] [배송] [기타]         │   ← suggested chips
+│                                  │
+│                                  │
+│                User bubble [▶]   │
+│                  배송 언제 와요? │
+│                                  │
+│  [Bot typing...]                 │   ← typing indicator
+│                                  │
+├──────────────────────────────────┤
+│ [📎] [Type a message...]   [▶]   │   ← input
+└──────────────────────────────────┘
+```
+
+## API
+
+```tsx
+<ChatInterface
+  messages={messages}
+  onSend={handleSend}
+  agentName="Aera Bot"
+  agentAvatar="/avatar.png"
+  variant="ai"                  // "chatbot" | "ai" | "live-agent"
+  isTyping={isTyping}
+  isStreaming={isStreaming}
+  suggestions={suggestedChips}
+  onSuggestionClick={handleSuggestion}
+  attachments
+  voice                          // enable voice input
+  locale="ko-KR"
+  honorificLevel="해요체"         // "합쇼체" | "해요체"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `messages` | `Message[]` | `[]` | Conversation history |
+| `onSend` | `(text: string, attachments?: File[]) => void` | — | Send handler |
+| `agentName` | `string` | — | Display name (Bot / Agent name) |
+| `agentAvatar` | `string` | — | Avatar URL |
+| `variant` | `"chatbot" \| "ai" \| "live-agent"` | `"chatbot"` | Visual style preset |
+| `isTyping` | `boolean` | `false` | Show typing indicator |
+| `isStreaming` | `boolean` | `false` | Last message is streaming (cursor + stop button) |
+| `onStop` | `() => void` | — | Stop streaming |
+| `suggestions` | `Suggestion[]` | `[]` | Quick-reply chips |
+| `onSuggestionClick` | `(s) => void` | — | Chip handler |
+| `attachments` | `boolean` | `false` | Allow file / image attachment |
+| `voice` | `boolean` | `false` | Show voice input button |
+| `locale` | `string` | `"ko-KR"` | For date formatting + Korean rendering |
+| `honorificLevel` | `"합쇼체" \| "해요체"` | `"해요체"` | Affects placeholder text |
+| `inputPlaceholder` | `string` | locale default | Override input placeholder |
+| `maxLength` | `number` | `4000` | Input character limit |
+| `disabled` | `boolean` | `false` | Disable input (e.g., closed conversation) |
+
+```ts
+type Message = {
+  id: string;
+  role: "user" | "bot" | "agent" | "system";
+  content: string | RichContent;
+  timestamp: number;
+  attachments?: Attachment[];
+  status?: "sending" | "sent" | "failed" | "streaming";
+};
+
+type RichContent = {
+  text?: string;
+  markdown?: string;        // rendered with markdown
+  card?: CardData;          // structured card
+  carousel?: CardData[];    // multi-card carousel
+};
+
+type Suggestion = { id: string; label: string };
+```
+
+## Variants
+
+### `chatbot`
+
+Standard chatbot — friendly, branded, button-driven.
+- Bot avatar visible.
+- Suggested chips heavy.
+- Markdown light or off.
+- Typing indicator.
+
+### `ai`
+
+AI chat (LLM-based) — long-form, streamed, markdown-rich.
+- No bot avatar OR minimal.
+- Markdown / code blocks rendered.
+- Streaming with cursor.
+- Stop / regenerate / copy controls.
+- Sidebar history (separate component).
+
+### `live-agent`
+
+Live support — human on the other side.
+- Agent name + photo.
+- Read receipts.
+- Attachments common.
+- Typing indicator.
+- "Agent left the chat" state.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty (first time) | Greeting from bot + suggested chips |
+| Active conversation | Messages stacked; latest at bottom |
+| User typing | Input field active |
+| Bot processing | Typing indicator (dots animation) |
+| Streaming response | Last bot bubble grows; cursor at end; "Stop" button |
+| Send failed | "Failed to send. Retry" on user message |
+| Disabled | Input grayed out |
+| End of conversation | Banner: "Chat ended" |
+
+## Tokens consumed
+
+```
+--chat-bg                       (background)
+--chat-bubble-bot-bg            (bot bubble)
+--chat-bubble-bot-fg            (bot text)
+--chat-bubble-user-bg           (user bubble — typically brand color)
+--chat-bubble-user-fg           (user text)
+--chat-bubble-agent-bg          (live agent bubble)
+--chat-input-bg                 (input field)
+--chat-input-fg                 (input text)
+--chat-suggestion-bg            (chip bg)
+--chat-suggestion-bg-hover
+--chat-divider                  (separators)
+--chat-timestamp-fg             (small timestamps)
+--chat-typing-dot-color
+--space-xs, --space-sm, --space-md
+--radius-md, --radius-lg
+--font-size-base, --font-size-sm
+--motion-fast, --motion-medium
+--ease-out
+```
+
+## Message rendering
+
+### Plain text
+
+```tsx
+<MessageBubble role="bot">
+  <p>안녕하세요! 무엇을 도와드릴까요?</p>
+</MessageBubble>
+```
+
+### Markdown (AI variant)
+
+```tsx
+<MessageBubble role="bot">
+  <Markdown>
+    {`Here's how to fix it:
+
+1. First, install the package
+2. Then run \`npm start\`
+
+\`\`\`js
+const x = 5;
+\`\`\`
+    `}
+  </Markdown>
+</MessageBubble>
+```
+
+Renders headings, lists, bold, code blocks (syntax highlighted, copy button), links, tables.
+
+### Card
+
+```tsx
+<MessageBubble role="bot">
+  <ChatCard
+    image="/product.jpg"
+    title="Product Name"
+    subtitle="Description"
+    price="₩50,000"
+    actions={[
+      { label: "Buy", action: handleBuy },
+      { label: "Details", action: handleDetails },
+    ]}
+  />
+</MessageBubble>
+```
+
+### Carousel
+
+```tsx
+<MessageBubble role="bot">
+  <ChatCarousel cards={cards} />
+</MessageBubble>
+```
+
+Horizontal scroll on mobile; arrow buttons on desktop.
+
+### Streaming
+
+```tsx
+<MessageBubble role="bot" status="streaming">
+  <Markdown stream>
+    {streamingContent}
+  </Markdown>
+  <StreamCursor />
+</MessageBubble>
+```
+
+Renders incrementally. Append tokens to `streamingContent`.
+
+## Suggested chips
+
+```tsx
+<Suggestions>
+  {suggestions.map(s => (
+    <Suggestion key={s.id} onClick={() => onSuggestionClick(s)}>
+      {s.label}
+    </Suggestion>
+  ))}
+</Suggestions>
+```
+
+Rules:
+- 3-5 chips max.
+- Clear under last bot message.
+- Disappear after user sends a message (or shortly after).
+- Korean copy: short ("배송 문의" not "배송에 대해 문의하기").
+
+## Typing indicator
+
+```
+●○○  (dot animation)
+```
+
+Standard 3-dot loop:
+- 200ms per cycle.
+- Three dots fade in sequence.
+- Position: under bot avatar / left side.
+- Hide when message arrives.
+
+## Input
+
+```tsx
+<ChatInput
+  value={input}
+  onChange={setInput}
+  onSend={handleSend}
+  placeholder={inputPlaceholder ?? "메시지를 입력해 주세요..."}
+  attachments={attachments}
+  onAttach={handleAttach}
+  voice={voice}
+  onVoice={handleVoice}
+  maxLength={4000}
+  disabled={disabled}
+  multiline
+/>
+```
+
+Behavior:
+- Enter sends; Shift+Enter newline.
+- Auto-grow up to 5 lines, then scroll.
+- Char counter visible if > 80% of max.
+- Voice button replaces send when input empty (some patterns).
+
+For Korean IME: handle composition events properly. Don't send mid-composition (handle `compositionstart` / `compositionend`).
+
+## Attachments
+
+```tsx
+<AttachmentPreview
+  files={pendingAttachments}
+  onRemove={handleRemove}
+/>
+```
+
+Above input field, show pending attachments as chips with thumbnail. Remove via X button.
+
+Inside messages: render image inline; PDF / file as card with icon.
+
+## Accessibility
+
+- **Live region** for new messages: `<div role="log" aria-live="polite">`.
+- **Per-message labels**: `<article role="group" aria-labelledby="msg-id-author">`.
+- **Send button**: `aria-label="메시지 전송"`.
+- **Suggestion chips**: focusable, Enter to activate.
+- **Stop streaming button**: focusable, Esc shortcut.
+- **Read aloud option** for users who prefer voice (TTS button per message).
+- **Adjustable text size** via parent (chat respects body font scaling).
+- **Color contrast**: bot vs user bubbles meet WCAG AA against bg.
+
+## Implementation hints
+
+```tsx
+function ChatInterface({ messages, onSend, isTyping, isStreaming, ... }: Props) {
+  const listRef = useRef<HTMLDivElement>(null);
+
+  // Auto-scroll on new message
+  useEffect(() => {
+    if (!listRef.current) return;
+    listRef.current.scrollTop = listRef.current.scrollHeight;
+  }, [messages.length]);
+
+  return (
+    <div className="chat-interface" data-variant={variant}>
+      <ChatHeader name={agentName} avatar={agentAvatar} />
+      <div ref={listRef} className="chat-list" role="log" aria-live="polite">
+        {messages.map(m => (
+          <MessageBubble key={m.id} message={m} variant={variant} />
+        ))}
+        {isTyping && <TypingIndicator />}
+      </div>
+      {suggestions.length > 0 && (
+        <Suggestions suggestions={suggestions} onClick={onSuggestionClick} />
+      )}
+      <ChatInput
+        onSend={onSend}
+        placeholder={inputPlaceholder}
+        disabled={disabled || isStreaming}
+        // ...
+      />
+      {isStreaming && <StopButton onClick={onStop} />}
+    </div>
+  );
+}
+```
+
+## Korean conventions
+
+| Aspect | Default |
+| --- | --- |
+| Greeting | "안녕하세요! 무엇을 도와드릴까요?" |
+| User addressing | "고객님" or "[username]님" |
+| Honorific level | 해요체 default |
+| Input placeholder | "메시지를 입력해 주세요..." |
+| Send button label | "전송" or icon ▶ |
+| Attach button | "파일 첨부" |
+| Voice button | "음성으로 입력" |
+| Stop button | "중지" |
+| Typing indicator label | "[bot name]이(가) 입력 중..." |
+| Failed send | "전송 실패. 다시 시도하시겠어요?" |
+
+For Korean IME: don't trigger send on Enter while composition is active (Hangul composition mid-character). Listen to `compositionend` to allow send.
+
+## Edge cases
+
+- **Very long message history**: virtualize (react-window). Don't render 10,000 messages in DOM.
+- **Network failure mid-send**: optimistic UI; show "Failed" with retry on user bubble.
+- **Streaming canceled**: trim to last delivered token; show "stopped" indicator.
+- **Switching between bot ↔ human**: visual transition (banner: "Connecting to agent..." → agent name appears).
+- **Conversation timeout / agent left**: banner; input disabled with explanation.
+- **Multiple attachments**: show as chip row above input.
+- **Message reactions** (thumbs up/down on AI responses): inline icons.
+- **Edit message** (AI variant — edit user's prior message regenerates everything after): warning + confirm.
+- **Korean IME composition**: handle properly, don't double-send.
+- **RTL languages**: layout flips; bubbles align right for LTR / left for RTL.
+
+## Don't
+
+- Don't render raw markdown for AI variant. Render it.
+- Don't auto-scroll if user has scrolled up (let them read history).
+- Don't disable copy. Users want to copy AI responses.
+- Don't ignore Korean IME. Composition events matter.
+- Don't show typing indicator for > 30 seconds. Show error if backend stuck.
+- Don't lose user's draft on accidental close. Persist locally.
+- Don't render inline scripts in markdown. Sanitize.
+- Don't ship without keyboard shortcuts (desktop).
+
+## Cross-reference
+
+- [`knowledge/conversational/chatbot-design.md`](../knowledge/conversational/chatbot-design.md) — chatbot patterns
+- [`knowledge/conversational/ai-chat-interfaces.md`](../knowledge/conversational/ai-chat-interfaces.md) — AI chat
+- [`knowledge/conversational/conversational-ui-fundamentals.md`](../knowledge/conversational/conversational-ui-fundamentals.md) — fundamentals
+- [`knowledge/conversational/korean-voice-conventions.md`](../knowledge/conversational/korean-voice-conventions.md) — KR
+- [`examples/component-voice-input.md`](component-voice-input.md) — voice input
+- [`knowledge/i18n/korean-typography.md`](../knowledge/i18n/korean-typography.md) — Hangul + IME