# 소개

> dsui가 무엇이고 어떻게 쓰는지 한눈에 볼 수 있어요.

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

## dsui가 뭐예요

dsui는 한국어 웹앱을 만들 때 쓰는 React 컴포넌트, 블록, 테마 라이브러리예요. 색, 간격, 모서리, 그림자, 모션을 모두 토큰으로 정해 두고, 컴포넌트는 그 토큰만 읽어요. 그래서 토큰을 바꾸면 화면 전체가 같이 바뀌어요.

패키지로 설치하지 않고 소스 파일을 내 프로젝트에 복사해서 써요. shadcn 형식의 레지스트리를 열어 두었기 때문에 `npx shadcn` 명령 한 줄로 컴포넌트와 필요한 공통 파일이 함께 들어와요. 복사된 코드는 내 코드라서 마음대로 고칠 수 있어요.

컴포넌트와 블록 대부분은 MIT 라이선스 항목을 바탕으로 다듬은 것이라, 설치하면 저작권 표시가 담긴 `LICENSE` 파일도 함께 들어와요. 지우지 말고 그대로 두면 돼요.

dsui는 devs7udio 스튜디오 사이트를 만드는 데에도 쓰여요. 지금 보고 있는 이 사이트의 머리글, 푸터, 404 화면, 버튼, 입력 필드가 모두 dsui 항목이에요.

지금 버전은 위의 `v` 배지에 있어요. 버전은 [변경 이력](/docs/changelog)의 맨 위 항목과 같고, 디자인시스템 아티팩트의 README에도 같은 번호가 적혀 있어요.

## 이렇게 구성돼 있어요

| 구분 | 개수 | 설명 |
| --- | --- | --- |
| 컴포넌트 | 126개 | 버튼, 입력 필드, 대화상자, 차트 같은 화면의 부품이에요. |
| 블록 | 35개 | 머리글, 히어로, 가격표, 자주 묻는 질문처럼 바로 쓰는 화면 단위예요. |
| 테마 | 5개 | 기준이 되는 `base`와 그 위에 얹은 시즌 테마 `halloween`, `seollal`, `chuseok`, `christmas`예요. 색뿐 아니라 아이콘, 소리, 모션, 제목 글꼴, 일러스트도 바꿔요. |
| 일러스트 | 17종 | 히어로, 섹션 헤더, 카드 커버, 페이지 상단(404, FAQ, 로그인, 연락), 스플래시, 푸터 띠에 쓰는 도형 그림이에요. `Illustration` 컴포넌트로 쓰고, 테마마다 따로 그릴 수 있어요. |
| 그 밖의 항목 | 3개 | 작은 요소, 모션, 애니메이션처럼 예전부터 있던 devs7udio 항목이에요. |

모든 컴포넌트와 블록은 같은 기반을 나눠 써요.

- **토큰:** `foundation.css`에 색, 서체, 모서리, 그림자, 모션 길이가 변수로 들어 있어요. 라이트와 다크 값이 함께 있어요.
- **모션:** 누름, 패널, 강조 이동에 쓰는 스프링과 곡선을 이름으로 불러 써요.
- **사운드:** 클릭, 선택, 열기와 닫기 같은 역할마다 짧은 효과음이 있어요. 사용자가 끄거나 음량을 줄일 수 있어요.
- **아이콘:** 닫기, 확인, 화살표 같은 인터페이스 아이콘을 역할 이름으로 불러요. 테마가 아이콘을 바꿀 수 있어요.
- **일러스트:** `<Illustration name="hero-collage" animated />`처럼 이름으로 불러요. 색은 테마 토큰이고, 테마가 직접 그린 그림이 없으면 base 그림을 그 테마의 색으로 그려요. `AuthPanel`, `FaqSection`, `ContactSection`, `SiteFooter`는 `illustration` 속성으로, `NotFound`(404) 블록은 기본으로 일러스트를 품고 있어요.

## 한 페이지는 이렇게 읽어요

항목마다 상세 페이지가 하나씩 있어요. 예를 들어 [버튼](/items/button) 페이지는 이렇게 짜여 있어요.

