@design-ai/cli 4.55.0

package/examples/component-accordion-actions.md

@@ -0,0 +1,153 @@
+# `AccordionActions` - spec
+
+> Direct upstream component: MUI `AccordionActions`. Parent pattern references: Ant Design `Collapse`, MUI `Accordion`, shadcn-ui `accordion`.
+
+## Purpose
+
+`AccordionActions` is the optional action row at the bottom of an expanded accordion panel. Use it for commands that apply only to the content inside that one panel, such as "Save section", "Reset", or "Learn more".
+
+Do not use it for page-level actions. Page-level Save / Cancel belongs in the form footer or sticky page action bar.
+
+## Anatomy
+
+```
+Accordion.Item
+├── AccordionSummary          required; button that expands/collapses
+├── AccordionDetails          required; body content
+└── AccordionActions          optional; scoped commands for this panel
+    ├── Secondary action      optional
+    └── Primary action        optional
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root | yes | Non-interactive row container. |
+| Action item | no | Usually `Button`, `IconButton`, or link-styled command. |
+| Alignment | yes | End-align actions in LTR; start/end flips in RTL via logical CSS. |
+
+## API
+
+```tsx
+<Accordion.Item value="billing">
+  <Accordion.Summary>결제 정보</Accordion.Summary>
+  <Accordion.Details>
+    <BillingFields />
+  </Accordion.Details>
+  <Accordion.Actions>
+    <Button variant="ghost">초기화</Button>
+    <Button>저장</Button>
+  </Accordion.Actions>
+</Accordion.Item>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Action controls rendered in the row. |
+| `classes` | `Partial<AccordionActionsClasses>` | - | Style override hooks for MUI-style implementations. |
+| `disableSpacing` | `boolean` | `false` | Removes the default horizontal gap between action children. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+## API choices made
+
+- Keep the component as a thin container. It should not own action state, validation, or submit logic.
+- Keep `disableSpacing` because MUI exposes it and dense admin forms sometimes need custom spacing.
+- Do not add `align` unless product usage proves it is needed. End alignment is the default for commit/cancel rows.
+- Do not add a `primaryAction` prop. Composition keeps button order, disabled state, and loading state explicit.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Default | Expanded parent panel | Top padding separates actions from body; row uses `display: flex`, `justify-content: flex-end`, gap token. |
+| Hover | Mouse over child action | Container does not change; child action handles hover. |
+| Focus-visible | Keyboard focus on child action | Child action shows a 2px focus ring with at least 3:1 contrast against the row background. |
+| Active | Press child action | Child action handles pressed state. |
+| Disabled | Child action disabled | Container unchanged; disabled action uses its own muted style and `aria-disabled` when not a native disabled control. |
+| Loading | Child action loading | Loading belongs to the action button, not the container. |
+| Error | Validation in panel | Show error near the field or panel summary; do not color the action row alone. |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-border-default
+--color-text-primary
+--color-focus-ring
+--space-sm
+--space-md
+--space-lg
+--radius-md
+```
+
+If the row has a divider, use `--color-border-default`; do not introduce a new hairline color.
+
+## Accessibility
+
+- Root element is normally a `<div>` or `<footer>` inside the panel. It does not need a landmark role.
+- If there are 3+ related commands, set `aria-label` on the row, for example `aria-label="결제 정보 작업"`.
+- Keyboard order follows DOM order: accordion summary, details focusables, action buttons.
+- Touch targets for actions must be at least 44x44 on mobile and 24x24 on desktop AA.
+- Focus ring is owned by the child controls, but must remain visible against `--color-bg-default`.
+- When the parent panel is collapsed, action controls must not remain tabbable.
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Direction | Row, wrap allowed only below 360px. |
+| Alignment | End aligned with logical `justify-content: flex-end`. |
+| Gap | `--space-sm` for dense; `--space-md` default. |
+| Padding | Match `AccordionDetails` horizontal padding. |
+| Divider | Optional top border when actions follow long content. |
+
+## Code example
+
+```tsx
+<Accordion type="multiple" defaultValue={["notifications"]}>
+  <Accordion.Item value="notifications">
+    <Accordion.Summary>알림 설정</Accordion.Summary>
+    <Accordion.Details>
+      <NotificationPreferenceFields />
+    </Accordion.Details>
+    <Accordion.Actions aria-label="알림 설정 작업">
+      <Button variant="ghost" onClick={resetNotificationPrefs}>
+        기본값으로 되돌리기
+      </Button>
+      <Button onClick={saveNotificationPrefs} loading={isSaving}>
+        저장
+      </Button>
+    </Accordion.Actions>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Edge cases
+
+- **Only one destructive action**: keep it visually separated from the primary action, and use the destructive button variant.
+- **Panel contains a form**: the action row may contain `type="submit"` only if it is inside the same `<form>`.
+- **Long localized labels**: allow buttons to wrap to two rows on narrow screens rather than shrinking below touch target size.
+- **Nested accordions**: avoid nested action rows. Move nested commands into the nested panel content.
+- **Collapsed state**: hidden actions must be removed from keyboard order via the parent accordion visibility strategy.
+- **RTL**: use logical start/end spacing so action order and alignment mirror predictably.
+- **Reduced motion**: no action-row-specific motion. Parent expand/collapse follows `Accordion` reduced-motion rules.
+
+## Don't
+
+- Don't put global page Save / Cancel only inside an accordion panel.
+- Don't render more than one primary action in the row.
+- Don't make the action row itself clickable.
+- Don't use the row to display validation errors without field-level error text.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/AccordionActions/AccordionActions.d.ts`](../refs/mui/packages/mui-material/src/AccordionActions/AccordionActions.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/AccordionActions/AccordionActions.js`](../refs/mui/packages/mui-material/src/AccordionActions/AccordionActions.js)
+- Parent MUI composition: [`refs/mui/packages/mui-material/src/Accordion/`](../refs/mui/packages/mui-material/src/Accordion/)
+- Ant Design parent pattern: [`refs/ant-design/components/collapse/`](../refs/ant-design/components/collapse/)
+- shadcn-ui parent pattern: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+
+## Cross-reference
+
+- [examples/component-accordion.md](component-accordion.md)
+- [examples/component-button.md](component-button.md)

