saadeghi/daisyui 딥다이브
— 클래스 이름 하나로 끝나는 Tailwind CSS 디자인 시스템

1프로젝트 한 줄 요약

Tailwind CSS는 bg-blue-500 hover:bg-blue-600 text-white font-semibold py-2 px-4 rounded-lg처럼 작은 유틸리티 클래스를 조합해 스타일을 만드는 방식이다. 강력하지만, 버튼 하나를 만들 때마다 이 긴 조합을 반복해야 한다. daisyUI는 이 조합들을 미리 만들어 btn btn-primary 같은 의미 있는 이름으로 묶어 제공하는 Tailwind 플러그인이다.

기술적으로는 @plugin "daisyui"; 한 줄을 CSS 파일에 추가하는 것이 전부다. React 프로젝트든, Rails·Laravel·WordPress 같은 서버 렌더링 프로젝트든, 순수 HTML 파일이든 클래스 이름만 그대로 옮겨 쓸 수 있다. 컴포넌트 로직(state)이 없고 오직 CSS 규칙만 있기 때문이다.

2왜 지금 주목받는가

daisyUI는 오래된 프로젝트지만, 최근 두 가지 큰 흐름과 정확히 맞물리며 다시 주목받고 있다.

① Tailwind CSS v4의 "CSS 우선(CSS-first)" 설정과 정확히 맞아떨어짐

Tailwind CSS v4는 tailwind.config.js 같은 JS 설정 파일 대신, CSS 파일 안에서 @import·@plugin 같은 지시어로 설정하는 방식으로 크게 바뀌었다. daisyUI 5는 이 변화에 맞춰 완전히 다시 쓰였고, 설치가 @plugin "daisyui"; 한 줄로 끝난다. "config 파일 자체가 필요 없다"는 v4의 철학을 가장 잘 보여주는 대표 플러그인 사례로 자주 언급된다.

② "JS 없는 UI"가 다시 매력적으로 보이는 시기

React 생태계가 번들 크기·수화(hydration) 비용에 예민해지면서, "인터랙션까지 CSS만으로 되는 컴포넌트"에 대한 관심이 커졌다. daisyUI의 모달·드롭다운·탭은 자바스크립트 없이 브라우저 내장 기능(<dialog>, :has(), 체크박스 트릭)만으로 동작해, 정적 사이트·서버 렌더링 위주 프로젝트에서 특히 부담이 적다.

③ AI 코딩 에이전트가 "알아서" 불러 쓰는 라이브러리가 됨

daisyUI는 저장소 안에 Claude Code·Cursor·Codex·Grok용 공식 스킬/플러그인 매니페스트(.claude-plugin, .cursor-plugin 등)를 함께 배포한다. 이 스킬의 설명 문구는 "HTML이나 JSX 코드를 생성할 때는, 사용자가 명시적으로 요청하지 않아도 트리거하라"다. 즉 AI가 UI 코드를 생성할 때 daisyUI 클래스 이름을 기본값처럼 쓰도록 스스로를 등록해 둔 것이다. "AI가 코드를 짜는 시대"에 자신을 그 코드 생성 파이프라인 안에 미리 심어둔 셈이다.

3무엇을 해결하는가

Tailwind CSS 자체는 아주 강력하지만, 초보자가 실제로 부딪히는 문제는 세 가지로 요약된다. daisyUI는 이 세 가지를 CSS 레벨에서 해결한다.

문제 ① — 버튼 하나에 클래스 열 개

순수 Tailwind로 버튼을 만들면 inline-flex items-center justify-center rounded-lg bg-blue-600 px-4 py-2 font-semibold text-white shadow hover:bg-blue-700 focus:outline-none focus:ring-2처럼 클래스가 끝없이 늘어난다. 프로젝트 전체에서 버튼 스타일을 통일하려면 이 조합을 그대로 복사·붙여넣기 해야 하고, 나중에 색을 바꾸려면 모든 곳을 찾아 고쳐야 한다.

