설치

KRDS 레지스트리를 기존 프로젝트에 적용하고 페이지 골격을 구성하는 방법입니다.

준비 사항

krdscn/ui는 CLI로 설치하는 레지스트리입니다. 기존 프로젝트에는 컴포넌트 레지스트리를 사용할 수 있는 기본 설정이 준비되어 있어야 합니다.

pnpm dlx shadcn@latest init

기존 Radix primitive 생태계와 호환되도록 이 레지스트리는 Radix 기반 구조를 유지합니다.

전체 설치

전체 UI 컴포넌트를 한 번에 가져옵니다.

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

설치된 컴포넌트는 프로젝트의 components/ui 경로에 복사됩니다. 이후에는 패키지 API에 맞추기보다, 프로젝트 안의 소스 코드를 기준으로 필요한 변경을 직접 적용하면 됩니다.

컴포넌트를 하나라도 설치하면 CLI가 krds-theme 레지스트리 아이템(registry:theme)을 자동으로 함께 설치합니다. 파일을 복사하거나 @import를 직접 추가할 필요가 없습니다 — KRDS 색상 팔레트, 시맨틱 토큰(light/high-contrast), 타이포그래피, 포커스 링 유틸리티가 components.json에 지정된 프로젝트 CSS 파일(기본 app/globals.css)에 @theme inline / :root / .dark / @utility 블록으로 직접 병합됩니다.

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

토큰만 먼저 확인하고 싶다면 위처럼 krds-theme 하나만 설치해도 됩니다. Tailwind CSS v4 기준이며, 다크 모드는 .dark 클래스를 사용합니다.

단일 컴포넌트 설치

필요한 컴포넌트만 선택해서 가져올 수도 있습니다.

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

다른 컴포넌트도 /r/{component}.json 형식의 레지스트리 URL로 설치합니다.

설치 후 확인

기존 컴포넌트와 경로가 겹치는 경우 CLI가 표시하는 변경 사항을 검토합니다.
서비스별 요구사항이 있다면 설치된 컴포넌트 파일을 직접 수정해 확장합니다.

페이지 셸

공공 누리집의 골격은 공식 배너(Masthead), 헤더, 본문, 운영기관 식별자(Identifier)가 포함된 푸터로 이루어집니다.

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

SkipLink·Identifier는 Header·Footer가 참조하는 파일로 함께 설치됩니다. 공식 배너(Masthead)는 별도 항목이며, 페이지 골격에서 헤더 위에 직접 배치합니다.

Header는 건너뛰기 링크(SkipLink)를 첫 자식으로 자동 렌더링합니다(WAI Skip Navigation). 공식 배너(Masthead)는 헤더에 내장되지 않으므로, 필요하면 페이지 최상단에서 Header 위에 직접 배치합니다. 헤더 자체는 유틸리티 메뉴·브랜드·액션·내비 네 영역을 조합합니다.

import { Menu, Search } from "lucide-react"
import {
  Header,
  HeaderActionItem,
  HeaderActions,
  HeaderBrand,
  HeaderNav,
  HeaderNavItem,
  HeaderUtility,
  HeaderUtilityItem,
} from "@/components/ui/header"

export function SiteHeader() {
  return (
    <Header>
      <HeaderUtility>
        <HeaderUtilityItem href="/about">기관 소개</HeaderUtilityItem>
        <HeaderUtilityItem href="/faq">자주 묻는 질문</HeaderUtilityItem>
      </HeaderUtility>

      <HeaderBrand href="/">우리기관</HeaderBrand>

      <HeaderActions>
        <HeaderActionItem icon={<Search />}>통합검색</HeaderActionItem>
        <HeaderActionItem href="/login">로그인</HeaderActionItem>
        <HeaderActionItem icon={<Menu />}>전체메뉴</HeaderActionItem>
      </HeaderActions>

      <HeaderNav aria-label="주요 메뉴">
        <HeaderNavItem href="/services" hasSubmenu>
          민원 서비스
        </HeaderNavItem>
        <HeaderNavItem href="/notice">공지사항</HeaderNavItem>
      </HeaderNav>
    </Header>
  )
}

본문 영역

Header에 내장된 건너뛰기 링크의 기본 대상이 #main-content입니다. 본문 <main>에 해당 id를 지정해야 키보드 사용자가 메뉴를 건너뛸 수 있습니다.

export function SiteMain({ children }: { children: React.ReactNode }) {
  return (
    <main id="main-content" tabIndex={-1}>
      {children}
    </main>
  )
}

푸터도 부분 조립식입니다. 운영기관 식별자(Identifier)는 Footer에 내장되어 있지 않으므로 FooterBottom 안에 직접 배치합니다.

import {
  Footer,
  FooterAddress,
  FooterBottom,
  FooterContact,
  FooterContactItem,
  FooterCopyright,
  FooterInfo,
  FooterLogo,
  FooterMenu,
  FooterMenuLink,
} from "@/components/ui/footer"
import { Identifier } from "@/components/ui/identifier"

export function SiteFooter() {
  return (
    <Footer>
      <div className="mx-auto flex max-w-[1200px] flex-col gap-9 px-4 py-10">
        <FooterLogo>우리기관</FooterLogo>

        <FooterInfo>
          <FooterAddress>(00000) 어딘가시 어딘가로 1 우리기관</FooterAddress>
          <FooterContact>
            <FooterContactItem label="대표전화 1500-0000" note="(유료, 평일 09시~18시)" />
          </FooterContact>
        </FooterInfo>

        <FooterBottom>
          <FooterMenu>
            <FooterMenuLink href="/privacy" point>
              개인정보처리방침
            </FooterMenuLink>
            <FooterMenuLink href="/copyright">저작권 정책</FooterMenuLink>
          </FooterMenu>
          <FooterCopyright>© 2026 Our Agency.</FooterCopyright>
          <Identifier notice="이 누리집은 우리부처 산하기관 누리집입니다." />
        </FooterBottom>
      </div>
    </Footer>
  )
}

FooterMenuLink의 point는 개인정보처리방침처럼 강조가 필요한 항목에 사용합니다.

골격 구성

app/layout.tsx (본문 부분)

export function Shell({ children }: { children: React.ReactNode }) {
  return (
    <>
      <SiteHeader />
      <main id="main-content" tabIndex={-1}>
        {children}
      </main>
      <SiteFooter />
    </>
  )
}

Masthead와 Identifier의 문구는 notice prop으로 기관에 맞게 변경할 수 있습니다. 단독으로 사용하려면 masthead, identifier 항목을 개별 설치합니다.

소개 레지스트리