@design-ai/cli 4.55.0

package/examples/component-label.md

@@ -0,0 +1,118 @@
+# `Label` — spec
+
+> Synthesized from shadcn-ui `label` and the HTML5 `<label>` element. The semantic + styled label primitive for form controls.
+
+## When to use
+
+- **Every form control** (Input, Select, Checkbox, Radio, Switch, Combobox).
+- Wherever you'd write `<label htmlFor="...">`.
+
+`Label` is a thin styled wrapper around `<label>` — adds typography tokens + optional required/optional indicator.
+
+## API
+
+```tsx
+<Label htmlFor="email">이메일</Label>
+<Input id="email" />
+
+<Label htmlFor="age" required>만 14세 이상입니다</Label>
+
+<Label htmlFor="bio" optional>자기소개 (선택)</Label>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `htmlFor` | `string` | — | Linked input id (mandatory for accessibility) |
+| `required` | `boolean` | `false` | Adds asterisk visual |
+| `optional` | `boolean` | `false` | Adds "(선택)" / "(optional)" text |
+| `children` | `ReactNode` | — | Label text |
+| `className` | `string` | — | Style override |
+
+## CSS
+
+```css
+.label {
+  font-size: var(--font-size-sm);
+  font-weight: 500;
+  color: var(--color-fg-default);
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-xxs);
+  cursor: pointer;
+  user-select: none;
+}
+
+.label[data-required]::after {
+  content: "*";
+  color: var(--color-error-default);
+  margin-left: 2px;
+}
+
+.label[data-disabled] {
+  opacity: 0.6;
+  cursor: not-allowed;
+}
+```
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Standard label color |
+| Hover (when paired with input) | No change (the input handles hover) |
+| Disabled (when input is disabled) | Reduced opacity |
+
+Label is presentational; states inherit from the linked input.
+
+## Accessibility
+
+- Always use `htmlFor` matching the input's `id`.
+- Click on label focuses / activates the linked input.
+- For Checkbox / Radio: clicking the label also toggles the control (native browser behavior).
+- For required field, prefer `aria-required="true"` on the input over visual asterisk alone — color-blind / screen reader users miss the star.
+
+```html
+<Label htmlFor="email" required>이메일</Label>
+<Input id="email" type="email" required aria-required="true" />
+```
+
+## Korean conventions
+
+- 필수 / 선택 marker patterns:
+  - 필수: asterisk `*` OR "(필수)" text after label
+  - 선택: "(선택)" text after label OR no marker (assume required by default)
+- Common labels: 이메일 / 비밀번호 / 이름 / 휴대폰 번호 / 주소 / 회원가입 약관 동의
+
+## Code example
+
+```tsx
+<Field>
+  <Label htmlFor="email" required>이메일</Label>
+  <Input id="email" type="email" autoComplete="email" required />
+  <FieldDescription>로그인할 때 사용해요.</FieldDescription>
+</Field>
+
+<Field>
+  <Label htmlFor="bio" optional>자기소개</Label>
+  <Textarea id="bio" rows={3} />
+</Field>
+```
+
+## Don't
+
+- Don't use Label without `htmlFor`. Just text without a link is decorative.
+- Don't put long instructional text in Label. Use FieldDescription.
+- Don't rely on color alone for required indicator — use asterisk OR `aria-required`.
+- Don't wrap multiple inputs in one Label — confusing. Use separate Labels.
+
+## References
+
+- HTML5 `<label>` element
+- shadcn-ui: [`label`](../refs/shadcn-ui/apps/v4/registry/new-york-v4/ui/label.tsx) (Radix)
+- MUI: `FormLabel`
+
+## Cross-reference
+
+- [`examples/component-field.md`](component-field.md) — wraps Label + control
+- [`examples/component-input.md`](component-input.md)
+- [`examples/component-form-controls.md`](component-form-controls.md)

package/examples/component-layout.md

@@ -0,0 +1,217 @@
+# `Layout` (page chrome) — spec
+
+> Citing Ant Design `Layout`, MUI (composition), shadcn-ui (composition)
+
+## Purpose
+
+The top-level page structure: header / sidebar / main / footer. Used as the root of any standard product page. Provides slot-based composition for consistent app chrome.
+
+## When Layout vs CSS Grid
+
+Layout component vs CSS Grid (`grid-template-areas`): both work. The Layout component:
+- Pre-defines the slots (Header, Sidebar, Content, Footer)
+- Applies sticky/fixed positioning consistently
+- Handles responsive collapse (sidebar → drawer on mobile)
+
+For dashboards with a fixed shape, Layout simplifies the wiring.
+
+## Anatomy
+
+```
+┌──────────────────────────────────────────────────┐
+│ Layout.Header (sticky)                           │
+├──────────┬───────────────────────────────────────┤
+│          │                                        │
+│ Layout.  │   Layout.Content                       │
+│ Sider    │                                        │
+│          │                                        │
+│          │                                        │
+├──────────┴───────────────────────────────────────┤
+│ Layout.Footer (optional)                          │
+└──────────────────────────────────────────────────┘
+```
+
+| Slot | Required | Notes |
+| --- | --- | --- |
+| `Layout` | yes | Root container |
+| `Layout.Header` | optional | Top app bar (typically with `AppBar` inside) |
+| `Layout.Sider` | optional | Sidebar nav (collapsible) |
+| `Layout.Content` | yes | Main page content |
+| `Layout.Footer` | optional | Footer (rare on apps; common on marketing) |
+
+## API
+
+```tsx
+<Layout>
+  <Layout.Header>
+    <AppBar leading={<Logo />} actions={[...]} />
+  </Layout.Header>
+  <Layout>
+    <Layout.Sider width={240} collapsible>
+      <SideNav />
+    </Layout.Sider>
+    <Layout.Content>
+      <PageContent />
+    </Layout.Content>
+  </Layout>
+  <Layout.Footer>
+    <SiteFooter />
+  </Layout.Footer>
+</Layout>
+```
+
+| Prop (Layout) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `direction` | `"column" \| "row"` | `"column"` | Children stack vertically or horizontally |
+
+| Prop (Sider) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `width` | `number \| string` | `200` | Expanded width |
+| `collapsedWidth` | `number` | `64` | Width when collapsed |
+| `collapsible` | `boolean` | `false` | Show toggle |
+| `collapsed` | `boolean` | — | Controlled |
+| `defaultCollapsed` | `boolean` | `false` | |
+| `breakpoint` | `string` | `"md"` | Auto-collapse below this width |
+| `onCollapse` | `(collapsed) => void` | — | |
+| `position` | `"left" \| "right"` | `"left"` | |
+
+| Prop (Header / Footer) | Type | Default | Description |
+| --- | --- | --- | --- |
+| `position` | `"static" \| "sticky" \| "fixed"` | `"static"` | |
+
+## Behavior
+
+### Sider collapse
+
+- Manual: user clicks toggle button.
+- Auto-collapse: at viewport breakpoint, sider collapses to icon-only or hides entirely.
+- Mobile: typically hide entirely; replace with hamburger that opens a Drawer.
+
+### Layout nesting
+
+You can nest `Layout` inside `Layout` to combine row + column flows:
+
+```tsx
+<Layout>          {/* column */}
+  <Layout.Header />
+  <Layout>        {/* row */}
+    <Layout.Sider />
+    <Layout.Content />
+  </Layout>
+</Layout>
+```
+
+This is the canonical "header + sidebar + content" pattern.
+
+## Responsive patterns
+
+| Viewport | Recommended layout |
+| --- | --- |
+| < 768 (mobile) | Header + Content; Sider hidden, opens via drawer |
+| 768–1024 (tablet) | Header + collapsed Sider (icon-only) + Content |
+| > 1024 (desktop) | Header + expanded Sider + Content |
+
+Use `breakpoint="md"` on Sider for auto-collapse.
+
+## States
+
+The Layout component doesn't have visual states. The Sider has expanded/collapsed.
+
+## Tokens consumed
+
+```
+--color-bg-default          (Content bg)
+--color-bg-elevated         (Header, Sider bg)
+--color-bg-subtle           (Footer bg)
+--color-border-default      (between regions)
+--color-text-primary
+--space-md, --space-base
+--motion-default            (Sider collapse animation)
+```
+
+## Sizes
+
+| Region | Default size |
+| --- | --- |
+| Header height | 56px (mobile) / 64px (desktop) |
+| Sider width | 200–280px |
+| Sider collapsed | 64px |
+| Footer height | 64–96px |
+
+Content fills remaining space.
+
+## Accessibility
+
+- `<Layout>` renders as `<div>` (or root structural element).
+- `Layout.Header` → `<header>` with `role="banner"`.
+- `Layout.Sider` → `<nav>` with `aria-label="Main navigation"`.
+- `Layout.Content` → `<main>` with `id="main-content"`.
+- `Layout.Footer` → `<footer>` with `role="contentinfo"`.
+- Provide a "Skip to main content" link before the header — keyboard users skip nav.
+
+```html
+<a href="#main-content" class="sr-only-focusable">본문으로 건너뛰기</a>
+```
+
+## Code example
+
+```tsx
+function AppLayout({ children }: Props) {
+  const [sidebarCollapsed, setSidebarCollapsed] = useLocalStorage("sidebar-collapsed", false);
+
+  return (
+    <Layout>
+      <Layout.Header position="sticky">
+        <AppBar
+          leading={<Logo />}
+          title={<NavLinks />}
+          actions={[<Notifications />, <ProfileMenu />]}
+        />
+      </Layout.Header>
+
+      <Layout direction="row">
+        <Layout.Sider
+          width={240}
+          collapsedWidth={64}
+          collapsible
+          collapsed={sidebarCollapsed}
+          onCollapse={setSidebarCollapsed}
+          breakpoint="md"
+          position="left"
+        >
+          <SideNav collapsed={sidebarCollapsed} />
+        </Layout.Sider>
+
+        <Layout.Content>
+          <a href="#main-content" className="sr-only-focusable">
+            본문으로 건너뛰기
+          </a>
+          <main id="main-content">
+            {children}
+          </main>
+        </Layout.Content>
+      </Layout>
+    </Layout>
+  );
+}
+```
+
+## Don't
+
+- Don't ship without a "Skip to main content" link.
+- Don't put critical content in the Sider only — mobile users may not see it.
+- Don't auto-collapse the sider on every page load — persist user preference.
+- Don't omit `<main>` — accessibility requires it.
+
+## References
+
+- Ant Design: [`refs/ant-design/components/layout/`](../refs/ant-design/components/layout/) — `Layout`, `Layout.Header`, `Layout.Sider`, `Layout.Content`, `Layout.Footer`. Most exhaustive.
+- MUI: no dedicated Layout — compose with `<Box>` + `<Drawer>` + `<AppBar>`.
+- shadcn-ui: no built-in. Use `resizable` + custom layout.
+
+## Cross-reference
+
+- [`examples/component-app-bar.md`](component-app-bar.md) — fits inside Layout.Header
+- [`examples/component-drawer.md`](component-drawer.md) — mobile alternative to Sider
+- [`examples/component-splitter.md`](component-splitter.md) — when sider needs resize
+- [`knowledge/layout/spacing-and-grid.md`](../knowledge/layout/spacing-and-grid.md) — broader layout system

package/examples/component-link.md

@@ -0,0 +1,223 @@
+# `Link` — spec
+
+> Synthesized from MUI `Link`, Ant Design's link styles, and shadcn-ui's `<a>` patterns. The canonical text link primitive — distinct from `Button` and `Anchor` (TOC nav).
+
+## Link vs Button
+
+> **Links navigate. Buttons do.**
+
+Use `Link` when the action is "go somewhere" (URL change). Use `Button` when the action is "do something" (state change, side effect).
+
+| | Link | Button |
+| --- | --- | --- |
+| Native element | `<a href>` | `<button>` |
+| Default keyboard | Enter activates | Enter / Space activate |
+| Default behavior | Navigate | Custom handler |
+| Right-click context | Open in new tab | n/a |
+| Drag | Drag URL | n/a |
+| User expectation | New URL | Stay |
+
+For ambiguous cases ("Sign out" — is that a state change or a navigation to /logout?): pick based on the destination. If `/logout` is a real route, use Link. If it's purely a state action, use Button.
+
+## Anatomy
+
+Inline link in flowing text:
+
+```
+The system audits your design system across five layers. See the full
+report.
+                                                            ↑ link
+```
+
+Standalone link (CTA-style):
+
+```
+[ → 자세히 보기 ]
+```
+
+External link with indicator:
+
+```
+Visit our docs ↗
+```
+
+## API
+
+```tsx
+<Link href="/docs">documentation</Link>
+<Link href="https://example.com" external>External site ↗</Link>
+<Link href="/profile" as={NextLink}>profile</Link>
+<Link variant="standalone">Learn more →</Link>
+<Link variant="muted" href="...">Privacy policy</Link>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `href` | `string` | required | Destination URL |
+| `external` | `boolean` | auto-detected from URL | Add visual indicator + open-in-new-tab semantics |
+| `variant` | `"default" \| "muted" \| "standalone" \| "destructive"` | `"default"` | Visual style |
+| `underline` | `"hover" \| "always" \| "none"` | `"hover"` | When underline is visible |
+| `as` | Component | `"a"` | Render as router-aware Link (NextLink, react-router Link) |
+| `disabled` | `boolean` | `false` | Disabled (rare for links; usually means "not yet available") |
+
+## Variants
+
+### `default` (in-flow link)
+
+Brand-colored, underline on hover (or always for accessibility-strict contexts). Used inline within paragraphs.
+
+### `muted`
+
+Gray, less prominent. For secondary links (legal, footer, "skip").
+
+### `standalone`
+
+CTA-style link, often with arrow indicator. Used as a section's primary navigation:
+
+```tsx
+<Link variant="standalone" href="/learn-more">
+  Learn more <ArrowRightIcon />
+</Link>
+```
+
+Larger touch target; bolder weight.
+
+### `destructive`
+
+Red. For "Delete account", "Cancel subscription" — actions that remove data. Pair with confirmation flow if irreversible.
+
+## Underline policies
+
+| Setting | When |
+| --- | --- |
+| `hover` (default) | Body text in well-styled pages — link is brand-colored already |
+| `always` | Long-form content, accessibility-strict, when link can't be color-distinguished |
+| `none` | Standalone CTAs that have arrow indicator + clear context |
+
+WCAG note: links must be distinguishable from surrounding text by **more than color alone**. If your design relies on color only: enable `underline="always"` to satisfy WCAG.
+
+## States
+
+| State | Visual |
+| --- | --- |
+| Default | Brand color (or muted), underline policy applies |
+| Hover | Underline visible (if hover policy); subtle color shift |
+| Visited | Optional muted color shift (rare in modern apps) |
+| Active (during click) | Slightly deeper color |
+| Focus-visible | 2px focus ring AROUND link (preserve underline) |
+| Disabled | `aria-disabled="true"`, gray text, no events |
+
+## External link
+
+```tsx
+<Link external href="https://example.com">Docs ↗</Link>
+```
+
+Adds:
+- `target="_blank"` (new tab)
+- `rel="noopener noreferrer"` (security)
+- Visual indicator (↗ arrow OR external icon)
+- `aria-label` extension: "Docs (opens in new tab)" for screen readers
+
+```html
+<a href="https://example.com"
+   target="_blank"
+   rel="noopener noreferrer"
+   aria-label="Docs (opens in new tab)">
+  Docs <ExternalIcon aria-hidden="true" />
+</a>
+```
+
+## Tokens consumed
+
+```
+--color-link-default               (typically brand color)
+--color-link-hover
+--color-link-visited               (optional)
+--color-link-active
+--color-link-muted
+--color-link-destructive
+--color-focus-ring
+--text-decoration-thickness        (1-2px underline)
+--text-underline-offset            (3-4px below text baseline)
+--motion-fast                      (color transition)
+```
+
+## Accessibility
+
+- Always use `<a>` (or framework Link). Don't fake a link with `<div onClick>`.
+- For non-text links (icon-only): `aria-label` required.
+- Focus-visible ring must be visible against any background.
+- Don't disable `pointer-events` to make a "disabled" link — use `aria-disabled="true"` and prevent navigation in the click handler.
+- For links that look like buttons (CTA-style): users expect them to navigate; if they trigger a state action, use Button.
+- Korean: identical accessibility rules apply. Hangul links should not be color-only either.
+
+## Korean conventions
+
+- 한국어 link 스타일은 일반적으로 영문보다 underline 사용이 약간 더 적극적 (Hangul 글자에서 underline 가독성이 좋음).
+- 외부 링크 표시: ↗ 또는 ↪ 화살표 + "(새 창에서 열림)" sr-only 텍스트.
+- "더보기 →" / "자세히 보기 →" / "전체 보기" — common standalone link copy.
+- For B2C: 해요체 ("자세히 보기"); for B2B: 합쇼체 ("더 알아보기").
+
+## Code example
+
+```tsx
+function ArticleFooter() {
+  return (
+    <footer className="article-footer">
+      <p>
+        이 글은 <Link href="/authors/sungjin">박성진</Link>이 작성했어요.
+        <Link href="https://blog.example.com" external>블로그</Link>에서
+        더 많은 글을 확인할 수 있어요.
+      </p>
+      <Link variant="standalone" href="/articles">
+        모든 글 보기 <ArrowRightIcon />
+      </Link>
+    </footer>
+  );
+}
+```
+
+## With Next.js / React Router
+
+```tsx
+import NextLink from "next/link";
+
+<Link as={NextLink} href="/docs">documentation</Link>
+```
+
+The `as` prop swaps the underlying element from `<a>` to a router-aware Link. This preserves design-ai's styling but uses client-side routing.
+
+## Edge cases
+
+- **Disabled link**: rare; typically means "not yet available". Use `aria-disabled` + click handler that prevents nav. Don't use `pointer-events: none` (still focusable, confusing).
+- **Link wrapping multiple lines**: ensure underline appears on each line, not just the first. Default browser behavior; verify in your CSS reset.
+- **Email link**: `<Link href="mailto:hello@example.com">` works; consider `mailto:` link best practices.
+- **Phone link** (mobile): `<Link href="tel:+8210...">`.
+- **Anchor link** (`#section`): scroll behavior + browser history. Use smooth scroll if appropriate.
+- **Protocol-relative**: avoid `//example.com` — fully qualify.
+- **RTL**: arrow direction flips automatically if using `→` / `←` SVG. For text arrows, use logical names (`block-start`, `inline-start`).
+- **Reduced motion**: skip color transition.
+
+## Don't
+
+- Don't use Link as a button (state action). Use Button.
+- Don't omit `target="_blank"` external indicator. Users hate context-loss.
+- Don't ship Link with `target="_blank"` without `rel="noopener"`. Security.
+- Don't disable underline AND make link only differentiated by color. WCAG fail.
+- Don't open EVERY link in a new tab. User-hostile.
+- Don't put long descriptive text inside link — extract a short label, use the surrounding paragraph for context.
+
+## References
+
+- HTML5 `<a>` element
+- MUI: [`Link`](../refs/mui/packages/mui-material/src/Link)
+- Ant Design: link styling within `Typography`
+- WCAG 2.1: SC 1.4.1 (Use of Color), SC 2.4.4 (Link Purpose)
+
+## Cross-reference
+
+- [`examples/component-button.md`](component-button.md) — when action is not navigation
+- [`examples/component-anchor.md`](component-anchor.md) — table-of-contents nav (different use)
+- [`examples/component-typography.md`](component-typography.md) — text primitives
+- [`knowledge/a11y/contrast.md`](../knowledge/a11y/contrast.md)

