@design-ai/cli 4.55.0

package/examples/component-step-connector.md

@@ -0,0 +1,157 @@
+# `StepConnector` - spec
+
+> Direct upstream component: MUI `StepConnector`. Parent pattern references: Ant Design `Steps`, MUI `Stepper`, and composed shadcn-style primitives.
+
+## Purpose
+
+`StepConnector` draws the visual line between steps in a stepper. It communicates sequence and completed progress, but it is not interactive and should not be announced by assistive technology.
+
+Use it only inside a `Steps` / `Stepper` composition.
+
+## Anatomy
+
+```
+Step
+└── StepIcon
+    |
+    |  StepConnector
+    |
+Step
+└── StepIcon
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root | yes | Positions the connector between adjacent steps. |
+| Line | yes | Visual track for wait/active/completed state. |
+| State classes | contextual | Active, completed, disabled, orientation, and alternative-label states come from parent context. |
+
+## API
+
+```tsx
+<Stepper connector={<StepConnector />}>
+  <Step>
+    <StepLabel>본인인증</StepLabel>
+  </Step>
+  <Step>
+    <StepLabel>정보 입력</StepLabel>
+  </Step>
+</Stepper>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `classes` | `Partial<StepConnectorClasses>` | - | Style override hooks for MUI-style implementations. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+`children` is intentionally omitted in MUI. This component renders the connector structure itself.
+
+## API choices made
+
+- Keep the API minimal. Connector state is derived from parent stepper context.
+- Do not add `status`, `orientation`, or `completed` props to the public API unless building a standalone custom connector.
+- Do not expose content slots. A connector is decorative, not a label surface.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Wait | Neither adjacent step is completed/current | Neutral border/line color. |
+| Active | Adjacent current step | Primary or emphasized line segment if the product wants active progress. |
+| Completed | Previous step completed | Primary filled line. |
+| Error | Adjacent step has error | Error line only when it helps locate the failing step; pair with error text on the step label. |
+| Disabled | Parent step disabled | Muted connector. |
+| Horizontal | Parent orientation | Line runs inline between indicators. |
+| Vertical | Parent orientation | Line runs block direction below the indicator. |
+| Alternative label | Parent layout | Connector positions behind labels and aligns to indicator centers. |
+
+## Tokens consumed
+
+```
+--color-border-default
+--color-primary-default
+--color-error
+--color-text-disabled
+--space-sm
+--space-md
+--step-icon-size-sm
+--step-icon-size-md
+--step-connector-thickness
+--motion-fast
+```
+
+If step-specific tokens do not exist, map to the existing border, size, and spacing tokens.
+
+## Accessibility
+
+- Connector is decorative: set `aria-hidden="true"` and keep it out of the tab order.
+- Do not encode step status only in connector color. `StepLabel` or the parent list must expose completed/current/error text.
+- In high contrast mode, connector should remain visible through border/outline properties.
+- Touch target requirements do not apply because the connector is not interactive.
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Thickness | 1px default; 2px only for high-emphasis progress flows. |
+| Horizontal | Flexible line between step indicators; do not force fixed width. |
+| Vertical | Minimum height should preserve spacing between labels. |
+| Last step | No trailing connector after the final step. |
+| RTL | Use logical inline properties; horizontal connector mirrors automatically. |
+
+## Code example
+
+```tsx
+function CheckoutConnector(props: StepConnectorProps) {
+  return (
+    <StepConnector
+      {...props}
+      aria-hidden="true"
+      className="checkout-step-connector"
+    />
+  );
+}
+
+<Steps current={currentStep} connector={<CheckoutConnector />}>
+  <Step completed>
+    <StepLabel>장바구니</StepLabel>
+  </Step>
+  <Step>
+    <StepLabel>배송 정보</StepLabel>
+  </Step>
+  <Step>
+    <StepLabel>결제</StepLabel>
+  </Step>
+</Steps>
+```
+
+## Edge cases
+
+- **One step only**: render no connector.
+- **Skipped optional step**: connector after the skipped step should follow the chosen status model, usually completed if the flow can advance.
+- **Error step**: show error on the step icon/label first; connector color is secondary.
+- **Vertical labels with long copy**: connector height should follow layout, not overlap label text.
+- **Alternative label layout**: align connector to icon centers, not label baselines.
+- **Reduced motion**: avoid animated line filling. State changes can switch instantly.
+- **Print**: connectors should remain visible in grayscale; avoid relying on primary color alone.
+
+## Don't
+
+- Don't make the connector clickable.
+- Don't place text or icons inside the connector line.
+- Don't show a connector after the final step.
+- Don't use connector color as the only indication of completed/error state.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/StepConnector/StepConnector.d.ts`](../refs/mui/packages/mui-material/src/StepConnector/StepConnector.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/StepConnector/StepConnector.js`](../refs/mui/packages/mui-material/src/StepConnector/StepConnector.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-icon.md](component-step-icon.md)
+- [examples/component-step-label.md](component-step-label.md)

