시작하기

Next.js 프로젝트에 krdscn/ui를 설정하고 첫 KRDS 컴포넌트를 렌더링하는 과정입니다.

준비 사항

Node.js 20 이상
Next.js(App Router) + Tailwind CSS v4 프로젝트

새 프로젝트가 필요하면 다음 명령으로 생성합니다.

pnpm create next-app@latest my-krds-app --typescript --tailwind --app

CLI 초기화

krdscn/ui는 npm 패키지가 아니라 컴포넌트 소스 코드를 프로젝트로 복사하는 레지스트리입니다. 먼저 shadcn CLI를 초기화합니다.

pnpm dlx shadcn@latest init

컴포넌트 설치

pnpm dlx shadcn@latest add https://krdscn-ui.smlee.info/r/button.json

이 명령은 다음 파일을 프로젝트에 추가합니다.

파일	설명
`components/ui/krds/(action)/button.tsx`	Button 컴포넌트 소스
`lib/cn.ts`	클래스 병합 유틸리티
`app/krds.css`	KRDS 디자인 토큰(색상·타이포그래피·포커스 링)

토큰 스타일시트(krds-theme)는 모든 컴포넌트의 의존성으로 등록되어 있어 어떤 컴포넌트를 설치해도 함께 설치됩니다.

토큰 스타일시트 연결

전역 CSS에서 krds.css를 불러옵니다.

app/globals.css

@import "tailwindcss";
@import "./krds.css";

이후 bg-krds-primary-50, text-krds-body-md 같은 KRDS 유틸리티 클래스를 프로젝트 전체에서 사용할 수 있습니다.

컴포넌트 사용

app/page.tsx

import { Button } from "@/components/ui/krds/(action)/button"

export default function Page() {
  return (
    <main className="flex min-h-svh items-center justify-center gap-3">
      <Button>신청하기</Button>
      <Button variant="secondary">임시저장</Button>
      <Button variant="tertiary">취소</Button>
    </main>
  )
}

KRDS 포커스 표시(이중 링)와 색상 토큰이 기본 적용된 상태로 렌더링됩니다.

폰트 설정

KRDS 공식 서체는 Pretendard GOV입니다. 토큰은 크기·행간만 정의하고 서체는 앱에서 관리합니다.

app/layout.tsx

import localFont from "next/font/local"

const pretendardGov = localFont({
  src: "./fonts/PretendardGOVVariable.woff2",
  variable: "--font-pretendard-gov",
})

app/globals.css

@theme inline {
  --font-sans: var(--font-pretendard-gov), "Pretendard GOV", sans-serif;
}

전체 설치

전체 컴포넌트를 한 번에 가져오려면 krds-all 항목을 설치합니다. 설치된 소스는 프로젝트 코드이므로 서비스 요구사항에 맞게 직접 수정하면 됩니다.

pnpm dlx shadcn@latest add https://krdscn-ui.smlee.info/r/krds-all.json

다음 단계

페이지 셸에서 공식 배너·헤더·푸터로 페이지 골격을 구성합니다.

가이드 페이지 셸