@infomind-ux/infoux-mcp 0.2.0 → 0.3.0

package/data/snippets/main-menu.md

@@ -1,6 +1,6 @@
 # 주 메뉴 (Main Menu) — KRDS
 
-드롭다운형 주 내비게이션. 헤더 안에서 사용.
+드롭다운형·메가형 주 내비게이션. 헤더 안에서 사용한다. 하위 메뉴는 **disclosure 패턴**(버튼이 링크 목록을 열고 닫는다)이다.
 
 ## 기본 마크업
 
@@ -12,8 +12,9 @@
     </li>
 
     <li class="main-menu__item">
-      <button type="button" class="main-menu__link" aria-haspopup="true" aria-expanded="false" aria-controls="submenu-services">
+      <button type="button" class="main-menu__toggle" aria-expanded="false" aria-controls="submenu-services">
         서비스
+        <svg class="main-menu__icon icon icon--xsmall" aria-hidden="true"><use href="/assets/icons/sprite.svg#chevron-down"></use></svg>
       </button>
       <ul id="submenu-services" class="main-menu__submenu" hidden>
         <li><a href="/services/a">서비스 A</a></li>
@@ -29,21 +30,87 @@
 </nav>
 ```
 
+## 시맨틱 구조
+
+- **Root 태그**: `<nav class="main-menu" aria-label="주 메뉴">`
+- **자식**: `ul.main-menu__list` → `li.main-menu__item` → `a.main-menu__link`(이동) 또는 `button.main-menu__toggle`(하위 패널 열기)
+- **필수 ARIA**: `nav`에 `aria-label` · 토글 버튼에 `aria-expanded` + `aria-controls` · 현재 페이지에 `aria-current="page"`
+- **쓰지 않는 것**: `role="menu"` · `role="menuitem"` · `aria-haspopup` — 링크 목록을 펼치는 것일 뿐 애플리케이션 메뉴가 아니다
+
+> 상세: `references/html-semantics.md#main-menu`
+
+## Variant
+
+| Variant | 클래스 | 용도 |
+|---------|--------|------|
+| 드롭다운 | (기본) | 항목 아래 작은 목록. 하위 링크가 한 줄로 끝나는 메뉴 |
+| 메가 | `.main-menu--mega` | 헤더 전체 폭 패널에 그룹별로 나눈 링크. 하위 링크가 많거나 그룹이 있는 메뉴 |
+
+### 메가 메뉴
+
+패널이 헤더 전체 폭으로 열린다. 그룹 제목은 링크가 아니라 텍스트이고, 목록은 `aria-labelledby`로 그룹 이름을 받는다.
+
+```html
+<nav class="main-menu main-menu--mega" aria-label="주 메뉴">
+  <ul class="main-menu__list">
+    <li class="main-menu__item">
+      <button type="button" class="main-menu__toggle" aria-expanded="false" aria-controls="mega-service">
+        민원 서비스
+        <svg class="main-menu__icon icon icon--xsmall" aria-hidden="true"><use href="/assets/icons/sprite.svg#chevron-down"></use></svg>
+      </button>
+      <div id="mega-service" class="main-menu__panel" hidden>
+        <div class="container main-menu__groups">
+          <div class="main-menu__group">
+            <p class="main-menu__group-title" id="mega-service-apply">신청</p>
+            <ul class="main-menu__group-list" aria-labelledby="mega-service-apply">
+              <li><a class="main-menu__sublink" href="/apply/permit">허가 신청</a></li>
+              <li><a class="main-menu__sublink" href="/apply/report">신고</a></li>
+              <li><a class="main-menu__sublink" href="/apply/certificate">증명서 발급</a></li>
+            </ul>
+          </div>
+          <div class="main-menu__group">
+            <p class="main-menu__group-title" id="mega-service-lookup">조회</p>
+            <ul class="main-menu__group-list" aria-labelledby="mega-service-lookup">
+              <li><a class="main-menu__sublink" href="/lookup/status" aria-current="page">처리 현황</a></li>
+              <li><a class="main-menu__sublink" href="/lookup/history">신청 내역</a></li>
+            </ul>
+          </div>
+        </div>
+      </div>
+    </li>
+
+    <li class="main-menu__item">
+      <a class="main-menu__link" href="/notice">공지사항</a>
+    </li>
+  </ul>
+</nav>
+```
+
 ## 동작 (JS)
 