- **미리보기:** 실제 컴포넌트가 움직이는 데모예요. 라이트와 다크, 테마를 바꿔 볼 수 있어요.
- **컨트롤:** 오른쪽 패널에서 종류, 크기, 비활성처럼 그 항목의 실제 속성을 바꾸면 미리보기에 바로 반영돼요. 색과 모서리는 테마가 정하니, 미리볼 테마만 고르면 돼요.
- **설명:** 제목, 한 줄 요약, 태그로 어떤 항목인지 알려 줘요.
- **소스:** 항목에 들어 있는 파일을 그대로 보여 줘요. 마크다운으로도 볼 수 있어요.
- **설치:** 설치 명령을 npm, pnpm, yarn, bun 탭으로 보여 줘요. 함께 설치되는 파일, npm 패키지, 공통 항목도 펼쳐서 확인할 수 있어요. 아직 설치할 수 없는 항목에는 명령 대신 안내가 보여요.
- **AI 프롬프트:** AI 도구에 붙여 넣어 비슷한 화면을 만들게 하는 지시문이에요. 일부 항목에만 있어요.
- **관련 항목:** 이 항목이 쓰는 항목, 이 항목을 쓰는 블록, 비슷한 항목을 이어서 볼 수 있어요.

## 설치해 볼까요

컴포넌트 하나는 주소로 바로 설치해요. 버튼을 넣어 볼게요.

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

블록도 같은 방법이에요. 블록이 쓰는 컴포넌트까지 한 번에 들어와요.

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

설치가 끝나면 공통 토큰 파일 `components/arc/foundation.css`를 전역 스타일시트에서 한 번만 불러오면 돼요. 이 파일이 없으면 컴포넌트에 색과 모서리가 입혀지지 않아요. 자세한 순서는 [설치](/docs/installation)에 있어요.

## 다른 점

- **한국어 문구가 기본이에요.** 안내문, 접근성 라벨, 오류 문구가 해요체로 들어 있고, 날짜와 숫자는 `ko-KR`, 시간대는 `Asia/Seoul`이 기본이에요. 블록의 예시 콘텐츠는 아직 영어로 남은 곳이 있어요.
- **입력 필드는 포커스를 받으면 면이 채워져요.** 고리를 그리는 대신 필드 면을 강조색으로 채우고 글자색을 바꿔요. 오류일 때는 위험 색으로 채워요.
- **사운드와 모션도 역할로 다뤄요.** 컴포넌트는 파일 이름이 아니라 `click`, `open` 같은 역할 이름을 불러요. 그래서 테마가 소리와 움직임을 바꿀 수 있어요.
- **테마는 물려받아요.** 새 테마는 `base`를 물려받고 바꾸고 싶은 값만 써요. 색, 아이콘, 소리, 모션, 글꼴, 모서리, 그림자, 일러스트 모두 쓰지 않은 값은 그대로 이어져요. 일러스트는 그림 한 장씩 따로 이어받아요.

## 최근에 바뀐 것

- **생성형 UI(미리 보기):** AI 모델이 dsui 컴포넌트로 화면을 만들어요. OpenUI와 json-render를 모두 지원하고, 컴포넌트는 한 번만 정의해요.
- **일러스트 17종:** 히어로, 섹션 헤더, 카드 커버, 페이지 상단, 스플래시, 푸터 띠를 더했고 시즌 테마가 직접 그린 그림도 있어요.
- **404 블록 `NotFound`:** 일러스트와 돌아갈 길을 함께 안내해요.
- **헤더:** 앱 헤더가 풀 로고를 쓰고, 스크롤하면 떠 있는 막대로 바뀌어요.
- **컨트롤 패널:** 항목마다 실제 속성을 조절할 수 있어요.
- **주소:** 설치 주소는 `/r/<이름>.json`, AI 문서는 `/llms.txt`와 `/items/<이름>.md`로 모였어요. 예전 주소는 새 주소로 옮겨 가요.

전체 목록은 [변경 이력](/docs/changelog)에 있어요.

## 다음 단계

- [설치](/docs/installation): 필요한 것, 설치 명령, 파일이 놓이는 곳, 문제 해결을 정리했어요.
- [테마 만들기](/docs/theming): 토큰이 어떻게 이어지는지, 내 테마를 어떻게 만드는지 알려 줘요.
- [AI와 MCP](/docs/ai): llms.txt, 항목 마크다운, MCP 서버로 AI 도구에 dsui를 알려 줘요.
- [생성형 UI](/docs/genui): AI 모델이 dsui 컴포넌트로 화면을 만들게 하는 방법이에요.