# 다른 프로젝트 적용 가이드 이 문서는 **새 사이트에 이 킷을 붙일 때** 체크리스트입니다. --- ## 1. 복사 순서 1. `font/` 전체 (또는 사용할 weight만) 2. `css/tokens.css` + `css/normalize.css` + `css/common.css` + **`css/layout.css`** (페이지 셸) 3. 필요한 컴포넌트 CSS만 (`button` / `form` / `table` / `popup` / `faq` / `loading` / `tab` / `slide` / `chart` / `menu` / `editor` / `main` / `board` / `search` / `breadcrumb` / `alert` / `step` / `footer` / `related` / `share` / `video` / `map` / `scroll-panel` / `login`) 4. 해당 컴포넌트 `img/` 파일 (아래·각 docs 참고) 5. `js/jquery-3.7.1.min.js` + `js/common.js` 6. 선택: `jquery.nice-select.js`, 우편번호 CDN 7. 데모 HTML에서 **마크업만** 복사 (`.ui-guide` 래퍼는 제외해도 됨) --- ## 2. 컴포넌트별 복사 패키지 ### 레이아웃 (페이지 셸) ``` css/tokens.css ← KRDS 색 (--ccolor = primary-50) css/layout.css css/common.css ← tokens import · #skipToContent img/logo.svg · util-login.svg · util-search.svg 마크업: layout.html → 상세: docs/layout.md · docs/tokens.md ※ 스킵(body 첫 요소) > #wrap > header(유틸·로고·GNB) > container > footer > quick ※ 1단 / .layout-body--aside (좌메뉴+본문) ※ GNB 상세: menu · 브레드크럼: breadcrumb · 푸터: footer ``` ### SEO · GEO ``` 마크업·체크: seo.html 문서: docs/seo.md css/seo.css ← 이 가이드 페이지 UI만 (실서비스 복사 X) → 상세: docs/seo.md · 메타는 docs/head.md ※ 페이지당 핵심 검색어 1개 · title·H1·description·첫 문단에 답 ※ JSON-LD는 화면 내용과 일치 · 숨은 키워드·클로킹 금지 ※ GEO: 질문형 소제목 · 짧은 정의 · FAQ 답이 HTML에 존재 ``` ### 버튼만 ``` css/button.css js/common.js ← .btn-switch(data-btn-switch) 쓸 때 (공통 css/common.css 권장) 마크업: button.html 참고 → 상세: docs/button.md ※ 버튼형 스위치: button + aria-pressed (쉬운화면 ON/OFF 패턴) ※ 폼용 트랙 스위치는 form.css .toggle-box ``` ### 폼 ``` css/form.css css/datepicker.css ← Duet 날짜선택 쓸 때 img/eye.svg, eye-off.svg ← 비번보기 img/icon-calendar.svg, calendar-time.svg ← 네이티브 캘린더·시간 아이콘 js/jquery + common.js js/jquery.nice-select.js ← select 커스텀 시 js/datepicker-a11y.js (module) ← Duet Date Picker 한국어 CDN: @duetds/date-picker themes ← 외부 날짜선택 postcode.v2.js (CDN) ← 주소검색 시 마크업: form.html → 상세: docs/form.md ``` ### 테이블 ``` css/table.css css/form.css ← 체크/라디오/입력형 테이블이면 js/jquery + common.js ← 전체선택 체크 시 마크업: table.html → 상세: docs/table.md ``` ### 페이징 ``` css/common.css 안의 .paging / .paging2 / .paging3 img/paging_*.svg 또는 paging2_*.svg 마크업: paging.html JS: 없음 ※ 현재 화면: href 없음 + aria-current="true" ※ 터치 영역 44×44px · 전체 페이지 수 표시 → 상세: docs/paging.md ``` ### 팝업(모달) ``` css/popup.css css/button.css ← 푸터 버튼 img/ly_close.png js/jquery + common.js (modal 섹션) 마크업: popup.html (레이어는 보통 직전) → 상세: docs/popup.md ``` ### FAQ ``` css/faq.css css/table.css ← table형일 때 img/faq_up.png, icon_attach.png js/jquery + common.js (FAQ 섹션) 마크업: faq.html → 상세: docs/faq.md ``` ### 로딩화면 ``` css/loading.css js/jquery + common.js (loading 섹션) 마크업: loading.html · 전체: #loadingOverlay (#wrap 밖) · loadingShow / loadingHide · 섹션: .loading-section > .loading-overlay--section loadingShowIn(target) / loadingHideIn(target) → 상세: docs/loading.md ``` ### 탭메뉴 ``` css/tab.css js/jquery + sectionDisplay.js 마크업: tab.html → 상세: docs/tab.md ``` ### 슬라이드 (Swiper CDN) ``` css/slide.css CDN: swiper-bundle.min.css / .js (v11) 마크업: slide.html (메인 비주얼 · 알림 · 하단 배너) → 상세: docs/slide.md ※ 자동재생 시 일시정지 버튼 필수 / prefers-reduced-motion 시 자동재생 OFF ``` ### 차트 (Chart.js CDN) ``` css/chart.css js/chart-a11y.js CDN: chart.umd.min.js (v4) css/table.css ← 대체 표 스타일 쓸 때 마크업: chart.html (.chart-block) → 상세: docs/chart.md ※ 대체 표 필수 / 키보드 탐색 + aria-live / 색만으로 구분 금지 ※ prefers-reduced-motion 시 애니메이션 OFF ``` ### 메뉴 (GNB · 전체메뉴 · 모바일) ``` css/menu.css js/menu.js ← vanilla (jQuery 불필요) 마크업: menu.html - header.a11y-header + #allMenuLayer (#wrap 밖 권장) → 상세: docs/menu.md ※ 서브: button + aria-expanded + hidden (Tab 순차) ※ ≤959px: PC GNB 숨김 → 전체메뉴 = 모바일 메뉴 ※ 전체메뉴: dialog · 포커스 트랩 · Esc · 초점 회귀 ``` ### 에디터 (TinyMCE · CKEditor 5 CDN) ``` css/editor.css css/form.css ← label / .form-textarea js/editor-a11y.js CDN TinyMCE: tinymce@7 · license_key: 'gpl' CDN CKEditor5: super-build/ckeditor.js@41.4.2 + translations/ko.js 마크업: editor.html - data-editor="tinymce" → a11yEditor.initAll() - data-editor="ckeditor5" → a11yEditor.initAllCkeditor5() (+ data-ck-mount) → 상세: docs/editor.md ※ 서식 불필요하면 네이티브 textarea 권장 ※ HTML 코드 전환(data-editor-plain) 권장 ※ CKEditor v44 UMD+GPL 은 읽기전용 이슈 → 41.x super-build 사용 (글꼴·크기) ``` ### 메인 · 최신글 · 팝업존 · 레이어 팝업 ``` css/main.css · slide.css Swiper 11 CDN (css + js) ← 팝업존 슬라이드 popup.css · button.css · form.css js/jquery + js/sectionDisplay.js js/common.js ← mainPopupInit({ autoOpen: true }) 마크업: main.html (.main-split · .latest-board · .popup-zone · .main-popup) img/popup_zone_0n.png · img/main_popup_notice.svg → 상세: docs/main.md · docs/slide.md ※ 팝업존(.popup-zone) ≠ 레이어(.main-popup) — 별개 ※ 팝업존 = Swiper 배너 (건수·이전·정지/재생·다음·+) ※ 레이어 = 조건 통과 시 1건 · hideDays(localStorage) ※ 탭: 게시글 5건 + 더보기 · 초점 선택 탭 → 게시글 → 더보기 ``` ### 게시판 (목록 / 상세) ``` css/board.css css/table.css ← 표형 목록 css/form.css ← 검색 필드 css/button.css ← 검색·목록 버튼 css/common.css ← 페이징 img/gallery/gallery_0n.svg ← 갤러리 데모 썸네일(선택) 마크업: board.html (.board / .board-gallery / .board-view) 예시: notice.html · press.html (표) · gallery.html (갤러리) → 상세: docs/board.md ※ 검색 role=search · 표 caption/scope ※ 갤러리: .board-gallery[data-cols="4"] · 카드당 링크 하나 · 제목 보이면 img alt="" ※ 공지·새글은 텍스트(+ .dn) · 첨부는 download.svg + .dn ※ 상세: 이전/다음 nav · 첨부 용량 표기 · 목록 버튼 ``` ### 검색 (통합 검색) ``` css/search.css css/form.css css/button.css css/common.css ← 페이징 마크업: search.html (.search / .search-bar / .search-result) → 상세: docs/search.md ※ role="search" · 모든 입력 label (숨김 시 label.dn) ※ 결과 건수 aria-live="polite" · 하이라이트 ※ 0건: .search-empty + role="status" ``` ### 브레드크럼 · 페이지 타이틀 ``` css/layout.css ← #location / .ptitle (기존) css/breadcrumb.css ← .breadcrumb / .page-head 마크업: breadcrumb.html → 상세: docs/breadcrumb.md ※ nav[aria-label] > ol > … > span[aria-current="page"] ※ 구분 기호(>)는 CSS ::before (DOM 텍스트로 넣지 않음) ※ 실서비스 제목: h1.page-title (페이지당 1개) ``` ### 알림 · 토스트 · 인라인 오류 ``` css/alert.css js/common.js ← toastShow / data-toast 마크업: alert.html - .alert (배너) · #toastRegion + .toast · .field-msg → 상세: docs/alert.md ※ 일반: role="status" / 오류·긴급: role="alert" ※ 필드 오류: aria-invalid + aria-describedby ※ 확인 필수 알림은 popup alertdialog ``` ### 스텝 (진행 단계) ``` css/step.css css/button.css ← 이전/다음 마크업: step.html (nav > ol.step) → 상세: docs/step.md ※ 현재: .is-current + aria-current="step" ※ 완료/현재/대기 상태는 .dn 텍스트로 제공 (색만 구분 금지) ※ 가로형 · .step--vertical · 좁은 화면은 세로 전환 ``` ### 푸터 ``` css/footer.css js/common.js ← 패밀리사이트 disclosure 마크업: footer.html (footer#footer.site-footer) → 상세: docs/footer.md ※ 로고·연락처 → 유틸(패밀리) → 정책(개인정보처리방침 강조) → 저작권 ※ 패밀리사이트: button + aria-expanded (select onchange 이동 비권장) ※ 새 창: 반드시 고지 — 링크 .dn(새 창) / 이동 버튼·안내 문구 (미고지 시 위반) ※ rel=noopener noreferrer 함께 사용 ``` ### 관련 콘텐츠 / 첨부 목록 ``` css/related.css img/download.svg 마크업: related.html (.attach / .relate / .relate--card) → 상세: docs/related.md ※ 첨부: 파일명·용량·형식 텍스트 + .dn「다운로드」(새 창 미리보기는 「새 창」) ※ 관련글: 제목 링크 · 카테고리·날짜 ※ 상세 본문 아래 배치 (게시판 .board-view__files 와 역할 유사) ※ 개인정보(웹): 오첨부 확인·설문 결과 비공개·대량메일 BCC·완전 파기·유출 즉시 통지 → docs/related.md ※ 샘플 PDF: media/privacy/ ``` ### 인쇄 / 공유 ``` css/share.css ← @media print 포함 js/common.js ← data-print / data-copy-url / 공유 패널 css/alert.css ← URL 복사 토스트(권장) 마크업: share.html (.page-tools) → 상세: docs/share.md ※ SNS 새 창: title="새 창으로 열림" + .dn(새 창) ※ .no-print / .print-only / .print-url ``` ### 동영상 ``` css/video.css media/*.vtt ← 자막(WebVTT) 마크업: video.html (.media-video / .media-transcript) → 상세: docs/video.md ※ 자동재생 금지 · controls 필수 ※ 자막 track 또는 스크립트(대체 텍스트) ※ iframe title 필수 · youtube-nocookie · autoplay 파라미터 금지 ``` ### 지도 · 연락처 ``` css/map.css 마크업: map.html (.map-block / .contact-card / .transit) → 상세: docs/map.md ※ 텍스트 주소(address) 필수 — 지도만 제공 금지 ※ iframe title에 장소명 · 큰 지도 새 창: title + .dn(새 창) ※ 전화 tel: · 메일 mailto: ``` ### 스크롤 패널 (고정 헤더·툴바 + 목록) ``` css/scroll-panel.css 마크업: scroll-panel.html (.scroll-panel) → 상세: docs/scroll-panel.md ※ scrollbar-gutter: stable — 스크롤 유무와 관계없이 너비 유지 ※ 여백: --scroll-panel-pad-x · 스크롤바 폭: --scroll-panel-sb ※ JS로 padding 토글 금지 ``` ### 로그인 · 회원 ``` css/login.css css/form.css · button.css · alert.css (선택) step.css · loading.css · popup.css js/common.js ← 비번보기 · 토스트 · 로딩 · 모달 · 로그인 데모 img/eye.svg · eye-off.svg media/captcha-demo.svg ← 캡차 데모(선택) 마크업: login.html (.login-box / .captcha-box / .auth-gate) → 상세: docs/login.md ※ label · autocomplete · aria-invalid / .field-msg ※ 비밀번호 보기 .btn-pw-view · 세션 만료 alertdialog ※ 캡차: alt · 새로고침 · aria-live · 음성 대체 ``` --- ## 3. HTML 뼈대 (권장) head 정리: [head.html](../head.html) · [docs/head.md](./head.md) SEO·GEO: [seo.html](../seo.html) · [docs/seo.md](./seo.md) 페이지 셸·1단/2단: [layout.html](../layout.html) · [docs/layout.md](./layout.md) ```html
...
...
``` - 스킵은 **문서의 첫 요소**, 링크는 **3개 이내**, 본문은 `#contents`(브레드크럼·사이드 제외) - 실행 시 목적지 스크롤 + 초점 (`common.js`) - 스킵 스타일: `css/common.css` `#skipToContent` (평소 숨김 → Tab 시 노출) - 모달 사용 시 `#wrap`·`#skipToContent`에 `aria-hidden`을 JS가 토글함 --- ## 4. common.js 기능 켜고 끄기 `js/common.js`는 **섹션 주석**으로 나뉩니다. 안 쓰는 블록은 삭제해도 됩니다. | 섹션 | 용도 | |------|------| | drags + 레이어 팝업 | 모달 | | 퀵메뉴 / gotop | 맨 위로(`a[href="#header"]`) · `#footer` 상단에서 멈춤 | | nice-select | 커스텀 셀렉트 | | 주소(우편번호) | 다음 주소 API | | toggle | role=switch | | 파일선택 | 파일명 표시 | | 비밀번호 보기 | `.btn-pw-view` | | FAQ table / ul | 아코디언 | | location → title | 문서 제목 자동 | | 테이블 체크 동기화 | `.chk-all` / `.chk-item` | | 로딩 오버레이 | 전체 `loadingShow` / `loadingHide` · 섹션 `loadingShowIn` / `loadingHideIn` | | 토스트 알림 | `toastShow` / `data-toast` | | 푸터 패밀리사이트 | `.site-footer__family-btn` disclosure | | 인쇄 / 공유 | `data-print` / `data-copy-url` / `data-share` · 공유 패널 | 차트는 `common.js`가 아니라 **`js/chart-a11y.js` + Chart.js CDN** 입니다. → [docs/chart.md](./chart.md) --- ## 5. 자주 하는 실수 | 증상 | 원인 | |------|------| | 셀렉트가 안 바뀜 | `nice-select.js` 미로드 / `select`에 `ignore` 클래스 | | 모달 초점 회귀 안 됨 | 열기 버튼에 `data-modal-open` 없고 `modalOpen`만 호출하며 opener 미전달 | | 비번 아이콘 안 보임 | `img/eye.svg` 경로 불일치 | | FAQ title이 안 바뀜 | 구버전 JS — 최신 `common.js` FAQ 섹션 사용 | | 표 체크 전체선택이 다른 표까지 영향 | `name`을 테이블마다 다르게 | --- ## 6. 가이드 UI는 가져가지 마세요 데모용 클래스 (실서비스 불필요): - `.ui-guide` / `.form-guide` / `.ui-guide-item` / `.btn-demo` / `.guide-opt` - 스타일 위치: `css/style.css` 하단 실서비스에는 **컴포넌트 마크업 + 해당 CSS/JS/img**만 복사하면 됩니다.