@makitt.io/mds-mcp-server 0.1.0

package/dist/data/playbook/page-layout.md

@@ -0,0 +1,222 @@
+# MDS Playbook — Page Layout (Shell / Sidebar / PageHeader / padding / max-width)
+
+페이지 의 layout 약속.
+
+> 모든 셀러 admin 페이지가 **같은 layout structure** 따라야 균일. mds 의 shells 활용.
+
+---
+
+## 1. 표준 Page 구조
+
+```tsx
+<AppShell>
+  <Sidebar>
+    {/* nav items */}
+  </Sidebar>
+  <Page>
+    <PageHeader title="..." actions={...} />
+    {/* content — section / Card / DataGrid / form 등 */}
+  </Page>
+</AppShell>
+```
+
+| Shell 컴포넌트 | 역할 | 위치 |
+|---|---|---|
+| `AppShell` | top-level wrapper (Sidebar + Page) | route layout (Next.js) |
+| `Sidebar` | nav menu (sticky left) | desktop left, mobile drawer |
+| `Topbar` (선택) | global header (logo / user / breadcrumb) | top sticky |
+| `Page` | content area | sidebar 우측 |
+| `PageHeader` | title + breadcrumb + actions | content 상단 |
+| `Section` (선택) | content 안 의미 단위 분할 | Page 안 |
+
+---
+
+## 2. Content max-width — 큰 모니터 대응
+
+### 결정 표
+
+| 페이지 종류 | max-width | 이유 |
+|---|---|---|
+| **DataGrid list 페이지** (customers / orders) | **full-bleed** (max-width X) | table 의 column 다 보임. 큰 모니터에서 더 좋음 |
+| **단순 form 페이지** (회원가입 / 단일 entity) | **640px** (modal-sm 와 같음) | 가독성 (긴 가로 input 어색) |
+| **복잡 form 페이지** (상품 등록 — Section + AnchorNav) | **content 자체 max-width X**, AnchorNav 좌측 + form 우측 (둘 다 fill) | 큰 form 은 넓은 공간 활용 |
+| **분석 / dashboard** (KPI + chart) | **full-bleed** | grid layout 의 cols 활용 |
+| **정보 페이지** (about / docs / blog) | **800-960px** | 글 가독성 |
+
+→ **default = full-bleed**. 가독성 필요한 경우 (form / 정보) 만 max-width.
+
+### 이전 발견 (apps/web 의 max-width 답답함)
+
+기존 apps/web 의 content 가 `max-w-7xl` (1280px) 같은 작은 fix → 1920px+ 모니터에서 양쪽 빔. **수정 필요**:
+- DataGrid 페이지 → full-bleed
+- form 페이지 → 명시적 max-width (640 or 800)
+
+---
+
+## 3. Padding 표준
+
+| Level | Padding token | 사용 |
+|---|---|---|
+| Page (content area 의 outer) | `var(--space-6)` ~ `var(--space-8)` (24~32px) | desktop |
+| Page (mobile) | `var(--space-4)` (16px) | mobile |
+| Section gap | `var(--section-gap)` (theme 별 — admin-light = 48px) | section 사이 |
+| Card padding | `var(--space-4)` (16px) — default | Card 안 |
+| Form 안 row gap | `var(--space-3)` (12px) | field 사이 |
+
+> Padding 의 mobile 자동 — Page shell 의 prop 또는 SCSS `@media (max-width: 768px)` 분기.
+
+---
+
+## 4. Sidebar — desktop vs mobile
+
+| State | Desktop | Mobile |
+|---|---|---|
+| 항상 표시 | `Sidebar` (sticky left) | drawer (top trigger 의 hamburger menu) |
+| Collapsed (icon only) | `Sidebar collapsed` | drawer + 그대로 |
+| Active route | `Sidebar.SubItem` 의 `data-active="true"` (Sidebar.subItemActive style) | drawer 안 동일 |
+
+> Mobile 변환 — `useIsBreakpointUp('lg')` (1024px) — 그 미만 = drawer.
+
+---
+
+## 5. PageHeader 표준
+
+```tsx
+<PageHeader
+  title="주문"
+  description="결제 / 발송 / 환불 관리"
+  breadcrumb={[{ label: '홈', href: '/' }, { label: '주문' }]}
+  actions={
+    <>
+      <Button variant="ghost">필터 reset</Button>
+      <Button>+ 새 주문</Button>
+    </>
+  }
+/>
+```
+
+| Slot | 사용 |
+|---|---|
+| `title` | h1 — 페이지 이름 |
+| `description` | 부제 (optional) |
+| `breadcrumb` | 위치 (홈 → category → 현 페이지) |
+| `actions` | 우측 primary / secondary buttons (예: "+ 새 주문") |
+| `tabs` | (선택) 페이지 안 sub-section 탭 |
+
+> PageHeader 의 actions = **페이지 단위 primary action**. row-level action 은 DataGrid 의 column action.
+
+---
+
+## 6. Section + AnchorNav (큰 form / 다단 페이지)
+
+### 사용 시점 (form.md §2 참조)
+
+- 6+ section 의 큰 form (상품 등록)
+- 의미 단위 분명 (기본정보 / 이미지 / 변형 / 가격 / 정책 / 추천 / SEO 등)
+
+### Layout
+
+```tsx
+<Page>
+  <PageHeader title="상품 등록" actions={<Button>저장</Button>} />
+  <div style={{ display: 'grid', gridTemplateColumns: '200px 1fr', gap: 'var(--space-6)' }}>
+    <AnchorNav sticky>
+      <AnchorNav.Item href="#basic">기본 정보</AnchorNav.Item>
+      <AnchorNav.Item href="#images">이미지</AnchorNav.Item>
+      {/* ... */}
+    </AnchorNav>
+    <div>
+      <Section id="basic" title="기본 정보">...</Section>
+      <Section id="images" title="이미지">...</Section>
+      {/* ... */}
+    </div>
+  </div>
+</Page>
+```
+
+> Mobile — AnchorNav → drawer (top trigger). Section 만 표시 + smooth scroll.
+
+---
+
+## 7. 결정 표 (lookup)
+
+| 케이스 | 답 |
+|---|---|
+| "list 페이지 (DataGrid)" | full-bleed AppShell + PageHeader + DataGrid |
+| "단일 entity form" | AppShell + PageHeader + max-width 640 form |
+| "큰 form (상품 등록)" | AppShell + PageHeader + Section/AnchorNav layout |
+| "dashboard (KPI + chart)" | full-bleed AppShell + Grid cols=4 (KPI) + Grid cols=2 (chart) |
+| "단순 정보 페이지" | AppShell + max-width 800 + body text |
+| "mobile" | Sidebar → drawer (`useIsBreakpointUp('lg')`) + Page padding 축소 |
+| "settings 페이지 (다 section)" | AppShell + PageHeader + Section/AnchorNav (left nav) |
+| "page 안 sub-page tabs" | PageHeader 의 `tabs` slot |
+
+---
+
+## 8. Mobile 변형
+
+| Desktop | Mobile (< lg) |
+|---|---|
+| Sidebar (left sticky) | Drawer (top trigger의 hamburger) |
+| Page padding (24-32px) | Page padding 16px |
+| Section/AnchorNav (2-col) | Section only + AnchorNav drawer |
+| DataGrid (table) | Card list (data-grid.md §3) |
+| PageHeader (1줄) | PageHeader (vertical stack — title / breadcrumb / actions 분리) |
+| max-width 640 form | full-width form |
+
+---
+
+## 9. 안티 패턴
+
+- ❌ **Page 마다 다른 layout** (사용자 mental model 깨짐) — 모든 페이지 같은 AppShell + PageHeader
+- ❌ **DataGrid 페이지에 max-width** — content 가 자연스럽지 못함. full-bleed
+- ❌ **form 페이지에 max-width 없음** — 1920px 의 가로 input 한 줄 어색
+- ❌ **PageHeader 의 actions 가 row-level** (예: row 의 "edit" 버튼) — DataGrid column action
+- ❌ **Sidebar 안 sub-Item 3 단계 이상** — 깊이 제한 (mental load)
+- ❌ **section 사이 gap 의 hardcoded px** — `var(--section-gap)` 사용
+- ❌ **page padding 의 hardcoded** — `var(--space-*)` token
+- ❌ **mobile 에서 Sidebar 그대로 left sticky** — drawer 변환 필수
+
+---
+
+## 10. Cross-cutting
+
+| Axis | 적용 |
+|---|---|
+| **Responsive** | Sidebar → drawer / padding 축소 / Section/AnchorNav 변환 / DataGrid → card list |
+| **A11y** | Sidebar `<nav>` semantic / PageHeader `<h1>` / Breadcrumb aria-label |
+| **i18n** | nav label / title / breadcrumb 모두 `t()` |
+| **Permission** | Sidebar.Item 의 권한별 hide (Step 7 Web Playbook) |
+| **Telemetry** | nav click / page view 자동 log (Step 7) |
+
+---
+
+## 11. apps/web 의 실 사용 (Step 7 Web Playbook 의 baseline)
+
+| Route | Layout |
+|---|---|
+| `/merchant/customers`, `/merchant/orders` etc. | AppShell + PageHeader + DataGrid (full-bleed) |
+| `/merchant/products/new`, `/merchant/products/[id]` | AppShell + PageHeader + Section/AnchorNav (큰 form) |
+| `/merchant/shop/business-info`, `/merchant/account/security` | AppShell + PageHeader + max-width 640 단순 form |
+| `/merchant/dashboard` (home) | AppShell + PageHeader + Grid (KPI / chart) full-bleed |
+| `/merchant/shop` (settings 종합) | AppShell + PageHeader + Section/AnchorNav (다 section) |
+
+---
+
+## 12. TBD
+
+1. **max-width 정확 px** — form 640? 720? 800? 페이지 종류별 정확 token
+2. **Sidebar collapsed (icon only) trigger** — 자동 (viewport 작음) vs 사용자 button
+3. **PageHeader sticky** — 스크롤 시 항상 위 또는 page top 만
+4. **AnchorNav drawer (mobile)** — top trigger vs bottom Sheet
+5. **Section gap responsive** — desktop 48px / mobile 32px 자동
+6. **container queries** — Page 안 Card 의 internal layout 이 Page width 아닌 Card width 기반
+
+---
+
+## Related Playbooks
+
+- [form.md](./form.md) — page-form / Section + AnchorNav (Step 4.1)
+- [data-grid.md](./data-grid.md) — DataGrid 가 Page 안 위치 (Step 4.3)
+- [overlay.md](./overlay.md) — Modal / Drawer 의 page 위 표시 (Step 4.4)
+- [async-states.md](./async-states.md) — Page-level loading / error (Step 4.7)

