@design-ai/cli 4.55.0

package/examples/component-checkbox.md

@@ -0,0 +1,149 @@
+# `Checkbox` — spec
+
+> Synthesized from Ant Design `Checkbox`, MUI `Checkbox`, shadcn-ui `checkbox`. Form selection control. See also [`component-form-controls.md`](component-form-controls.md) for Switch + Radio comparisons.
+
+## Checkbox vs Switch vs Radio
+
+| | Checkbox | Switch | Radio |
+| --- | --- | --- | --- |
+| Use | Multi-select; binary form input | Setting toggle (immediate effect) | Mutually exclusive choice |
+| Default state matters | Yes (form has explicit unchecked option) | Yes (immediate state) | One must be selected |
+| Visual | Square box + check | iOS-style slider | Circle |
+
+For **forms with submit button**: Checkbox.
+For **immediately-applied settings**: Switch.
+For **pick-one-of-many**: Radio.
+
+## Anatomy
+
+```
+☐ Send me promotional email      ← unchecked
+☑ Subscribe to newsletter         ← checked
+☒ I agree (indeterminate)         ← rare, used for "mixed" group state
+```
+
+## API
+
+```tsx
+<Checkbox
+  checked={subscribed}
+  onCheckedChange={setSubscribed}
+  id="subscribe"
+/>
+<label htmlFor="subscribe">Subscribe</label>
+
+<Checkbox checked="indeterminate" onCheckedChange={...}>
+  Select all
+</Checkbox>
+
+<Checkbox required disabled />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checked` | `boolean \| "indeterminate"` | controlled | State |
+| `defaultChecked` | `boolean` | `false` | Uncontrolled initial |
+| `onCheckedChange` | `(checked: boolean) => void` | — | Callback |
+| `disabled` | `boolean` | `false` | — |
+| `required` | `boolean` | `false` | For form validation |
+| `name` | `string` | — | Form field name |
+| `value` | `string` | `"on"` | Form value when checked |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Unchecked | Empty box with border |
+| Checked | Filled box with check icon |
+| Indeterminate | Filled box with horizontal bar (group "some-checked") |
+| Hover | Border color shift |
+| Focus-visible | 2px focus ring |
+| Disabled | Reduced opacity, no events |
+| Error | Red border (form validation) |
+
+## Indeterminate use
+
+The "select all" pattern:
+
+```tsx
+const allChecked = items.every(i => i.checked);
+const someChecked = items.some(i => i.checked) && !allChecked;
+const indeterminate = someChecked;
+
+<Checkbox
+  checked={allChecked ? true : indeterminate ? "indeterminate" : false}
+  onCheckedChange={(c) => setAll(c === true)}
+>
+  Select all
+</Checkbox>
+
+{items.map(item => (
+  <Checkbox
+    key={item.id}
+    checked={item.checked}
+    onCheckedChange={(c) => updateItem(item.id, c)}
+  >
+    {item.label}
+  </Checkbox>
+))}
+```
+
+## Tokens consumed
+
+```
+--checkbox-bg-unchecked
+--checkbox-bg-checked              (brand)
+--checkbox-border
+--checkbox-border-checked
+--checkbox-fg-check                (check icon color)
+--checkbox-error-border
+--checkbox-size                    (typically 16-20px)
+--space-xs                         (label-checkbox gap)
+--motion-fast
+```
+
+## Accessibility
+
+- Native `<input type="checkbox">` (or Radix `<Checkbox>` with proper ARIA).
+- `<label htmlFor="...">` linked. Click on label toggles.
+- `aria-checked="true|false|mixed"` — the third value for indeterminate.
+- For groups: wrap in `<fieldset>` + `<legend>`.
+- Keyboard: Space toggles. Tab moves between checkboxes (no arrow-nav unless in a group with `role="group"`).
+- Touch target ≥ 44pt mobile.
+
+## Korean conventions
+
+- 마케팅 정보 수신 동의 (marketing consent) — required field per 정보통신망법; default unchecked, never auto-check.
+- 이용약관 동의 (terms agreement) — typically with link to terms; required for signup.
+- 만 14세 이상입니다 (age confirmation) — required for KR services.
+
+```tsx
+<Checkbox required>
+  <span>
+    <Link href="/terms" external>이용약관</Link>에 동의합니다 (필수)
+  </span>
+</Checkbox>
+<Checkbox>
+  마케팅 정보 수신에 동의합니다 (선택)
+</Checkbox>
+```
+
+## Don't
+
+- Don't auto-check marketing consent. KR law (정보통신망법) prohibits.
+- Don't omit label or `aria-label`.
+- Don't use Checkbox for "Apply immediately" settings — use Switch.
+- Don't make checkbox visual smaller than 16x16 (touch target may still be 44pt via padding, but visual must be readable).
+
+## References
+
+- Ant: [`Checkbox`](../refs/ant-design/components/checkbox)
+- MUI: [`Checkbox`](../refs/mui/packages/mui-material/src/Checkbox)
+- shadcn-ui: [`checkbox`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/checkbox.tsx)
+
+## Cross-reference
+
+- [`examples/component-form-controls.md`](component-form-controls.md) — combined Switch + Radio + Checkbox
+- [`examples/component-radio.md`](component-radio.md)
+- [`examples/component-switch.md`](component-switch.md) — N/A (covered in form-controls)
+- [`knowledge/patterns/email-design.md`](../knowledge/patterns/email-design.md) — KR marketing consent rules