daisyUI는 이 조합 전체를 .btn·.btn-primary 같은 미리 컴파일된 CSS 규칙으로 대신 제공한다. 클래스 개수가 줄어드는 건 부수 효과일 뿐이고, 진짜 핵심은 "버튼이라는 개념 하나가 CSS 파일 한 곳에 정의돼 있다"는 유지보수성이다.

문제 ② — 색을 숫자(500, 600...)로 다뤄야 하는 문제

Tailwind의 기본 색상은 blue-500, red-600처럼 구체적인 색상값이다. "이 프로젝트의 주요 강조색"이라는 의미는 코드 어디에도 남지 않는다. 다크 모드나 브랜드 색을 바꾸려면 blue-500이 쓰인 곳을 전부 찾아 green-500으로 바꿔야 한다.

daisyUI는 primary·secondary·accent·neutral·base-100 같은 의미 기반 색상 이름을 CSS 변수로 제공한다. 실제 색상값은 테마 하나에만 정의돼 있어서, 테마를 통째로 바꾸면 사이트 전체 색이 한 번에 바뀐다.

문제 ③ — "디자인 시스템"을 매번 처음부터 설계해야 하는 문제

버튼 크기 5단계, 여백 규칙, 모서리 둥글기, 그림자 깊이 같은 것들을 프로젝트마다 새로 정의하는 건 지루하고 실수가 잦다. daisyUI는 35개 완성된 테마와, 크기·반경·테두리 굵기를 담당하는 공통 토큰(--radius-box, --size-field 등)을 미리 갖춘 채로 제공해, "디자인 시스템을 0에서 설계하는" 초기 비용 자체를 없앤다.

4전체 구조

저장소는 Bun 워크스페이스 모노레포(bun@1.3.14, workspaces: ["packages/*"])로, packages/ 아래 6개 패키지가 있다. 실제로 npm에 배포되는 것은 이 중 딱 하나, packages/daisyui뿐이다. 나머지는 문서·플레이그라운드·부가 도구다.

구조가 말해주는 것은 명확하다. "CSS 소스(src/) → 빌드 스크립트(functions/) → 배포용 결과물"이라는 전형적인 CSS 라이브러리 파이프라인이고, 여기에 문서 사이트와 AI 에이전트 연동이라는 두 축이 나란히 붙어 있다. 실제 컴포넌트가 "어떻게 만들어지는지"는 다음 5번 섹션에서 자세히 뜯어본다.

5핵심 설계 · 동작 원리

