설치

• React 앱: dsui 사이트는 React 19와 Next.js로 만들어요. 컴포넌트는 "use client"를 쓰는 클라이언트 컴포넌트예요.
• CSS 모듈을 읽는 번들러: 컴포넌트는 Tailwind 클래스가 아니라 CSS 모듈(*.module.css)과 토큰 변수로 꾸며요. Tailwind는 없어도 돼요. Next.js나 Vite처럼 CSS 모듈을 지원하는 환경이면 돼요.
• shadcn CLI: 설치는 npx shadcn@latest add로 해요. 프로젝트에 components.json이 없으면 CLI가 먼저 만들자고 물어볼 수 있어요.

npm 패키지는 직접 설치하지 않아도 돼요. 항목마다 필요한 패키지가 레지스트리에 적혀 있어서 CLI가 함께 설치해요.

항목 이름을 주소에 넣으면 돼요. 항목 상세 페이지의 "설치" 칸에도 같은 명령이 있어서 바로 복사할 수 있어요.

npx shadcn@latest add https://dsui.vercel.app/r/button.json

CLI는 이 항목이 기대는 다른 항목도 같이 가져와요. 버튼이면 공통 기반 arc-foundation과 효과음 arc-sound가 따라오고, 아이콘을 쓰는 항목이면 arc-theme도 들어와요. 블록은 안에서 쓰는 컴포넌트까지 함께 설치돼요.

npx shadcn@latest add https://dsui.vercel.app/r/hero-section.json

파일끼리는 상대 경로로 서로를 불러요. 폴더 구조를 바꾸면 import 경로도 같이 고쳐야 해요.

foundation.css를 전역 스타일시트에서 한 번만 불러와요. 컴포넌트가 읽는 색, 모서리, 그림자, 모션 변수가 모두 여기 있어요.

@import "../components/arc/foundation.css";

경로는 전역 스타일시트 위치에 맞게 바꿔요. 위 예시는 app/globals.css에서 부르는 경우예요. 파일 맨 위에 두면 나중에 설치하는 테마의 규칙이 그 뒤에 쓰여서 기본값을 덮어요.

링크와 이미지를 그리는 컴포넌트는 기본으로 평범한 <a>와 <img>를 써요. 그래서 Next.js가 아니어도 동작해요. Next.js의 Link와 Image를 쓰고 싶으면 앱을 ArcProvider로 한 번 감싸요.

import Link from "next/link";
import Image from "next/image";
import { ArcProvider } from "@/components/arc/lib/arc-provider";

export default function Providers({ children }: { children: React.ReactNode }) {
  return (
    <ArcProvider link={Link} image={Image}>
      {children}
    </ArcProvider>
  );
}

ArcProvider는 클라이언트 컴포넌트라서, 위 파일처럼 따로 둔 제공자 파일에서 감싸면 편해요.

토큰은 본문과 제목 서체로 Pretendard Variable을 먼저 찾고, 없으면 시스템 서체(Apple SD Gothic Neo, Noto Sans KR 등)를 써요. 서체 파일은 레지스트리에 들어 있지 않아요. 같은 모양을 원하면 Pretendard Variable을 직접 불러와요.

@font-face {
  font-family: "Pretendard Variable";
  font-style: normal;
  font-weight: 45 930;
  font-display: swap;
  src: url("/fonts/PretendardVariable.woff2") format("woff2-variations");
}

Pretendard는 SIL OFL 라이선스라서 함께 배포할 수 있어요.

<html>에 data-theme="dark"나 class="dark"를 달면 다크 토큰으로 바뀌어요. 둘 다 없으면 운영체제 설정을 따르고, data-theme="light"나 class="light"면 라이트로 고정돼요.

<html lang="ko" data-theme="dark">

next-themes처럼 .dark 클래스를 다는 도구를 이미 쓰고 있으면 그대로 두면 돼요.

주소 대신 짧은 이름으로 설치하고 싶으면 components.json에 레지스트리 이름공간을 등록해요.

{
  "registries": {
    "@devs7udio": "https://dsui.vercel.app/r/{name}.json"
  }
}

등록한 뒤에는 이렇게 설치해요.

npx shadcn@latest add @devs7udio/button

CLI로 등록할 수도 있어요.

npx shadcn@latest registry add @devs7udio=https://dsui.vercel.app/r/{name}.json

모든 주소 앞에는 https://dsui.vercel.app이 붙어요.

• 404가 나와요. 이름을 다시 확인해요. 레지스트리 이름은 상세 페이지 주소의 마지막 부분과 같고, 영어 소문자와 하이픈으로만 돼 있어요. 아래 "설치할 수 없는 항목"에 있는 항목도 404가 나요.
• 패키지 버전이 맞지 않는대요. 레지스트리는 motion@^14.2.0처럼 범위를 적어 둬요. 이미 다른 메이저 버전을 쓰고 있으면 CLI나 패키지 관리자가 경고를 낼 수 있어요. React는 19를 기준으로 만들었어요.
• 색과 모서리가 안 보여요. foundation.css를 불러왔는지 확인해요. 한 번만 불러오면 되고, 다른 전역 스타일보다 먼저 불러오는 것이 좋아요.
• 버튼이 회색이에요. shadcn init이 만든 :root의 --background, --foreground, --accent, --accent-foreground, --border가 foundation.css의 같은 이름을 덮고 있어요. 그 다섯 줄을 지우거나 테마를 설치해요.
• 컴포넌트에 스타일이 하나도 없어요. 새 Next.js 프로젝트의 next.config.ts에 "*.css" 규칙(@tailwindcss/turbopack, as: "*.css")이 있으면 CSS 모듈이 일반 CSS로 읽혀서 클래스 이름이 비어요. 규칙의 키를 "globals.css"로 좁혀 주세요.
• 블록의 사진과 로고가 깨져요. 예시 이미지는 dsui 사이트의 /public/media와 /public/block-logos에 있고 레지스트리로 배포하지 않아요. blog-grid, hero-section, logo-marquee, page-header 같은 블록과 components/arc/lib/media.ts의 예시 데이터를 내 이미지로 바꿔 주세요.

예전부터 있던 devs7udio 항목은 대부분 레지스트리로 배포하지 않아요. 데모용 키트나 사이트 안에서만 쓰는 경로에 기대고 있어서 다른 프로젝트에서는 동작하지 않거든요. 상세 페이지의 "설치" 칸에는 명령 대신 이 안내가 보이고, 소스를 보고 참고할 수는 있어요.

지금 설치할 수 있는 devs7udio 항목은 테마 base, halloween, seollal, chuseok, christmas예요. 나머지 컴포넌트 9개, 블록 3개, 요소 1개, 모션, 애니메이션은 설치할 수 없어요.