@design-ai/cli 4.55.0

package/examples/component-textarea-autosize.md

@@ -0,0 +1,114 @@
+# `TextareaAutosize` — spec
+
+> Synthesized from MUI `TextareaAutosize`. A `<textarea>` that grows with its content. Sibling to `Textarea` (with optional `autoResize`); shipped as separate primitive in MUI for use without other Textarea behaviors.
+
+## When to use
+
+- Comment fields that should grow as user types.
+- Chat input that expands to multiple lines.
+- Form fields where content length varies wildly (description, bio).
+
+## API
+
+```tsx
+<TextareaAutosize
+  minRows={2}
+  maxRows={8}
+  placeholder="Type a message..."
+  value={message}
+  onChange={(e) => setMessage(e.target.value)}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `minRows` | `number` | `1` | Floor — height matches at least this many rows |
+| `maxRows` | `number` | — | Cap — past this, scroll inside |
+| `value` / `onChange` | controlled | — | Standard textarea props |
+| `placeholder` | `string` | — | — |
+
+## Implementation note
+
+CSS-only autoResize via field-sizing (modern):
+
+```css
+textarea {
+  field-sizing: content;
+  min-height: 2lh;
+  max-height: 8lh;
+}
+```
+
+`field-sizing: content` (CSS Working Draft, in Chrome / Safari / Firefox 2024+) handles this natively.
+
+For older browsers: JS measurement via hidden cloned textarea OR a ref + scrollHeight.
+
+```tsx
+const ref = useRef<HTMLTextAreaElement>(null);
+
+useEffect(() => {
+  if (!ref.current) return;
+  ref.current.style.height = "auto";
+  ref.current.style.height = `${ref.current.scrollHeight}px`;
+}, [value]);
+```
+
+## States
+
+Same as Textarea. Grows in addition to standard states.
+
+## Tokens consumed
+
+Same as `component-textarea.md`. Plus:
+
+```
+--textarea-line-height            (lh unit base)
+```
+
+## Accessibility
+
+- Same as Textarea — `<label>` linking, `aria-invalid`, IME handling.
+- Resize handle (browser-default) usually visible. For `field-sizing: content`, no manual handle.
+
+## Code example — chat input
+
+```tsx
+function ChatInput() {
+  const [message, setMessage] = useState("");
+
+  return (
+    <div className="chat-input">
+      <TextareaAutosize
+        minRows={1}
+        maxRows={5}
+        placeholder="메시지를 입력하세요..."
+        value={message}
+        onChange={(e) => setMessage(e.target.value)}
+        onKeyDown={(e) => {
+          if (e.key === "Enter" && !e.shiftKey && !e.nativeEvent.isComposing) {
+            e.preventDefault();
+            send();
+          }
+        }}
+      />
+      <Button onClick={send}>Send</Button>
+    </div>
+  );
+}
+```
+
+## Don't
+
+- Don't auto-grow beyond viewport. Always set `maxRows`.
+- Don't break Korean IME with Enter handler — check `isComposing` before submit.
+- Don't measure on every keystroke without debouncing.
+
+## References
+
+- MUI: [`TextareaAutosize`](../refs/mui/packages/mui-material/src/TextareaAutosize)
+- CSS `field-sizing` property (Working Draft)
+
+## Cross-reference
+
+- [`examples/component-textarea.md`](component-textarea.md)
+- [`examples/component-chat-interface.md`](component-chat-interface.md)

package/examples/component-textarea.md

@@ -0,0 +1,173 @@
+# `Textarea` — spec
+
+> Synthesized from shadcn-ui `textarea` and HTML5 `<textarea>`. Multi-line text input. Distinct from `Input` (single line) and rich text editors.
+
+## When to use
+
+- Multi-line text: comments, descriptions, messages, addresses.
+- Code / config snippets (use a code editor for syntax highlighting).
+- Long-form notes.
+
+## Anatomy
+
+```
+┌──────────────────────────────────┐
+│ Description                      │   ← Label (separate)
+└──────────────────────────────────┘
+┌──────────────────────────────────┐
+│                                  │
+│ Textarea content...              │
+│                                  │
+│                                  │
+└──────────────────────────────────┘
+   2-5 rows visible by default; scrolls or grows.
+```
+
+## API
+
+```tsx
+<Textarea
+  rows={4}
+  placeholder="Tell us about yourself..."
+  value={bio}
+  onChange={(e) => setBio(e.target.value)}
+  maxLength={500}
+/>
+
+<Textarea autoResize />   {/* MUI's textarea-autosize variant */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `rows` | `number` | `3` | Visible row count |
+| `maxRows` | `number` | — | Cap when autoResize=true |
+| `minRows` | `number` | `1` | Floor when autoResize=true |
+| `autoResize` | `boolean` | `false` | Grow with content (MUI textarea-autosize) |
+| `value` / `onChange` | controlled | — | Standard input props |
+| `placeholder` | `string` | — | — |
+| `maxLength` | `number` | — | Char limit + counter |
+| `disabled` / `readOnly` | `boolean` | — | — |
+| `resize` | `"none" \| "vertical" \| "horizontal" \| "both"` | `"vertical"` | CSS resize behavior |
+
+## Variants
+
+### Fixed rows
+
+```tsx
+<Textarea rows={3} />
+```
+
+Standard. User can resize (per `resize` prop) or scroll if content overflows.
+
+### Auto-resize (MUI textarea-autosize)
+
+```tsx
+<Textarea autoResize minRows={2} maxRows={8} />
+```
+
+Grows with content up to `maxRows`, then scrolls.
+
+### With character counter
+
+```tsx
+const [text, setText] = useState("");
+<Textarea
+  value={text}
+  onChange={(e) => setText(e.target.value)}
+  maxLength={500}
+/>
+<FieldDescription>{text.length} / 500</FieldDescription>
+```
+
+Show counter when approaching max (>80%).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Border + transparent bg |
+| Focused | Brand-color border ring |
+| Filled | Same as default with content |
+| Disabled | Reduced opacity, no events |
+| Read-only | No focus ring, muted bg |
+| Error | Red border |
+
+## Tokens consumed
+
+```
+--textarea-bg
+--textarea-fg
+--textarea-placeholder
+--textarea-border
+--textarea-border-focus           (brand)
+--textarea-border-error
+--textarea-resize-handle          (drag corner)
+--radius-md
+--space-sm                        (padding)
+--font-size-base
+--font-family-text                (or monospace for code)
+--motion-fast
+```
+
+## Accessibility
+
+- Always use `<label htmlFor>` linking. Or `aria-label` for inline.
+- `aria-invalid="true"` when error.
+- `aria-describedby` references help text + error.
+- For maxLength: `aria-label` should NOT include "(max 500)" — visible counter is enough.
+- Korean IME composition: don't fire onChange / submit during composition.
+
+## Korean IME
+
+```tsx
+const [composing, setComposing] = useState(false);
+
+<Textarea
+  value={text}
+  onChange={(e) => !composing && setText(e.target.value)}
+  onCompositionStart={() => setComposing(true)}
+  onCompositionEnd={(e) => {
+    setComposing(false);
+    setText(e.currentTarget.value);
+  }}
+/>
+```
+
+Critical for Hangul input — composition events span multiple keystrokes.
+
+## Code example
+
+```tsx
+<Field>
+  <Label htmlFor="bio">자기소개</Label>
+  <Textarea
+    id="bio"
+    rows={4}
+    maxLength={500}
+    placeholder="자기소개를 입력해 주세요"
+    {...register("bio")}
+  />
+  <FieldDescription>
+    {watch("bio")?.length ?? 0} / 500
+  </FieldDescription>
+</Field>
+```
+
+## Don't
+
+- Don't omit `<label>`.
+- Don't auto-grow beyond viewport. Cap with `maxRows`.
+- Don't use Textarea for rich-text needs (bold / italic / link). Use a real RTE.
+- Don't ignore Korean IME composition events.
+
+## References
+
+- HTML5 `<textarea>`
+- shadcn-ui: [`textarea`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/textarea.tsx)
+- MUI: TextareaAutosize
+
+## Cross-reference
+
+- [`examples/component-input.md`](component-input.md) — single-line variant
+- [`examples/component-textarea-autosize.md`](component-textarea-autosize.md) — autoResize specifics
+- [`examples/component-field.md`](component-field.md) — common wrapper

package/examples/component-time-picker.md

@@ -0,0 +1,205 @@
+# `TimePicker` — spec
+
+> Synthesized from Ant Design `TimePicker` and MUI `TimePicker`. A picker for hour / minute / second selection. Distinct from `DatePicker` (date only) and `DateTimePicker` (combined).
+
+## When to use
+
+- Schedule pickers (meeting time, alarm, reservation).
+- Time-only inputs (no date context).
+- Time range selection (start + end time).
+
+When NOT to use:
+- Date-only — use `DatePicker`.
+- Date + time combined — use `DateTimePicker`.
+- Duration (e.g., "30 minutes") — use a duration input (numeric stepper).
+
+## Anatomy
+
+```
+[ 14:30  ▾ ]                ← trigger field
+       ↓ open
+       ┌─────────────────────┐
+       │  10  ▲  20  ▲  00 ▲  │
+       │  11     21     45    │
+       │  12     22     50    │
+       │  13     23     55    │
+       │  14   ◀ 30   ◀ 00 ◀ │   ← currently selected
+       │  15     31     05    │
+       │  ...                 │
+       │                      │
+       │  [Now]    [Confirm]  │
+       └─────────────────────┘
+```
+
+## API
+
+```tsx
+<TimePicker
+  value={time}
+  onChange={setTime}
+  format="HH:mm"
+  use12Hours={false}
+  step={5}
+/>
+
+<TimeRangePicker
+  value={[start, end]}
+  onChange={([s, e]) => { setStart(s); setEnd(e); }}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Date \| Dayjs \| null` | controlled | Selected time |
+| `onChange` | `(time) => void` | — | Callback |
+| `format` | `string` | `"HH:mm:ss"` | Display format |
+| `use12Hours` | `boolean` | `false` | 12-hour with AM/PM |
+| `step` | `number` | `1` | Minute granularity (5, 10, 15, 30) |
+| `showSecond` | `boolean` | `true` | Include seconds picker |
+| `disabled` | `boolean` | `false` | — |
+| `disabledHours` | `() => number[]` | — | Hours unavailable |
+| `disabledMinutes` | `(hour) => number[]` | — | Minutes unavailable per hour |
+| `placeholder` | `string` | locale default | Placeholder |
+
+## Variants
+
+### Granularity
+
+| Step | Use |
+| --- | --- |
+| 1 | Precise scheduling |
+| 5 | Most consumer apps |
+| 15 | Calendar appointments |
+| 30 | Hourly time slots |
+
+Avoid step=2 / 3 — feels arbitrary.
+
+### 12 vs 24 hour
+
+| Format | Default region |
+| --- | --- |
+| 24-hour (HH:mm) | Korea, EU, military |
+| 12-hour (h:mm AM/PM) | US, casual contexts |
+
+Korean apps default to 24-hour. Some consumer apps offer toggle.
+
+### Range
+
+```tsx
+<TimeRangePicker value={[start, end]} onChange={...} />
+```
+
+For appointments, schedules. End must be after start (validate inline).
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Field shows placeholder or value |
+| Focus | Field highlighted; picker can open on click |
+| Open | Time grid overlay |
+| Selected | Highlighted hour / minute / second columns |
+| Disabled hour/min | Grayed in picker |
+| Error | Red border (validation) |
+
+## Tokens consumed
+
+```
+--time-picker-bg                   (panel)
+--time-picker-fg
+--time-picker-bg-hover
+--time-picker-bg-selected
+--time-picker-border
+--space-sm, --space-md
+--font-size-sm
+--motion-fast
+--z-overlay
+```
+
+## Accessibility
+
+- Trigger: `<input>` with `role="combobox" aria-haspopup="dialog"`.
+- Picker: `role="dialog"` (or `listbox`).
+- Each column (hours / minutes / seconds): `role="listbox"` with `<li role="option">` items.
+- Keyboard:
+  - Arrow Up/Down within column.
+  - Tab moves between columns.
+  - Enter confirms selection.
+  - Esc closes picker.
+- Touch: large tap targets (≥ 44pt) for each cell.
+- Format announcement: read selected time clearly ("오후 2시 30분" or "14시 30분").
+
+## Korean conventions
+
+- 24-hour default; some apps toggle 오전/오후 (AM/PM).
+- Format: "14:30" or "오후 2:30".
+- Speaker: "오후 두 시 삼십 분" (TTS).
+- Korean step convention: 30분 (half-hour) for appointments; 5분 / 10분 for finer-grained.
+
+```tsx
+<TimePicker
+  value={time}
+  onChange={setTime}
+  format="HH:mm"
+  step={5}
+  placeholder="시간 선택"
+  locale={koLocale}
+/>
+```
+
+## Code example — appointment booking
+
+```tsx
+function AppointmentBooking() {
+  const [date, setDate] = useState(null);
+  const [time, setTime] = useState(null);
+
+  // Disable past times today
+  const disabledHours = () => {
+    if (!isSameDay(date, today)) return [];
+    const now = new Date().getHours();
+    return Array.from({ length: now }, (_, i) => i);
+  };
+
+  return (
+    <Field>
+      <Label>예약 시간</Label>
+      <TimePicker
+        value={time}
+        onChange={setTime}
+        format="HH:mm"
+        step={30}
+        disabled={!date}
+        disabledHours={disabledHours}
+      />
+    </Field>
+  );
+}
+```
+
+## Edge cases
+
+- **DST transitions**: spring-forward / fall-back hours may have valid time pairs (1:30 AM happens twice on fall-back). Disambiguate via timezone.
+- **Different timezones**: clearly label which zone is being selected.
+- **Async-disabled times**: server checks "is this slot available?" — show loading + filter.
+- **End-time before start-time** (range picker): validate inline; show error before submit.
+- **Reduced motion**: skip column-scroll animation.
+- **RTL**: column order may flip (hours/min/sec right-to-left).
+
+## Don't
+
+- Don't use 24-hour AM/PM ("14:30 PM"). One or the other.
+- Don't use step=1 minute by default for casual schedulers — 30 picks per hour is overwhelming.
+- Don't omit "Now" button on time-of-day pickers.
+- Don't allow seconds for casual scheduling (most users don't care).
+
+## References
+
+- Ant: [`TimePicker`](../refs/ant-design/components/time-picker)
+- MUI: `TimePicker` (in @mui/x-date-pickers)
+- HTML5: `<input type="time">` (limited but accessible default)
+
+## Cross-reference
+
+- [`examples/component-date-picker.md`](component-date-picker.md)
+- [`examples/component-calendar.md`](component-calendar.md)

