@design-ai/cli 4.55.0

package/examples/component-stack.md

@@ -0,0 +1,130 @@
+# `Stack` — spec
+
+> Synthesized from MUI `Stack`. The flexbox-based linear layout primitive — children laid out in a row or column with consistent spacing. Most-used layout container after `Box`. The shadcn equivalent uses Tailwind utilities directly (`flex flex-col gap-4`) — Stack abstracts that for design-system enforcement.
+
+## When to use
+
+- Any group of elements that need consistent spacing (button rows, form rows, card stacks).
+- Replacing `<div style={{ display: 'flex', gap: 16 }}>` boilerplate.
+- For grid-style 2D layouts, use `Grid` instead.
+
+## Anatomy
+
+```
+Direction = "row":
+┌──────┬──[gap]──┬──────┬──[gap]──┬──────┐
+│ <1/> │         │ <2/> │         │ <3/> │
+└──────┴─────────┴──────┴─────────┴──────┘
+
+Direction = "column":
+┌──────┐
+│ <1/> │
+├─[gap]┤
+│ <2/> │
+├─[gap]┤
+│ <3/> │
+└──────┘
+```
+
+## API
+
+```tsx
+<Stack direction="row" gap={2} alignItems="center" justifyContent="flex-end">
+  <Button onClick={onCancel}>취소</Button>
+  <Button onClick={onSave} variant="contained">저장</Button>
+</Stack>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `'row' \| 'column' \| 'row-reverse' \| 'column-reverse'` | `'column'` | Flex axis |
+| `spacing` / `gap` | `number \| string` | `0` | Gap between children (theme spacing units; `gap={2}` = 16px on 8-base) |
+| `alignItems` | `'flex-start' \| 'center' \| 'flex-end' \| 'stretch' \| 'baseline'` | — | Cross-axis alignment |
+| `justifyContent` | `'flex-start' \| 'center' \| 'flex-end' \| 'space-between' \| 'space-around'` | — | Main-axis alignment |
+| `divider` | `ReactNode` | — | Element rendered between children (e.g., `<Divider />`) |
+| `useFlexGap` | `boolean` | `true` (MUI v6+) | Use CSS `gap` instead of margins; safer with `divider` |
+| `flexWrap` | `'nowrap' \| 'wrap'` | `'nowrap'` | Wrap children to next line |
+| `sx` | `SxProps` | — | Style override (responsive values, custom CSS) |
+
+### Responsive
+
+```tsx
+<Stack
+  direction={{ xs: 'column', md: 'row' }}
+  gap={{ xs: 1, md: 2 }}
+>
+  ...
+</Stack>
+```
+
+## States
+
+Layout primitive — no interactive states.
+
+## Tokens consumed
+
+```
+--space-xs   /* gap={0.5} */
+--space-sm   /* gap={1} */
+--space-md   /* gap={2} */
+--space-lg   /* gap={3} */
+--space-xl   /* gap={4} */
+```
+
+## Accessibility
+
+- `Stack` is a `<div>` (default). For semantic groupings, override via `component`:
+  - List of nav items: `component="nav"` + ARIA label.
+  - Toolbar: `component="div" role="toolbar"`.
+- For RTL languages, `direction="row"` automatically reverses if the document is `dir="rtl"`. For Korean (LTR), no special handling needed.
+
+## Edge cases
+
+- **Mixed-width children with `space-between`** — Stack distributes remaining space; long children may shrink. Use `flex={1}` on the spreading child if needed.
+- **Korean text in row direction** — Korean labels run wider than Latin equivalents; test row layouts at 320px viewport. Switch to `direction={{ xs: 'column', md: 'row' }}` if cramped.
+- **Nested Stacks** — common and fine. `Stack` doesn't add semantic meaning, just layout.
+- **`divider` with `useFlexGap=false`** — older MUI versions used margin-based spacing which collides with dividers. Set `useFlexGap` explicitly.
+
+## Code example
+
+```tsx
+// Card footer with cancel + primary
+<Card>
+  <CardContent>...</CardContent>
+  <Stack direction="row" gap={1} justifyContent="flex-end" sx={{ p: 2 }}>
+    <Button onClick={onCancel}>취소</Button>
+    <Button onClick={onSave} variant="contained">저장</Button>
+  </Stack>
+</Card>
+
+// Form row that stacks on mobile
+<Stack direction={{ xs: 'column', sm: 'row' }} gap={2}>
+  <TextField label="이름" />
+  <TextField label="사번" />
+  <TextField label="부서" />
+</Stack>
+
+// Vertical list of cards with dividers
+<Stack gap={2} divider={<Divider flexItem />}>
+  {items.map((it) => <Card key={it.id}>{it.title}</Card>)}
+</Stack>
+```
+
+## Don't
+
+- Don't reach for `Stack` for 2D grids — use `Grid`.
+- Don't nest 4+ Stacks deep — extract to a custom layout component.
+- Don't use `Stack direction="row"` for content that should wrap to multiple lines without explicit `flexWrap`.
+- Don't apply `Stack` to a single child — pure overhead.
+
+## References
+
+- MUI: [`Stack`](../refs/mui/packages/mui-material/src/Stack/)
+
+## Cross-reference
+
+- [`knowledge/components/INDEX.md`](../knowledge/components/INDEX.md)
+- [`component-box.md`](component-box.md)
+- [`component-grid.md`](component-grid.md)
+- [`component-flex.md`](component-flex.md) — alternate flex primitive
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)

package/examples/component-statistic.md

@@ -0,0 +1,282 @@
+# `Statistic` — spec
+
+> Citing Ant Design `Statistic`, MUI (no direct equivalent — composition), shadcn-ui (composition)
+
+## Purpose
+
+Displays a single number prominently — a KPI, count, balance, or metric. The "hero number" of a card or dashboard tile.
+
+## When Statistic vs alternatives
+
+| Pattern | Use |
+| --- | --- |
+| **Statistic** | Single value with label + optional delta/trend |
+| **AmountInput display** (read-only) | Editable monetary value |
+| **Progress** | Completion % with bar/ring |
+| **Chart** | Time-series or comparison data |
+| **Card with body text** | Number is part of a paragraph |
+
+Use Statistic when the number is the message. The label, delta, and unit are supporting cast.
+
+## Anatomy
+
+```
+┌──────────────────────────────┐
+│ 이번 달 매출                   │ ← label
+│                              │
+│ ₩2,847,500                   │ ← value (display tier, tabular numerals)
+│                              │
+│ ↑ 12% vs 지난 달               │ ← delta (optional, color-coded)
+└──────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| Label / title | yes | What this number is |
+| Value | yes | The number itself, formatted |
+| Prefix / suffix | optional | Currency symbol, unit |
+| Delta indicator | optional | Trend arrow + comparison ("↑ 12%") |
+| Tooltip / icon | optional | "i" icon for definition |
+| Trend chart (sparkline) | optional | Tiny line chart inline |
+
+## API
+
+```tsx
+<Statistic
+  label="이번 달 매출"
+  value={2847500}
+  prefix="₩"
+  precision={0}
+  delta={{ value: 0.12, period: "지난 달 대비" }}
+/>
+
+<Statistic
+  label="활성 사용자"
+  value={1247}
+  delta={{ value: -0.03, period: "지난 주" }}
+  variant="compact"
+/>
+
+<Statistic
+  label="응답 시간"
+  value={328}
+  suffix="ms"
+  delta={{ value: -0.15, period: "지난 시간", goalDirection: "down" }}
+/>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string \| ReactNode` | — | Required. What the number is. |
+| `value` | `number \| string` | — | Required. The number (or pre-formatted string). |
+| `prefix` | `string \| ReactNode` | — | E.g., `₩`, `$`, icon |
+| `suffix` | `string \| ReactNode` | — | E.g., `원`, `%`, `ms` |
+| `precision` | `number` | `0` (KRW) / `2` (USD/EUR) | Decimal places |
+| `groupSeparator` | `string` | `,` | Thousands separator |
+| `decimalSeparator` | `string` | `.` | |
+| `delta` | `Delta` | — | Comparison indicator |
+| `variant` | `"default" \| "compact"` | `"default"` | |
+| `size` | `"sm" \| "md" \| "lg" \| "xl"` | `"lg"` | Value font size |
+| `loading` | `boolean` | `false` | Skeleton |
+| `tooltip` | `string` | — | Hover definition (small `i` icon next to label) |
+| `sparkline` | `number[]` | — | Optional inline mini chart |
+
+```ts
+type Delta = {
+  value: number;            // 0.12 means +12%; -0.03 means -3%
+  period: string;           // "지난 달 대비" / "vs last month"
+  goalDirection?: "up" | "down" | "neutral";  // up=positive trend
+};
+```
+
+## Sizes
+
+| Size | Value font | Label | Use |
+| --- | --- | --- | --- |
+| `sm` | 18px | 12px | Sidebar, dashboard tile inside a card |
+| `md` | 24px | 13px | Standard KPI card |
+| `lg` (default) | 32px | 14px | Hero KPI in a dashboard |
+| `xl` | 48px | 16px | Single hero stat (account balance display) |
+
+For account balance / hero amounts: `xl` with `tnum` font feature for tabular numerals.
+
+## Delta — color and direction semantics
+
+The delta value's color depends on whether the trend is "good":
+
+```ts
+const goodTrend = delta.goalDirection === "up" ? delta.value > 0 : delta.value < 0;
+const color = goodTrend ? "money-positive" : "money-negative";
+```
+
+| Stat | `goalDirection` | Positive delta = | Color |
+| --- | --- | --- | --- |
+| Revenue | `up` | Good | `money-positive` (green or red KR-stocks) |
+| Errors / latency | `down` | Bad | `money-negative` |
+| Conversion rate | `up` | Good | `money-positive` |
+| Bounce rate | `down` | Bad | `money-negative` |
+| Active users | `up` | Good | `money-positive` |
+
+Default: `up`. Most metrics are "more is better".
+
+For Korean stock UIs: see [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — color convention is inverted (red=up).
+
+### Delta visual
+
+```
+↑ 12% vs 지난 달          ← positive trend, good direction (green/red)
+↓ 3% vs 지난 주            ← negative trend, color depends on goalDirection
+─ vs 지난 달               ← no change (gray)
+```
+
+Delta arrows: `↑` `↓` are most common. Some apps use `▲` `▼` for stocks.
+
+## Variants
+
+### Default
+
+Vertical stack: label top, value middle, delta bottom.
+
+### Compact
+
+Single line: `Label  Value  ±Delta`.
+
+```
+이번 달 매출    ₩2,847,500    ↑ 12%
+```
+
+Use in dense table cells, sidebar lists.
+
+### Hero
+
+`xl` size, often with sparkline inline:
+
+```
+Account balance
+₩2,847,500     ▁▂▃▅▆▇  ← sparkline
+↑ 12% 이번 달
+```
+
+## Tokens consumed
+
+```
+--color-text-primary
+--color-text-secondary           (label)
+--color-text-tertiary
+--color-money-positive            (good delta)
+--color-money-negative            (bad delta)
+--color-money-neutral             (no change)
+--space-xs, --space-sm
+--font-size-base, --font-size-xl, --font-size-2xl
+--font-feature-amount: 'tnum' 1   (tabular numerals)
+--font-weight-semibold (value)
+--font-weight-regular (label)
+```
+
+## Sparkline (inline mini chart)
+
+When passed `sparkline`:
+- Renders a small line chart inside the Statistic body.
+- Width: ~60–80px, height: 16–24px.
+- Single line, no axes, no labels — just shape.
+- Color matches the delta direction (or stays neutral).
+
+For libraries: `react-sparklines`, `recharts` mini variant, or hand-roll an SVG.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Resting |
+| Loading | Skeleton placeholders for label + value |
+| No data / undefined | Show `—` or "—" instead of "0" — clarifies vs zero |
+| Error | "—" + tooltip explaining failure |
+
+## Accessibility
+
+- Label is associated with value via DOM proximity (no special wiring needed for static stats).
+- Numeric value: `aria-label="이번 달 매출 ₩2,847,500"` if the visual format is hard for screen readers.
+- Delta: also include in aria-label — "12% increase vs last month".
+- Don't rely on color alone for delta direction — the arrow does the work.
+
+```html
+<div class="statistic">
+  <div class="label">이번 달 매출</div>
+  <div class="value" aria-label="이번 달 매출 290만 원, 지난 달 대비 12% 증가">
+    ₩2,847,500
+  </div>
+  <div class="delta delta--positive" aria-hidden="true">↑ 12%</div>
+</div>
+```
+
+## Code example
+
+```tsx
+// Hero balance
+<Statistic
+  label="사용 가능 금액"
+  value={user.balance}
+  prefix="₩"
+  size="xl"
+  delta={{ value: 0.04, period: "이번 달", goalDirection: "up" }}
+/>
+
+// KPI grid
+<div className="grid grid-cols-1 md:grid-cols-4 gap-4">
+  <Card><Statistic label="신규 가입" value={47} delta={{ value: 0.18, period: "지난 주" }} /></Card>
+  <Card><Statistic label="활성 사용자" value={1247} delta={{ value: -0.03, period: "지난 주" }} /></Card>
+  <Card><Statistic label="평균 응답 시간" value={328} suffix="ms" delta={{ value: -0.15, period: "지난 시간", goalDirection: "down" }} /></Card>
+  <Card><Statistic label="에러율" value={0.012} suffix="%" delta={{ value: 0.005, period: "지난 시간", goalDirection: "down" }} precision={3} /></Card>
+</div>
+
+// Compact in a sidebar
+<aside>
+  <Statistic variant="compact" label="잔액" value={user.balance} prefix="₩" />
+  <Statistic variant="compact" label="활동 수" value={user.activityCount} />
+</aside>
+
+// Loading state
+<Statistic loading label="이번 달 매출" />
+
+// No data
+<Statistic label="평균 응답 시간" value="—" />
+```
+
+## Edge cases
+
+- **Zero value with no delta**: render as `0` with no trend indicator.
+- **Negative value** (loss, debt): use `--color-money-negative` for the value, optionally show `−` prefix.
+- **Very large numbers** (1조+): display normally with separators; for hero contexts, consider Korean compact form ("1.2조원" instead of "1,200,000,000,000원").
+- **Currency symbol with locale**: `₩` for KRW, `$` for USD; respect the user's locale preference.
+- **Sparkline with insufficient data** (< 2 points): hide sparkline.
+- **Delta of exactly 0**: render `─ vs 지난 달` (no arrow).
+- **Time-period without comparison data**: omit delta entirely.
+- **Stat that's a fraction** ("12 of 50"): render as compound — `<Statistic value="12 / 50" />` rather than just 12.
+
+## Don't
+
+- Don't put 10+ Statistics in one row. 4–6 max for a KPI grid.
+- Don't use Statistic for non-numeric "stats" like "Most popular: Coffee" — that's a Card with body text.
+- Don't auto-update Statistic without a visual cue. Number-tick animations are OK; flashes are not.
+- Don't use `--color-error` for negative-trend values. Use `--color-money-negative`.
+- Don't show delta for static values that don't change (e.g., "Member since 2024-01-15").
+- Don't omit the label. "₩2,847,500" alone is unintelligible.
+- Don't use proportional numerals — use tabular for column alignment.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/statistic/`](../refs/ant-design/components/statistic/) — `Statistic` + `Statistic.Countdown` (auto-counting). Solid baseline.
+- MUI: no dedicated component — compose `<Card><CardContent><Typography variant="overline">label</Typography>...`.
+- shadcn-ui: no built-in. Compose from `Card` + Tailwind.
+
+API choices made:
+- **`delta` as a structured prop** rather than rendered string: enables consistent color/arrow logic.
+- **`goalDirection` opt-in**: most metrics are "up = good"; let consumer flip when needed.
+- **Tabular numerals enforced** via `font-feature-settings`: KPI grids align cleanly.
+
+## Cross-reference
+
+- [`knowledge/patterns/money-and-amount.md`](../knowledge/patterns/money-and-amount.md) — money color semantics + tabular numerals
+- [`knowledge/patterns/dashboard-composition.md`](../knowledge/patterns/dashboard-composition.md) — placing Statistics in a dashboard
+- [`examples/component-card.md`](component-card.md) — wrapping Statistic in a Card
+- [`examples/component-progress.md`](component-progress.md) — alternative for completion-style metrics

package/examples/component-step-button.md

@@ -0,0 +1,157 @@
+# `StepButton` - spec
+
+> Direct upstream component: MUI `StepButton`. Parent pattern references: Ant Design `Steps`, MUI `Stepper`, and composed shadcn-style primitives.
+
+## Purpose
+
+`StepButton` makes a step indicator clickable in non-linear steppers. Use it when users may revisit completed steps, fix validation errors, or jump between sections in a wizard.
+
+Do not use it when the flow must be strictly linear. Future steps should remain unavailable until prerequisites are satisfied.
+
+## Anatomy
+
+```
+StepButton
+├── Root button
+│   ├── StepIcon        optional override
+│   ├── StepLabel       text/content
+│   └── Optional text   optional helper, e.g. "선택"
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root button | yes | Receives focus and activates navigation to the step. |
+| Icon | optional | Overrides the default number/check/error icon. |
+| Label | yes | Names the step. |
+| Optional node | optional | Marks optional/skipped status. |
+
+## API
+
+```tsx
+<Step completed={isCompleted}>
+  <StepButton onClick={() => goToStep(index)} optional={<Text size="sm">선택</Text>}>
+    결제 수단
+  </StepButton>
+</Step>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Usually `StepLabel` or label content passed into `StepLabel`. |
+| `classes` | `Partial<StepButtonClasses>` | - | Style override hooks for MUI-style implementations. |
+| `component` | `React.ElementType` | MUI `ButtonBase` default | Root override. Must preserve button semantics. |
+| `icon` | `ReactNode` | Step index from parent | Icon displayed by the step label. |
+| `optional` | `ReactNode` | - | Secondary optional/skipped content below or beside label. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+Inherits button-like props from MUI `ButtonBase`. In MUI, `disabled` is controlled by step context rather than the `StepButton` prop surface.
+
+## API choices made
+
+- Keep `StepButton` as a child of `Step`. Status and disabled logic should come from the parent stepper.
+- Expose `optional` because multi-step forms often need visible "선택" or "건너뜀" context.
+- Do not add `status` here. Status belongs to `Step`, `StepLabel`, or the parent `Steps` model.
+- Do not use anchors for wizard navigation unless the route actually changes.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Wait | Future or incomplete step | Muted label and neutral icon. |
+| Process | Current active step | Primary icon/label; set current-step semantics. |
+| Finish | Completed step | Check icon or completed marker; remains clickable if revisiting is allowed. |
+| Error | Step has validation error | Error icon and text label; do not rely on color alone. |
+| Hover | Pointer over enabled step | Subtle background or label emphasis. |
+| Focus-visible | Keyboard focus | 2px focus ring around the whole button, not only the icon. |
+| Active | Press | Pressed background; no layout shift. |
+| Disabled | Future locked step | Muted, non-clickable, `aria-disabled` if not native disabled. |
+| Loading | Step validation pending | Small spinner near label/icon; suppress repeated activation. |
+
+## Tokens consumed
+
+```
+--color-primary-default
+--color-error
+--color-text-primary
+--color-text-secondary
+--color-text-disabled
+--color-bg-subtle
+--color-border-default
+--color-focus-ring
+--space-xs
+--space-sm
+--space-md
+--radius-md
+--motion-fast
+```
+
+## Accessibility
+
+- Render a native `<button type="button">` when the step does not navigate to a new route.
+- The active step must be announced as current. Use `aria-current="step"` on the current step item or button, consistently with the parent `Steps` implementation.
+- Disabled future steps use native `disabled` where possible; custom roots need `aria-disabled="true"` and no activation.
+- Error steps need text in the accessible name, such as "오류: 결제 수단".
+- Touch target must be at least 44x44 on mobile.
+- The connector line remains `aria-hidden`; the button owns only the step label/icon.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Moves through enabled clickable steps in order. |
+| `Enter` / `Space` | Activates the focused step. |
+| Arrow keys | Optional parent-level roving behavior when the stepper is implemented as a tablist. |
+
+## Code example
+
+```tsx
+<Steps current={currentStep} clickable onChange={setCurrentStep}>
+  {steps.map((step, index) => (
+    <Step
+      key={step.id}
+      completed={index < currentStep && !step.hasError}
+      disabled={index > highestReachableStep}
+      status={step.hasError ? "error" : undefined}
+    >
+      <StepButton
+        aria-current={index === currentStep ? "step" : undefined}
+        onClick={() => setCurrentStep(index)}
+        optional={step.optional ? <Text size="sm">선택</Text> : undefined}
+      >
+        {step.label}
+      </StepButton>
+    </Step>
+  ))}
+</Steps>
+```
+
+## Edge cases
+
+- **User jumps back and edits**: mark later dependent steps as needing review if their data becomes stale.
+- **Future step disabled**: keep it visible so progress is understandable, but suppress focus/activation.
+- **Validation error in completed step**: keep the step clickable and expose error text in the label.
+- **Vertical stepper**: root button can fill width for easier scanning and larger touch target.
+- **Custom component root**: must forward refs, keyboard events, disabled state, and focus-visible styles.
+- **Long Korean labels**: allow two-line labels in vertical mode; truncate in compact horizontal mode with tooltip only if necessary.
+- **Reduced motion**: remove animated icon transitions; state changes still occur.
+
+## Don't
+
+- Don't make future locked steps clickable.
+- Don't use `StepButton` for a decorative progress indicator.
+- Don't put form fields inside the button.
+- Don't encode error/completed state only with icon color.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/StepButton/StepButton.d.ts`](../refs/mui/packages/mui-material/src/StepButton/StepButton.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/StepButton/StepButton.js`](../refs/mui/packages/mui-material/src/StepButton/StepButton.js)
+- MUI stepper docs/examples: [`refs/mui/docs/data/material/components/steppers/`](../refs/mui/docs/data/material/components/steppers/)
+- Ant Design parent pattern: [`refs/ant-design/components/steps/`](../refs/ant-design/components/steps/)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+
+## Cross-reference
+
+- [examples/component-steps.md](component-steps.md)
+- [examples/component-step-label.md](component-step-label.md)
+- [examples/component-step-icon.md](component-step-icon.md)