package/examples/component-click-away-listener.md

@@ -0,0 +1,87 @@
+# `ClickAwayListener` — spec
+
+> Synthesized from MUI `ClickAwayListener`. Utility that fires a callback when user clicks outside a wrapped element. Used internally by Popover / Modal / Menu to handle click-outside-closes.
+
+## When to use
+
+- Custom dropdowns / popups that should close on outside click.
+- Image galleries / lightboxes with click-outside-to-close.
+- Any custom floating UI not built on Popover.
+
+When NOT to use:
+- Standard Popover / Menu / Modal — they include this internally.
+- Form inputs (focus / blur events handle this naturally).
+
+## API
+
+```tsx
+<ClickAwayListener onClickAway={() => setOpen(false)}>
+  <div className="custom-popup">
+    {/* content */}
+  </div>
+</ClickAwayListener>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onClickAway` | `(event) => void` | required | Fires on outside click / touch |
+| `mouseEvent` | `"onClick" \| "onMouseDown" \| "onMouseUp" \| false` | `"onClick"` | Which mouse event triggers |
+| `touchEvent` | `"onTouchStart" \| "onTouchEnd" \| false` | `"onTouchEnd"` | Touch event |
+| `disableReactTree` | `boolean` | `false` | Use document listener instead of React's synthetic events |
+| `children` | `ReactNode` | — | Single child — the inside |
+
+## Implementation note
+
+For modern projects, the same effect via hooks:
+
+```tsx
+function useClickAway<T extends HTMLElement>(
+  ref: React.RefObject<T>,
+  onAway: () => void,
+) {
+  useEffect(() => {
+    function handler(e: MouseEvent | TouchEvent) {
+      if (!ref.current || ref.current.contains(e.target as Node)) return;
+      onAway();
+    }
+    document.addEventListener("mousedown", handler);
+    document.addEventListener("touchstart", handler);
+    return () => {
+      document.removeEventListener("mousedown", handler);
+      document.removeEventListener("touchstart", handler);
+    };
+  }, [ref, onAway]);
+}
+
+// Use:
+const ref = useRef<HTMLDivElement>(null);
+useClickAway(ref, () => setOpen(false));
+return <div ref={ref}>...</div>;
+```
+
+shadcn-based projects don't include this as a separate primitive — Popover / Sheet handle it internally via Radix.
+
+## Edge cases
+
+- **Click on a portal child**: portal renders outside DOM tree; `ref.contains()` won't match. Use `disableReactTree` OR maintain a list of "inside" elements.
+- **Mobile touch + click both fire**: prevent double-fire by debouncing or using only one event.
+- **Synthetic vs native events**: React's synthetic events bubble through React tree even if rendered to portal; native events don't.
+- **Esc key**: ClickAwayListener doesn't handle Esc — pair with separate keydown listener.
+
+## Don't
+
+- Don't ship custom modals without click-outside handling.
+- Don't fire on all clicks — limit to outside-the-wrapped-element.
+- Don't forget mobile touch events.
+- Don't rely on ClickAwayListener for accessibility — focus trap + Esc still required.
+
+## References
+
+- MUI: [`ClickAwayListener`](../refs/mui/packages/mui-material/src/ClickAwayListener)
+- Hook alternatives in many libs (use-click-away, react-use, etc.)
+
+## Cross-reference
+
+- [`examples/component-popover.md`](component-popover.md) — uses click-away internally
+- [`examples/component-modal.md`](component-modal.md) — uses click-away (or backdrop click)
+- [`examples/component-dropdown.md`](component-dropdown.md) — uses click-away

package/examples/component-code.md