-- 드롭다운 토글: `aria-haspopup` 가진 `<button>` 클릭 → 해당 `aria-controls` 서브메뉴 hidden 토글 + `aria-expanded` 토글
-- 외부 클릭 시 닫기
-- ESC 키로 닫기 + 트리거 버튼으로 포커스 복귀
-- 키보드: 화살표로 항목 이동, Enter/Space로 선택
+`src/js/disclosure-nav.js` — 드롭다운·메가 공통.
+
+- 토글 버튼 클릭(`Enter`/`Space`) → 해당 `aria-controls` 패널의 `hidden` 토글 + `aria-expanded` 갱신. 다른 패널은 닫는다
+- `Esc` → 열린 패널을 닫고 **초점을 토글 버튼으로 되돌린다**
+- 메뉴 바깥 클릭 → 닫기
+- `Tab`으로 열린 항목 밖으로 초점이 나가면 닫기
+- 방향키 운용은 하지 않는다 — 링크는 `Tab`으로 순서대로 지난다
+- 마우스를 올리는 것만으로는 열지 않는다(클릭 전용). 호버로 열리면 WCAG 1.4.13(호버 콘텐츠)을 따로 만족시켜야 한다
 
 ## 접근성
 
-- 서브메뉴 트리거는 `<button>` 권장 (`<a>` 아님 — 링크가 아니므로)
-- `aria-haspopup="true"` + `aria-expanded` 상태값
-- `aria-controls`로 서브메뉴 id 연결
-- 서브메뉴 `<ul>`은 `hidden` 속성으로 노출 제어
-- 현재 페이지: `aria-current="page"`
+- 하위 메뉴 트리거는 `<button>` (링크가 아니므로 `<a>` 쓰지 않는다)
+- `aria-expanded`(`true`/`false`) + `aria-controls`(패널 id) — 연결 대상 id가 실제로 존재해야 한다
+- 패널은 `hidden` 속성으로 노출을 제어한다 — 닫힌 패널의 링크는 Tab 순서에서 빠진다
+- 현재 페이지는 `aria-current="page"`. 패널 안에 현재 페이지가 있어도 토글 버튼은 그대로 둔다
+- 링크 터치 영역 44px 이상 — 패널 링크는 `min-h-[4.4rem]`를 포함한다
+- 초점 외곽선: 칸을 꽉 채우는 패널 링크는 `outline-offset`을 음수로 두어 안쪽에 그린다
+- 아이콘은 장식 — `aria-hidden="true"`, 의미는 옆 텍스트가 전한다
+- 메가 패널이 열려 있어도 본문 스크롤을 막지 않는다. 포커스 트랩이 없다(모달이 아니다)
 
 ## 출처
 
