Stats
Actions
Tags
From krds
Use when implementing UI components (buttons, inputs, menus, modals, tables, cards, etc.) for Korean government digital services following KRDS. Triggers on 버튼, 입력, 메뉴, 헤더, 푸터, 모달, 탭, 테이블, 체크박스, 라디오, 셀렉트, 아코디언, 배지, 캐러셀, 페이지네이션, 컴포넌트.
How this skill is triggered — by the user, by Claude, or both
Slash command
/krds:krds-componentsThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
KRDS(Korea Design System)는 대한민국 정부 디지털 서비스의 일관된 사용자 경험을 위해 10개 카테고리, 43개 이상의 UI 컴포넌트를 정의한다. 모든 컴포넌트의 CSS 클래스는 `krds-` 접두사를 사용한다.
KRDS(Korea Design System)는 대한민국 정부 디지털 서비스의 일관된 사용자 경험을 위해 10개 카테고리, 43개 이상의 UI 컴포넌트를 정의한다. 모든 컴포넌트의 CSS 클래스는 krds- 접두사를 사용한다.
KRDS에 정의된 컴포넌트가 있으면 커스텀 컴포넌트를 만들지 마세요. html/code/ 파일을 먼저 확인하세요.
사용자가 컴포넌트 요청
→ Read node_modules/krds-uiux/html/code/{name}.html
→ 정확한 마크업 제공
→ 변형 필요 시 {name}_{variant}.html 추가 Read
→ 커스텀 필요 시 Read resources/scss/component/_{name}.scss
→ JS 필요 시 Read resources/js/component/ui-script.js 관련 부분
→ 아이콘 필요 시 Glob resources/img/component/icon/ 확인
모든 HTML 스니펫은 node_modules/krds-uiux/html/code/ 에 위치한다.
| Category | Files |
|---|---|
| Buttons | button.html, button_size.html, button_hierarchy.html, button_icon.html, button_text.html, button_with_icon.html |
| Text Input | text_input.html, text_input_icon.html, text_input_size.html, text_input_state.html |
| Select | select.html, select_size.html, select_sorting.html, select_state.html |
| Checkbox | checkbox.html, checkbox_chip.html, checkbox_size.html |
| Radio | radio_button.html, radio_chip.html, radio_size.html |
| Toggle | toggle_switch.html, toggle_switch_size.html |
| Identity | header.html, footer.html, masthead.html, identifier.html |
| Navigation | main_menu_pc.html, main_menu_mobile.html, side_navigation.html, breadcrumb.html, pagination.html, skip_link.html, tab.html, in_page_navigation.html |
| Overlay | modal.html, modal_sample.html, tooltip.html, tooltip_box.html, tooltip_vertical.html |
| Accordion | accordion.html, accordion_line.html |
| Data | table.html, structured_list.html, structured_list_table.html, text_list.html, text_list_ordered.html |
| Badge/Tag | badge.html, badge_number.html, badge_size.html, tag.html, tag_link.html |
| Media | carousel.html, carousel_banner.html, calendar.html, calendar_range.html |
| Input | date_input.html, textarea.html, file_upload.html |
| Feedback | spinner.html, step_indicator.html |
| Help | help_panel.html, tutorial_panel.html, contextual_help.html, coach_mark.html |
| Alert | critical_alerts.html |
| Settings | language_switcher.html, language_switcher_page.html, resize.html |
| Accessibility | tts.html, tts_icon.html, tts_size.html |
| Other | disclosure.html, link.html, favicon.html |
컴포넌트 래디어스는 컨테이너 높이에 비례하며, 최대 12px이다.
| 단계 | 크기 |
|---|---|
| xsmall | 2px |
| small | 4px |
| medium | 6~8px |
| large | 10px |
| xlarge | 12px |
| 상태 | Primary Fill | Secondary Fill | Tertiary Fill |
|---|---|---|---|
| Default | primary-50 | primary-5 | transparent |
| Hover | primary-60 | primary-10 | gray-5 |
| Pressed | primary-70 | primary-20 | gray-10 |
| Disabled | gray-20 | gray-5 | gray-5 |
모든 대화형 컴포넌트에는 다음 ARIA 속성을 적절히 적용한다:
aria-label — 시각적 레이블이 없는 요소에 대체 텍스트 제공aria-expanded — 아코디언, 드롭다운 등 펼침/접힘 상태 표시aria-selected — 탭, 목록 등 선택 상태 표시role — 시맨틱 HTML로 표현할 수 없는 역할 명시| 키 | 동작 |
|---|---|
Tab | 포커스 이동 (다음 대화형 요소) |
Shift+Tab | 포커스 이동 (이전 대화형 요소) |
Enter | 활성화 / 실행 |
Space | 활성화 / 토글 |
Esc | 닫기 / 취소 |
Arrow | 목록/탭/메뉴 내 항목 이동 |
포커스 링은 모든 대화형 요소에 표시되어야 하며, outline 속성으로 구현한다. 포커스 링을 제거하거나 숨기지 않는다.
아이콘 SVG 파일은 node_modules/krds-uiux/resources/img/component/icon/ 에 91개 존재한다.
| 아이콘 | 파일명 | 용도 |
|---|---|---|
| 이동 | ico_go.svg | 외부 링크, 바로가기 |
| 닫기 | ico_close.svg | 모달, 패널 닫기 |
| 화살표 | ico_angle.svg | 드롭다운, 아코디언, 페이지네이션 |
| 달력 | ico_calendar.svg | 날짜 입력 |
| 검색 | ico_sch.svg | 검색 입력 |
| 다운로드 | ico_download.svg | 파일 다운로드 |
| 업로드 | ico_upload.svg | 파일 업로드 |
| 삭제 | ico_delete.svg | 항목 삭제 |
| 도움말 | ico_help.svg | 도움말 트리거 |
| 정보 | ico_information.svg | 정보 메시지 |
| 홈 | ico_bread_home.svg | 브레드크럼 홈 |
| 더보기 | ico_more.svg | 추가 동작 |
| 필터 | ico_filter.svg | 필터 동작 |
| 확장 | ico_expand.svg | 영역 확장 |
| 볼륨 | ico_volume.svg | TTS 음성 |
<!-- img 태그 방식 -->
<img src="resources/img/component/icon/ico_go.svg" alt="바로가기" />
<!-- 인라인 SVG 방식 (색상 제어 가능) -->
<svg class="krds-icon" aria-hidden="true">
<use xlink:href="#ico_go"></use>
</svg>
아이콘은 반드시 텍스트 레이블과 함께 사용해야 한다. 아이콘만 단독으로 사용할 경우 aria-label을 제공한다.
다음 컴포넌트는 JavaScript 동작이 필수이며, 모든 스크립트는 resources/js/component/ui-script.js에서 관리된다.
| 컴포넌트 | JS 동작 |
|---|---|
| accordion | 패널 펼침/접힘, aria-expanded 토글 |
| tab | 탭 전환, aria-selected 토글, Arrow 키 탐색 |
| modal | 열기/닫기, 포커스 트랩, inert 관리 |
| calendar | 월/연 이동, 날짜 선택, 범위 선택 |
| tooltip | 호버/포커스 시 표시, 위치 계산 |
| contextual_help | 인라인 도움말 토글 |
| main_menu | 서브메뉴 확장/축소, 모바일 토글 |
| side_navigation | 하위 메뉴 확장/축소 |
| help_panel | 슬라이드 열기/닫기 |
| tutorial_panel | 단계 이동, 진행률 표시 |
| disclosure | 콘텐츠 펼침/접힘 |
| file_upload | 파일 선택, 목록 관리, 삭제 |
| toggle_switch | 토글 상태 전환 |
| tts | 텍스트 음성 변환 제어 |
| in_page_navigation | 스크롤 연동, 현재 섹션 강조 |
| carousel | 슬라이드 이동, 자동재생 제어 |
| dropdown | 드롭다운 열기/닫기 |
| resize | 텍스트 크기 조절 |
| coach_mark | 순차 안내, 단계 이동 |
// ui-script.js 내 관련 함수를 Read로 확인
Read resources/js/component/ui-script.js
// 컴포넌트명으로 검색하여 해당 초기화 및 이벤트 바인딩 코드 확인
캐러셀(carousel) 컴포넌트의 재생/멈춤 버튼, 이전/다음 버튼, 페이지네이션 인디케이터를 구현할 때 반드시 다음을 준수하세요:
필수 의존성:
<!-- 반드시 이 두 파일을 페이지에 추가 -->
<link rel="stylesheet" href="node_modules/krds-uiux/resources/css/plugin/swiper-bundle.min.css">
<script src="node_modules/krds-uiux/resources/js/plugin/swiper-bundle.min.js"></script>
절대 하지 마세요:
swiper-button-play, swiper-button-stop, swiper-button-prev, swiper-button-next 클래스의 아이콘은 krds CSS가 자동으로 렌더링합니다<span class="sr-only"> 접근성 텍스트만 넣으세요올바른 구현 (carousel_banner.html 기준):
<div class="swiper-indicator">
<div class="swiper-pagination"></div>
<div class="swiper-controller">
<button type="button" class="swiper-button-play">
<span class="sr-only">슬라이드 재생</span>
</button>
<button type="button" class="swiper-button-stop">
<span class="sr-only">슬라이드 멈춤</span>
</button>
</div>
<div class="swiper-navigation">
<button type="button" class="swiper-button-prev">
<span class="sr-only">이전</span>
</button>
<button type="button" class="swiper-button-next">
<span class="sr-only">다음</span>
</button>
</div>
</div>
추천 패턴 (실제 운영 사이트 수준 — Swiper 렌더링 후 완성된 형태):
Swiper.js가 초기화되면 swiper-pagination 내부에 bullet이 자동 생성됩니다. 아래는 Swiper가 렌더링한 후의 완성된 HTML 구조입니다. 직접 이 HTML을 작성하는 것이 아니라, Swiper JS가 자동 생성하는 결과물임을 이해하세요. 다만 sr-only 텍스트는 섹션 맥락에 맞게 구체적으로 작성해야 합니다.
<div class="swiper-indicator">
<!-- Swiper가 자동 생성하는 pagination bullets (직접 작성 X) -->
<div class="swiper-pagination swiper-pagination-clickable swiper-pagination-bullets swiper-pagination-horizontal">
<span class="swiper-pagination-bullet" tabindex="0" role="button" aria-label="Go to slide 1"></span>
<span class="swiper-pagination-bullet swiper-pagination-bullet-active" tabindex="0" role="button" aria-label="Go to slide 2" aria-current="true"></span>
<span class="swiper-pagination-bullet" tabindex="0" role="button" aria-label="Go to slide 3"></span>
</div>
<!-- 재생/멈춤 (직접 작성, 아이콘은 CSS가 렌더링) -->
<div class="swiper-controller">
<button type="button" class="swiper-button-play" style="display: none;">
<span class="sr-only">주요소식 슬라이드 재생</span>
</button>
<button type="button" class="swiper-button-stop">
<span class="sr-only">주요소식 슬라이드 멈춤</span>
</button>
</div>
<!-- 이전/다음 (직접 작성, 아이콘은 CSS가 렌더링) -->
<div class="swiper-navigation">
<button type="button" class="swiper-button-prev" tabindex="0" aria-label="Previous slide">
<span class="sr-only">이전 주요소식으로 이동</span>
</button>
<button type="button" class="swiper-button-next" tabindex="0" aria-label="Next slide">
<span class="sr-only">다음 주요소식으로 이동</span>
</button>
</div>
</div>
추천 패턴 핵심 포인트:
sr-only 텍스트를 섹션 맥락에 맞게 구체적으로 작성 (예: "슬라이드 재생" → "주요소식 슬라이드 재생")swiper-pagination 내부는 비워두세요 — Swiper JS가 bullet을 자동 생성합니다swiper-button-play는 초기 상태에서 display: none (autoplay가 기본 실행 중이므로)aria-label="Previous slide", aria-label="Next slide" 속성 추가style="user-select: auto !important;" 는 브라우저 DevTools에서 보이는 인라인 스타일이며, 직접 작성하지 않아도 됩니다잘못된 구현 (이렇게 하면 아이콘이 깨집니다):
<!-- ❌ 텍스트 문자로 아이콘을 대체하면 안 됩니다 -->
<button class="swiper-button-play">▶</button>
<button class="swiper-button-stop">▮▮</button>
<button class="swiper-button-prev"><</button>
<button class="swiper-button-next">></button>
JS 초기화 (autoplay + 재생/멈춤):
const swiper = new Swiper(".swiper-container .swiper", {
slidesPerView: 1,
loop: true,
autoplay: { delay: 2500, disableOnInteraction: false, pauseOnMouseEnter: true },
navigation: { nextEl: ".swiper-button-next", prevEl: ".swiper-button-prev" },
pagination: { el: ".swiper-pagination", type: "fraction" },
});
const $play = document.querySelector(".swiper-button-play");
const $stop = document.querySelector(".swiper-button-stop");
$play.style.display = "none";
$play.addEventListener("click", () => {
swiper.autoplay.start();
$stop.style.display = "";
$play.style.display = "none";
});
$stop.addEventListener("click", () => {
swiper.autoplay.stop();
$stop.style.display = "none";
$play.style.display = "";
});
사용자가 자체 서비스 로고를 사용하는 경우, KRDS 기본 로고와 겹치는 문제가 발생합니다.
원인: KRDS 헤더의 .logo 클래스는 CSS background-image로 KRDS 기본 로고를 표시합니다. 사용자가 <img> 태그나 다른 방식으로 로고를 추가하면 두 개가 겹칩니다.
해결 방법 — 기관 유형별 분기:
중앙행정기관 (대표) — 정부 상징 로고 사용:
<!-- 정부 상징 로고를 사용하므로 KRDS 기본 로고를 그대로 유지 -->
<h2 class="logo">
<a href="/">
<span class="sr-only">기관명 - Korea Design System</span>
</a>
</h2>
CSS의 background-image가 정부 상징 로고를 표시합니다. <img> 태그를 추가하지 마세요.
중앙행정기관 (운영), 공공기관, 지자체 — 자체 로고 사용:
<!-- 자체 로고를 사용할 때는 background-image를 제거하고 img 태그 사용 -->
<h2 class="logo">
<a href="/">
<img src="/path/to/custom-logo.svg" alt="서비스명">
</a>
</h2>
/* 반드시 KRDS 기본 로고 background를 제거 */
#krds-header .logo a {
background-image: none;
}
절대 하지 마세요:
.logo a background-image를 제거하지 않고 <img> 태그를 추가 → 로고 겹침<img> 태그 없이 background-image만 변경 → alt 텍스트 누락으로 접근성 위반올바른 패턴:
<span class="sr-only">로 기관명 제공background-image: none 적용 후 <img alt="서비스명"> 삽입각 컴포넌트 카테고리별 상세 가이드라인은 다음 레퍼런스 파일을 참조한다:
references/identity.md — 헤더, 푸터, 공식 배너, 운영기관 식별자references/navigation.md — 메인 메뉴, 사이드 메뉴, 브레드크럼, 탭, 페이지네이션, 건너뛰기 링크, 콘텐츠 내 탐색references/action-input.md — 버튼, 링크, 텍스트 입력, 텍스트 영역, 날짜 입력, 파일 업로드references/selection.md — 라디오 버튼, 셀렉트, 체크박스, 태그references/layout.md — 모달, 아코디언, 탭, 테이블, 배지, 캐러셀 등 레이아웃/표시 컴포넌트npx claudepluginhub jiminlee-way/awsome-krds-koreadesignsystem --plugin krdsCreates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.