Tailwind CSS
토큰을 `@theme` 로 이어 붙여 `bg-bg` · `p-4` 가 우리 값을 쓰게 만듭니다.
@coldsurfers/tailwind4-theme 는 토큰을 Tailwind v4 의 @theme 로 옮긴 CSS 한 장입니다.
JS 는 없고, Tailwind 를 안 쓰는 소비자는 설치를 안 해 0 바이트입니다 — DS 의 exports 에
올리지 않고 패키지를 가른 이유입니다.
설치
@coldsurfers 스코프는 GitHub Packages 에 있습니다. 레지스트리 설정은 시작하기 와 같습니다.
pnpm add -D @coldsurfers/tailwind4-themetailwindcss@4 와 @coldsurfers/surf-ui 이 peer 입니다. 값의 정본은 DS 쪽이고 이
패키지는 그 값을 var() 로 참조만 하므로, 변수 시트를 반드시 같이 물어야 합니다.
배선
Tailwind 로 화면을 짜면서 색 · 간격만 우리 값으로 맞출 때입니다.
@import "tailwindcss";
@import "@coldsurfers/surf-ui/tokens.css";
@import "@coldsurfers/tailwind4-theme";tokens.css 는 무레이어 :root 한 장입니다 — 리셋도 컴포넌트 CSS 도 들어 있지 않습니다.
레이어 밖이라 캐스케이드 다툼도 없고, 그래서 이 조합은 import 순서를 타지 않습니다.
@layer …; 선언을 손으로 적지 않습니다. styles.css 의 첫 줄이 순서 계약을
직접 발행합니다 — 적어야 할 건 import 순서 하나뿐입니다.
무엇이 열리는가
@theme 는 Tailwind 네임스페이스에 이름을 얹을 뿐입니다. 값은 여기 없습니다 — 아래 표의
"정본" 이 값을 갖습니다.
| 네임스페이스 | 유틸 | 정본 |
|---|---|---|
--color-* | bg-bg · text-heading · border-border | 색 |
--color-cover-* | bg-cover-forest · text-cover-plum | 색 |
--color-paper-* | bg-paper-warm | 색 |
--radius-* | rounded-lg · rounded-full | 색 |
--spacing-* | p-4 · gap-2.5 · mt-14 | 여백 |
--text-* | text-sm · text-3xs | 타이포 |
--text-{그룹}-{크기} | text-display-md · text-eyebrow-sm | 타이포 |
--leading-* · --font-weight-* | leading-relaxed · font-regular | 타이포 |
--font-* | font-sans · font-serif · font-mono | 타이포 |
--breakpoint-* | tablet:p-8 · desktop:p-10 | 계약과 레이어 |
<article className="rounded-xl border border-border bg-surface p-6">
<p className="text-eyebrow-md font-mono uppercase text-muted">now playing</p>
<h2 className="text-display-md font-serif text-heading">Slowdive</h2>
<p className="text-sm leading-relaxed text-body">Souvlaki, 1993</p>
</article>uppercase 를 직접 적은 게 실수가 아닙니다 — 아래 "안 넘어오는 것" 을 보세요.
좌표계가 둘이 됩니다
Tailwind 기본 스케일은 지워지지 않습니다. 우리 이름이 덮어쓴 자리만 바뀌고 나머지는 그대로 살아 있어서, 같은 뜻의 이름이 둘씩 생깁니다.
sm:·md:·lg:가 그대로입니다.tablet:(768px)과md:(48rem)은 값이 같지만 이름이 둘입니다 — 팀에서 하나로 정해 씁니다- 스케일 밖 값도 조용히 컴파일됩니다.
p-9는calc(var(--spacing) * 9)로 떨어집니다 — 4px 격자를 벗어난 걸 Tailwind 가 막아주지 않습니다 font-bold(700)는 Tailwind 기본값입니다. 토큰의 무게는light·regular·medium·semibold넷뿐입니다
안 넘어오는 것
textTransform. eyebrow 는 대문자 변환이 스타일의 일부지만--text-*네임스페이스로는 크기 · 행간 · 자간까지만 표현됩니다.uppercase는 직접 적습니다sprinkles·vars· 컴포넌트 recipe. JS 쪽 계약이라 CSS 한 장에 담기지 않습니다..css.ts를 직접 쓰는 소비자는 계약과 레이어로 갑니다
이름에 4 가 붙은 이유
Tailwind major 마다 @theme 규약이 갈립니다. 이름에 major 를 박아 두면 v5 용을 나란히 낼 수
있습니다 — 기존 소비자를 깨지 않고. (선례: @seed-design/tailwind4-theme)