package/dist/data/playbook/responsive-tokens.md

@@ -0,0 +1,191 @@
+# MDS Playbook — Responsive Tokens
+
+mds 의 "Responsive by default" 의 token 측 구현 — caller 의 코드 변경 없이 mobile 별 visual scale 자동 적용.
+
+---
+
+## 1. 결정 — 2 방식 의 조합
+
+| 방식 | 적용 | 의도 |
+|---|---|---|
+| **Token responsive** (CSS @media) | 단순 visual scale (font-size / spacing) | caller 코드 변경 없이 자동 |
+| **JS breakpoint hook** (`useBreakpoint`) | layout 분기 (DataGrid → card list 같은 큰 변형) | 의도 명시 + reactive |
+| **Tailwind utility** (`text-3xl md:text-4xl`) | 페이지 별 override 또는 의도된 단계 | caller 명시 |
+
+> **default = token responsive** (자동). 큰 layout 변형 만 hook / utility 명시.
+
+---
+
+## 2. Token 의 `$extensions.mds.responsive`
+
+W3C DTCG 표준 의 `$extensions` field 활용 — vendor 별 metadata.
+
+```jsonc
+// packages/mds/src/tokens/global/typography.json
+"3xl": {
+  "$value": "24px",
+  "$type": "fontSize",
+  "$description": "Tone 1 h1 (Stripe slim). Mobile (max-sm): 20px (0.83x).",
+  "$extensions": {
+    "mds.responsive": {
+      "max-sm": "20px"
+    }
+  }
+}
+```
+
+### 지원 breakpoint key
+
+| Key | CSS @media | 의도 |
+|---|---|---|
+| `max-sm` | `(max-width: 639px)` | mobile (< 640px) |
+| `max-md` | `(max-width: 767px)` | mobile + small tablet |
+| `max-lg` | `(max-width: 1023px)` | 모든 portrait device |
+| `max-xl` | `(max-width: 1279px)` | non-wide desktop |
+
+> `min-*` 도 추후 추가 가능 (현재 mobile-first compress 만 — desktop 의 base 가 더 큰 size, mobile 이 축소). 의도 다르면 추가 cycle.
+
+---
+
+## 3. Build pipeline
+
+`packages/mds/scripts/lib/formats.ts` 의 `cssThemeFormat` 가 `$extensions.mds.responsive` 인식.
+
+### Output 예 (dist/css/global.css)
+
+```css
+:root, [data-theme="light"] {
+  --text-3xl: 24px;
+  --text-4xl: 30px;
+  --space-8: 32px;
+  --space-12: 48px;
+  --space-20: 80px;
+}
+
+@media (max-width: 639px) {
+  :root, [data-theme="light"] {
+    --space-8: 16px;
+    --space-10: 20px;
+    --space-12: 24px;
+    --space-16: 32px;
+    --space-20: 40px;
+    --text-3xl: 20px;
+    --text-4xl: 24px;
+  }
+}
+```
+
+→ 3 theme (admin-light / admin-dark / marketing) 모두 동일.
+
+---
+
+## 4. 현재 적용 token
+
+### Typography (`typography.json`)
+
+| Token | desktop | max-sm (mobile) | 의도 |
+|---|---|---|---|
+| `text-3xl` | 24px | 20px (0.83x) | h1 heading |
+| `text-4xl` | 30px | 24px (0.8x) | display heading |
+| `text-2xl` 이하 | 그대로 | (override 없음) | small 이미 mobile-OK |
+| `display-1/2/3` | `clamp(...)` | (clamp 자체 vw 기반 자동) | marketing hero |
+
+### Space (`space.json`)
+
+| Token | desktop | max-sm (mobile) | 의도 |
+|---|---|---|---|
+| `space-8` | 32px | 16px (0.5x) | page padding x |
+| `space-10` | 40px | 20px (0.5x) | (특수) |
+| `space-12` | 48px | 24px (0.5x) | section gap (default) |
+| `space-16` | 64px | 32px (0.5x) | large section gap |
+| `space-20` | 80px | 40px (0.5x) | bottom page padding |
+| `space-6` 이하 | 그대로 | (override 없음) | small 이미 mobile-OK |
+
+---
+
+## 5. Caller — 활용
+
+### A. 자동 (default)
+
+```tsx
+// 코드 변경 없이 mobile 자동 적용
+<h1 style={{ fontSize: 'var(--text-3xl)' }}>제목</h1>
+<section style={{ marginBottom: 'var(--space-12)' }}>...</section>
+```
+
+### B. Tailwind 통한 (token reference)
+
+```tsx
+<h1 className="text-3xl">제목</h1>
+<section className="mb-12">...</section>
+```
+
+Tailwind preset 의 `text-3xl` 가 `var(--text-3xl)` reference → 자동 mobile.
+
+### C. JS 분기 (큰 layout 변형 만)
+
+```tsx
+import { useBreakpoint, useIsBreakpointUp } from '@makitt/mds';
+
+const bp = useBreakpoint();
+const isDesktop = useIsBreakpointUp('lg');
+
+if (bp === null) return <MobileList />;     // < sm
+if (!isDesktop) return <TabletGrid />;      // sm 이상 lg 미만
+return <DesktopDataGrid />;
+```
+
+> 단순 visual scale (font-size / spacing) 에 hook 사용 = anti-pattern. token responsive 활용.
+
+---
+
+## 6. 결정 표 (lookup)
+
+| 케이스 | 답 |
+|---|---|
+| "h1 의 mobile 의 size 축소" | token responsive — `$extensions.mds.responsive.max-sm` |
+| "DataGrid → mobile 의 card list" | `useBreakpoint() === null` 의 분기 (큰 변형) |
+| "Sidebar → mobile 의 drawer 모드" | `useIsBreakpointUp('md')` 의 분기 (또는 mds 의 AppShell 자체 처리) |
+| "특정 페이지 의 큰 hero size" | Tailwind `text-4xl md:text-6xl` 또는 token clamp (display-*) |
+| "section gap 의 mobile 축소" | token responsive — `space-12` 의 `max-sm` |
+| "특정 페이지 의 unique padding" | inline / Tailwind utility (token override 보다 caller 직접) |
+
+---
+
+## 7. 안티 패턴
+
+- ❌ **inline JS 분기 의 padding / font-size** (`style={{ padding: bp === null ? 16 : 32 }}`) — token responsive 활용
+- ❌ **DataGrid → card list 전환 의 token 만 의지** — layout 큰 변형 = JS 분기 필요
+- ❌ **token 의 한 size 만 mobile 안 적용** (다른 size 는 mobile 자동 인데) — 일관성. token responsive 의 metadata 통일
+- ❌ **`@media` block 의 직접 inline** (component SCSS 의 `@media (max-width: 640px) { ... }`) — token responsive 가 자동
+- ❌ **breakpoint 의 hardcoded px** (`@media (max-width: 700px)`) — token sm/md/lg/xl 통해
+- ❌ **mobile 의 "고정" size** (clamp 대신 max-sm = 12px 같은 너무 작은) — 사용자 가 읽을 size 보장 (≥ 14px body)
+
+---
+
+## 8. TBD (별도 cycle)
+
+1. **min-* breakpoint** — desktop 이 더 큰 size 의 의도 (mobile-first 보다 의도 다름). 현재 max-* 만
+2. **breakpoint 의 dynamic mapping** — `formats.ts` 의 `RESPONSIVE_BREAKPOINT_QUERIES` 가 hardcoded. `breakpoint.json` read 후 dynamic 가능
+3. **추가 token 의 mobile fallback** — line-height / radius / shadow / icon-size 의 mobile 의도. 추가 token JSON 의 `$extensions` metadata
+4. **Tailwind preset 의 responsive** — Tailwind 의 `text-3xl md:text-4xl` 같은 utility 의 자동 generation (token 의 mobile / desktop 양쪽 활용)
+5. **Storybook viewport addon** — Storybook 의 viewport addon 의 standard viewport 추가 (mobile 375 / tablet 768 / desktop 1280)
+
+---
+
+## 9. Cross-cutting
+
+| Axis | 적용 |
+|---|---|
+| **A11y** | mobile 의 최소 font-size (14px body 기준) + tap target (44x44px 권장) 따로 |
+| **i18n** | 한국어 의 폰 size 별 가독성 (CJK 가 라틴 보다 작은 px 에 어려움) — mobile 의 base 가 너무 작지 않게 |
+| **AI fill** | token 명 의 catalog 가 mds_components_get 통해 (Step 5) — AI 가 `var(--text-3xl)` 자동 권장 |
+| **Catalog** | token / 페이지 별 사용 의 inventory (TBD — 추가 catalog) |
+
+---
+
+## Related Playbooks
+
+- [page-layout.md](./page-layout.md) — Page / Section / Sidebar 의 responsive 변형
+- [data-grid.md](./data-grid.md) — DataGrid → mobile card list 변형 (큰 변형)
+- [form.md](./form.md) — Form 의 mobile 변형 표 (각 § 의 Mobile 컬럼)

