@design-ai/cli 4.55.0

package/examples/component-icon.md

@@ -0,0 +1,102 @@
+# `Icon` — spec
+
+> Synthesized from MUI `Icon`/`SvgIcon` and Ant Design `Icon`. The base primitive for rendering icons. Pairs with [`knowledge/icons/curated-sets.md`](../knowledge/icons/curated-sets.md) for icon-set selection.
+
+## When to use
+
+- Inline icons in buttons, links, list items.
+- Decorative or status indicators.
+- As building blocks for `IconButton`, `Avatar`, `Toast`.
+
+## API
+
+```tsx
+<Icon as={CheckIcon} />
+<Icon size="md" color="brand" />
+<Icon as={WarningIcon} aria-label="Warning" />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `as` | `ComponentType` | required | The actual icon SVG component (Phosphor, Lucide, etc) |
+| `size` | `"xs" \| "sm" \| "md" \| "lg" \| "xl" \| number` | `"md"` | Pixel size |
+| `color` | `"current" \| "brand" \| "muted" \| "success" \| "warning" \| "error"` | `"current"` | Color via token |
+| `weight` | `"thin" \| "light" \| "regular" \| "bold" \| "fill"` | `"regular"` | Phosphor-style weight (if icon set supports) |
+| `aria-label` | `string` | — | Required for meaningful icons |
+| `aria-hidden` | `boolean` | auto | True for decorative |
+
+## Sizes
+
+| Size | px |
+| --- | --- |
+| `xs` | 12 |
+| `sm` | 16 |
+| `md` (default) | 20-24 |
+| `lg` | 32 |
+| `xl` | 48 |
+
+## Color via `currentColor`
+
+```svg
+<svg viewBox="0 0 24 24" fill="currentColor">
+  <path d="..." />
+</svg>
+```
+
+The icon SVG should use `fill="currentColor"` (or `stroke="currentColor"` for stroke-style). Icon component sets the parent `color` token; SVG inherits.
+
+```css
+.icon[data-color="brand"]   { color: var(--color-brand-default); }
+.icon[data-color="muted"]   { color: var(--color-fg-muted); }
+.icon[data-color="success"] { color: var(--color-success-default); }
+.icon[data-color="warning"] { color: var(--color-warning-default); }
+.icon[data-color="error"]   { color: var(--color-error-default); }
+```
+
+## Accessibility
+
+| Use | Pattern |
+| --- | --- |
+| Decorative (label-redundant) | `aria-hidden="true"` |
+| Meaningful (no adjacent label) | `<span role="img" aria-label="...">` wrapper |
+| Inside button text label | `aria-hidden="true"` (button label conveys meaning) |
+| Inside icon-only button | label on the button, NOT the icon |
+
+```tsx
+{/* Decorative inside text-labeled button */}
+<button>
+  <Icon as={SaveIcon} aria-hidden /> 저장
+</button>
+
+{/* Meaningful icon-only button */}
+<button aria-label="저장">
+  <Icon as={SaveIcon} aria-hidden />
+</button>
+```
+
+## Icon-set conventions
+
+- Pick **one set** per project (Phosphor, Lucide, Heroicons, Material Icons).
+- Don't mix stroke and fill icon sets — visual inconsistency.
+- For Phosphor: weights (thin / light / regular / bold / fill) accepted.
+- For Lucide / Heroicons: stroke-only; uniform line weight.
+
+See [`knowledge/icons/curated-sets.md`](../knowledge/icons/curated-sets.md).
+
+## Don't
+
+- Don't use color alone to convey state. Pair with adjacent text or shape.
+- Don't render icon SVG inline without `aria-hidden` if it's decorative.
+- Don't use `<i className="icon-...">` icon-font pattern. Bad a11y, no theming.
+- Don't render at non-multiple-of-2 sizes (15px). Stays sharp on retina at 16/20/24.
+
+## References
+
+- MUI: [`SvgIcon`](../refs/mui/packages/mui-material/src/SvgIcon)
+- Phosphor Icons: 1200+ icons, 5 weights
+- Lucide: stroke-only minimalist set
+
+## Cross-reference
+
+- [`examples/component-icon-button.md`](component-icon-button.md)
+- [`knowledge/icons/curated-sets.md`](../knowledge/icons/curated-sets.md)

package/examples/component-illustration.md

@@ -0,0 +1,280 @@
+<!-- hand-written -->
+# `Illustration` (custom — themeable SVG illustration display) — spec
+
+> Generic wrapper for displaying a system illustration with theming, sizing, accessibility, and reduced-motion support. Used directly when `EmptyState` / `Result` / `OnboardingStep` aren't the right fit. Pairs with [`knowledge/illustration/svg-optimization.md`](../knowledge/illustration/svg-optimization.md).
+
+## Purpose
+
+When you want to drop a system illustration into a screen — feature explainer, onboarding card, marketing surface — without the empty-state layout. `Illustration` provides:
+
+1. **Registry-backed name** — typesafe lookup from the system's illustration set.
+2. **Theming via `currentColor` + CSS variables**.
+3. **Responsive sizing** — width or height; the other auto-scales via aspect ratio.
+4. **Accessibility** — decorative by default; meaningful on opt-in.
+5. **Lottie escape hatch** — if the illustration is animated, delegate to `LottiePlayer`.
+
+## Anatomy
+
+```
+┌──────────────────┐
+│                  │
+│   [SVG render]   │  ← from registry
+│                  │
+└──────────────────┘
+        OR
+┌──────────────────┐
+│                  │
+│  [Lottie render] │  ← when name maps to a Lottie source
+│                  │
+└──────────────────┘
+```
+
+## API
+
+```tsx
+<Illustration name="onboarding-welcome" size="lg" />
+
+<Illustration
+  name="payment-success"
+  size={200}
+  label="결제가 완료되었습니다"   // makes meaningful (not decorative)
+/>
+
+const heroMoneyFlowSize = { desktop: 480, mobile: 240 };
+<Illustration name="hero-money-flow" size={heroMoneyFlowSize} />
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `IllustrationName` | — | Registry key. Required. Typesafe via TS union. |
+| `size` | `"sm" \| "md" \| "lg" \| "xl" \| number \| { desktop: number; mobile: number }` | `"md"` | Display size in px. Object form for responsive. |
+| `label` | `string` | `undefined` | If set, illustration is meaningful (`role="img"` + `aria-label`). Default: decorative (`aria-hidden`). |
+| `tone` | `"brand" \| "neutral" \| "success" \| "warning" \| "danger"` | `"brand"` | Color theme via CSS variable cascade |
+| `as` | `"div" \| "span" \| "figure"` | `"div"` | Wrapper element |
+| `className` | `string` | — | Additional classes |
+
+## Sizes
+
+| token | px |
+| --- | --- |
+| `sm` | 80 |
+| `md` (default) | 120 |
+| `lg` | 200 |
+| `xl` | 320 |
+
+For responsive: pass `{ desktop, mobile }` object. The component renders both via CSS `clamp()`:
+
+```css
+.illustration[data-size-responsive] {
+  width: clamp(var(--mobile-size), 30vw, var(--desktop-size));
+}
+```
+
+## Tones
+
+`tone` maps to a CSS variable setting the illustration's `currentColor`:
+
+```css
+.illustration[data-tone="brand"]   { color: var(--color-brand-default); }
+.illustration[data-tone="neutral"] { color: var(--color-fg-muted); }
+.illustration[data-tone="success"] { color: var(--color-success-default); }
+.illustration[data-tone="warning"] { color: var(--color-warning-default); }
+.illustration[data-tone="danger"]  { color: var(--color-error-default); }
+```
+
+The illustration's SVG must use `currentColor` for the themable element. Multi-color illustrations also use CSS variables (`var(--color-bg-illo)`).
+
+Contrast contract: each tone token must clear at least **3:1** against `--color-bg-default` for non-text graphic strokes/fills, and any nearby explanatory text must keep the normal **4.5:1** body-text contrast target from [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md).
+
+## Usage context
+
+Use `Illustration` as a reusable visual-language primitive when the layout is owned by another surface: onboarding panels, fintech confirmation screens, feature explainers, or Korean payment-success moments where the surrounding copy already carries the meaning. Use `label` only when the image itself adds information not repeated in text; otherwise keep it decorative so screen-reader output stays concise.
+
+## Registry
+
+```ts
+// illustrations/registry.ts
+import { OnboardingWelcome } from "./svg/OnboardingWelcome";
+import { PaymentSuccess } from "./svg/PaymentSuccess";
+import { HeroMoneyFlow } from "./svg/HeroMoneyFlow";
+
+export const illustrationRegistry = {
+  // Spot illustrations
+  "onboarding-welcome": { type: "svg", component: OnboardingWelcome },
+  "payment-success": { type: "svg", component: PaymentSuccess },
+  "filter-empty": { type: "svg", component: FilterEmpty },
+
+  // Hero illustrations
+  "hero-money-flow": { type: "svg", component: HeroMoneyFlow },
+  "hero-onboarding": { type: "svg", component: HeroOnboarding },
+
+  // Animated (Lottie)
+  "celebration": { type: "lottie", src: "/illustrations/celebration.json", poster: "/illustrations/celebration.png" },
+} as const;
+
+export type IllustrationName = keyof typeof illustrationRegistry;
+```
+
+The registry is the **only** place new illustrations get added. Engineers can't ship an illustration not in the registry — enforces governance.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default (decorative) | Renders illustration with brand tone |
+| Meaningful (label set) | Same render; adds `role="img"` and `aria-label` |
+| Reduced motion + animated illustration | Static frame from poster |
+| Loading (Lottie source) | Poster while JSON streams; cross-fade when ready |
+| Error (illustration name not in registry) | Dev: throw. Prod: fallback to `generic` illustration. |
+
+## Tokens consumed
+
+```
+--color-brand-default
+--color-fg-muted
+--color-success-default
+--color-warning-default
+--color-error-default
+--color-bg-illo                  (multi-color illustrations)
+--motion-fast                    (poster → animation cross-fade)
+```
+
+## Accessibility
+
+### Default — decorative
+
+```html
+<div class="illustration" aria-hidden="true">
+  <svg ...>...</svg>
+</div>
+```
+
+Screen readers skip. Used when surrounding text already explains.
+
+### Meaningful — label set
+
+```html
+<div class="illustration" role="img" aria-label="결제가 완료되었습니다">
+  <svg aria-hidden="true">...</svg>
+</div>
+```
+
+The wrapper carries the label. Inner SVG stays `aria-hidden` to avoid double-announcement.
+
+### Animated illustrations
+
+If `name` maps to a Lottie source, delegates to `LottiePlayer` which handles `prefers-reduced-motion`. See [`examples/component-lottie-player.md`](component-lottie-player.md).
+
+## Implementation
+
+```tsx
+import { illustrationRegistry, type IllustrationName } from "./registry";
+import { LottiePlayer } from "./LottiePlayer";
+
+interface Props {
+  name: IllustrationName;
+  size?: "sm" | "md" | "lg" | "xl" | number | { desktop: number; mobile: number };
+  label?: string;
+  tone?: "brand" | "neutral" | "success" | "warning" | "danger";
+  as?: "div" | "span" | "figure";
+  className?: string;
+}
+
+const SIZE_MAP = { sm: 80, md: 120, lg: 200, xl: 320 };
+
+export function Illustration({
+  name,
+  size = "md",
+  label,
+  tone = "brand",
+  as: Tag = "div",
+  className,
+}: Props) {
+  const entry = illustrationRegistry[name];
+
+  if (!entry) {
+    if (process.env.NODE_ENV !== "production") {
+      throw new Error(`Illustration "${name}" not in registry`);
+    }
+    return null; // or fallback
+  }
+
+  const dims = typeof size === "number"
+    ? { width: size, height: size }
+    : typeof size === "string"
+    ? { width: SIZE_MAP[size], height: SIZE_MAP[size] }
+    : { responsive: size };
+
+  const a11y = label
+    ? { role: "img", "aria-label": label }
+    : { "aria-hidden": "true" };
+
+  return (
+    <Tag
+      className={cn("illustration", className)}
+      data-tone={tone}
+      data-size-responsive={dims.responsive ? "" : undefined}
+      style={
+        dims.responsive
+          ? {
+              "--desktop-size": `${dims.responsive.desktop}px`,
+              "--mobile-size": `${dims.responsive.mobile}px`,
+            }
+          : { width: dims.width, height: dims.height }
+      }
+      {...a11y}
+    >
+      {entry.type === "svg" ? (
+        <entry.component aria-hidden="true" />
+      ) : (
+        <LottiePlayer src={entry.src} poster={entry.poster} ariaLabel={label ?? ""} />
+      )}
+    </Tag>
+  );
+}
+```
+
+## Performance
+
+- SVG illustrations: inlined as React components via SVGR / vite-plugin-svgr; treeshaken automatically.
+- Lottie illustrations: lazy-loaded via `LottiePlayer`'s built-in lazy strategy.
+- For 50+ illustrations in registry: import on-demand to avoid shipping all in main bundle:
+
+```ts
+"hero-money-flow": {
+  type: "svg",
+  component: lazy(() => import("./svg/HeroMoneyFlow")),
+},
+```
+
+Wrap consumers in `<Suspense fallback={<IllustrationSkeleton width={width} height={height} />}>`.
+
+## Edge cases
+
+- **Name not in registry (typo)**: TS catches at compile time. Runtime: throw in dev, fallback in prod.
+- **Responsive size on SSR**: server renders both sizes; CSS `clamp()` resolves on client paint. No layout shift if dimensions are reserved.
+- **Dark mode**: registry's SVGs use `currentColor` + CSS variables. Tone variable cascades through dark theme. No per-illustration dark variant needed if SVG is built right.
+- **RTL languages**: most illustrations are visually symmetric; if not, mark in registry with `flippable: true` and apply `transform: scaleX(-1)` in RTL contexts.
+- **Print**: illustrations using `currentColor` print in current text color. For colored print, use named colors in registry's CSS layer.
+
+## Don't
+
+- Don't pass arbitrary SVG nodes — extend the registry.
+- Don't bake tone color in the SVG file. Use `currentColor`.
+- Don't size illustrations with raw px from the consumer's css. Use the `size` prop.
+- Don't render an `<img src=".svg">` — that's the wrong escape. Use the registry; SVG is inlined for theming.
+- Don't auto-loop animated illustrations on every screen. Battery + a11y.
+- Don't omit `label` if the illustration carries the only meaning on the screen. Defaults are decorative.
+
+## References
+
+No upstream component matches. Most libraries either ship icon systems (different concern) or expect raw `<img>` / `<svg>` for illustrations. This component formalizes the registry + theming pattern.
+
+## Cross-reference
+
+- [`knowledge/illustration/illustration-systems.md`](../knowledge/illustration/illustration-systems.md) — system foundation
+- [`knowledge/illustration/svg-optimization.md`](../knowledge/illustration/svg-optimization.md) — SVG production
+- [`knowledge/illustration/spot-illustrations.md`](../knowledge/illustration/spot-illustrations.md) — illustration types
+- [`examples/component-empty-state.md`](component-empty-state.md) — common consumer
+- [`examples/component-lottie-player.md`](component-lottie-player.md) — animated branch
+- [`examples/component-hero-block.md`](component-hero-block.md) — hero illustration consumer