@@ -0,0 +1,213 @@
+# `Code` (inline + block) — spec
+
+> Citing Ant Design `Typography.Text code` (inline) / `pre` (block), MUI (composition), shadcn-ui (composition with shiki/prism)
+
+## Purpose
+
+Renders code with monospace font + appropriate styling. Two variants:
+
+| Variant | Use |
+| --- | --- |
+| **Inline** | Code within prose (`const x = 1`) |
+| **Block** | Standalone code blocks with optional syntax highlighting + copy button |
+
+## Anatomy
+
+### Inline
+
+```
+This is some `inline code` within text.
+```
+
+A short, monospace token in the flow of text.
+
+### Block
+
+```
+┌──────────────────────────────────────────────────┐
+│ TypeScript                              [Copy]   │
+├──────────────────────────────────────────────────┤
+│ 1  type User = {                                 │
+│ 2    name: string;                               │
+│ 3    email: string;                              │
+│ 4  };                                            │
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Language label | optional | Header showing the language |
+| Copy button | optional | Top-right corner |
+| Line numbers | optional | Left gutter |
+| Code content | yes | Highlighted or plain |
+
+## API
+
+### Inline
+
+```tsx
+<Code inline>const x = 1</Code>
+```
+
+Or as a tagged element:
+
+```tsx
+<code>{value}</code>      {/* native */}
+<Code>{value}</Code>      {/* component */}
+```
+
+### Block
+
+```tsx
+<Code language="typescript" showLineNumbers showCopyButton>
+{`type User = {
+  name: string;
+  email: string;
+};`}
+</Code>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `string` | — | Code content |
+| `inline` | `boolean` | `false` | Inline vs block |
+| `language` | `string` | — | Syntax highlighting language (e.g., `"typescript"`, `"python"`, `"bash"`) |
+| `showLineNumbers` | `boolean` | `false` | |
+| `showCopyButton` | `boolean` | `true` (block only) | |
+| `theme` | `"light" \| "dark" \| "auto"` | `"auto"` | Highlighter theme |
+| `wrapLines` | `boolean` | `false` | Soft-wrap long lines vs horizontal scroll |
+| `highlightLines` | `number[]` | — | Line numbers to highlight |
+
+## Syntax highlighting
+
+Use a library — don't roll your own:
+- **Shiki** (best for static / SSR — uses VS Code engine)
+- **Prism** (lighter weight, more themes)
+- **highlight.js** (largest language coverage)
+
+For React: `react-syntax-highlighter` wraps these.
+
+For server-rendered (Next.js, SvelteKit): Shiki is best — pre-renders highlighted HTML on the server, no client JS needed.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Code visible |
+| Hover (block) | Copy button appears (or stays visible) |
+| Copy clicked | Brief "복사됨!" toast or button text change |
+| Copy failed | "복사 실패" inline |
+
+## Tokens consumed
+
+```
+--font-mono                   (e.g., "SFMono-Regular, Consolas, ...")
+--color-bg-code               (block bg — slightly tinted)
+--color-bg-inline-code        (inline bg — subtle highlight)
+--color-text-primary          (default code text)
+--color-text-secondary        (line numbers)
+--color-syntax-*              (syntax highlight tokens — keyword, string, comment, etc.)
+--color-bg-elevated           (header bg, copy button bg)
+--space-sm, --space-md
+--radius-md                   (block corners)
+--font-size-sm, --font-size-base
+```
+
+For inline: typically a subtle background tint (`--color-bg-subtle`) and slightly smaller font (90%).
+
+For block: full-bleed monospace, dedicated background, comfortable padding.
+
+## Sizes
+
+Inline: matches surrounding text but slightly smaller (font-size 90%).
+
+Block:
+| Prop | Compact | Default | Comfortable |
+| --- | --- | --- | --- |
+| Font | 12px | 14px | 16px |
+| Line height | 1.4 | 1.6 | 1.8 |
+| Padding | 12px | 16px | 20px |
+
+## Accessibility
+
+- Inline: native `<code>` element. No special wiring needed.
+- Block: `<pre><code>` (semantic).
+- Copy button: `<button>` with `aria-label="복사"` (with success feedback).
+- For users navigating with screen readers: code blocks are read character-by-character. This is desired for code reading.
+
+```html
+<pre>
+  <code class="language-typescript">
+    const x = 1;
+  </code>
+</pre>
+```
+
+For language announcement:
+```html
+<pre aria-label="TypeScript code">
+  <code>...</code>
+</pre>
+```
+
+## Code example
+
+```tsx
+// Inline
+<p>
+  Set <Code>NODE_ENV</Code> to <Code>production</Code> for deployment.
+</p>
+
+// Block with syntax highlighting
+<Code language="typescript" showCopyButton>
+  {`const greet = (name: string) => \`안녕, \${name}!\`;`}
+</Code>
+
+// Long block with line numbers
+<Code language="python" showLineNumbers showCopyButton wrapLines>
+{`def fibonacci(n):
+    if n <= 1:
+        return n
+    return fibonacci(n - 1) + fibonacci(n - 2)`}
+</Code>
+
+// Highlighted lines (e.g., showing a diff)
+<Code language="js" highlightLines={[2, 3]}>
+{`function add(a, b) {
+  // ⚠ subtle bug here
+  return a + b + 1;
+}`}
+</Code>
+```
+
+## Edge cases
+
+- **Very long lines**: default to horizontal scroll (no wrap). User can opt into wrap.
+- **Multi-line inline code**: defaults to inline behavior; force inline-block to keep it on one line.
+- **Code with HTML special chars** (`<`, `>`, `&`): the renderer must escape these. Library handles.
+- **Code containing the copy-target itself**: copy returns the original string, not the rendered HTML.
+- **Print**: code blocks should print readably — fix font + page-break-inside: avoid.
+
+## Don't
+
+- Don't show syntax-highlighted code in critical UI paths (first paint) without SSR — flicker.
+- Don't omit copy button on documentation block (huge UX win).
+- Don't truncate code blocks. Show all or scroll.
+- Don't apply syntax highlighting to non-code (e.g., shell output that's not a command).
+- Don't use raw `<code>` in screen readers without context — wrap with description.
+
+## References
+
+- Ant Design: [`Typography.Text code`](../refs/ant-design/components/typography/) — inline. Block code: just use HTML `<pre>` with optional CSS.
+- MUI: no dedicated Code component. Use `<code>` or `<Typography component="pre">`.
+- shadcn-ui: no built-in. Compose with `react-syntax-highlighter` + Tailwind.
+
+Common libraries:
+- `react-syntax-highlighter` — React wrapper for Prism / Highlight.js
+- `shiki` — VS Code's highlighter, server-side rendering
+- `prism-react-renderer` — lightweight Prism wrapper
+
+## Cross-reference
+
+- [`examples/component-typography.md`](component-typography.md) — text rendering primitives
+- [`knowledge/typography/type-scale-fundamentals.md`](../knowledge/typography/type-scale-fundamentals.md) — monospace font choices

package/examples/component-collapsible.md

@@ -0,0 +1,219 @@
+# `Collapsible` — spec
+
+> Synthesized from shadcn-ui `collapsible` (Radix). The base primitive for any expand/collapse interaction. `Accordion` is a multi-instance manager built on top; `Collapsible` is the standalone single-instance version.
+
+## When to use
+
+- **Single expandable section** — e.g., "Show more details" toggle.
+- **Optional content** that's hidden by default to reduce density.
+- **As a primitive** for building Accordion, Disclosure, FAQ widgets.
+
+When NOT to use:
+- **Multi-section accordion** → use `Accordion`.
+- **Modal / drawer / sheet content** — those are different patterns.
+- **Persistent navigation** — keep nav always visible.
+
+## Anatomy
+
+```
+[Trigger ▶ Show more]      (closed)
+
+[Trigger ▼ Show less]      (open)
+   Content panel revealed
+   Multiple lines of content here.
+```
+
+## API
+
+```tsx
+<Collapsible defaultOpen={false} onOpenChange={track}>
+  <Collapsible.Trigger asChild>
+    <button className="trigger">
+      <ChevronIcon className="data-[state=open]:rotate-90 transition-transform" />
+      Show {open ? "less" : "more"}
+    </button>
+  </Collapsible.Trigger>
+  <Collapsible.Content>
+    <div className="content">
+      {/* content here */}
+    </div>
+  </Collapsible.Content>
+</Collapsible>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `open` | `boolean` | controlled | Controlled state |
+| `defaultOpen` | `boolean` | `false` | Uncontrolled initial state |
+| `onOpenChange` | `(open: boolean) => void` | — | Callback |
+| `disabled` | `boolean` | `false` | Disable trigger |
+
+## Composition
+
+| Part | Purpose |
+| --- | --- |
+| `Collapsible` | Wrapper / state holder |
+| `Trigger` | The clickable element that toggles |
+| `Content` | The collapsible panel |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Closed | Content hidden; Trigger shows "expand" affordance |
+| Opening | Content height animates from 0 to natural |
+| Open | Content visible; Trigger shows "collapse" affordance |
+| Closing | Reverse animation |
+| Disabled | Trigger unclickable, no events |
+
+## Animation
+
+The classic CSS challenge — `height: auto` doesn't animate. Modern approaches:
+
+### CSS Grid trick (works in 2024+)
+
+```css
+.collapsible-content {
+  display: grid;
+  grid-template-rows: 0fr;
+  transition: grid-template-rows 200ms var(--ease-out);
+}
+.collapsible-content[data-state="open"] {
+  grid-template-rows: 1fr;
+}
+.collapsible-content > div {
+  overflow: hidden;
+}
+```
+
+`1fr` works as auto-height in grid. Animatable.
+
+### CSS variable + JS measurement
+
+```js
+// On open: measure content; set CSS var; transition height to it
+const height = content.scrollHeight;
+content.style.setProperty('--height', `${height}px`);
+content.dataset.state = 'open';
+
+// On close: instant re-measure; transition to 0
+```
+
+```css
+.collapsible-content {
+  height: 0;
+  overflow: hidden;
+  transition: height 200ms var(--ease-out);
+}
+.collapsible-content[data-state="open"] {
+  height: var(--height);
+}
+```
+
+### Reduced motion
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .collapsible-content { transition: none; }
+}
+```
+
+## Tokens consumed
+
+```
+--space-sm, --space-md       (content padding)
+--motion-medium              (200ms transition)
+--ease-out
+```
+
+Collapsible is structural; visual styling is on the children (Trigger + Content).
+
+## Accessibility
+
+- Use the **WAI-ARIA Disclosure pattern**:
+  - Trigger: `<button aria-expanded="true|false" aria-controls="content-id">`.
+  - Content: `<div id="content-id">` (no special role; just a region).
+- `Enter` / `Space` toggles.
+- Tab moves into Content's focusable items when open; skips when closed.
+- Don't use `aria-hidden` on Content when closed — `display: none` (or grid 0fr) removes it from a11y tree natively.
+
+## Code example — FAQ item
+
+```tsx
+function FAQItem({ question, answer }: Props) {
+  const [open, setOpen] = useState(false);
+
+  return (
+    <Collapsible open={open} onOpenChange={setOpen} className="faq-item">
+      <Collapsible.Trigger asChild>
+        <button className="faq-trigger">
+          <span>{question}</span>
+          <ChevronIcon
+            className={cn("transition-transform", open && "rotate-180")}
+          />
+        </button>
+      </Collapsible.Trigger>
+      <Collapsible.Content>
+        <div className="faq-content">{answer}</div>
+      </Collapsible.Content>
+    </Collapsible>
+  );
+}
+```
+
+## Code example — "Show more" details
+
+```tsx
+function ProductDetails({ product }: Props) {
+  const [showMore, setShowMore] = useState(false);
+
+  return (
+    <div>
+      <p>{product.shortDescription}</p>
+      <Collapsible open={showMore} onOpenChange={setShowMore}>
+        <Collapsible.Trigger asChild>
+          <button className="link-button">
+            {showMore ? "간단히 보기" : "자세히 보기"}
+          </button>
+        </Collapsible.Trigger>
+        <Collapsible.Content>
+          <div className="details">
+            <p>{product.longDescription}</p>
+            <SpecsTable specs={product.specs} />
+          </div>
+        </Collapsible.Content>
+      </Collapsible>
+    </div>
+  );
+}
+```
+
+## Edge cases
+
+- **Initial state on SSR**: pass `defaultOpen` matching server render to avoid hydration mismatch.
+- **Content with focus on open**: don't auto-focus (Disclosure pattern doesn't trap focus); user tabs in naturally.
+- **Animating content with images**: images may load AFTER initial measurement, causing height jumps. Use `content-visibility` or pre-load.
+- **Nested Collapsible**: works; just style independently.
+- **Long content**: scroll inside Content if exceeds reasonable height (cap with max-height).
+- **Disabled while open**: keep open (or close, depending on UX); disable Trigger so user can't close.
+- **Korean toggle labels**: "자세히 보기 / 간단히 보기", "더 보기 / 접기", or "펼치기 / 접기".
+
+## Don't
+
+- Don't use Collapsible for navigation menus — different a11y pattern (Menu).
+- Don't omit visual rotate / chevron change — affords state.
+- Don't put critical info inside (closed-by-default) without a visible summary.
+- Don't animate longer than 300ms — feels slow for repeated toggles.
+- Don't forget reduced motion.
+- Don't use Collapsible for multi-instance accordion — that needs `Accordion`.
+
+## References
+
+- shadcn-ui: [`collapsible`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/collapsible.tsx) (Radix)
+- WAI-ARIA: [Disclosure pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)
+
+## Cross-reference
+
+- [`examples/component-accordion.md`](component-accordion.md) — multi-section variant
+- [`knowledge/motion/principles.md`](../knowledge/motion/principles.md) — height animation
+- [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)