daisyUI를 이해하는 데 가장 중요한 사실 하나: 이 저장소에 있는 것은 손으로 쓴 CSS 소스(src/*.css)와, 그것을 가공하는 빌드 스크립트뿐이다. React 컴포넌트도, 상태 관리도 없다. "잘 만든 CSS 라이브러리가 실제로 어떻게 빌드되는가"를 배우기에 아주 좋은 실물 사례다.

설계 원리 ① — 캐스케이드 레이어로 "순서 전쟁"을 없앤다

CSS의 오래된 골칫거리는 "나중에 쓴 클래스가 이긴다"는 로드 순서 의존성이다. btn-primary 다음에 btn-outline을 썼는지, 그 반대인지에 따라 결과가 달라지면 유지보수가 악몽이 된다. daisyUI는 이 문제를 최신 CSS의 @layer(캐스케이드 레이어) 기능으로 정면 돌파한다.

button.css 원본을 보면 규칙마다 @layer daisyui.l1.l2.l3처럼 레이어 이름이 박혀 있다. 기본 형태는 가장 낮은 레이어에, 색상 지정(btn-primary)은 l2에, 테두리 스타일 변형(btn-outline, btn-ghost)은 더 높은 레이어에 둔다. 브라우저는 레이어 우선순위로 승자를 정하기 때문에, HTML에 클래스를 어떤 순서로 나열하든 결과가 항상 똑같다.

설계 원리 ② — 빌드 스크립트가 CSS를 "자동 증식"시킨다

packages/daisyui/build.js는 functions/ 안의 스크립트 30여 개를 순서대로 호출하는 오케스트레이터다. 사람이 src/components/button.css 한 파일만 손으로 쓰면, 빌드 과정이 그 뒤에서 훨씬 많은 일을 대신 해준다.

즉 src/components/button.css 한 파일은 실제로는 수백~수천 줄의 색상 유틸리티, 테마별 변형, 압축본으로 불어난 뒤에야 사용자에게 도달한다. "작은 소스 → 빌드 타임에 자동 증식"이라는 패턴은 대규모 CSS 라이브러리를 유지보수 가능하게 만드는 핵심 기법이다.

설계 원리 ③ — 테마는 "색상 20여 개짜리 CSS 변수 묶음"일 뿐

daisyUI 테마 하나의 실체는 다음과 같은 OKLCH 색상값 목록이다(light.css 전체):

--color-*는 배경·글자·강조 다섯 가지 의미 색(primary·secondary·accent·neutral·상태색)에 대해, 색 자체(-primary)와 그 색 위에 놓을 글자색(-content)을 항상 쌍으로 정의한다는 점이 핵심이다. 컴포넌트 CSS는 var(--color-primary)만 참조하므로, 테마를 바꾸는 것 = 이 변수 목록 20여 줄을 통째로 교체하는 것일 뿐이다. 버튼·카드·모달 CSS는 단 한 줄도 안 바뀐다.

설계 원리 ④ — 옵션 처리는 "테마 목록 문자열 하나"를 파싱하는 것

@plugin "daisyui" { themes: light --default, dark --prefersdark; }처럼 쓰는 이 설정은 functions/pluginOptionsHandler.js가 처리한다. 이 함수는 "light --default" 같은 문자열을 테마 이름 + 플래그로 쪼갠 뒤, --default면 :root 선택자에, --prefersdark면 @media (prefers-color-scheme: dark) 안에, 그 외에는 [data-theme="이름"] 선택자에 테마 변수를 꽂아 넣는다. "테마 전환에 자바스크립트가 필요 없는 이유"가 바로 여기 있다 — 전환은 CSS 선택자(data-theme 속성, 라디오 :checked)가 담당하고, 값 자체는 빌드 시점에 이미 CSS 안에 다 박혀 있다.

설계 원리 ⑤ — 인터랙션은 "새 자바스크립트"가 아니라 "브라우저가 원래 갖고 있던 기능"

모달(modal.css)을 열어보면 &:popover-open, &::backdrop, &:target, .modal-toggle:checked + & 같은 선택자가 나온다. 이것들은 daisyUI가 만든 게 아니라 HTML5/CSS 표준 자체의 기능이다.

즉 daisyUI의 "인터랙티브 컴포넌트"는 버튼 클릭 이벤트를 자바스크립트로 감지해 스타일을 바꾸는 것이 아니라, 애초에 그 상태를 표현할 수 있는 HTML 요소·CSS 의사 클래스를 골라 쓰고 그 상태에 대응하는 스타일만 CSS로 정의한 것이다. 그래서 daisyUI 패키지 안에는 런타임 자바스크립트 파일이 하나도 없다.

6기술 스택 · 의존성

daisyUI 패키지(packages/daisyui/package.json)를 열어 보면 놀라운 점이 있다. dependencies 항목도, peerDependencies 항목도 아예 없다. Tailwind CSS 위에서만 의미가 있는 플러그인인데도, npm 차원에서 "Tailwind CSS가 필요하다"고 명시하지 않는다. 대신 functions/plugin.js라는 파일에서 Tailwind의 플러그인 등록 방식(plugin.withOptions)을 자체적으로 아주 작게 재구현해 쓴다. 그만큼 런타임에서 실행되는 코드가 최소한