package/examples/component-step-content.md

@@ -0,0 +1,121 @@
+# `StepContent` — spec
+
+> Synthesized from MUI `StepContent`. The body region under a vertical-orientation `Step`. Renders the step's actual form / instruction / control panel. Only used with `<Stepper orientation="vertical">`.
+
+## When to use
+
+- Vertical-orientation steppers (each step has expanded body content).
+- Mobile onboarding flows where steps stack vertically.
+- For horizontal steppers, render content separately below the stepper.
+
+## API
+
+```tsx
+<Stepper activeStep={step} orientation="vertical">
+  <Step>
+    <StepLabel>이메일 입력</StepLabel>
+    <StepContent>
+      <TextField fullWidth label="이메일" />
+      <Stack direction="row" gap={1} sx={{ mt: 2 }}>
+        <Button onClick={handleNext} variant="contained">다음</Button>
+      </Stack>
+    </StepContent>
+  </Step>
+</Stepper>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Step body content |
+| `transitionDuration` | `number \| 'auto'` | `'auto'` | Collapse animation |
+| `TransitionComponent` | `Component` | `Collapse` | Custom transition |
+| `TransitionProps` | `TransitionProps` | — | Pass-through |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Active step | Content expanded |
+| Inactive step | Content collapsed (animated) |
+
+## Tokens consumed
+
+```
+--space-md                  /* horizontal padding */
+--space-md-y                /* vertical padding */
+--motion-duration-auto
+--step-connector-line       /* left vertical rule */
+```
+
+## Accessibility
+
+- Hidden content is `aria-hidden` when collapsed.
+- Focus moves into the active step's content automatically when activeStep changes.
+- For long step content with internal scrolling, the parent step should handle scroll-into-view.
+
+## Edge cases
+
+- **Form validation per step** — show errors inline AND prevent progression to next step. Keep current `StepContent` expanded until valid.
+- **Long content (10+ form fields)** — that's a multi-screen flow, not a vertical stepper. Switch to a separate page per step.
+- **Mobile narrow viewport** — vertical orientation works well; ensure step labels and content fit at 320px.
+
+## Code example
+
+```tsx
+function VerticalOnboarding() {
+  const [step, setStep] = useState(0);
+  const totalSteps = 3;
+
+  return (
+    <Stepper activeStep={step} orientation="vertical">
+      <Step>
+        <StepLabel>기본 정보</StepLabel>
+        <StepContent>
+          <Stack gap={2}>
+            <TextField label="이름" />
+            <TextField label="이메일" />
+            <Stack direction="row" gap={1}>
+              <Button onClick={() => setStep(1)} variant="contained">
+                다음
+              </Button>
+            </Stack>
+          </Stack>
+        </StepContent>
+      </Step>
+      <Step>
+        <StepLabel>비밀번호</StepLabel>
+        <StepContent>
+          <TextField fullWidth label="비밀번호" type="password" />
+          <Stack direction="row" gap={1} sx={{ mt: 2 }}>
+            <Button onClick={() => setStep(0)}>이전</Button>
+            <Button onClick={() => setStep(2)} variant="contained">다음</Button>
+          </Stack>
+        </StepContent>
+      </Step>
+      <Step>
+        <StepLabel>완료</StepLabel>
+        <StepContent>
+          <Typography>가입이 완료됐어요.</Typography>
+          <Button variant="contained" sx={{ mt: 2 }}>시작하기</Button>
+        </StepContent>
+      </Step>
+    </Stepper>
+  );
+}
+```
+
+## Don't
+
+- Don't use with horizontal stepper — content won't render.
+- Don't omit Back/Next buttons — users need explicit progression controls.
+
+## References
+
+- MUI: [`StepContent`](../refs/mui/packages/mui-material/src/StepContent/)
+
+## Cross-reference
+
+- [`component-steps.md`](component-steps.md)
+- [`component-step.md`](component-step.md)
+- [`component-step-label.md`](component-step-label.md)
+- [`knowledge/patterns/b2b-onboarding-flows.md`](../knowledge/patterns/b2b-onboarding-flows.md)

package/examples/component-step-icon.md

@@ -0,0 +1,115 @@
+# `StepIcon` — spec
+
+> Synthesized from MUI `StepIcon`. The numbered/checked circle in a `Stepper` flow. Shows step number when upcoming/active, checkmark when complete, error icon when failed.
+
+## When to use
+
+- Inside `StepLabel` (auto-rendered by `Step` parent).
+- For custom step icons, override via `StepLabel.StepIconComponent`.
+
+## API
+
+```tsx
+<Step>
+  <StepLabel
+    StepIconComponent={CustomStepIcon}
+    error={hasError}
+  >
+    배송지 입력
+  </StepLabel>
+</Step>
+```
+
+`StepIcon` is rarely used directly — `Step` + `StepLabel` render it automatically. Override only when you need a custom icon set.
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `icon` | `ReactNode` | step number | The icon content (number, custom component) |
+| `active` | `boolean` | `false` | Current step |
+| `completed` | `boolean` | `false` | Past step |
+| `error` | `boolean` | `false` | Step failed |
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Upcoming | outlined circle, step number, fg-muted |
+| Active | filled brand circle, step number, fg-on-brand, slightly larger |
+| Completed | filled brand circle, checkmark icon, fg-on-brand |
+| Error | filled error circle, X icon, fg-on-error |
+| Disabled | reduced opacity |
+
+## Tokens consumed
+
+```
+--step-icon-size-24
+--step-icon-bg-active           /* brand */
+--step-icon-bg-completed        /* brand */
+--step-icon-bg-error            /* error */
+--step-icon-bg-upcoming         /* transparent */
+--step-icon-border-upcoming     /* fg-muted */
+--step-icon-fg-on-brand
+--step-icon-fg-on-error
+--step-icon-fg-upcoming
+```
+
+## Accessibility
+
+- Decorative (the `StepLabel` text is the accessible name).
+- For error states, screen readers announce via `StepLabel.error` setting `aria-invalid` on the step.
+
+## Edge cases
+
+- **Long stepper (8+ steps)** — number-in-circle becomes hard to read; switch to `MobileStepper` (dots/progress) for mobile.
+- **Custom icons per step** (e.g., shopping cart → payment → confirmation) — override `StepIconComponent` per `StepLabel`. Different icons signal step *type*, not just step *number*.
+
+## Code example
+
+```tsx
+function CartStepper({ activeStep }) {
+  const steps = [
+    { label: '장바구니', icon: <CartIcon /> },
+    { label: '결제 정보', icon: <CardIcon /> },
+    { label: '주문 확인', icon: <CheckIcon /> },
+  ];
+
+  return (
+    <Stepper activeStep={activeStep} alternativeLabel>
+      {steps.map((step, idx) => (
+        <Step key={step.label}>
+          <StepLabel
+            StepIconComponent={({ active, completed }) => (
+              <Avatar
+                sx={{
+                  bgcolor: completed ? 'success.main' : active ? 'primary.main' : 'grey.300',
+                  width: 32,
+                  height: 32,
+                }}
+              >
+                {step.icon}
+              </Avatar>
+            )}
+          >
+            {step.label}
+          </StepLabel>
+        </Step>
+      ))}
+    </Stepper>
+  );
+}
+```
+
+## Don't
+
+- Don't render directly outside `StepLabel`.
+- Don't use icons that don't communicate progress (e.g., decorative-only flowers).
+
+## References
+
+- MUI: [`StepIcon`](../refs/mui/packages/mui-material/src/StepIcon/)
+
+## Cross-reference
+
+- [`component-step.md`](component-step.md)
+- [`component-step-label.md`](component-step-label.md)
+- [`component-steps.md`](component-steps.md)

package/examples/component-step-label.md

@@ -0,0 +1,101 @@
+# `StepLabel` — spec
+
+> Synthesized from MUI `StepLabel`. The text label of a `Step` — primary text + optional caption. Combines `StepIcon` + label into the standard step appearance.
+
+## When to use
+
+- Inside every `Step` that has a visible label.
+- For step-only-by-position (rare), use `Step` without `StepLabel`.
+
+## API
+
+```tsx
+<Step>
+  <StepLabel
+    optional={<Typography variant="caption">선택</Typography>}
+    error={!!stepErrors[currentStep]}
+  >
+    배송지 정보
+  </StepLabel>
+</Step>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Primary label |
+| `icon` | `ReactNode` | step number | Override icon |
+| `optional` | `ReactNode` | — | Caption beneath label (e.g., "Optional", "Required") |
+| `error` | `boolean` | `false` | Mark step as failed |
+| `StepIconComponent` | `ElementType` | `StepIcon` | Custom icon component |
+| `StepIconProps` | `StepIconProps` | — | Pass-through to icon |
+
+## States
+
+Inherited from parent `Step`:
+- Upcoming: muted text + outlined icon
+- Active: bold text + filled icon
+- Completed: regular text + checkmark icon
+- Error: error-colored text + error icon
+
+## Tokens consumed
+
+```
+--font-size-body
+--font-weight-medium       /* active */
+--font-weight-regular
+--color-fg-default
+--color-fg-muted
+--color-fg-error
+--space-sm                 /* gap between icon and label */
+```
+
+## Accessibility
+
+- The label is the accessible name of the step.
+- For `error={true}`, `aria-invalid="true"` propagates.
+- `optional` content is read after the primary label.
+- Korean step labels: keep concise (1-3 words). Long labels truncate.
+
+## Edge cases
+
+- **Korean honorific** — step labels use noun form ("배송지 입력") not sentence form ("배송지를 입력하세요").
+- **Optional steps** — set `optional={<Typography variant="caption">선택</Typography>}`. Don't bake "(선택)" into the primary label.
+- **Long labels in horizontal stepper** — switch to `<Stepper alternativeLabel>` so labels render below icons (more horizontal room).
+
+## Code example
+
+```tsx
+<Stepper activeStep={step} orientation="vertical">
+  <Step>
+    <StepLabel>이메일 인증</StepLabel>
+  </Step>
+  <Step>
+    <StepLabel
+      optional={<Typography variant="caption" color="text.secondary">선택</Typography>}
+    >
+      프로필 사진
+    </StepLabel>
+  </Step>
+  <Step>
+    <StepLabel error={!!errors.payment}>
+      결제 정보
+    </StepLabel>
+  </Step>
+</Stepper>
+```
+
+## Don't
+
+- Don't put block-level content inside the label — break composition.
+- Don't omit error state when a step actually failed — silent failure is confusing.
+
+## References
+
+- MUI: [`StepLabel`](../refs/mui/packages/mui-material/src/StepLabel/)
+
+## Cross-reference
+
+- [`component-step.md`](component-step.md)
+- [`component-step-icon.md`](component-step-icon.md)
+- [`component-steps.md`](component-steps.md)
+- [`knowledge/patterns/onboarding.md`](../knowledge/patterns/onboarding.md)

