커스텀 스타일 추가하기

커스텀 스타일 추가하기

프레임워크를 쓰다 보면 "이건 프레임워크가 해 주지 않는데?" 하는 순간이 꼭 찾아와요. Tailwind는 처음부터 확장 가능하게 설계돼서, 커스텀 스타일을 넣는 방법이 잘 갖춰져 있어요. 디자인 토큰(테마)을 바꾸거나, 테마 밖으로 벗어나야 할 때 임의 값을 쓰거나, 필요한 곳에 직접 CSS·유틸리티·변형자를 더하는 방식까지 하나씩 살펴볼게요.

출처: Adding custom styles — Tailwind CSS 공식문서

테마 커스터마이징

색 팔레트·간격·타이포그래피·브레이크포인트를 바꾸고 싶다면 CSS 안에서 @theme 디렉티브로 원하는 변수를 정의하면 돼요.

@import "tailwindcss";

@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 120rem;
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-500: oklch(0.84 0.18 117.33);
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  /* ... */
}

이렇게 정의한 변수는 곧바로 bg-avocado-500 같은 유틸리티로 이어져요. 테마 변수에 대한 자세한 내용은 Theme 변수 문서에서 다룰게요.

임의 값으로 테마 밖으로 벗어나기

테마 토큰만으로 픽셀 단위가 안 맞는 경우가 있어요. 예를 들어 top: 117px이 딱 필요한 상황이라면 대괄호 문법으로 그 자리에서 클래스를 생성할 수 있어요.

<div class="top-[117px] lg:top-[344px]"></div>

인라인 스타일과 비슷해 보이지만 결정적으로 다른 점은, hover 같은 상태 변형자나 lg 같은 반응형 변형자와 함께 쓸 수 있다는 거예요. 색·글자 크기·가상 요소의 content까지 전부 가능해요.

<div class="bg-[#bada55] text-[22px] before:content-['Festivus']"></div>

CSS 변수를 값으로 참조할 땐 fill-(--my-brand-color)처럼 쓰면 fill-[var(--my-brand-color)]의 축약형이 돼요.

임의 프로퍼티와 임의 변형자

Tailwind에 없는 CSS 프로퍼티가 필요하면 대괄호 안에 프로퍼티 자체를 넣을 수 있어요. [mask-type:luminance] hover:[mask-type:alpha]처럼 변형자와 함께 쓰면 조건에 따라 다른 값도 가능해요. CSS 변수도 마찬가지로 [--scroll-offset:56px] lg:[--scroll-offset:44px]처럼 상황별로 바꿀 수 있죠.

임의 변형자는 임의 값의 변형자 버전이에요. 내장 의사 클래스 변형자(hover:)나 반응형 변형자(md:) 대신 대괄호 안에 셀렉터를 직접 넣을 수 있어요. 예를 들면 이렇게요.

<li class="lg:[&:nth-child(-n+3)]:hover:underline">{item}</li>

공백과 모호성 처리

임의 값에 공백이 필요하면 밑줄(_)을 쓰면 빌드 타임에 공백으로 바뀌어요. grid-cols-[1fr_500px_2fr] 같은 식이죠. 다만 URL처럼 밑줄이 의미 있는 경우(bg-[url('/what_a_rush.png')])엔 밑줄을 그대로 유지해요. 정말 공백 대신 밑줄을 써야 한다면 백슬래시로 이스케이프해서 before:content-['hello\_world']처럼 쓰면 되고, JSX에선 String.raw를 쓰는 걸 권장해요.

