KRDS 컴포넌트 라이브러리 krdscn/ui를 공개합니다

krdscn/ui를 공개합니다. KRDS(대한민국 정부 디자인 시스템) 컴포넌트를 shadcn/ui + Radix Primitives + Tailwind CSS v4 위에 구현한 컴포넌트 라이브러리입니다.

왜 만들었나

KRDS는 정부 및 공공기관 웹사이트가 따라야 하는 디자인 시스템입니다. 공공 SI 프로젝트에서 KRDS 준수 요구는 계속 늘어나는데, 공식 자료는 마크업과 디자인 가이드 중심이라 React + Tailwind 스택에서 바로 쓰기가 어려웠습니다.

한편 shadcn/ui 생태계는 이미 검증된 기반을 갖고 있습니다. Radix Primitives가 접근성과 키보드 인터랙션을 책임지고, Tailwind로 스타일을 완전히 통제할 수 있죠. 그래서 "KRDS를 처음부터 새로 만들지 말고, shadcn/ui 위에 얹자"는 접근을 택했습니다.

무엇이 들어있나

KRDS 공식 분류를 따라 9개 그룹, 41개 컴포넌트를 구현했습니다.

• 아이덴티티 — 공식 배너(Masthead), 운영기관 식별자, 헤더, 푸터
• 탐색 — 건너뛰기 링크, 메인 메뉴, 브레드크럼, 사이드 메뉴, 콘텐츠 내 탐색, 페이지네이션
• 레이아웃 및 표현 — 구조화 목록, 긴급 공지, 달력, 디스클로저, 모달, 배지, 아코디언, 캐러셀, 탭, 표, 텍스트 목록
• 액션 — 링크, 버튼
• 선택 — 라디오 버튼, 체크박스, 셀렉트, 태그, 토글 스위치
• 피드백 — 단계 표시기, 스피너
• 도움 — 도움 패널, 따라하기 패널, 맥락적 도움말, 코치마크, 툴팁
• 입력 — 날짜 입력 필드, 텍스트 영역, 텍스트 입력 필드, 파일 업로드
• 설정 — 언어 변경, 화면 크기 조정

컴포넌트마다 전용 문서 페이지가 있습니다. 코드 예제(총 199개), Props 테이블, 한국어 설명이 함께 제공되며 전부 정적으로 사전 렌더링됩니다.

어떻게 만들었나

구조는 단순합니다.

• 2계층 구조 — components/ui/에는 shadcn/ui base 컴포넌트를 그대로 두고, components/ui/krds/에서 KRDS 토큰과 스타일을 입힌 래퍼를 제공합니다. base를 건드리지 않으니 shadcn 업데이트를 따라가기 쉽습니다.
• KRDS 디자인 토큰 — 색상, 타이포그래피 등을 --krds-* CSS 변수로 정의하고 Tailwind CSS v4의 @theme로 연결했습니다.
• 접근성 — 모든 인터랙티브 컴포넌트는 Radix Primitives 기반입니다. 포커스 관리, 키보드 인터랙션, ARIA 속성을 기본으로 갖추고 시작합니다.

얼마나 정확한가

"KRDS를 구현했다"는 말은 검증이 따라야 합니다. krdscn/ui는 Playwright로 공식 KRDS Storybook과 구현체를 나란히 캡처해 대조하고, 라이트/다크 모드 렌더링은 픽셀 단위로 비교해 토큰 누수를 잡습니다. 모달, 툴팁, 날짜 선택기처럼 열림 상태가 있는 컴포넌트는 자동 인터랙션 후 캡처합니다.

이 검증 파이프라인 이야기는 별도 글에서 자세히 다룰 예정입니다.

앞으로

krdscn/ui를 만들며 정리한 내용을 시리즈로 이어갑니다.

1. shadcn/ui 위에 KRDS를 얹는 래퍼 전략
2. KRDS 디자인 토큰을 Tailwind CSS v4로 옮기기
3. 컴포넌트 딥다이브 — Button
4. KRDS 폼 컴포넌트와 접근성
5. Props 테이블과 199개 예제를 자동으로 문서화하기
6. Playwright로 공식 KRDS Storybook과 나란히 검증하기

피드백과 이슈는 GitHub 저장소로 부탁드립니다.