package/examples/component-step.md

@@ -0,0 +1,84 @@
+# `Step` — spec
+
+> Synthesized from MUI `Step`. A single step in a `Steps` / `Stepper` flow. Sub-component spec for completeness; in practice, use [`component-steps.md`](component-steps.md) for the full Stepper pattern.
+
+## API
+
+```tsx
+<Steps current={1}>
+  <Step title="배송지 입력" />
+  <Step title="결제 수단" status="active" />
+  <Step title="주문 확인" status="upcoming" />
+</Steps>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `string` | required | Step label |
+| `description` | `string` | — | Sub-label |
+| `status` | `"complete" \| "active" \| "upcoming" \| "error"` | derived | Visual state |
+| `icon` | `ReactNode` | — | Custom icon override |
+| `disabled` | `boolean` | `false` | Disabled |
+
+## States
+
+| Status | Visual |
+| --- | --- |
+| `complete` | Filled circle + check icon, brand color |
+| `active` (current) | Filled circle + step number, brand color, larger |
+| `upcoming` | Outline circle + step number, muted |
+| `error` | Filled circle + X icon, error color |
+
+## Connector lines
+
+Between Step instances, render a connector line indicating progress:
+- Complete → Active: solid brand color line.
+- Active → Upcoming: muted line.
+- Error: red dashed.
+
+This is handled by the parent `Steps` component, not Step itself.
+
+## Tokens consumed
+
+```
+--step-circle-bg-complete
+--step-circle-bg-active
+--step-circle-bg-upcoming
+--step-circle-bg-error
+--step-fg-complete
+--step-connector-complete
+--step-connector-incomplete
+--space-sm
+--font-size-sm
+```
+
+## Accessibility
+
+- Each Step: `<li>` (parent is `<ol role="list">`).
+- Step status communicated via `aria-current="step"` (active) or text label.
+- Don't rely on color alone — include icon (check / X / number).
+
+## Code example
+
+```tsx
+<Steps current={2}>
+  <Step title="배송지" description="입력 완료" />
+  <Step title="결제" description="진행 중" />
+  <Step title="확인" />
+  <Step title="완료" />
+</Steps>
+```
+
+## Don't
+
+- Don't ship Step without parent Steps. Step is a sub-component.
+- Don't use Step for non-sequential UI. Use Tabs or Pagination instead.
+
+## References
+
+- MUI: [`Step`](../refs/mui/packages/mui-material/src/Step)
+- Ant: [`Steps`](../refs/ant-design/components/steps) (parent)
+
+## Cross-reference
+
+- [`examples/component-steps.md`](component-steps.md) — full Stepper spec