text-lg(글자 크기)와 text-black(색)처럼 같은 네임스페이스를 공유하지만 다른 프로퍼티를 가리키는 유틸리티도 있어요. 임의 값은 대개 값의 형태로 알아서 판단해요. text-[22px]는 글자 크기, text-[#bada55]는 색으로 잡히죠. 그래도 모호할 땐 값 앞에 CSS 데이터 타입을 힌트로 붙일 수 있어요. text-(length:--my-var)는 글자 크기, text-(color:--my-var)는 색으로 해석돼요.

커스텀 CSS 작성하기

Tailwind가 대부분의 스타일을 맡아도, 평범한 CSS를 직접 쓰는 걸 막는 건 아니에요. @import "tailwindcss"; 아래에 그냥 규칙을 쓰면 됩니다.

  • 기본 스타일(base) — 페이지 기본값(텍스트 색·배경·폰트)은 html이나 body 요소에 클래스를 넣어 마크업 안에서 관리할 수 있어요. 특정 요소에 기본 스타일을 넣고 싶다면 @layer base를 써서 Tailwind의 base 레이어에 추가해요.
@layer base {
  h1 { font-size: var(--text-2xl); }
  h2 { font-size: var(--text-xl); }
}
  • 컴포넌트 클래스 — card·btn 같은 클래스를 만들고 싶다면 @layer components를 씁니다. 이 레이어에 정의해 두면 나중에 유틸리티로 덮어쓰는 게 가능해요. 예를 들어 카드 모양을 정의해 두고 rounded-none으로 모서리를 바꿀 수 있죠. 서드파티 컴포넌트의 커스텀 스타일도 여기 넣기 좋아요.
@layer components {
  .card {
    background-color: var(--color-white);
    border-radius: var(--radius-lg);
    padding: --spacing(6);
    box-shadow: var(--shadow-xl);
  }
}
  • 변형자 사용 — 커스텀 CSS 안에서 @variant 디렉티브로 Tailwind 변형자를 적용할 수 있어요. @variant dark { ... }로 다크 모드 분기를, @variant hover:focus처럼 쌓거나 @variant hover, focus처럼 여러 화면에 같은 스타일을 줄 수도 있어요.
.my-element {
  background: white;
  @variant dark {
    background: black;
  }
}

커스텀 유틸리티 추가하기

단순 유틸리티

Tailwind가 기본 제공하지 않는 CSS 기능이 필요할 때 @utility 디렉티브로 직접 유틸리티를 추가할 수 있어요. 추가한 유틸리티는 내장 유틸리티와 함께 자동으로 utilities 레이어에 들어가고, hover:content-auto처럼 변형자와도 함께 쓸 수 있어요.

@utility content-auto {
  content-visibility: auto;
}

복잡한 유틸리티와 기능성 유틸리티

클래스 하나로 끝나지 않는 복잡한 유틸리티는 중첩(nesting)으로 정의할 수 있어요. 예를 들어 스크롤바를 숨기는 @utility scrollbar-hidden { &::-webkit-scrollbar { display: none; } } 같은 형태죠.

인자를 받는 기능성 유틸리티도 만들 수 있어요. @utility tab-* { tab-size: --value(--tab-size-*); } 형태로 --value() 함수로 값을 해석해요.

  • 테마 값 매칭 — tab-size: --value(--tab-size-*)로 두면 --tab-size-2, --tab-size-github 같은 테마 키와 매칭돼 tab-2, tab-github 같은 클래스가 생겨요.
  • Bare 값 — --value(integer)처럼 타입으로 값을 검증해 tab-1, tab-76을 허용할 수 있어요. 사용 가능한 타입은 number, integer, ratio, percentage예요.
  • 기본값 — --default()로 값을 명시하지 않았을 때의 기본값을 줄 수 있어요. tab-size: --value(integer, --default(4))면 tab 하나만 써도 4로 해석돼요.
  • 음수·수정자·분수 — 음수 유틸리티는 -inset-*처럼 양수와 따로 등록하고, 수정자는 --modifier()로, 분수는 ratio 타입으로 처리해요. 예를 들어 aspect-*는 --value(--aspect-ratio-*, ratio, [ratio])로 정의돼 aspect-square, aspect-3/4 같은 클래스를 만들어요.

커스텀 변형자 추가하기

내장 변형자 외에 나만의 변형자가 필요하면 @custom-variant 디렉티브로 추가할 수 있어요. 예를 들어 data-theme="midnight" 요소 아래에서만 동작하는 theme-midnight: 변형자를 만들 수 있어요.

@custom-variant theme-midnight (&:where([data-theme="midnight"] *));

이제 theme-midnight:bg-black처럼 쓸 수 있어요. 규칙이 여러 개면 중첩해서 정의할 수도 있고요.

더 알아보기 (Learn more)