+- WAI-ARIA APG: Disclosure Navigation Menu (https://www.w3.org/WAI/ARIA/apg/patterns/disclosure/examples/disclosure-navigation/)
 - CSS: `src/styles/6-components/main-menu.css`
+- JS: `src/js/disclosure-nav.js`
+- 아이콘: `chevron-down` 스프라이트 — `/assets/icons/sprite.svg` (아이콘 카탈로그, R-27)

package/data/snippets/mobile-menu.md

@@ -0,0 +1,99 @@
+# 모바일 메뉴 (Mobile Menu) — infoUX
+
+헤더 햄버거로 여는 전체 화면 메뉴. 1280px 미만(모바일·태블릿)에서 [주 메뉴](main-menu.md)를 대신한다. 화면 전체를 덮으므로 모달처럼 초점을 가둔다.
+
+## 기본 마크업
+
+헤더의 햄버거 버튼과 패널은 **한 쌍**이다. 패널은 `header` 바깥(페이지 shell의 `body` 직계)에 둔다.
+
+```html
+<header id="header" class="site-header">
+  <div class="container site-header__inner">
+    <a class="site-header__brand" href="/">
+      <img src="/logo.svg" alt="기관명">
+    </a>
+    <div class="site-header__actions">
+      <button type="button" class="site-header__toggle" aria-label="전체 메뉴" aria-expanded="false" aria-controls="mobile-menu" data-mobile-menu-open="mobile-menu">
+        <svg class="icon" aria-hidden="true"><use href="/assets/icons/sprite.svg#menu"></use></svg>
+      </button>
+    </div>
+  </div>
+</header>
+
+<div id="mobile-menu" class="mobile-menu" role="dialog" aria-modal="true" aria-labelledby="mobile-menu-title" hidden>
+  <div class="mobile-menu__header">
+    <p id="mobile-menu-title" class="mobile-menu__title">전체 메뉴</p>
+    <button type="button" class="mobile-menu__close" aria-label="전체 메뉴 닫기" data-mobile-menu-close>
+      <svg class="icon" aria-hidden="true"><use href="/assets/icons/sprite.svg#close"></use></svg>
+    </button>
+  </div>
+
+  <nav class="mobile-menu__nav" aria-label="주 메뉴">
+    <ul class="mobile-menu__list">
+      <li class="mobile-menu__item">
+        <a class="mobile-menu__link" href="/about">소개</a>
+      </li>
+      <li class="mobile-menu__item">
+        <details class="mobile-menu__group">
+          <summary class="mobile-menu__summary">
+            서비스
+            <svg class="mobile-menu__icon icon icon--xsmall" aria-hidden="true"><use href="/assets/icons/sprite.svg#chevron-down"></use></svg>
+          </summary>
+          <ul class="mobile-menu__sublist">
+            <li><a class="mobile-menu__sublink" href="/services/apply">신청</a></li>
+            <li><a class="mobile-menu__sublink" href="/services/lookup" aria-current="page">조회</a></li>
+            <li><a class="mobile-menu__sublink" href="/services/guide">이용 안내</a></li>
+          </ul>
+        </details>
+      </li>
+      <li class="mobile-menu__item">
+        <a class="mobile-menu__link" href="/notice">공지사항</a>
+      </li>
+    </ul>
+  </nav>
+</div>
+```
+
+## 시맨틱 구조
+
+- **Root 태그**: `<div class="mobile-menu" role="dialog" aria-modal="true" aria-labelledby="…" hidden>`
+- **자식**: `__header`(제목 + 닫기 버튼) → `nav.mobile-menu__nav` → `ul.mobile-menu__list`
+- **하위 메뉴**: native `<details>/<summary>` — 열고 닫는 상태를 브라우저가 관리한다. ARIA를 덧붙이지 않는다
+- **필수 ARIA**: 패널에 `role="dialog"` + `aria-modal="true"` + `aria-labelledby` · 햄버거에 `aria-expanded` + `aria-controls`
+
+> 상세: `references/html-semantics.md#mobile-menu`
+
+## 동작 (JS)
+
+`src/js/mobile-menu.js`
+
+- 열기: 햄버거(`data-mobile-menu-open="패널 id"`) 클릭 → `hidden` 제거 + 햄버거 `aria-expanded="true"` + 본문 스크롤 잠금 + 첫 포커스 가능 요소(닫기 버튼)로 초점 이동
+- 닫기: 닫기 버튼(`data-mobile-menu-close`) 또는 `Esc` → `hidden` 복원 + `aria-expanded="false"` + **햄버거로 초점 복귀**
+- 포커스 트랩: `Tab`/`Shift+Tab`이 패널 안에서만 순환한다. 닫힌 `details` 안의 링크는 순환에서 빠진다
+- 같은 페이지 앵커(`href="#…"`)를 누르면 메뉴를 닫는다
+- 화면이 1280px 이상으로 넓어지면 열려 있던 패널을 정리한다 (주 메뉴가 대신한다)
+
+## 사용 조건
+
+- 하위 단계는 한 단계까지 — `details` 안에 `details`를 또 넣지 않는다. 더 깊으면 메뉴 구조를 다시 짠다
+- 패널 안에 검색·로그인 같은 유틸리티를 둘 수 있다. 이 경우에도 닫기 버튼이 항상 첫 번째 포커스 대상이다
+- 패널 타이틀은 "전체 메뉴"처럼 기능 이름을 쓴다. 기관 홍보 문구를 넣지 않는다
+- 장식 애니메이션은 쓰지 않는다. 열림은 즉시 나타나는 것이 기본이다 (필요하면 fade 150~200ms, `prefers-reduced-motion` 가드 필수 · R-22)
+
+## 접근성
+
+- 패널 열림 중 뒤쪽 콘텐츠는 `aria-modal="true"`로 스크린리더 탐색에서 빠진다
+- 햄버거 `aria-label`은 **고정**한다 (`전체 메뉴`). 열림 여부는 `aria-expanded`가 전하므로 라벨을 "열기/닫기"로 바꾸지 않는다
+- 닫기 버튼 `aria-label="전체 메뉴 닫기"` 필수 — 아이콘만 있는 버튼이므로
+- 아이콘은 모두 장식 — `aria-hidden="true"`. 햄버거·닫기 모양의 텍스트 기호로 아이콘을 대신하지 않는다 (R-27)
+- 터치 영역: 햄버거·닫기 44×44px, 항목 56px / 하위 항목 48px (R-13)
+- 초점 외곽선: 스크롤 영역(`overflow-y: auto`) 안에서 칸을 꽉 채우는 항목은 바깥 외곽선이 잘리므로 `outline-offset`을 음수로 두어 안쪽에 그린다
+- 현재 페이지는 `aria-current="page"`
+- 키보드: `Tab` 순환 · `Enter`/`Space`로 `summary` 토글 · `Esc` 닫기
+
+## 출처
+
+- WAI-ARIA APG: Dialog (Modal) — https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+- CSS: `src/styles/6-components/mobile-menu.css`
+- JS: `src/js/mobile-menu.js`
+- 아이콘: `menu` · `close` · `chevron-down` 스프라이트 — `/assets/icons/sprite.svg` (아이콘 카탈로그, R-27)

package/data/snippets/notice-bar.md

@@ -0,0 +1,85 @@
+# 공지 띠 (Notice Bar) — infoUX
+
+페이지 최상단에서 사이트 방문자 모두에게 한 번 알리는 공지. 점검·휴무·운영 변경처럼 **기간이 있는 안내**에 쓴다.
+
+## 기본 마크업
+
+페이지 shell에서 **건너뛰기 링크(`.skip-to-content`) 다음, `header#header` 앞**에 둔다.
+
+```html
+<section class="notice-bar notice-bar--info" aria-label="사이트 공지" data-notice-id="2026-10-maintenance">
+  <div class="container notice-bar__inner">
+    <span class="notice-bar__label">점검</span>
+    <p class="notice-bar__message">
+      <a class="notice-bar__link" href="/notice/maintenance">10월 12일 새벽 0시부터 6시까지 시스템 점검이 있습니다</a>
+    </p>
+    <button type="button" class="notice-bar__close" aria-label="공지 닫기">
+      <svg class="icon" aria-hidden="true"><use href="/assets/icons/sprite.svg#close"></use></svg>
+    </button>
+  </div>
+</section>
+```
+
+## 시맨틱 구조
+
+- **Root 태그**: `<section class="notice-bar" aria-label="사이트 공지">` — 이름 있는 영역(region)이 되어 스크린리더 랜드마크 탐색에 잡힌다
+- **자식**: `.container` → `__label`(분류 텍스트) · `__message`(문장 + 링크) · `__close`(닫기 버튼)
+- **필수 ARIA**: `aria-label` (영역 이름) · 닫기 버튼 `aria-label="공지 닫기"`
+- **라이브 영역을 쓰지 않는다**: `role="alert"` · `aria-live`는 붙이지 않는다. 페이지 로드 때 이미 있는 정적 안내이고, 낭독을 강제하면 매 페이지마다 방해가 된다
+
+> 상세: `references/html-semantics.md#notice-bar`
+
+## Variant
+
+| Variant | 클래스 | 용도 | 라벨 예 |
+|---------|--------|------|---------|
+| 정보 | `.notice-bar--info` | 일반 안내 (기본) | 공지 |
+| 주의 | `.notice-bar--warning` | 점검·휴무·일정 변경 | 점검 |
+| 긴급 | `.notice-bar--danger` | 서비스 중단·장애·재난 | 긴급 |
+
+톤은 색만으로 전하지 않는다 — 라벨 텍스트가 같은 뜻을 전한다 (WCAG 1.4.1).
+
+## 동작 (JS)
+
+`src/js/notice-bar.js`
+
+- 닫기 버튼 → 띠에 `hidden` 부여. `data-notice-id`가 있으면 `localStorage`에 닫은 기록을 남긴다
+- 다음 방문에는 같은 `data-notice-id`의 띠를 로드 때 숨긴다. **공지 내용이 바뀌면 `data-notice-id`도 바꾼다** — 그래야 새 공지가 다시 보인다
+- 닫은 뒤 초점은 헤더의 첫 링크·버튼으로 옮긴다 (사라진 버튼에 초점이 남지 않게)
+- 저장소를 못 쓰는 환경(시크릿 모드·차단)에서도 닫기 자체는 동작한다. 다음 방문에 다시 보일 뿐이다
+
+## 사용 조건
+
+- **한 번에 하나만** 둔다. 여러 공지가 있으면 가장 중요한 하나를 띄우고 나머지는 공지사항 목록으로 안내한다
+- **자동으로 넘어가거나 굴러가는 형태(롤링·마키)로 만들지 않는다.** 5초 넘게 움직이는 콘텐츠는 멈출 수 있어야 하고(WCAG 2.2.2), 읽기 어려운 사용자를 만든다
+- 장문의 본문을 띠에 넣지 않는다. 한 줄 요약 + 상세 페이지 링크로 둔다
+- 만료일이 지난 공지는 내린다. 기간 없는 상시 안내(약관 변경 등)에 쓰지 않는다
+- 쿠키·개인정보 동의 배너와 다르다 — 동의 요청은 이 컴포넌트로 만들지 않는다
+- 사이트 유형: 공공서비스·공공기관·일반사이트·커머스에서 쓴다. CMS·관리자는 시스템 공지를 `alert`로 화면 안에 둔다
+
+### 다른 알림 컴포넌트와의 구분
+
+| | 공지 띠 | Alert | Toast |
+|---|---------|-------|-------|
+| 위치 | 페이지 최상단 | 해당 콘텐츠 영역 안 | 화면 모서리 |
+| 성격 | 사이트 전체 안내 (정적) | 이 화면의 상태 메시지 | 방금 한 동작의 결과 |
+| 사라짐 | 사용자가 닫음 | 상태가 바뀔 때 | 몇 초 뒤 자동 |
+| 라이브 영역 | 쓰지 않음 | `role="alert"`/`status` | `role="status"`/`alert` |
+
+## 접근성
+
+- 영역 이름 `aria-label="사이트 공지"` — 페이지에 비슷한 영역이 더 있으면 서로 다른 이름으로 구분한다
+- 링크는 밑줄로 구분한다. 색 차이만으로 링크임을 전하지 않는다
+- 닫기 버튼은 아이콘만 있으므로 `aria-label` 필수. 아이콘은 `aria-hidden="true"`
+- 터치 영역: 닫기 버튼 44×44px, 링크 `min-h-[4.4rem]` (R-13)
+- 대비: 본문 텍스트 `--color-text`, 라벨은 `--color-text-inverse` on `--color-information-60`/`--color-warning-60`/`--color-danger-60` (4.5:1 이상)
+- 닫은 뒤 초점이 문서 처음으로 날아가지 않도록 헤더로 옮긴다 (WCAG 2.4.3)
+- 동적으로 삽입하는 긴급 안내(장애 발생 직후 등)는 이 컴포넌트가 아니라 [alert](alert.md)의 `role="alert"`를 쓴다
+
+## 출처
+
+- 색상은 `--color-info-surface` · `--color-information-20` · `--color-information-60` (톤별 warning/danger 동일 구조)
+- 간격·타이포는 프로젝트 밀도에 맞는 CSS/Tailwind 직접값 사용
+- CSS: `src/styles/6-components/notice-bar.css`
+- JS: `src/js/notice-bar.js`
+- 아이콘: `close` 스프라이트 — `/assets/icons/sprite.svg` (아이콘 카탈로그, R-27)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@infomind-ux/infoux-mcp",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "INFOMIND UX 퍼블리싱 기준(infoUX)을 MCP로 제공한다. 토큰·컴포넌트·규칙·접근성 기준을 에이전트가 직접 조회한다.",
   "bin": {
     "infoux-mcp": "bin/server.js"