@design-ai/cli 4.55.0

package/examples/component-button-base.md

@@ -0,0 +1,190 @@
+# `ButtonBase` — spec
+
+> Synthesized from MUI `ButtonBase`, with public action-button guidance cross-checked against Ant Design `Button` and shadcn-ui `Button`. `ButtonBase` is a low-level interactive primitive for building design-system controls, not a product-facing component.
+
+## When to use
+
+- Building a new design-system primitive such as `IconButton`, `CardActionArea`, `ListItemButton`, `Tab`, `StepButton`, or a toolbar control.
+- You need native button/link semantics, focus-visible handling, disabled behavior, and optional press/ripple feedback without inheriting a visual Button style.
+- You are authoring a library layer where the consumer owns the visual treatment.
+
+When NOT to use:
+- Product actions such as "저장", "결제하기", or "삭제" — use `Button`.
+- Icon-only actions — use `IconButton` so the accessible name, size, and variant contract are already enforced.
+- Links inside body copy — use `Link`.
+- Toggle formatting controls — use `Toggle` / `ToggleGroup`.
+
+## Anatomy
+
+```
+ButtonBase
+├── Root interactive element (`button` by default)
+├── Focus-visible state bridge
+├── Optional TouchRipple layer
+└── Children
+```
+
+| Part | Purpose | Required | Default if omitted |
+| --- | --- | --- | --- |
+| Root | Receives events, disabled state, `tabIndex`, and semantic element choice. | yes | `<button type="button">` |
+| Focus-visible bridge | Applies keyboard-only focus state and exposes `onFocusVisible`. | yes | internal state/class |
+| TouchRipple | Optional visual feedback layer for pointer/keyboard press. | no | rendered unless ripple is disabled |
+| Children | The visual content supplied by the composed component. | no | empty interactive shell; avoid in product code |
+
+## API
+
+```tsx
+<ButtonBase
+  component="button"
+  type="button"
+  focusVisibleClassName="focus-visible"
+  onFocusVisible={handleFocusVisible}
+>
+  <span className="toolbar-button-content">정렬</span>
+</ButtonBase>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Visual content. The composed component must provide text or an accessible label. |
+| `component` | `React.ElementType` | `"button"` | Root element override. Use sparingly and preserve keyboard behavior. |
+| `href` | `string` | — | Switches the root toward link behavior in MUI's overload. |
+| `LinkComponent` | `React.ElementType` | `"a"` | Router-aware link component when `href` / `to` is present. |
+| `type` | `string` | `"button"` | Native button type. Keep the default unless submitting a form intentionally. |
+| `disabled` | `boolean` | `false` | Removes interaction. Non-native roots still need `aria-disabled` handling. |
+| `tabIndex` | `number` | `0` | Keyboard order override. Avoid positive values. |
+| `focusVisibleClassName` | `string` | — | Class applied for keyboard focus-visible styling. |
+| `onFocusVisible` | `(event) => void` | — | Fires when focus was reached through keyboard-like interaction. |
+| `action` | `ref` | — | Imperative handle; supports `focusVisible()`. |
+| `centerRipple` | `boolean` | `false` | Centers ripple instead of starting from pointer location. |
+| `focusRipple` | `boolean` | `false` | Adds keyboard-focus ripple feedback. |
+| `disableRipple` | `boolean` | `false` | Removes ripple. Must be paired with an explicit focus-visible visual. |
+| `disableTouchRipple` | `boolean` | `false` | Removes touch ripple while keeping other focus behavior. |
+| `TouchRippleProps` | `object` | — | Props passed to the ripple layer. Treat as advanced. |
+| `touchRippleRef` | `ref` | — | Imperative access to ripple actions. Treat as internal. |
+| `nativeButton` | `boolean` | inferred | Declares whether a custom component renders a real `<button>`. |
+| `sx` / `classes` | system styles | — | MUI-specific style extension points. Prefer local component tokens in this repo. |
+
+## API choices made
+
+- Keep `ButtonBase` **advanced/internal**. Product teams should rarely import it directly because it has no visible affordance by itself.
+- Preserve MUI's polymorphic `component` / `LinkComponent` model, but document it as a semantic responsibility: if the root is not a native button or anchor, the wrapper must recreate keyboard activation and ARIA state.
+- Do not expose visual variants here. Variants belong to composed controls (`Button`, `IconButton`, `Toggle`) so the primitive stays stable.
+- Treat ripple as optional decoration. Focus-visible is mandatory whether ripple is on or off.
+
+## States
+
+| State | Trigger | Visual / behavior |
+| --- | --- | --- |
+| Default | resting | Transparent reset; composed component owns size, color, and layout. |
+| Hover | pointer hover | Optional consumer style using `--color-bg-action-hover`; not defined by the base. |
+| Focus-visible | keyboard focus | 2px outline using `--color-focus-ring`, offset 2px, contrast at least 3:1 against adjacent surfaces. |
+| Active | pointer or keyboard press | Optional pressed layer or ripple; do not rely on motion alone. |
+| Disabled | `disabled` | Remove pointer activation, suppress ripple, expose disabled semantics. |
+| Link mode | `href` / `to` | Behaves as navigation; do not attach form-submit semantics. |
+
+## Tokens consumed
+
+`ButtonBase` itself should consume only primitive interaction tokens. Composed controls map these to real visual tokens.
+
+```css
+--color-focus-ring
+--color-bg-action-hover
+--color-bg-action-active
+--color-text-primary
+--space-1
+--space-2
+--radius-sm
+--motion-fast
+--easing-out
+```
+
+## Accessibility
+
+- **Semantic element**: default to `<button type="button">`; use `<a>` only for navigation.
+- **Keyboard**: `Tab` reaches the control, `Enter` and `Space` activate button semantics. Custom roots must implement both keys.
+- **Focus**: visible focus is non-negotiable. If `disableRipple` is true, add a separate focus-visible style; otherwise keyboard users lose the only visible cue.
+- **Disabled**: native `disabled` is enough for real buttons; custom roots need `aria-disabled="true"`, suppressed events, and removal from activation shortcuts.
+- **Touch target**: composed controls must provide at least 44x44 mobile hit area and at least 24x24 WCAG AA web target size.
+- **Name**: icon-only composition requires `aria-label`; decorative icons inside a text label need `aria-hidden="true"`.
+- **Toggle state**: expose `aria-pressed` only for two-state buttons. Do not put `aria-selected` on generic buttons.
+
+## Code example — design-system toolbar button
+
+```tsx
+type ToolbarButtonProps = {
+  label: string;
+  selected?: boolean;
+  disabled?: boolean;
+  onPress: () => void;
+  children: React.ReactNode;
+};
+
+export function ToolbarButton({
+  label,
+  selected = false,
+  disabled = false,
+  onPress,
+  children,
+}: ToolbarButtonProps) {
+  return (
+    <ButtonBase
+      type="button"
+      disabled={disabled}
+      aria-label={label}
+      aria-pressed={selected}
+      focusVisibleClassName="toolbar-button-focus-visible"
+      className="toolbar-button"
+      onClick={onPress}
+    >
+      {children}
+    </ButtonBase>
+  );
+}
+```
+
+```css
+.toolbar-button {
+  min-width: 44px;
+  min-height: 44px;
+  border-radius: var(--radius-sm);
+  color: var(--color-text-primary);
+}
+
+.toolbar-button:hover {
+  background: var(--color-bg-action-hover);
+}
+
+.toolbar-button[aria-pressed="true"] {
+  background: var(--color-bg-action-active);
+}
+
+.toolbar-button-focus-visible {
+  outline: 2px solid var(--color-focus-ring);
+  outline-offset: 2px;
+}
+```
+
+## Edge cases
+
+- **Inside a form**: omit `type` and a native button may submit unexpectedly in some wrappers. Keep `type="button"` for non-submit actions.
+- **Router links**: pass a router-aware `LinkComponent`, but keep anchor semantics when the action navigates.
+- **Disabled links**: anchors do not support native `disabled`; use `aria-disabled`, remove `href` or intercept activation, and keep the visual disabled state.
+- **Nested interactive children**: never put another button, input, select, or link inside `ButtonBase`.
+- **No ripple**: disabling ripple is fine for quiet UIs, but the focus-visible ring must still be explicit.
+- **Korean dense toolbars**: reduce visual padding if needed, but keep the hit target through invisible padding or `::before` hit area.
+
+## Don't
+
+- Don't import `ButtonBase` in product pages when `Button`, `IconButton`, or `Link` fits.
+- Don't render a `<div>` root unless you also implement role, tab stop, disabled suppression, and keyboard activation.
+- Don't remove focus outlines globally to make ripple the only state indicator.
+- Don't use ripple or pressed animation as the only selected-state signal.
+
+## References
+
+- MUI: [`ButtonBase.d.ts`](../refs/mui/packages/mui-material/src/ButtonBase/ButtonBase.d.ts), [`ButtonBase.js`](../refs/mui/packages/mui-material/src/ButtonBase/ButtonBase.js), [`useButtonBase.ts`](../refs/mui/packages/mui-material/src/ButtonBase/useButtonBase.ts)
+- Ant Design: [`Button.tsx`](../refs/ant-design/components/button/Button.tsx), [`button/index.en-US.md`](../refs/ant-design/components/button/index.en-US.md)
+- shadcn-ui: [`button.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button.tsx)
+- Knowledge: [`a11y/keyboard-and-focus.md`](../knowledge/a11y/keyboard-and-focus.md), [`layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md)
+- Cross-reference: [`component-button.md`](component-button.md), [`component-icon-button.md`](component-icon-button.md), [`component-toggle.md`](component-toggle.md)

package/examples/component-button-group.md

@@ -0,0 +1,117 @@
+# `ButtonGroup` — spec
+
+> Synthesized from MUI `ButtonGroup` and shadcn-ui's `button-group`. A horizontal cluster of related buttons, visually unified — no gap between them; shared border for outline variant.
+
+## When to use
+
+- Related actions with one shared visual frame ("Save", "Save as...", "Cancel" together).
+- Toolbar action clusters.
+- Segmented-style action button row (different from `ToggleGroup` which has persistent selection).
+
+When NOT to use:
+- Mutually exclusive selection — use `ToggleGroup` (single).
+- Independent actions with distinct purposes — use separate `Button`s with gap.
+
+## ButtonGroup vs ToggleGroup vs Segmented
+
+| | ButtonGroup | ToggleGroup | Segmented |
+| --- | --- | --- | --- |
+| Persistent selection | No | Yes | Yes |
+| Visual shape | Joined buttons | Joined toggle buttons | Pill-style |
+| Use | Action cluster | Multi-select / radio of toggles | iOS-style mode switch |
+
+## Anatomy
+
+```
+[ Save ][ Save as... ][ Cancel ]
+   ↑ no gap; shared border
+```
+
+## API
+
+```tsx
+<ButtonGroup>
+  <Button onClick={save}>Save</Button>
+  <Button onClick={saveAs}>Save as...</Button>
+  <Button variant="ghost" onClick={cancel}>Cancel</Button>
+</ButtonGroup>
+
+<ButtonGroup variant="outline" orientation="vertical">
+  <Button>Option 1</Button>
+  <Button>Option 2</Button>
+  <Button>Option 3</Button>
+</ButtonGroup>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `orientation` | `"horizontal" \| "vertical"` | `"horizontal"` | Direction |
+| `variant` | `"default" \| "outline" \| "ghost"` | `"default"` | Visual style applied to all children |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Size applied to all children |
+| `disabled` | `boolean` | `false` | Disable all |
+
+## States
+
+Same as Button — each Button child has its own hover / focus / disabled state.
+
+The `ButtonGroup` adjusts:
+- First child: rounded left corners only.
+- Last child: rounded right corners only.
+- Middle children: no rounded corners.
+- Borders: shared (outline variant) — adjacent buttons share a 1px border, not 2px.
+
+## Tokens consumed
+
+```
+--button-group-divider             (subtle line between buttons in default variant)
+--radius-md                        (only at outer corners)
+```
+
+Otherwise inherits Button's tokens.
+
+## Accessibility
+
+- `role="group"` + `aria-label` describing the group's purpose.
+- Each Button is independently focusable; standard Button keyboard contract.
+- For toolbars: wrap ButtonGroup in `<div role="toolbar">`.
+
+## Code example
+
+```tsx
+function EditorToolbar() {
+  return (
+    <div role="toolbar" aria-label="Text formatting">
+      <ButtonGroup>
+        <Button onClick={undo} aria-label="실행 취소"><UndoIcon /></Button>
+        <Button onClick={redo} aria-label="다시 실행"><RedoIcon /></Button>
+      </ButtonGroup>
+
+      <Separator orientation="vertical" />
+
+      <ButtonGroup>
+        <Button onClick={cut}>잘라내기</Button>
+        <Button onClick={copy}>복사</Button>
+        <Button onClick={paste}>붙여넣기</Button>
+      </ButtonGroup>
+    </div>
+  );
+}
+```
+
+## Don't
+
+- Don't use ButtonGroup for mutually exclusive selection. Use ToggleGroup or Segmented.
+- Don't put 5+ buttons in one group — visual clutter; split.
+- Don't mix variants within one group (some outline, some filled).
+- Don't use ButtonGroup as a navigation menu. Use NavigationMenu / Menubar.
+
+## References
+
+- MUI: [`ButtonGroup`](../refs/mui/packages/mui-material/src/ButtonGroup)
+- shadcn-ui: [`button-group`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button-group.tsx)
+
+## Cross-reference
+
+- [`examples/component-button.md`](component-button.md)
+- [`examples/component-toggle.md`](component-toggle.md) — for persistent selection
+- [`examples/component-segmented.md`](component-segmented.md) — pill-style alternative

package/examples/component-button.md

@@ -0,0 +1,213 @@
+# `Button` — spec
+
+> Status: example artifact for `component-spec-writer` skill
+> Generated by: `skills/component-spec-writer` skill, citing Ant Design, MUI, and shadcn-ui
+
+## Purpose
+
+A button performs an action when activated. The most-used component in any product UI. It must be unmistakable as interactive, support all input modalities, and clearly express priority.
+
+## Anatomy
+
+```
+Button
+├── [iconStart]?         // optional leading icon
+├── label                // children — text or ReactNode
+├── [iconEnd]?           // optional trailing icon
+└── [loadingIndicator]?  // shown when loading
+```
+
+| Part | Purpose | Required | Default if omitted |
+| --- | --- | --- | --- |
+| `iconStart` | Visual cue before the label | no | none |
+| `label` | Action text | **yes** (children) | renders empty button — usually a bug |
+| `iconEnd` | Visual cue after the label (e.g., chevron, arrow) | no | none |
+| `loadingIndicator` | Spinner shown when `loading={true}` | no | system default `CircularProgress`-equivalent |
+
+Slot rules:
+- `iconStart` and `iconEnd` may not both convey the same meaning. If both are present, they should be complementary (e.g., search icon + chevron-down).
+- When `loading={true}`, the indicator replaces `iconStart` (or center if no start icon). Label stays visible unless `loadingPosition="center"`.
+
+## API
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | Label content. Required for accessible name unless `aria-label` provided. |
+| `variant` | `"solid" \| "outline" \| "ghost" \| "link"` | `"solid"` | Visual emphasis. `solid` is most prominent; `link` reads as text. |
+| `intent` | `"primary" \| "neutral" \| "success" \| "warning" \| "danger"` | `"primary"` | Semantic color. **One** `primary`+`solid` per surface. |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Dense → comfortable. |
+| `disabled` | `boolean` | `false` | Removes interactivity. Sets `aria-disabled`, dims appearance. |
+| `loading` | `boolean` | `false` | Shows spinner, blocks clicks, sets `aria-busy="true"`. |
+| `loadingPosition` | `"start" \| "end" \| "center"` | `"start"` | Where the indicator sits. `center` hides label. |
+| `iconStart` | `ReactNode` | — | Leading icon. |
+| `iconEnd` | `ReactNode` | — | Trailing icon. |
+| `fullWidth` | `boolean` | `false` | Stretches to container width. Use sparingly — usually a sign of mobile or form layout. |
+| `href` | `string` | — | If provided, renders `<a>` instead of `<button>`. |
+| `target` | `"_self" \| "_blank" \| "_parent" \| "_top"` | — | Only with `href`. |
+| `asChild` | `boolean` | `false` | Render-as-child (Radix `Slot` pattern) — composes with `<Link>` from routers without nesting `<a>` inside `<button>`. |
+| `type` | `"button" \| "submit" \| "reset"` | `"button"` | HTML form behavior. **Always `"button"` unless inside a form's submit slot** — the default `"submit"` of bare `<button>` is the #1 form bug. |
+| `onClick` | `(e: MouseEvent) => void` | — | Fires on click and on `Enter`/`Space` keypress. |
+
+## States
+
+| State | Trigger | Visual |
+| --- | --- | --- |
+| Default | resting | base styles per variant + intent |
+| Hover | mouse-over | bg shift (solid: -8% L; outline: bg becomes 5% intent; ghost: bg becomes 8% intent) |
+| Focus-visible | keyboard tab | 2px ring `--color-focus-ring`, 2px offset, 3:1 contrast both sides |
+| Active | press | bg darken 12% from default |
+| Disabled | `disabled={true}` | opacity 0.5, pointer-events: none, `aria-disabled="true"` |
+| Loading | `loading={true}` | spinner replaces start icon; `aria-busy="true"`; click blocked |
+| Read-only | N/A | buttons don't have read-only |
+| Error | parent form invalid | unchanged — error state lives on form fields, not their submit button |
+
+`hover` styles must NOT fire on touch devices. Use `@media (hover: hover)` to gate.
+
+## Variants
+
+### `variant`
+
+| Value | Visual | Use |
+| --- | --- | --- |
+| `solid` | filled background, on-color text | primary CTAs |
+| `outline` | transparent bg, intent border, intent text | secondary actions |
+| `ghost` | no border, no bg, intent text on hover-bg | tertiary actions, toolbar items |
+| `link` | text-only, underline on hover | inline within text, low-emphasis nav |
+
+### `intent`
+
+| Value | Default solid bg | On-color | When |
+| --- | --- | --- | --- |
+| `primary` | `--color-primary-default` | `--color-on-primary` | the main action of the surface |
+| `neutral` | `--color-neutral-200` (light) / `--color-neutral-700` (dark) | `--color-text-primary` | secondary action paired with primary |
+| `success` | `--color-success` | white | rare — confirm of irreversible positive action |
+| `warning` | `--color-warning` | white or near-black | rarely used as button bg; usually as outline |
+| `danger` | `--color-error` | white | destructive actions (delete, leave) |
+
+### `size`
+
+| Size | Height | Font | Padding | Icon size |
+| --- | --- | --- | --- | --- |
+| `sm` | 32px | 13px | 6px 12px | 14px |
+| `md` | 40px | 14px | 8px 16px | 16px |
+| `lg` | 48px | 16px | 12px 20px | 20px |
+
+Icon-only variants get square dimensions matching height.
+
+## Tokens consumed
+
+```
+--color-primary-default
+--color-primary-hover
+--color-primary-active
+--color-on-primary
+--color-neutral-200
+--color-neutral-300
+--color-text-primary
+--color-error
+--color-error-hover
+--color-success
+--color-warning
+--color-focus-ring
+--space-md
+--space-sm
+--space-lg
+--radius-md
+--font-size-sm
+--font-size-base
+--font-size-lg
+--font-weight-medium
+--transition-fast
+```
+
+If any of these don't exist in your token system, **stop and add them before implementing the Button** — don't inline values.
+
+## Accessibility
+
+- **Semantic**: `<button type="button">` by default. `<a>` if `href` is set. Never `<div onClick>`.
+- **Accessible name**: from `children` (text content). If icon-only, **must** provide `aria-label` (e.g., `aria-label="Close"`).
+- **`aria-disabled="true"`** when `disabled` (in addition to native `disabled` attribute, which removes from tab order and prevents events).
+- **`aria-busy="true"`** when `loading`.
+- **`aria-pressed`** is **not** for regular buttons — that's for toggle buttons. Don't add.
+- **Keyboard**:
+  - `Tab` reaches.
+  - `Enter` activates.
+  - `Space` activates (when rendered as `<button>`, not when rendered as `<a>` — `Space` scrolls anchors).
+  - `Escape` does nothing on a button (escapes apply to overlays containing the button).
+- **Focus indicator**: 2px ring with `--color-focus-ring`, 2px offset. Must clear 3:1 against the button's resting background AND against the page background. Cite [knowledge/a11y/contrast.md](../knowledge/a11y/contrast.md).
+- **Touch target**: minimum 44×44 hit area on mobile. If the visual height is `sm` (32px), extend hit area via padding or invisible expanded area.
+- **High contrast mode (Windows)**: ensure border or fill remains visible. Test with `forced-colors: active`.
+- **Reduced motion**: omit fade/scale transitions on hover/active. State changes still happen, just instant.
+- **Screen reader on loading**: announcing "loading" on every Button activation is noisy. Prefer toast/live-region for "Saving…" instead, with the button just becoming `disabled` + visually showing spinner.
+
+## Code example
+
+```tsx
+// Default — primary CTA
+<Button onClick={handleSave}>
+  Save changes
+</Button>
+
+// Loading mid-action
+<Button onClick={handleSave} loading={isPending} disabled={isPending}>
+  Save changes
+</Button>
+
+// Destructive
+<Button intent="danger" onClick={handleDelete}>
+  Delete project
+</Button>
+
+// Icon-only — REQUIRES aria-label
+<Button variant="ghost" size="sm" aria-label="Close dialog">
+  <CloseIcon />
+</Button>
+
+// As link (renders <a>, not <button>)
+<Button asChild variant="link">
+  <Link to="/pricing">See pricing</Link>
+</Button>
+
+// Outline secondary paired with solid primary
+<div className="flex gap-2">
+  <Button variant="outline">Cancel</Button>
+  <Button>Confirm</Button>
+</div>
+```
+
+## Edge cases
+
+- **Empty label**: renders nothing visible. Treat as a bug — log warning in dev.
+- **Long label**: by default, the button grows to fit. If the parent constrains width, the label truncates with `…`. Provide `title` attribute for the full text.
+- **`disabled` and `loading` both true**: precedence is `disabled` (no spinner). Document this — surprises if not specified.
+- **Submit form with `Enter`**: the form's first `<button type="submit">` (or first `<button>` if no type) handles it. Always set `type="button"` on non-submit buttons in forms.
+- **Inside a `<a>` parent (don't)**: invalid HTML. Use `asChild` to compose.
+- **RTL**: `iconStart` mirrors to the right, `iconEnd` to the left, padding swaps. CSS logical properties (`padding-inline-start`, etc.) handle this automatically with `dir="rtl"`.
+- **Print**: hidden by default (`@media print { display: none; }`).
+
+## Don't
+
+- Don't use `intent="primary"` for more than **one** button on a surface.
+- Don't pass an icon as children when also using `iconStart` — pick one approach.
+- Don't disable the only path forward without offering an alternative ("submit" can't just be disabled with no error explanation).
+- Don't use `onClick` to navigate when `href` is appropriate — middle-click and right-click expectations break.
+- Don't put `onClick` on `<a>` — use `<Button>` or wire the link properly.
+- Don't put two solid + primary buttons next to each other. If both are essential, make one `outline`.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/button/Button.tsx`](../refs/ant-design/components/button/Button.tsx) — most exhaustive prop coverage; uses `type` (legacy) and `variant` (modern) in parallel, with `color` as a separate axis.
+- MUI: [`refs/mui/packages/mui-material/src/Button/Button.d.ts`](../refs/mui/packages/mui-material/src/Button/Button.d.ts) — `variant` (`text`/`outlined`/`contained`), `color` (semantic), `loadingPosition`. The most thoroughly documented.
+- shadcn-ui: [`refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button.tsx`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/button.tsx) — Tailwind `cva` pattern, `asChild` via Radix Slot, simplest API surface. Inspired the `iconStart`/`iconEnd` and `asChild` choices in this spec.
+
+API choices made:
+- **`variant` names**: `solid`/`outline`/`ghost`/`link` over MUI's `text`/`outlined`/`contained` (clearer for non-Material teams) and over Ant's `default`/`dashed`/`text`/`link` (`default` is uninformative).
+- **`intent` over `color`**: `intent` reads as semantic (purpose), `color` reads as visual (which can clash with theme tokens).
+- **`asChild` adopted from shadcn**: cleaner composition with router `<Link>` than MUI's `component` prop.
+- **`loadingPosition` adopted from MUI**: covers a real ergonomic need (don't always want spinner at start).
+
+## Cross-reference
+
+- [knowledge/components/INDEX.md](../knowledge/components/INDEX.md) — cross-library component index
+- [knowledge/a11y/keyboard-and-focus.md](../knowledge/a11y/keyboard-and-focus.md) — keyboard contract
+- [knowledge/a11y/contrast.md](../knowledge/a11y/contrast.md) — WCAG ratios