@design-ai/cli 4.55.0

package/examples/component-select.md

@@ -0,0 +1,258 @@
+# `Select` / `Combobox` — spec
+
+> Citing Ant Design `Select`, MUI `Autocomplete`, shadcn-ui `select` + `combobox`
+
+## Purpose
+
+Lets the user pick one (or multiple) from a list of options. Two distinct patterns:
+
+| Pattern | When |
+| --- | --- |
+| **Select** (`<select>`-style) | Closed list of ≤ 20 options, no typing needed. Country, currency, status. |
+| **Combobox** (typeahead / autocomplete) | Long lists (50+), async loading, allow free-text + suggestions. User search. |
+
+This spec covers both as variants of one component, since modern systems (Radix, Headless UI) treat them as the same primitive with `searchable: true|false`.
+
+## Anatomy
+
+```
+Trigger:                          Popover (when open):
+┌──────────────────────┐         ┌──────────────────────┐
+│ Selected value    ▾  │         │ ▣ Type to search...  │  ← optional search input
+└──────────────────────┘         ├──────────────────────┤
+                                  │ ✓ Option 1           │  ← active
+                                  │   Option 2           │
+                                  │   Option 3 (group)   │
+                                  │   ───────────        │
+                                  │   Option 4           │
+                                  │ + Create "new tag"   │  ← optional creatable
+                                  └──────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Trigger | yes | Looks like an Input with chevron |
+| Search input | combobox only | Inside popover for long lists |
+| Option list | yes | Scrollable if > ~10 visible |
+| Option item | yes | Can have icon, description, badge |
+| Group header | optional | `<optgroup>`-style grouping |
+| Create option | optional (creatable mode) | Adds new value not in list |
+| Empty state | yes | "검색 결과가 없습니다" |
+| Footer | optional | "Apply" button for multi-select, links to elsewhere |
+
+## API
+
+```tsx
+<Select
+  value={country}
+  onValueChange={setCountry}
+  options={[
+    { value: "kr", label: "대한민국", flag: "🇰🇷" },
+    { value: "jp", label: "日本",      flag: "🇯🇵" },
+    { value: "us", label: "United States", flag: "🇺🇸" },
+  ]}
+  placeholder="국가를 선택하세요"
+  searchable
+  clearable
+/>
+
+<MultiSelect
+  values={tags}
+  onValuesChange={setTags}
+  options={tagOptions}
+  creatable
+  placeholder="태그 선택"
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` / `values` | `T \| T[]` | — | Controlled |
+| `defaultValue` | same | — | Uncontrolled |
+| `onValueChange` | `(value) => void` | — | |
+| `options` | `Option[]` or `(query) => Promise<Option[]>` | `[]` | Static list or async loader |
+| `multiple` | `boolean` | `false` | Multi-select mode |
+| `searchable` | `boolean` | `false` (Select) / `true` (Combobox) | Show search input in popover |
+| `creatable` | `boolean` | `false` | Allow creating values not in list |
+| `clearable` | `boolean` | `false` | Show ✕ to clear |
+| `placeholder` | `string` | — | |
+| `disabled` / `readOnly` | `boolean` | `false` | |
+| `error` / `errorText` | — | — | Validation state |
+| `loading` | `boolean` | `false` | Show spinner inside popover |
+| `maxDisplayedTags` | `number` | `3` (multi) | Tags shown before "+N more" |
+| `groupBy` | `(option) => string` | — | Render group headers |
+| `optionRender` | `(option) => ReactNode` | default | Custom option rendering |
+| `noResultsMessage` | `ReactNode` | "검색 결과가 없습니다" | |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | |
+
+### Option type
+
+```ts
+type Option<T = string> = {
+  value: T;
+  label: string;
+  description?: string;
+  icon?: ReactNode;
+  group?: string;
+  disabled?: boolean;
+  // free-form metadata for custom rendering
+  [key: string]: unknown;
+};
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Empty | Placeholder, chevron `▾` |
+| Filled | Selected label, optional icon |
+| Hover | Border emphasis |
+| Focus-visible | 2px ring |
+| Open | Border emphasis, chevron flips to `▴` |
+| Disabled | 50% opacity, no events |
+| Loading (async) | Spinner replaces chevron |
+| Error | Border `--color-error` |
+
+For multi-select with values: each value renders as a `Tag` chip inside the trigger. Overflow shows `+N`:
+
+```
+┌──────────────────────────────────────────────┐
+│ [태그1 ✕] [태그2 ✕] [태그3 ✕] +5            ▾ │
+└──────────────────────────────────────────────┘
+```
+
+## Variants
+
+### Single select
+
+Default. Closes on selection.
+
+### Multi-select
+
+- Stays open after each selection.
+- Selected items show checkmarks in the popover.
+- Selected items render as tags in the trigger.
+- "Apply" footer button for "confirm and close" UX (optional — most close on outside click).
+
+### Searchable / combobox
+
+- Search input appears at the top of the popover (or replaces the trigger value).
+- Filter applies as user types (client-side or async).
+- Highlight matched substring in option labels.
+
+### Async loading (combobox)
+
+- `options` is a function `(query: string) => Promise<Option[]>`.
+- Debounce: 250–300ms before each request.
+- Loading spinner during fetch.
+- Error state with retry.
+- Cache results per query for the session (cancel on new query).
+
+### Creatable (tag input)
+
+- Allow committing values not in the option list.
+- Visual: a "Create '<input>'" item at the bottom of the dropdown.
+- Confirmation: pressing Enter on this item adds the new value.
+- Use cases: tag inputs, free-form labels, email-list inputs.
+
+## Accessibility — WAI-ARIA Combobox / Listbox pattern
+
+This is one of the more complex a11y components. Use a battle-tested primitive (Radix, Headless UI) and don't roll from scratch.
+
+### Pattern depending on variant
+
+| Variant | Pattern |
+| --- | --- |
+| Single, not searchable | `role="listbox"` (button-triggered) — Radix Select |
+| Single, searchable | `role="combobox"` |
+| Multi-select with search | `role="combobox" aria-multiselectable="true"` |
+
+### ARIA structure
+
+- Trigger: `role="combobox"` (searchable) or `role="button"` (non-searchable), `aria-expanded`, `aria-controls`, `aria-haspopup="listbox"`.
+- Popover listbox: `role="listbox"`, `aria-multiselectable="true|false"`.
+- Each option: `role="option"`, `aria-selected="true|false"`.
+- Active option (currently highlighted by keyboard): `aria-activedescendant` on the combobox.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Reaches trigger. From open popover, tab moves out. |
+| `↓` / `Enter` (closed) | Opens popover, focus first option (or selected) |
+| `↓` / `↑` (open) | Move highlight |
+| `Home` / `End` | First / last option |
+| `Enter` / `Space` (open) | Select highlighted option, close (or stay open if multi) |
+| `Esc` | Close popover, return focus to trigger |
+| Type-ahead (non-searchable) | Jump to first option starting with typed char |
+| Type-ahead (searchable) | Filters list |
+| `Backspace` (multi-select with values) | Remove last tag |
+
+## Tokens consumed
+
+```
+--color-bg-default          (popover bg, trigger bg)
+--color-bg-subtle           (option hover)
+--color-bg-elevated         (active option)
+--color-text-primary
+--color-text-secondary      (description text)
+--color-primary-default     (selected indicator)
+--color-primary-subtle-bg   (selected option highlight)
+--color-border-default
+--color-border-strong       (hover border on trigger)
+--color-focus-ring
+--color-error
+--space-sm, --space-md
+--radius-md
+--shadow-popover
+--motion-fast, --easing-out
+```
+
+## Sizes
+
+| Size | Trigger height | Option height | Font |
+| --- | --- | --- | --- |
+| `sm` | 32px | 28px | 13px |
+| `md` (default) | 40px | 36px | 14px |
+| `lg` | 48px | 44px | 16px |
+
+## Edge cases
+
+- **Long option labels**: truncate with `…`, full text in `title`. For comboboxes where users search by full text, allow wrapping if option count is small.
+- **Many options (1000+)**: virtualize the option list. `react-virtual` or `tanstack-virtual`. Don't render 1000 DOM nodes.
+- **Async load with no results**: show `noResultsMessage`. Provide creatable path if applicable.
+- **Mobile**: prefer **bottom sheet** over popover for searchable selects on mobile. The keyboard takes most of the screen otherwise.
+- **Korean IME**: don't filter on every composition keystroke. Wait for `compositionend`. Otherwise `김`+`민` filters out everything between.
+- **Tag input with paste**: pasting "tag1, tag2, tag3" should split on `,` and add as 3 tags.
+- **RTL**: chevron flips, padding swaps. Tag chips wrap RTL.
+- **Pre-selected value not in current options list** (rare async case): show the value in the trigger but resolve label via a separate lookup if possible.
+- **Disabled options**: visually muted, skipped by keyboard nav, not selectable.
+
+## Don't
+
+- Don't use a `<select>` for 50+ options. Native dropdowns become unusable. Use a searchable combobox.
+- Don't use a Select for binary choices (yes/no, on/off). Use a Switch or radio buttons.
+- Don't auto-select the first option. Show placeholder until user picks.
+- Don't lose typed text on accidental blur — on blur with no selection, either close cleanly or show "press Enter to confirm".
+- Don't force "Apply" button on multi-select that closes on outside click anyway. Pick one model.
+- Don't combine creatable + restrictive validation (e.g., "must be from list"). Pick one.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/select/`](../refs/ant-design/components/select/) — `Select`, supports `mode="multiple"`, `mode="tags"` (creatable). Has `Cascader` for hierarchical select.
+- MUI: `<Select>` (basic, like native) and `<Autocomplete>` (combobox). Autocomplete is the canonical reference for the searchable variant.
+- shadcn-ui:
+  - [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/select.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/select.tsx) — Radix Select. No search.
+  - [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/command.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/command.tsx) — cmdk-based searchable. Combine with Popover for combobox pattern.
+
+API choices made:
+- **`Select` and `MultiSelect` as separate top-level exports** for type safety on `value` (single value vs array). Internally same primitive with `multiple={true|false}`.
+- **`searchable` and `creatable` as boolean props** rather than separate components — fewer concepts, same WAI-ARIA pattern.
+- **`options` accepting either array or async function**: covers both static and remote-load cases without a separate component.
+- **Tag chips inside the trigger for multi**: matches Ant + Autocomplete; clearer than checkbox-list-only.
+
+## Cross-reference
+
+- [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md) — Select in forms
+- [WAI-ARIA Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/)
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — keyboard contract

