# KRDS Vue

> 대한민국 정부 디자인 시스템(KRDS)을 Vue 3와 TypeScript로 구현한 컴포넌트 라이브러리(@krds.ui/vue) 문서입니다.

- 전체 문서: https://krds.initializer.org/llms-full.txt
- AI 개발 지침: https://krds.initializer.org/ai/guidelines.md

## 가이드

- [시작하기](https://krds.initializer.org/guide/getting-started): KRDS Vue는 KRDS(대한민국 정부 디자인 시스템)를 Vue 3 + TypeScript 환경에서 사용할 수 있도록 구현한 컴포넌트 라이브러리입니다. 이 패키지는 ESM 전용이며 CommonJS require()는 지원하지 않습니다.
- [AI로 개발하기](https://krds.initializer.org/guide/ai): Claude Code, Cursor, GitHub Copilot 같은 AI 코딩 도구가 KRDS Vue를 올바르게 쓰도록 지침 파일과 AI용 문서를 제공합니다. AI가 문서에 없는 속성을 지어내거나 KRDS 구조를 벗어난 마크업을 만드는 일을 줄일 수 있습니다.

## 컴포넌트

### 아이덴티티

- [공식 배너 Masthead](https://krds.initializer.org/components/masthead): 공식 배너는 사용자가 대한민국 정부 조직 및 관련 기관에서 운영 및 관리하는 디지털 정부서비스임을 식별할 수 있도록 제공하는 정보 배너이다.
- [운영기관 식별자 Identifier](https://krds.initializer.org/components/identifier): 운영기관 식별자는 디지털 정부서비스에 대한 신뢰성을 위해 서비스 운영 및 관리 주체를 안내하는 요소로 공식 배너, 푸터와 함께 서비스의 일관성, 브랜드를 확인할 수 있는 핵심 요소이다.
- [헤더 Header](https://krds.initializer.org/components/header): 헤더는 웹사이트의 상단 헤더 영역을 구성하는 컴포넌트이다. 유틸리티 메뉴, 브랜딩 영역, 네비게이션 메뉴를 슬롯을 통해 유연하게 구성할 수 있다. 네비게이션 슬롯에는 KrdsMainMenu 등 완성된 메뉴 컴포넌트를 그대로 전달한다.
- [푸터 Footer](https://krds.initializer.org/components/footer): 푸터는 화면을 구성하는 가장 마지막 요소로 헤더와 본문에서 원하는 정보를 찾지 못하였거나 사이트 구조 탐색 중에 길을 잃은 사용자들이 대면하게 되는 정보이다. 따라서 푸터에는 사용자가 서비스를 탐색할 수 있는 추가적인 수단, 문제를 해결하는 데 참고할 수 있는 유용한 링크가 제공되어야 한다.

### 탐색

- [건너뛰기 링크 Skip link](https://krds.initializer.org/components/skip-link): 건너뛰기 링크는 웹사이트에서 웹 페이지의 주요 콘텐츠 섹션의 탐색을 도와주는 페이지 내부 링크이다. 키보드나 가상 초점을 이용하여 콘텐츠를 탐색하는 사용자는 건너뛰기 링크를 이용하여 대부분의 페이지에서 반복되는 콘텐츠 영역을 건너뛰고 주요 콘텐츠로 빠르게 이동할 수 있다.
- [메인 메뉴 Main menu](https://krds.initializer.org/components/main-menu): 메인 메뉴는 서비스 전체의 구조를 보여주고 주요 화면으로 이동할 수 있게 하는 메뉴이다. 일반적으로 헤더 영역에 위치하며, 데스크탑에서는 메가 메뉴 형태로, 모바일에서는 드로어 형태로 제공된다.
- [브레드크럼 Breadcrumb](https://krds.initializer.org/components/breadcrumb): 브레드크럼은 탐색 계층 구조를 표시하여 사용자가 현재 위치를 파악하고 계층 구조의 수준을 이동할 수 있게 해준다. 브레드크럼을 통해 사용자는 탐색 중인 화면의 상위 수준 화면으로 이동할 수 있다.
- [사이드 메뉴 Side navigation](https://krds.initializer.org/components/side-navigation): 사이드 메뉴는 서브 화면 내에서의 이동을 위해 사용하는 메뉴이다. 일반적으로 본문 영역의 좌측에 사이드바 형태로 제공된다. 메인 메뉴보다 훨씬 좁고 깊은 페이지 구조 탐색에 사용되기 때문에 링크의 개수가 많고 복잡하게 표현되기 쉽다.
- [콘텐츠 내 탐색 In-page navigation](https://krds.initializer.org/components/in-page-navigation): 콘텐츠 내 탐색은 사용자가 본문의 구조를 훑어보고 원하는 콘텐츠로 빠르게 이동할 수 있도록 하는 탐색 수단이다. 화면을 스크롤 할 때 특정 위치에 고정되어 콘텐츠의 목차 역할을 하는 동시에 사용자가 페이지 내 탐색에서 특정 항목을 클릭하면 연결된 섹션으로 스크롤 된다.
- [페이지네이션 Pagination](https://krds.initializer.org/components/pagination): 페이지네이션은 많은 양의 콘텐츠를 탐색하기 쉽도록 여러 화면에 나누고, 분할된 화면을 탐색하는 데 사용되는 요소이다.

### 레이아웃 및 표현

- [구조화 목록 Structured list](https://krds.initializer.org/components/structured-list): 구조화 목록은 유사하거나 관련된 콘텐츠 집합을 표현하기 위한 형식으로 목록에 제공된 데이터에 대한 상세 정보 탐색 수단 또는 관련 기능 실행 수단으로 활용된다. 사용자가 콘텐츠를 효율적으로 탐색하고 다음 행동을 빠르게 결정할 수 있도록 목록 내 정보는 상세 페이지에서 제공되는 복잡한 콘텐츠 중 핵심적이거나 흥미를 끌 수 있는 정보를 논리적 흐름에 따라 조직화하여 명확한 위계 구조를 반영해 제공해야 한다.
- [긴급 공지 Critical alerts](https://krds.initializer.org/components/critical-alerts): 긴급 공지는 본문 상단에 강조되어 표시되는 배너로 사용자에게 긴급하거나 중요한 정보를 전달하는 데 사용된다. 모든 공공 디지털 서비스에서 동일한 긴급 공지 컴포넌트를 사용함으로써 사용자는 긴급한 정보를 일관되고 예측 가능한 방식으로 찾고 이해할 수 있다.
- [디스클로저 Disclosure](https://krds.initializer.org/components/disclosure): 디스클로저는 특정한 정보/컨트롤/섹션에 관련된 부가적인 정보를 표시하거나 숨기는 데 사용되는 요소이다. 디스클로저 하위 콘텐츠 섹션은 기본으로 축소된 상태로 제공되며 사용자가 요청하는 경우에 확장되어 자세한 정보가 표시된다. 이는 사용자의 인지적 부담을 감소시키고 정보를 빠르게 훑어보는 데 도움이 된다.
- [모달 Modal](https://krds.initializer.org/components/modal): 모달은 대화창의 한 종류로 기본 창에 종속된 요소이다. 기본 창과 겹쳐져 가장 상단에 표시되며, 이때 기본 창은 비활성 상태로 전환되어 상호작용이 불가능하므로 사용자는 모달에서의 단일한 과업 또는 메시지에 집중할 수 있다.
- [배지 Badge](https://krds.initializer.org/components/badge): 컴포넌트에 대한 빠른 인지와 탐색을 돕기 위해 컴포넌트 근처에 표시되는 작은 문자 또는 숫자 데이터이다. 컴포넌트의 분류 체계, 구조화된 정보, 상태 정보, 기타 메타 데이터를 표시할 수 있으며 사용자의 주의를 끌기 위해 색상을 활용할 수 있다.
- [아코디언 Accordion](https://krds.initializer.org/components/accordion): 아코디언은 한 페이지에서 관련 있는 여러 콘텐츠 섹션을 확인할 수 있도록 하는 컴포넌트로 콘텐츠 섹션의 헤더 목록이 수직으로 쌓여 있는 형태로 표현된다. 일반적으로 헤더 목록은 컨트롤 요소로 활용되며 사용자는 필요에 따라 헤더를 선택하여 하위 콘텐츠 섹션을 표시하거나 숨길 수 있다.
- [이미지 Image](https://krds.initializer.org/components/image): 이미지는 콘텐츠 양식 중 하나로 단일 이미지 또는 이미지 시퀀스로 표현될 수 있다. 이미지를 적절하게 사용하게 되면 사용자는 텍스트보다 효과적으로 정보를 인지할 수 있으며, 텍스트로 표현하기 어려운 정보를 전달할 수 있다.
- [캐러셀 Carousel](https://krds.initializer.org/components/carousel): 캐러셀은 하나의 영역에서 여러 개의 콘텐츠를 순차적으로 번갈아 보여주는 컴포넌트이다. 한정된 공간에 여러 콘텐츠를 노출할 수 있으나 첫 번째 슬라이드 외에는 주목도가 크게 떨어지므로, 중요한 정보는 캐러셀에만 담지 않는 것이 좋다. 슬라이드는 기본 슬롯으로 전달하며 최상위 노드 하나가 슬라이드 한 장이 된다. 자동 재생 시에는 사용자가 즉시 정지할 수 있도록 재생/정지 버튼을 함께 노출한다.
- [탭 Tab](https://krds.initializer.org/components/tabs): 탭은 버튼을 눌러 상호배타적인 여러 개의 콘텐츠 섹션을 전환할 수 있는 컴포넌트이다. 탭 버튼 목록과 콘텐츠 패널이 수직으로 쌓여 있는 형태로 표현되며, 사용자는 탭을 선택하여 해당 콘텐츠 섹션을 표시할 수 있다.
- [표 Table](https://krds.initializer.org/components/table): 표는 데이터를 하나 이상의 행과 열로 조직화하여 표현하는 형식으로 사용자가 빠르게 많은 양의 정보를 확인하고 비교할 수 있도록 도와준다. 기본적으로 대화형 요소가 아니기 때문에 열 제목에 데이터를 정렬하기 위한 컨트롤 요소가 포함된 상황 외에 행 전체나 데이터 셀이 대화형으로 작동하지 않는다.
- [텍스트 목록 Text list](https://krds.initializer.org/components/text-list): 텍스트 목록은 계층 구조가 있는 텍스트 블록을 읽기 쉽게 구성한 것이다.

### 액션

- [링크 Link](https://krds.initializer.org/components/link): 링크는 다른 서비스/애플리케이션, 한 서비스 내의 다른 화면, 한 화면 내의 다른 섹션 등으로 이동하는 데 사용되는 탐색 요소이다.
- [버튼 Button](https://krds.initializer.org/components/button): 버튼은 어떤 기능이나 동작을 실행하거나 기능을 사용하기 위한 상태로 변경하는 요소이다. 사용자가 서비스를 이용하는 과정에서 어떤 행동이 중요한지에 따라 관련된 버튼이 다양한 스타일로 표현된다.
- [플로팅 버튼 Floating action button](https://krds.initializer.org/components/floating-button): 플로팅 버튼은 사용자가 화면에서 가장 자주 사용하고 중요한 작업에 단일 또는 다중으로 사용한다. 페이지가 스크롤될 때에도 화면 우측 하단에 계속 표현한다.

### 선택

- [라디오 버튼 Radio button](https://krds.initializer.org/components/radio): 라디오 버튼은 사용자가 여러 개의 옵션 중 하나만 선택할 수 있도록 하는 경우에 사용한다. 즉, 라디오 버튼 옵션의 선택은 상호배타적이므로 한 개의 옵션을 선택하면 다른 옵션은 자동으로 선택 해제된다.
- [체크박스 Checkbox](https://krds.initializer.org/components/checkbox): 체크박스는 사용자가 여러 개의 옵션 중 한 개 이상의 값을 선택할 수 있도록 하는 경우에 사용한다. 즉, 체크박스 옵션의 선택은 상호배타적이므로 한 개의 옵션을 선택하는 것은 다른 옵션의 선택에 영향을 미치지 않는다.
- [셀렉트 Select](https://krds.initializer.org/components/select): 셀렉트는 사용자에게 여러 개의 옵션 목록을 팝업으로 제공하여 그 중 한 개의 값을 선택할 수 있도록 하는 경우에 사용한다.
- [태그 Tag](https://krds.initializer.org/components/tag): 태그는 키워드 또는 레이블을 사용하여 콘텐츠를 분류하는 수단이다. 콘텐츠 항목에 직접 관련 분류 체계, 데이터 속성을 표시하거나, 목록에서 특정 분류 체계, 데이터 속성을 가진 항목이 선택되었음을 보여주기 위한 태그 그룹으로 사용된다.
- [토글 스위치 Toggle switch](https://krds.initializer.org/components/toggle-switch): 토글은 상호 배타적인 두 가지 상태를 전환하는 데 사용되는 요소이다.

### 피드백

- [단계 표시기 Step indicator](https://krds.initializer.org/components/step-indicator): 단계 표시기는 서비스 이용을 위해 사용자가 거쳐야 하는 일련의 단계를 시각화하여 표현한 것으로 진행 상태에 대한 피드백을 사용자에게 전달한다.
- [스피너 Spinner](https://krds.initializer.org/components/spinner): 스피너는 화면이나 요소의 다양한 처리 상태를 시각적으로 표시한 것으로 화면 전체나 일부 요소에 접근하기 위해 일정 시간 동안 대기해야 함을 사용자에게 안내한다.

### 도움

- [패널 Panel](https://krds.initializer.org/components/panel): 패널은 본문 콘텐츠의 섹션이나 일부 요소에 대한 개념/용어 설명, 옵션의 구성, 이용 방법 등과 관련된 정보나 도움말, 따라하기 콘텐츠를 제공하는 사이드 패널이다.
- [맥락적 도움말 Contextual help](https://krds.initializer.org/components/contextual-help): 컴포넌트 주변에 배치되어 해당 컴포넌트의 상태나 관련된 상세 정보를 제공하는 컴포넌트이다. 맥락적 도움말은 정보 아이콘이나 도움 아이콘 버튼을 통해 사용자가 요청하는 경우에만 화면에 표시된다.
- [코치마크 Coach mark](https://krds.initializer.org/components/coach-mark): 코치마크는 사용자에게 새로 도입된 기능을 안내하거나, 여러 단계를 거쳐 수행해야 하는 복잡한 과업을 사용자가 보다 쉽게 완료할 수 있도록 세부 수행 단계별로 고맥락적 도움말을 제공하는 컴포넌트이다.
- [툴팁 Tooltip](https://krds.initializer.org/components/tooltip): 툴팁은 요소나 본문 텍스트에 제공되는 짧은 부가 설명이다. 설명이 필요한 대상 또는 별도의 활성화 버튼에 마우스를 올리거나 초점을 이동했을 때 설명 텍스트가 표시된다.
- [음성 지원 TTS](https://krds.initializer.org/components/tts): TTS(Text-to-Speech)는 텍스트를 음성으로 변환하여 읽어주는 기능을 제공하는 버튼 컴포넌트이다. Web Speech API를 사용하며, 볼륨 아이콘과 재생 아이콘 두 가지 타입을 지원한다.

### 입력

- [날짜 입력 필드 Date input](https://krds.initializer.org/components/date-input): 날짜 입력 필드는 사용자가 특정 날짜 또는 기간을 입력하거나 선택하는 데 사용되는 요소이다.
- [텍스트 영역 Textarea](https://krds.initializer.org/components/textarea): 텍스트 영역은 사용자가 키보드로 글자, 숫자, 기호 등이 조합된 여러 줄의 텍스트를 입력하는 경우에 사용하는 요소이다.
- [텍스트 입력 필드 Text input](https://krds.initializer.org/components/input): 텍스트 입력 필드는 사용자가 키보드로 글자, 숫자, 기호 등이 조합된 한 줄의 짧은 텍스트를 입력하는 경우에 사용하는 요소이다.
- [파일 업로드 File upload](https://krds.initializer.org/components/file-upload): 파일 업로드는 하나 이상의 디바이스의 로컬 파일을 선택하고 첨부하는 데 사용하는 입력 컴포넌트이다.

### 설정

- [언어 변경 Language switcher](https://krds.initializer.org/components/language-switcher): 언어 변경은 서비스의 콘텐츠를 표시할 언어를 변경하거나 별도의 외국어 서비스로 이동하는 데 사용되는 요소이다. 한국어가 익숙하지 않은 사용자가 콘텐츠 표시 언어를 변경할 수 있는 수단을 발견하지 못한다면 서비스를 이용할 수 없게 되므로, 디지털 정부서비스로 직관적이고 일관된 방식으로 언어 변경을 제공하는 것이 매우 중요하다.
- [화면 크기 조정 Resize](https://krds.initializer.org/components/resize): 화면 크기 조정은 텍스트를 포함하여 화면에 표시되는 정보를 확대하거나 축소하는 데 사용되는 요소이다. 사용자에 따라 읽을 수 있는 텍스트의 크기, 조작할 수 있는 요소의 크기는 다르다. 디바이스나 사용자 에이전트가 지원하는 여러 가지 설정 기능을 활용하면 사용자가 선호하는 방식으로 콘텐츠의 표시 방식을 수정할 수 있다. 그러나 화면 크기 조정 기능을 필요로 하는 사용자는 관련 기능을 찾아 설정하는 데 어려움을 겪을 가능성이 높으므로 서비스 자체적으로 화면 크기 조정 기능을 제공하고 접근하기 쉽게 만드는 것이 중요하다.

### 콘텐츠

- [접근 가능한 미디어 Accessible multimedia](https://krds.initializer.org/components/media): 미디어 콘텐츠에 설명이 필요한 경우에 사용하는 컴포넌트이다. 정지된 이미지에 설명을 제공할 때에는 숨김 콘텐츠를, 오디오/비디오/멀티미디어 콘텐츠에 설명을 제공할 때는 접근 가능한 미디어 컴포넌트를 사용한다.
- [숨긴 콘텐츠 v-sr-only](https://krds.initializer.org/components/sr-only): v-sr-only 디렉티브는 스크린 리더 전용 텍스트를 위한 최소 구현 디렉티브이다.

### 모바일

- [범위슬라이드 Range slider](https://krds.initializer.org/components/range-slider): 범위 슬라이더는 사용자가 연속된 옵션 범위에서 값을 선택할 수 있도록 하는 경우 사용한다. 사용자가 선택한 값은 선택하는 동안 계속 보이도록 표시하여야 한다.
- [수량 토글 Quantity toggle](https://krds.initializer.org/components/quantity-toggle): 수량 토글은 사용자가 수량 옵션을 늘리거나 줄이는 데 사용되며, 한정된 범위 내에서 수량 선택을 위해 사용한다.
- [토스트 Toast](https://krds.initializer.org/components/toast): 토스트는 사용자 행동에 대한 결과를 일시적으로 표시했다 사라지는 알림 메시지를 표시하는데 사용한다. 알림 메시지는 사용자가 인지할 수 있는 시간만큼 충분히 표시되어야 한다.
- [스낵바 Snackbar](https://krds.initializer.org/components/snackbar): 스낵바는 사용자 행동에 대한 결과나 서비스 이용 중 발생한 중요도 낮은 메시지를 추가 행동과 함께 제공하는데 사용한다. 사용자의 주요 흐름을 방해하지 않으면서, 되돌리기 또는 다시 시도 등과 같이 간단한 조치를 포함한다.
- [탭바 Tab bar](https://krds.initializer.org/components/tab-bar): 탭바는 화면 하단에 고정하여 제공하는 탐색 수단으로 작은 디바이스나 좁은 화면에서 서비스의 핵심 화면으로 빠르게 접근할 수 있도록 도와준다.
- [스플래시 스크린 Splash screen](https://krds.initializer.org/components/splash-screen): 스플래시 스크린은 응용 프로그램이 실행되기 전에 사용자에게 짧은 시간 동안 제공되는 화면으로 모바일 애플리케이션 전용 컴포넌트이다.

### 부가 컴포넌트

- [폼 그룹 Form group](https://krds.initializer.org/components/form-group): KrdsFormGroup은 입력 컴포넌트 하나와 그 레이블·도움말을 묶는 .form-group 영역입니다. KrdsFormLabel은 레이블(.form-tit 안의 ), KrdsFormHint는 입력 필드 아래의 도움말()을 만듭니다. 텍스트 입력 필드, 텍스트 영역, 셀렉트, 날짜 입력 필드 등과 함께 씁니다.
- [아이콘 Icon](https://krds.initializer.org/components/icon): KRDS SVG 아이콘을 표시하는 컴포넌트이다. name 속성에 아이콘 클래스명(ico-\*)을 지정하며, 실제 그래픽은 스타일 시트의 svg-icon 마스크로 렌더링된다.
- [레이아웃 Layout](https://krds.initializer.org/components/layout): 웹사이트의 전체 레이아웃 구조를 제공하는 컴포넌트이다. 스크롤 방향에 따라 자동으로 scroll-up/scroll-down 클래스를 추가한다.