package/examples/component-image-list.md

@@ -0,0 +1,107 @@
+# `ImageList` — spec
+
+> Synthesized from MUI `ImageList`. Grid of images with consistent rules — distinct from `Masonry` (varied heights) and `Grid` (general).
+
+## When to use
+
+- Photo galleries where uniform proportions OK.
+- Product image grids.
+- Avatars / icons in a grid.
+
+When NOT to use:
+- Pinterest-style varied heights → `Masonry`.
+- Reading-order content → semantic `<ul>`/`<ol>`.
+
+## Anatomy
+
+```
+┌──┬──┬──┬──┐
+│  │  │  │  │
+├──┼──┼──┼──┤
+│  │  │  │  │
+├──┼──┼──┼──┤
+│  │  │  │  │
+└──┴──┴──┴──┘
+   uniform tiles
+```
+
+## API
+
+```tsx
+<ImageList cols={4} gap={8}>
+  {photos.map(p => (
+    <ImageList.Item key={p.id}>
+      <img src={p.thumb} alt={p.alt} loading="lazy" />
+      <ImageList.ItemBar
+        title={p.title}
+        subtitle={p.author}
+        actionIcon={<IconButton><InfoIcon /></IconButton>}
+      />
+    </ImageList.Item>
+  ))}
+</ImageList>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `cols` | `number` | `2` | Column count |
+| `gap` | `number` | `4` | Gap between tiles (px) |
+| `rowHeight` | `number \| "auto"` | `"auto"` | Fixed row height; "auto" sizes by content |
+| `variant` | `"standard" \| "quilted" \| "masonry" \| "woven"` | `"standard"` | Layout style |
+
+## Variants
+
+- **standard**: uniform grid.
+- **quilted**: different tile sizes (some span 2 cols/rows) for visual rhythm.
+- **masonry**: varying heights (use `Masonry` instead — clearer name).
+- **woven**: alternating row heights.
+
+## States
+
+Stateless. Tiles can be interactive (click → open / navigate); each tile follows Item semantics.
+
+## Tokens consumed
+
+```
+--image-list-gap
+--image-list-bar-bg              (caption bar bg)
+--image-list-bar-fg
+--radius-sm                      (tile rounding)
+```
+
+## Accessibility
+
+- Each `<img alt="...">` required.
+- For interactive grids: wrap each Item in `<a>` or `<button>`.
+- Keyboard: Tab through items; arrow keys can navigate (configurable).
+
+## Code example
+
+```tsx
+<ImageList cols={3} gap={12} rowHeight={200}>
+  {products.map(p => (
+    <ImageList.Item key={p.id}>
+      <a href={`/products/${p.id}`}>
+        <img src={p.image} alt={p.name} loading="lazy" />
+      </a>
+      <ImageList.ItemBar title={p.name} subtitle={`₩${p.price.toLocaleString()}`} />
+    </ImageList.Item>
+  ))}
+</ImageList>
+```
+
+## Don't
+
+- Don't omit `alt` on images.
+- Don't use ImageList for non-image grids — use Grid.
+- Don't lazy-load above-the-fold — they should appear immediately.
+
+## References
+
+- MUI: [`ImageList`](../refs/mui/packages/mui-material/src/ImageList)
+
+## Cross-reference
+
+- [`examples/component-masonry.md`](component-masonry.md) — varied heights
+- [`examples/component-grid.md`](component-grid.md) — generic 2D
+- [`examples/component-aspect-ratio.md`](component-aspect-ratio.md) — single tile