package/examples/component-accordion-details.md

@@ -0,0 +1,147 @@
+# `AccordionDetails` - spec
+
+> Direct upstream component: MUI `AccordionDetails`. Parent pattern references: Ant Design `Collapse`, MUI `Accordion`, shadcn-ui `accordion`.
+
+## Purpose
+
+`AccordionDetails` is the body container for the expanded content of one accordion item. It holds text, forms, lists, or supporting controls that are disclosed by `AccordionSummary`.
+
+Use it when content is secondary until the user chooses to expand the section. Keep critical information visible outside the accordion.
+
+## Anatomy
+
+```
+Accordion.Item
+├── AccordionSummary       expands/collapses the section
+└── AccordionDetails       revealed body region
+    ├── Body content
+    ├── Inline controls
+    └── Optional nested layout
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root | yes | Body wrapper linked to the summary through the parent item. |
+| Content | yes | Any readable or interactive content. |
+| Region semantics | parent-owned | `role="region"` and labels usually belong to the collapsible content wrapper, not an inner styling div. |
+
+## API
+
+```tsx
+<Accordion.Item value="security">
+  <Accordion.Summary>보안</Accordion.Summary>
+  <Accordion.Details>
+    <p>2단계 인증과 로그인 알림을 관리합니다.</p>
+    <SecuritySettings />
+  </Accordion.Details>
+</Accordion.Item>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Body content for the expanded panel. |
+| `classes` | `Partial<AccordionDetailsClasses>` | - | Style override hooks for MUI-style implementations. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+## API choices made
+
+- Keep `AccordionDetails` layout-only. Expansion state, `aria-expanded`, and keyboard behavior stay on `AccordionSummary` / parent item.
+- Do not add `padding`, `variant`, or `scroll` props. Use parent accordion variants and tokenized CSS.
+- Do not make the details wrapper focusable by default. Focus should move to meaningful content inside.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Collapsed | Parent item closed | Details content is hidden and not keyboard reachable. |
+| Expanding | Parent item opens | Body follows parent expand motion; no separate fade unless specified by parent. |
+| Expanded | Parent item open | Content uses readable spacing and inherits text color. |
+| Focus-visible | Focusable child receives focus | Child shows visible focus; details wrapper remains neutral. |
+| Disabled | Parent item disabled | Details remain collapsed unless parent allows disabled expanded display; text is not independently disabled. |
+| Loading | Async content inside | Use skeleton or progress inside details, not on the wrapper. |
+| Error | Form/list error inside | Show error near the failing field/section and reflect status in summary if needed. |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-text-primary
+--color-text-secondary
+--color-border-default
+--color-focus-ring
+--space-sm
+--space-md
+--space-lg
+--radius-md
+--motion-default
+--easing-in-out
+```
+
+## Accessibility
+
+- The accordion content wrapper should have `id`, `role="region"` when the panel is substantial, and `aria-labelledby` pointing to the summary button.
+- Do not add a second unlabeled `region` inside `AccordionDetails`.
+- Hidden details must not leave form fields, links, or buttons in the tab order.
+- If content is short plain text, `role="region"` is optional; overusing regions makes screen-reader navigation noisy.
+- Keyboard behavior is inherited from the parent accordion: `Tab` enters visible focusable content, and `Enter` / `Space` toggles the summary.
+- Touch target rules apply to controls inside details: at least 44x44 on mobile.
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Padding | Match parent size: `sm` 12px, `md` 16px, `lg` 20px equivalent tokens. |
+| Text | Body text uses `--color-text-primary`; helper copy uses `--color-text-secondary`. |
+| Width | Fill parent item width. Avoid fixed widths inside details. |
+| Scroll | Prefer page scroll. Only create inner scroll if the panel is inside a constrained modal/drawer. |
+| Forms | Preserve field state across collapse unless product explicitly discards edits. |
+
+## Code example
+
+```tsx
+<Accordion type="single" collapsible defaultValue="account">
+  <Accordion.Item value="account">
+    <Accordion.Summary>계정 정보</Accordion.Summary>
+    <Accordion.Details>
+      <Stack gap="md">
+        <Text tone="secondary">
+          이름과 연락처는 본인인증 이후에만 변경할 수 있습니다.
+        </Text>
+        <AccountProfileFields />
+      </Stack>
+    </Accordion.Details>
+  </Accordion.Item>
+</Accordion>
+```
+
+## Edge cases
+
+- **Async body data**: render a skeleton inside the expanded details. Do not collapse the panel while loading.
+- **Form state**: keep fields mounted or persist their values before unmounting, otherwise collapse can discard edits.
+- **Very long content**: consider splitting into separate accordion items or a dedicated page.
+- **Nested accordions**: avoid by improving information architecture; if unavoidable, nested summaries must have distinct labels.
+- **Tables inside details**: ensure horizontal overflow is keyboard accessible and not clipped by the accordion item.
+- **High contrast mode**: body/background boundaries must remain visible through border or spacing, not color alone.
+- **Print**: print styles should expand important details or provide a clear "collapsed content omitted" rule.
+
+## Don't
+
+- Don't make `AccordionDetails` itself a button, link, or focus target.
+- Don't put critical CTAs only inside details.
+- Don't add independent expand/collapse logic inside the details wrapper.
+- Don't hide validation errors by collapsing the panel after submit.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/AccordionDetails/AccordionDetails.d.ts`](../refs/mui/packages/mui-material/src/AccordionDetails/AccordionDetails.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/AccordionDetails/AccordionDetails.js`](../refs/mui/packages/mui-material/src/AccordionDetails/AccordionDetails.js)
+- Parent MUI composition: [`refs/mui/packages/mui-material/src/Accordion/`](../refs/mui/packages/mui-material/src/Accordion/)
+- Ant Design parent pattern: [`refs/ant-design/components/collapse/`](../refs/ant-design/components/collapse/)
+- shadcn-ui parent pattern: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+
+## Cross-reference
+
+- [examples/component-accordion.md](component-accordion.md)
+- [knowledge/patterns/form-design.md](../knowledge/patterns/form-design.md)

package/examples/component-accordion-summary.md

@@ -0,0 +1,180 @@
+# `AccordionSummary` - spec
+
+> Direct upstream component: MUI `AccordionSummary`. Parent pattern references: Ant Design `Collapse`, MUI `Accordion`, shadcn-ui `accordion`.
+
+## Purpose
+
+`AccordionSummary` is the interactive header for one accordion item. It names the section, communicates whether the section is expanded, and toggles the associated details panel.
+
+This is the accessibility-critical part of the accordion. It must behave like a real button.
+
+## Anatomy
+
+```
+AccordionSummary
+├── Root button
+│   ├── Leading icon          optional
+│   ├── Content
+│   │   ├── Title             required
+│   │   └── Description       optional
+│   └── Expand icon wrapper   required visual affordance
+```
+
+| Part | Required | Purpose |
+| --- | --- | --- |
+| Root button | yes | Receives focus and toggles the panel. |
+| Title | yes | Short label for the section. |
+| Description | optional | Secondary context; keep to one line when possible. |
+| Expand icon | yes | Shows collapsed/expanded state visually. |
+| Leading icon | optional | Helps scan settings/category accordions. |
+
+## API
+
+```tsx
+<Accordion.Item value="privacy">
+  <Accordion.Summary expandIcon={<ChevronDownIcon aria-hidden="true" />}>
+    <Accordion.SummaryContent
+      title="개인정보"
+      description="프로필 공개 범위와 데이터 다운로드"
+    />
+  </Accordion.Summary>
+  <Accordion.Details>
+    <PrivacySettings />
+  </Accordion.Details>
+</Accordion.Item>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | - | Title/content rendered inside the summary button. |
+| `classes` | `Partial<AccordionSummaryClasses>` | - | Style override hooks for MUI-style implementations. |
+| `component` | `React.ElementType` | MUI default root | Overrides the root element. Must preserve button semantics. |
+| `expandIcon` | `ReactNode` | - | Visual expand/collapse indicator. Mark decorative icons `aria-hidden`. |
+| `slots` | `{ root?, content?, expandIconWrapper? }` | - | Slot component overrides for MUI-style implementations. |
+| `slotProps` | `{ root?, content?, expandIconWrapper? }` | - | Props forwarded to summary slots. |
+| `sx` | `SxProps<Theme>` | - | MUI system override. Prefer tokens for shared design-system code. |
+
+Inherits button-like props from MUI `ButtonBase` in MUI implementations.
+
+## API choices made
+
+- Treat `AccordionSummary` as a button first and a layout row second.
+- Keep `expandIcon` as a visual prop because Ant, MUI, and shadcn/Radix patterns all expose an expand affordance.
+- Prefer composition for title/description rather than `title` and `description` props; complex summaries often need badges or metadata.
+- Allow `component` only when semantics are preserved. A `<div>` without button behavior is not acceptable.
+
+## States
+
+| State | Trigger | Visual rule |
+| --- | --- | --- |
+| Collapsed | `aria-expanded="false"` | Title primary, icon points closed, details hidden. |
+| Expanded | `aria-expanded="true"` | Icon rotates or swaps, row may use subtle active background. |
+| Hover | Pointer over enabled summary | `--color-bg-subtle` background shift. |
+| Focus-visible | Keyboard focus | 2px focus ring with at least 3:1 contrast against background. |
+| Active | Press | Slight pressed background or transform-free pressed color. |
+| Disabled | Parent item disabled | Muted text/icon, no toggle, expose disabled state. |
+| Loading | Content inside panel loading | Summary may show a small trailing spinner, but still names the section. |
+| Error | Panel contains error | Add error badge/text in summary and keep color paired with label/icon. |
+
+## Tokens consumed
+
+```
+--color-bg-default
+--color-bg-subtle
+--color-text-primary
+--color-text-secondary
+--color-text-disabled
+--color-border-default
+--color-error
+--color-focus-ring
+--space-sm
+--space-md
+--space-lg
+--radius-md
+--motion-fast
+--easing-in-out
+```
+
+## Accessibility
+
+- Render a native `<button type="button">` whenever possible.
+- Set `aria-expanded="true|false"` on the summary button.
+- Set `aria-controls` to the details/content `id`.
+- The details/content wrapper sets `aria-labelledby` back to the summary button `id`.
+- Decorative expand icons use `aria-hidden="true"` and do not duplicate the label.
+- Disabled summaries should use native `disabled` when possible; custom roots need `aria-disabled="true"` and must suppress activation.
+- Minimum target: 44x44 on mobile, 24x24 on desktop AA.
+
+### Keyboard
+
+| Key | Behavior |
+| --- | --- |
+| `Tab` | Moves focus to each enabled summary in document order. |
+| `Enter` / `Space` | Toggles the focused summary. |
+| `ArrowUp` / `ArrowDown` | Optional parent-level shortcut to previous/next summary. |
+| `Home` / `End` | Optional parent-level shortcut to first/last summary. |
+
+## Layout rules
+
+| Rule | Value |
+| --- | --- |
+| Height | `sm` 40px, `md` 48px, `lg` 56px minimum. |
+| Title | Single line by default; wrap to two lines only for content-heavy admin UIs. |
+| Description | Secondary text, one line, truncates before the expand icon. |
+| Icon placement | Trailing in LTR; mirror with logical CSS in RTL. |
+| Expand motion | 150-200ms rotation; remove rotation for `prefers-reduced-motion`. |
+
+## Code example
+
+```tsx
+<Accordion.Item value="security" disabled={isLocked}>
+  <Accordion.Summary
+    id="security-summary"
+    aria-controls="security-panel"
+    expandIcon={<ChevronDownIcon aria-hidden="true" />}
+  >
+    <Stack gap="xs">
+      <Text weight="semibold">보안</Text>
+      <Text size="sm" tone={hasSecurityError ? "error" : "secondary"}>
+        {hasSecurityError ? "확인이 필요한 항목이 있습니다" : "2단계 인증과 로그인 알림"}
+      </Text>
+    </Stack>
+  </Accordion.Summary>
+  <Accordion.Details id="security-panel" aria-labelledby="security-summary">
+    <SecuritySettings />
+  </Accordion.Details>
+</Accordion.Item>
+```
+
+## Edge cases
+
+- **Long title**: wrap title before hiding the expand icon. The icon must remain visible.
+- **Icon-only summary**: avoid. If unavoidable, provide a specific `aria-label`.
+- **Summary contains badge/count**: ensure the accessible name stays concise and does not repeat decorative count text.
+- **Disabled but expanded**: allowed for read-only review states, but communicate why the row cannot be toggled.
+- **RTL**: chevron placement and rotation should mirror; use logical properties.
+- **Reduced motion**: state change remains instant; remove icon rotation animation.
+- **Error state**: do not rely on red alone. Add text such as "오류" or an error icon with accessible text.
+
+## Don't
+
+- Don't render the summary as a clickable `<div>` without native button behavior.
+- Don't put form fields or nested buttons inside the summary.
+- Don't hide the expand icon when the row is collapsible.
+- Don't use the summary as navigation to another page.
+
+## References
+
+- MUI direct source: [`refs/mui/packages/mui-material/src/AccordionSummary/AccordionSummary.d.ts`](../refs/mui/packages/mui-material/src/AccordionSummary/AccordionSummary.d.ts)
+- MUI implementation: [`refs/mui/packages/mui-material/src/AccordionSummary/AccordionSummary.js`](../refs/mui/packages/mui-material/src/AccordionSummary/AccordionSummary.js)
+- Parent MUI composition: [`refs/mui/packages/mui-material/src/Accordion/`](../refs/mui/packages/mui-material/src/Accordion/)
+- Ant Design parent pattern: [`refs/ant-design/components/collapse/`](../refs/ant-design/components/collapse/)
+- shadcn-ui parent pattern: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/accordion.tsx)
+- Accessibility baseline: [`knowledge/a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md)
+- Motion baseline: [`knowledge/motion/principles.md`](../knowledge/motion/principles.md)
+
+## Cross-reference
+
+- [examples/component-accordion.md](component-accordion.md)
+- [WAI-ARIA Accordion Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/accordion/)
+- [WAI-ARIA Disclosure Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/)