package/dist/index.d.ts

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+/**
+ * @makitt/mds-mcp-server — MCP server for mds.
+ *
+ * AI (Claude Code / Cursor) 가 mds catalog + playbook 자동 query 가능.
+ * Fabrication 0 의 최종 layer — 사용자가 mds 의 props / 안티패턴 / 사용 약속 정확 lookup.
+ *
+ * Tools:
+ *   - mds_components_list — 모든 컴포넌트 list (layer 필터)
+ *   - mds_components_get — 특정 컴포넌트 의 full spec (props/types/description)
+ *   - mds_components_search — text search (name / description / prop)
+ *   - mds_playbook_list — 모든 Playbook area list
+ *   - mds_playbook_get — 특정 Playbook 의 content (form / feedback / data-grid 등)
+ *   - mds_playbook_search — Playbook 의 decision matrix / 안티패턴 검색
+ *
+ * Transport: stdio (Claude Code / Cursor 호환)
+ *
+ * Setup:
+ *   1. Build: `pnpm build`
+ *   2. Claude Code MCP config: ~/.claude/claude_desktop_config.json
+ *      {
+ *        "mcpServers": {
+ *          "mds": { "command": "node", "args": ["/path/to/mds-mcp-server/dist/index.js"] }
+ *        }
+ *      }
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG"}