krds-developer

KRDS를 참고해 화면을 만들거나 고칠 때는 임의의 UI 관습보다 KRDS 문서에 먼저 맞춘다. 스타일, 컴포넌트, 기본 패턴, 서비스 패턴, 체크리스트를 한 번에 다 읽지 말고, 과업에 맞는 계층만 좁혀 읽는다.

시작 순서

처음에는 아래 5개 문서를 먼저 읽어 전체 구조를 잡는다.

• references/utility_01.md
• references/outline_03.md
• references/component_summary.md
• references/global_summary.md
• references/service_summary.md

이 다섯 문서를 읽은 뒤 작업을 아래 네 범주 중 하나로 분류한다.

1. 스타일과 토큰
2. 개별 컴포넌트
3. 기본 패턴
4. 서비스 플로

문서 선택 규칙

스타일과 토큰

• 색상, 서체, 형태, 아이콘, 레이아웃, 엘리베이션은 references/style_01.md부터 읽는다.
• 디자인 토큰 구조와 수정 원칙은 references/style_07.md를 읽는다.
• 토큰·파일·변수 이름 규칙은 references/utility_03.md를 읽는다.
• 접근성 기준을 함께 봐야 하면 references/utility_04.md를 읽는다.
• KRDS 도입 범위와 역할 구분이 필요하면 references/utility_01.md를 다시 확인한다.

개별 컴포넌트

• 먼저 references/component_summary.md에서 대상 컴포넌트를 찾는다.
• 그 다음 해당 component_XX_YY.md 문서를 읽고 구조, 유형, 사용성, 상호작용, 접근성 항목을 확인한다.
• 사이트 공통 영역을 다루면 헤더, 푸터, 공식 배너, 건너뛰기 링크를 우선 확인한다.

기본 패턴

• 먼저 references/global_summary.md에서 과업 유형을 찾는다.
• 폼, 동의, 오류, 목록 탐색, 필터링·정렬처럼 여러 컴포넌트가 결합된 흐름이면 해당 global_XX.md를 읽는다.
• 사용자가 여러 단계를 거쳐 데이터를 입력하면 입력폼 패턴을 우선 검토한다.

서비스 플로

• 먼저 references/service_summary.md에서 서비스군을 찾는다.
• 방문, 검색, 로그인, 신청, 정책정보 확인 중 어느 여정인지 정한 뒤 해당 service_XX_YY.md를 읽는다.
• 서비스 패턴은 필수(Do), 권장(Better), 우수(Best) 수준을 구분해 적용한다. 최소한 필수 수준은 지킨다.

구현과 설치

• KRDS HTML Component Kit 설치, CDN 사용, React/Vue 적용, 토큰 추출, SCSS 사용 방식은 references/outline_03.md를 읽는다.
• KRDS는 SCSS 기반 사용을 권장한다. 가능하면 토큰과 원본 구조를 유지하고, 임의 CSS 덮어쓰기는 최소화한다.
• SCSS 경로 문제가 있으면 Kit의 resources 디렉터리를 프로젝트로 복제해 참조 경로를 명시적으로 관리한다.

작업 절차

1. 현재 작업이 스타일, 컴포넌트, 기본 패턴, 서비스 플로 중 무엇인지 먼저 정한다.
2. 요약 문서에서 후보를 고른 뒤 해당 상세 문서만 읽는다.
3. 표준형인지 확장형인지 판단한다.
4. 새 UI를 만들기보다 KRDS 구조와 상태를 그대로 재사용하는 쪽을 먼저 검토한다.
5. 스타일 값은 하드코딩보다 토큰으로 연결한다.
6. 구현 후 체크리스트로 다시 검증한다.

구현 원칙

• KRDS에서 정의한 구조와 상태 이름을 유지한다.
• 프리미티브 토큰을 직접 남발하지 말고 시멘틱 토큰 또는 컴포넌트 토큰으로 연결한다.
• 색상만으로 상태를 구분하지 않는다.
• 아이콘 버튼과 아이콘 링크에는 텍스트 레이블 또는 접근 가능한 이름을 제공한다.
• 플레이스홀더를 레이블 대용으로 쓰지 않는다.
• 키보드 탐색, 초점 이동, 스크린 리더 이름을 기본 요구사항으로 본다.
• 헤더, 푸터, 공식 배너, 건너뛰기 링크처럼 서비스 공통 골격은 임의 변형을 피한다.
• 여러 단계 입력은 정말 필요한 경우에만 쓴다. 한 화면에서 해결 가능한 복잡도라면 점진적 공개를 먼저 검토한다.
• 파일 업로드, 오류, 확인, 동의처럼 실수 비용이 큰 구간은 관련 패턴 문서를 반드시 읽고 구현한다.

빠른 판단 기준

먼저 확인할 항목

• 공공 웹사이트 전체 구조인가
• 단일 컴포넌트 수정인가
• 폼 입력과 제출 흐름인가
• 로그인, 신청, 검색 같은 대표 과업인가
• 토큰, 색상, 서체, 간격 수정인가
• 접근성 지적 사항을 수정하는 일인가

자주 걸리는 위반

• KRDS 토큰 대신 임의 색상과 간격을 직접 넣는 경우
• 헤더, 푸터, 배너, 건너뛰기 링크를 생략하거나 구조를 바꾸는 경우
• 플레이스홀더를 레이블처럼 쓰는 경우
• 필터링·정렬 컨트롤을 숨기거나 현재 상태를 불명확하게 만드는 경우
• 드롭다운 메뉴를 마우스오버 중심으로 여는 경우
• 현재 상태, 오류, 선택 상태를 색상만으로 표현하는 경우
• 파일 업로드 후 자동 제출하거나 제약 조건 안내를 생략하는 경우

검증 방법

최종 검토 전 references/디지털 정부 서비스 UIUX 가이드라인 자체 검증 체크리스트.md를 읽고 관련 항목만 추려 점검한다.

• 스타일 검토: 색상, 서체, 형태
• 컴포넌트 검토: 헤더, 푸터, 입력, 탐색, 도움, 모바일
• 기본 패턴 검토: 입력폼, 개인 식별 정보, 첨부파일, 필터링·정렬
• 서비스 검토: 방문, 검색, 로그인, 신청, 정책정보 확인

체크리스트는 가능한 한 “통과/수정 필요/해당 없음”으로 짧게 판정한다. 문제가 있으면 어느 문서의 어느 계층에서 어긋났는지 함께 적는다.

검색 요령

참조 문서가 많으니 필요한 파일만 찾는다.

rg --files references
rg "헤더|푸터|공식 배너|건너뛰기 링크" references/component_*.md
rg "입력폼|개인 식별 정보|필터링·정렬|오류" references/global_*.md
rg "로그인|신청|검색|방문" references/service_*.md
rg "디자인 토큰|서체|색상 팔레트|접근성" references/style_*.md references/utility_*.md

문서를 읽을 때는 아래 순서로 훑는다.

1. # page title
2. 구조, 유형, 용례
3. 사용성 가이드라인
4. 상호작용 가이드라인
5. 접근성 가이드라인

응답 방식

• KRDS 기준에 맞는 안과 맞지 않는 안을 구분해 설명한다.
• 가능하면 “어떤 문서를 봤고, 그래서 무엇을 적용했다”까지 짧게 남긴다.
• 새 코드를 제안할 때는 토큰, 상태, 접근성 속성, 반응형 대응을 함께 점검한다.
• KRDS 문서에 없는 임의 패턴을 도입해야 한다면 그 사실을 명시하고, 기존 KRDS 패턴으로 대체 가능한지 먼저 검토한다.