package/examples/component-timeline.md

@@ -0,0 +1,170 @@
+# `Timeline` — spec
+
+> Citing Ant Design `Timeline`, MUI (no built-in), shadcn-ui (composition)
+
+## Purpose
+
+A vertical (or horizontal) sequence of events. Used for: activity feeds, order tracking, history logs, project milestones, audit trails.
+
+## Anatomy
+
+```
+Vertical (default):
+●─── 2026.05.07 14:30 ────
+│    주문이 접수되었습니다
+│    주문번호 #1234
+│
+●─── 2026.05.07 15:00 ────
+│    결제가 완료되었습니다
+│    KakaoPay
+│
+○─── 2026.05.07 (예정) ────
+│    배송 준비 중
+│
+○─── 2026.05.10 (예정) ────
+     배송 완료 예정
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Indicator (per event) | yes | Dot, icon, or filled vs outline |
+| Connector line | yes | Vertical line connecting events |
+| Event title | yes | The event name |
+| Timestamp | yes | When |
+| Description | optional | Detail |
+| Custom content | optional | Image, link, button |
+
+## API
+
+```tsx
+<Timeline>
+  <Timeline.Item status="completed" timestamp="2026.05.07 14:30">
+    <h4>주문이 접수되었습니다</h4>
+    <p>주문번호 #1234</p>
+  </Timeline.Item>
+  <Timeline.Item status="completed" timestamp="2026.05.07 15:00">
+    <h4>결제가 완료되었습니다</h4>
+    <p>KakaoPay</p>
+  </Timeline.Item>
+  <Timeline.Item status="pending" timestamp="2026.05.07 (예정)">
+    <h4>배송 준비 중</h4>
+  </Timeline.Item>
+  <Timeline.Item status="pending" timestamp="2026.05.10 (예정)">
+    <h4>배송 완료 예정</h4>
+  </Timeline.Item>
+</Timeline>
+```
+
+| Prop (root) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `mode` | `"left" \| "right" \| "alternate"` | `"left"` | Indicator placement |
+| `orientation` | `"vertical" \| "horizontal"` | `"vertical"` | |
+| `compact` | `boolean` | `false` | Tighter spacing |
+
+| Prop (Item) | Type | Description |
+| --- | --- | --- |
+| `status` | `"pending" \| "completed" \| "active" \| "error"` | Drives indicator color |
+| `timestamp` | `string \| ReactNode` | When this happened |
+| `icon` | `ReactNode` | Custom indicator (overrides dot) |
+| `color` | `string` | Override indicator color |
+| `position` | `"left" \| "right"` | (alternate mode only) which side |
+
+## Variants
+
+### Modes
+
+| Mode | Indicator placement | Use |
+| --- | --- | --- |
+| `left` (default) | Left side, content right | Most common, KR convention |
+| `right` | Right side, content left | RTL contexts |
+| `alternate` | Alternates left/right | Marketing pages, "story" timelines |
+
+### Status → indicator
+
+| Status | Indicator |
+| --- | --- |
+| `completed` | Filled circle, primary color |
+| `active` (current) | Filled circle, larger or pulsing |
+| `pending` | Empty / outline circle |
+| `error` | Filled circle, error red, X icon |
+
+## States
+
+A timeline doesn't have hover/focus states unless individual items are interactive (links, drill-ins).
+
+## Tokens consumed
+
+```
+--color-primary-default      (completed indicator)
+--color-text-tertiary        (pending indicator + connector line)
+--color-error                 (error status)
+--color-text-primary
+--color-text-secondary        (timestamp)
+--space-md, --space-base
+--radius-full                  (indicator circle)
+```
+
+## Accessibility
+
+- Container: `<ol>` (ordered list — order matters in a timeline).
+- Each item: `<li>`.
+- Timestamps: `<time datetime="ISO-format">` for machine-readable.
+- Status: include in screen reader text — "Completed: 결제가 완료되었습니다".
+
+```html
+<ol>
+  <li>
+    <time datetime="2026-05-07T14:30:00+09:00">2026.05.07 14:30</time>
+    <span class="sr-only">완료됨: </span>
+    <h4>주문이 접수되었습니다</h4>
+  </li>
+  ...
+</ol>
+```
+
+## Use cases
+
+| Where | Pattern |
+| --- | --- |
+| Order tracking (e-commerce) | `left` mode, completed → pending sequence |
+| Activity feed (social, project) | `left`, all completed, scrollable |
+| Audit log | Compact mode, dense |
+| Marketing "story" page | `alternate` mode with images |
+| Project milestones | Horizontal, large indicators with dates |
+
+## Korean convention
+
+For order/transaction tracking (대표적인 한국 e-commerce / fintech):
+
+```
+● 주문 접수            2026.05.07 14:30
+● 결제 완료            2026.05.07 15:00
+● 상품 준비            2026.05.08 09:30
+○ 배송 시작            예정
+○ 배송 완료            예정
+```
+
+Status terms:
+- 완료 (completed)
+- 진행 중 (in progress)
+- 대기 (pending)
+- 실패 (failed)
+- 취소됨 (cancelled)
+
+## Don't
+
+- Don't use Timeline for non-sequential data. Use a list.
+- Don't omit timestamps. Timeline without "when" is just a list.
+- Don't use 50+ items. Paginate or virtualize. For activity feeds, use a scroll-load pattern.
+- Don't use horizontal Timeline on mobile (cramped).
+
+## References
+
+- Ant Design: [`refs/ant-design/components/timeline/`](../refs/ant-design/components/timeline/) — `Timeline` with modes, custom icons, color overrides.
+- MUI: `@mui/lab` `Timeline` (separate package) — alternate mode well-supported.
+- shadcn-ui: no built-in. Compose from primitives.
+
+## Cross-reference
+
+- [`examples/component-steps.md`](component-steps.md) — when sequence has discrete user actions
+- [`knowledge/patterns/list-and-feed.md`](../knowledge/patterns/list-and-feed.md) — activity feed patterns