# 설치

> 레지스트리 주소로 컴포넌트와 블록을 내 프로젝트에 넣는 방법을 알려 드려요.

- URL: https://dsui.vercel.app/docs/installation

## 먼저 준비할 것

- **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가 함께 설치해요.

| 패키지 | 쓰는 곳 |
| --- | --- |
| `motion` | 거의 모든 컴포넌트와 블록의 움직임 |
| `@hugeicons/react`, `@hugeicons/core-free-icons` | 아이콘을 쓰는 컴포넌트와 공통 테마 파일 |
| `@radix-ui/react-*` | 대화상자, 드롭다운 메뉴, 팝오버, 툴팁, 탭 같은 일부 컴포넌트 |

## 컴포넌트 하나 설치하기

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

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

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

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

## 파일이 놓이는 곳

| 항목 | 위치 |
| --- | --- |
| 컴포넌트 | `components/arc/<이름>/` |
| 블록 | `components/arc/blocks/<이름>/` |
| 공통 기반 (`arc-foundation`) | `components/arc/foundation.css`, `components/arc/motion-tokens.ts`, `components/arc/lib/`, `components/arc/LICENSE` |
| 테마 역할 (`arc-theme`) | `components/arc/theme/` |
| 효과음 (`arc-sound`) | `components/arc/sound/` |
| devs7udio 항목 | `components/devs7udio/<이름>/` |

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

## 토큰 파일 불러오기

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

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

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

## Next.js의 Link와 Image 쓰기

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

```tsx
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을 직접 불러와요.

```css
@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"`면 라이트로 고정돼요.

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

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

## 이름으로 설치하기

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

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

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

```bash
npx shadcn@latest add @devs7udio/button
```

CLI로 등록할 수도 있어요.

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

## 레지스트리 주소

| 주소 | 내용 |
| --- | --- |
| `/r/registry.json` | 설치할 수 있는 항목 전체 목록이에요. 지금은 133개예요. |
| `/r/<이름>.json` | 항목 하나예요. 이름은 상세 페이지 주소(`/items/<이름>`)와 같아요. |
| `/r/arc-foundation.json` | 토큰, 모션 프리셋, 공통 도구, 라이선스예요. 모든 항목이 기대요. |
| `/r/arc-theme.json` | 역할 아이콘(`UiIcon`), 테마 제공자, 모션 역할이에요. |
| `/r/arc-sound.json` | 효과음 엔진과 효과음 11개예요. |

모든 주소 앞에는 `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`의 같은 이름을 덮고 있어요. 그 다섯 줄을 지우거나 [테마](/docs/theming)를 설치해요.
- **컴포넌트에 스타일이 하나도 없어요.** 새 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](/themes#base), [halloween](/themes#halloween), [seollal](/themes#seollal), [chuseok](/themes#chuseok), [christmas](/themes#christmas)예요. 나머지 컴포넌트 9개, 블록 3개, 요소 1개, 모션, 애니메이션은 설치할 수 없어요.