package/examples/component-separator.md

@@ -0,0 +1,177 @@
+# `Separator` — spec
+
+> Synthesized from shadcn-ui `separator` (Radix) and the HTML5 `<hr>` element. A thin visual divider — horizontal or vertical — separating content. Distinct from `Divider` (an alias in some libraries) and from layout gaps (which use spacing tokens).
+
+## Separator vs spacing
+
+| | Separator | Spacing gap |
+| --- | --- | --- |
+| Visible | Yes (line) | No (whitespace) |
+| Use | Strong section break | Visual breathing room |
+| Semantics | "Topic boundary" | "Layout pad" |
+
+For mild visual rhythm: use spacing. For explicit topic / section change: use Separator.
+
+## Anatomy
+
+```
+Top section content
+
+────────────────────────       ← horizontal Separator
+
+Bottom section content
+```
+
+```
+[ left ]  │  [ right ]         ← vertical Separator
+```
+
+## API
+
+```tsx
+<Separator />                              {/* horizontal default */}
+<Separator orientation="horizontal" />     {/* explicit */}
+<Separator orientation="vertical" />       {/* vertical */}
+
+<Separator decorative={false} />           {/* semantic — actual <hr> equivalent */}
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction |
+| `decorative` | `boolean` | `true` | If true: pure visual (`role="none"`); if false: semantic (`role="separator"`) |
+| `as` | `keyof JSX.IntrinsicElements` | `"div"` | Element type |
+| `className` | `string` | — | Style override |
+
+## Decorative vs semantic
+
+- **`decorative={true}` (default)**: line is purely visual. Doesn't show up in the accessibility tree.
+- **`decorative={false}`**: line is meaningful structurally — represents a content boundary. Announced to screen readers.
+
+Most separators are decorative. Use `decorative={false}` only for genuine content breaks (between articles, between menu groups conceptually).
+
+For semantic horizontal separators: prefer the native `<hr>`.
+
+## Variants
+
+### Solid (default)
+
+```css
+.separator {
+  background: var(--color-border-default);
+  shrink: 0;
+}
+.separator[data-orientation="horizontal"] {
+  height: 1px;
+  width: 100%;
+}
+.separator[data-orientation="vertical"] {
+  width: 1px;
+  height: 100%;
+}
+```
+
+### Dashed / dotted (variant via class)
+
+```css
+.separator[data-variant="dashed"] {
+  background: none;
+  border-top: 1px dashed var(--color-border-default);
+  height: 0;
+}
+```
+
+### With label (centered text)
+
+```
+─────  Section title  ─────
+```
+
+```tsx
+<div className="separator-with-label">
+  <Separator />
+  <span>Section title</span>
+  <Separator />
+</div>
+```
+
+## States
+
+Stateless. Separator is presentational.
+
+## Tokens consumed
+
+```
+--color-border-default             (line color)
+--color-border-strong              (high-contrast variant)
+--space-xxs                        (1px standard)
+```
+
+For Korean print contexts (receipt-style dotted dividers): `border-style: dotted` with brand color is a Toss / banking visual convention.
+
+## Accessibility
+
+- Default decorative: `role="none"`. Screen reader skips.
+- Semantic: `role="separator"` (with `aria-orientation` if vertical).
+- Native `<hr>` is the simplest semantic separator (defaults to horizontal).
+- For visual-only "decorations" between elements: keep decorative.
+
+## Code examples
+
+### List sections
+
+```tsx
+<List>
+  <ListSection>...</ListSection>
+  <Separator />
+  <ListSection>...</ListSection>
+</List>
+```
+
+### Vertical between flexbox items
+
+```tsx
+<div className="flex items-center gap-4">
+  <Avatar />
+  <Separator orientation="vertical" className="h-8" />
+  <UserName />
+  <Separator orientation="vertical" className="h-8" />
+  <Status />
+</div>
+```
+
+### With centered label
+
+```tsx
+<div className="flex items-center gap-4">
+  <Separator className="flex-1" />
+  <span className="text-muted">또는</span>
+  <Separator className="flex-1" />
+</div>
+```
+
+## Edge cases
+
+- **Vertical inside flex without explicit height**: collapses to 0px. Always set height for vertical.
+- **Inside grid**: behaves as a child cell; may need `grid-column: 1 / -1` for full-width horizontal.
+- **Dark mode**: tokens cascade; ensure visible against dark bg.
+- **Print**: native `<hr>` prints; CSS `background` may not. Use `border-top` for print fidelity.
+- **RTL**: orientation unaffected; horizontal separators flip nothing.
+
+## Don't
+
+- Don't use Separator where a heading + spacing would be clearer.
+- Don't pile up 5 separators in close proximity — visual noise.
+- Don't make separator too dark / heavy. Subtle (~20% opacity grayscale) is the convention.
+- Don't use Separator for rough layout work — use Grid / Flex with gap.
+
+## References
+
+- HTML5 `<hr>` element
+- shadcn-ui: [`separator`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/separator.tsx) (Radix)
+- Ant Design `Divider` is the equivalent name there
+
+## Cross-reference
+
+- [`examples/component-divider.md`](component-divider.md) — Ant-style alias
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)