@une-front/krds

v0.5.0

Published

19 days ago

Self-built React component library based on the KRDS (Korea Government Design System) official specification.

Downloads

165

0High
0Medium
0Low

woojin93

bomhee

@une-front/krds

대한민국 정부 디자인 시스템(KRDS) 공식 스펙을 기반으로 자체 구축하는 React 컴포넌트 라이브러리.

위치

@une-front/design-system 모노레포의 modules/krds/ 워크스페이스. 자매 패키지인 @une-front/react-ui(자사 사내용)와는 완전 독립이며 서로 참조하지 않습니다. 정부·공공 도입 프로젝트가 대상이며, @une-front/react-ui는 자사 사내 앱이 대상입니다.

원칙

KRDS 공식 스펙이 진실의 원천: HANUI 같은 커뮤니티 구현이 아니라 krds-uiux GitHub의 SCSS 원본과 KRDS_v1.0.0 Figma를 근거로 삼습니다.
1rem = 10px (KRDS 62.5% 사양): KRDS 공식 $font-size-base: 62.5% 정책에 따라 --krds-pc-font-size-body-medium: 1.7rem = 17px 등 모든 rem 값이 10px 기준으로 계산됩니다. 도입 프로젝트는 반드시 html { font-size: 62.5% } 를 지정해야 원본 크기가 그대로 재현됩니다. react-ui 의 1rem = 1px 커스텀과도, 브라우저 기본 16px 과도 다릅니다. 도입 프로젝트가 이미 다른 rem 스케일(예: 1rem = 1px)을 쓰는 경우 @une-front/krds/portable 서브패스로 격리 사용할 수 있습니다 (아래 "도입 프로젝트에서 사용하기" 참조).
선명한 화면 모드(High Contrast) = 다크 팔레트: KRDS 공식 명명 규칙을 따라 다크 모드는 .high-contrast 클래스로 활성화되며, tailwind 커스텀 variant hc: 로 스타일링합니다. 도입 프로젝트가 이미 .dark 규약을 쓰는 경우도 셀렉터가 병기(:where(.high-contrast, .dark)) 되어 있어 자동 동작합니다.
접근성 기준 반영: KRDS 명도 대비 스펙(본문 15:1, 헤딩 7:1, 아이콘 4.5:1 이상)을 컴포넌트/스토리 단계에서 검증합니다.

도입 프로젝트에서 사용하기

두 가지 번들을 제공합니다.

A. 기본 (rem) — `@une-front/krds`

도입 프로젝트가 html { font-size: 62.5% } 를 세팅할 수 있는 신규 프로젝트에 권장.

import { Button } from "@une-front/krds";
import "@une-front/krds/css";

B. Portable — `@une-front/krds/portable`

도입 프로젝트가 이미 다른 rem 스케일(예: 1rem = 1px)을 쓰고 있어 html { font-size: 62.5% } 로 바꿀 수 없을 때 사용합니다. 빌드 시점에 KRDS 내부의 모든 Nrem 리터럴을 calc(N × var(--krds-unit, 10px)) 로 치환한 별도 번들이며, 도입 프로젝트의 rem 시스템과 무관하게 동작합니다.

import { Button } from "@une-front/krds/portable";
import "@une-front/krds/portable/css";

기본 동작: --krds-unit 미정의 시 fallback 10px 로 자동 세팅 → 별도 wrapper 없이 컴포넌트만 심어도 원본 크기 재현.
반응형 스케일링을 원하면: 도입 프로젝트의 :root 또는 KRDS 를 감싼 wrapper 에 --krds-unit 만 조정.
```
:root {
  --krds-unit: clamp(8px, 0.56vw, 10px);  /* 뷰포트에 따라 KRDS 전체 스케일 */
}
```

Portal 컴포넌트 (Tooltip / ContextualHelp): <body> 로 마운트되므로 wrapper 스코프를 이탈합니다. wrapper 로 스코프 격리를 하는 경우 portalContainer prop 으로 wrapper ref 를 전달하세요.

const wrapperRef = useRef<HTMLDivElement | null>(null);

return (
  <div ref={wrapperRef} className="krds-scope">
    <Tooltip content="..." portalContainer={wrapperRef.current}>
      <button>...</button>
    </Tooltip>
  </div>
);

다크 모드: KRDS 는 .high-contrast 를 공식 사용하지만 셀렉터가 .dark 도 병기해서 인식합니다. 도입 프로젝트가 <html class="dark"> 규약을 쓰면 그대로 KRDS 컴포넌트가 다크 팔레트로 렌더됩니다.

개발

# 저장소 루트에서
npm run storybook:krds   # Storybook 개발 서버 (포트 6009)
npm run build:krds       # 라이브러리 빌드
npm run test:krds        # Vitest 실행
npm run typecheck:krds   # 타입 체크

react-ui Storybook(포트 6006)과 독립 실행되므로 동시에 띄울 수 있습니다. 이미 6008 이 사용 중이면 다른 포트로 자동 대체되지 않도록 --no-open 옵션을 걸어두었으며, 필요 시 package.json 의 storybook 스크립트에서 포트를 조정하세요.

로드맵

Phase 0 · 스캐폴딩 (완료)

워크스페이스 신설, 빌드/테스트/스토리북 파이프라인
react-ui와 완전 독립 구조

Phase 1 · 토큰 (예정)

KRDS 공식 색상 팔레트(라이트 / 선명한 화면 모드) CSS 변수화
타이포그래피·spacing·elevation 토큰 이식
Storybook FOUNDATIONS 스토리로 시각 검증

Phase 2 · 리프 컴포넌트 15~20개 (예정)

우선순위 초안: Button → Badge → Tag → Input → Label → Checkbox → Radio → Switch → Textarea → Select → Divider → Icons → Tooltip → ...

각 컴포넌트는 다음을 갖춥니다.

Figma variant 전수 커버
라이트 / 선명한 화면 모드 두 모드 대응
키보드 내비게이션·ARIA·포커스 관리
Storybook 스토리 + Vitest 브라우저 테스트

라이센스

ISC

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@une-front/krds

위치

원칙

도입 프로젝트에서 사용하기

A. 기본 (rem) — @une-front/krds

B. Portable — @une-front/krds/portable

개발

로드맵

Phase 0 · 스캐폴딩 (완료)

Phase 1 · 토큰 (예정)

Phase 2 · 리프 컴포넌트 15~20개 (예정)

라이센스

A. 기본 (rem) — `@une-front/krds`

B. Portable — `@une-front/krds/portable`