package/examples/component-list-item-avatar.md

@@ -0,0 +1,72 @@
+# `ListItemAvatar` — spec
+
+> Synthesized from MUI `ListItemAvatar`. The leading-avatar slot — like `ListItemIcon` but sized for `Avatar` (40px default vs 24px). Used in user/contact lists, message lists, and any row identified by a person/entity image.
+
+## When to use
+
+- User lists (team members, followers).
+- Message threads (sender avatar).
+- Brand/entity rows with logos.
+
+## API
+
+```tsx
+<ListItem secondaryAction={<IconButton><CloseIcon /></IconButton>}>
+  <ListItemAvatar>
+    <Avatar src={user.avatarUrl} alt={user.name} />
+  </ListItemAvatar>
+  <ListItemText primary={user.name} secondary={user.role} />
+</ListItem>
+```
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | — | An `Avatar` component |
+
+## Tokens consumed
+
+```
+--avatar-size-md            /* 40px default */
+--list-avatar-min-width     /* 56px reserved column */
+--space-md                  /* gap to text */
+```
+
+## Accessibility
+
+- `Avatar` should have meaningful `alt` (the person's name) — don't set `alt=""`.
+- For image-failed states, MUI's Avatar falls back to initials or generic icon; ensure both are readable.
+
+## Edge cases
+
+- **Status badge** — wrap Avatar in `Badge` for online/unread indicators.
+- **Initials fallback** — Korean names use 2-3 character initials (성+이름 first char). Latin: 1-2.
+- **Compact lists** — set `Avatar size={32}` and override `ListItemAvatar` `minWidth`.
+
+## Code example
+
+```tsx
+<Badge
+  overlap="circular"
+  anchorOrigin={{ vertical: 'bottom', horizontal: 'right' }}
+  badgeContent={user.online ? <OnlineDot /> : null}
+>
+  <ListItemAvatar>
+    <Avatar src={user.avatarUrl}>{user.name[0]}</Avatar>
+  </ListItemAvatar>
+</Badge>
+```
+
+## Don't
+
+- Don't use for plain icons — use `ListItemIcon` (smaller column).
+- Don't omit `alt` on the inner Avatar — failed loads become anonymous gray circles.
+
+## References
+
+- MUI: [`ListItemAvatar`](../refs/mui/packages/mui-material/src/ListItemAvatar/)
+
+## Cross-reference
+
+- [`component-list-item.md`](component-list-item.md)
+- [`component-avatar.md`](component-avatar.md)
+- [`component-list-item-icon.md`](component-list-item-icon.md)