[Tailwind] Tailwind v4.0 마이그레이션 ( 다크모드 , 색상 재정의, transition-property 설정 등 ) - 번역글

현재 테일윈드 4가 릴리스된 지 일주일이 된 시점에서 

v4.0으로 자동 업그레이드가 되지 않을 때, 수동 구성에 대한 이야기를 다룬 블로그는

거의 없었습니다. 

 

그중 한 블로그를 발견하여 해당 내용을 번역합니다.

https://timomeh.de/posts/upgrading-to-tailwind-v4

Upgrading to Tailwind v4.0 | timomeh.de

 

 

 

이 글을 쓰는 시점으로부터 3일 전인 1월 22일, 몇 가지 주요 변경 사항이 포함된 Tailwind v4.0이 출시되었습니다. 

저는 오늘 업그레이드를 결정했는데, 솔직히 말해서 업그레이드 경로가 복잡했습니다!

Tailwind는 자동 업그레이드 도구를 제공하는데, 꽤 괜찮게 작동했습니다. 주요 변경 사항 중 하나는 기존의 자바스크립트 기반 구성 대신 새로운 CSS 우선 구성이 추가되었다는 것입니다. 안타깝게도 업그레이드 도구는 구성을 마이그레이션할 수 없다며 구성을 마이그레이션하지 않았습니다. 타이포그래피 플러그인 때문인지, 아니면 다른 이유 때문인지 모르겠지만 알려주지 않았습니다.

 

번역주: 기존의 tailwind.config.ts 혹은 js 파일이 삭제되고 하나의 css 파일에 선언하도록 변경 되었습니다.

/* 새 구성 파일은 다음과 같아야 합니다 */
@import"tailwindcss";
@theme {
  --font-display: "Satoshi", "sans-serif";
  --breakpoint-3xl: 1920px;
  --color-avocado-100: oklch(0.99 0 0);
  --color-avocado-200: oklch(0.980.04113.22);.
  --color-avocado-300: oklch(0.940.11115.03);.
  --color-avocado-400: oklch(0.920.19114.08);.
  --color-avocado-500: oklch(0.840.18117.33);.
  --color-avocado-600: oklch(0.530.12118.34);.
  --ease-fluid: cubic-bezier(0.3, 0, 0, 1);
  --ease-snappy: cubic-bezier(0.2,0,0,1);
}

/* 업그레이드 도구가 수행한 작업입니다 */
@config "../../tailwind.config.js";

 

하지만 새로운 CSS 기반 구성은 Tailwind 4의 큰 부분이기 때문에 사용하고 싶었습니다. 업그레이드 도구는 호환성 모드에서 이전 구성 을 로드하기만 했습니다.

그래서 수동으로 마이그레이션해야 했지만 업그레이드 가이드에는 이전 JavaScript 기반 구성을 마이그레이션하는 방법이 제대로 설명되어 있지 않았습니다. 그래서 제가 직접 알아내야 했는데, 일부는 분명하고 쉽게 찾을 수 있었지만 다른 것들은 쉽지 않았습니다.

 

다크 모드 변형

 

저는 여러 가지 다크 모드 변형을 사용합니다. 이전 구성에서는 이렇게 표시되었습니다:

module.exports = {
  darkMode: [
    'variant',
    [
      '@media (prefers-color-scheme: dark) { &:not(html[data-theme=light] *, [data-theme=light]) }',
      '&:is([data-theme=dark] *, html[data-theme=dark])',
    ],
  ]
}

 

dark: 변형은 이제 @custom-variant 지시어로 구성할 수 있습니다. 암흑 모드 문서에는 단일 규칙으로 재정의하는 방법의 예가 있지만 이전 구성에서처럼 여러 규칙과 함께 사용하려면 어떻게 해야 하나요? 문서가 축약 표현을 사용하고 긴 구문으로 여러 규칙을 사용할 수 있다는 것을 알아내는 데 시간이 좀 걸렸습니다:

 

/* 문서의 예시, 축약 표현 사용 */
@custom-variant dark (&:where([data-theme=dark], [data-theme=dark] *));

/* 멀티 셀렉터를 사용하는 방식(번역 원본 버전) */
@custom-variant dark {
  &:where([data-theme='dark'] *, [data-theme='dark']) {
    @slot;
  }

  @media (prefers-color-scheme: dark) {
    &:not(html[data-theme='light'] *, [data-theme='light']) {
      @slot;
    }
  }
}

 

저 같은 경우는 클릭 시, dark 클래스를 추가하게 해결하여 다른 방식의 설정을 했습니다

 

/* 추가로 수정한 번역자 작동된 방식*/
@custom-variant dark (
  /* 케이스 1: .dark 클래스를 사용할 때 */
  &:where(.dark, .dark *), 
  /* 케이스 2: 시스템 다크모드 + data-theme="dark" 속성 사용할 때 */
  &:where(:not(.light):is(:root[data-theme="dark"] *, :root[data-theme="dark"]))
);

 

// app.js

let checkBox = document.querySelector("input[type='checkbox']");

checkBox.addEventListener("click", () => {
  document.body.classList.toggle("dark");
});

 

회색 색상표 재정의하기

테일윈드의 색상표에는 'Slate'라는 쿨톤의 파란색 회색부터 'Stone'이라는 웜톤의 갈색 회색까지 5가지 회색 계열이 있습니다. 보통 이 회색 중 하나만 사용합니다. 저는 "Stone"을 사용하고 gray로 별칭을 지정했습니다.

const colors = require('tailwindcss/colors')

module.exports = {
  theme: {
    extends: {
      colors: {
        gray: colors.stone,
      }
    }
  }

새로운 CSS 기반 구성에서 이 앨리어싱은 어떻게 작동하나요? 모든 회색 음영을 재정의해야 합니다.

 

@theme{
  --color-gray-50: var(--color-stone-50);
  --color-gray-100: var(--color-stone-100);
  --color-gray-200: var(--color-stone-200);
  --color-gray-300: var(--color-stone-300);
  --color-gray-400: var(--color-stone-400);
  --color-gray-500: var(--color-stone-500);
  --color-gray-600: var(--color-stone-600);
  --color-gray-700: var(--color-stone-700);
  --color-gray-800: var(--color-stone-800);
  --color-gray-900: var(--color-stone-900);
  --color-gray-950: var(--color-stone-950);
}

 

 

사용자 정의 배경 이미지

 

사용자 정의 배경 이미지(그라데이션이 아닌 이미지 파일용)가 있는 유틸리티 클래스를 만들려면 다른 유틸리티처럼 테마를 확장하면 됩니다:

module.exports = {
  theme: {
    extends: {
      backgroundImage: {
        'dark-grain':"url(dark-grain-pattern.svg)",
        'light-grain':"url(light-grain-pattern.svg)"
      }
    }
  }
}

 

customize background-image에 대한 새 문서는 그라데이션만 언급하고 이미지에 대해서는 언급하지 않습니다. 그래서 예전 작동 방식을 기준으로 어떻게 작동해야 하는지 추측했지만 잘못 추측했습니다. 또한 테마 내에서 확장할 수 있는 방법

이 있는지 알아낼 수 없어서 지금은 단순히 유틸리티를 사용하고 있습니다.

 

@theme {
  /* This does not work! */
  --bg-dark-grain: url("dark-grain-pattern.svg"); 
  --bg-light-grain: url("light-grain-pattern.svg"); 
}

/* This works */
@utility bg-dark-grain {
  background-image: url("dark-grain-pattern.svg"); 
}

@utility bg-light-grain {
  background-image: url("light-grain-pattern.svg"); 
}

 

번역주) 현재 외부 url ('https:/address.jpg')을 받아 보여주는 이미지는 백그라운드에서 기존대로 정상작동을  확인했습니다.

 

임의의 transition-property 값 사용

트랜스폼 및 불투명도 속성만 전환하고 싶은 곳이 있는데, 이 전환을 적용하기 위해 transition-[transform,opacity]를 간단히 사용했죠. 하지만 v4로 업그레이드한 후에는 이러한 전환이 깨졌습니다! 업그레이드 가이드에서 아무것도 찾을 수 없었고, 전환 속성 문서도 언뜻 보기에는 달라진 점이 없어 보였습니다.

하지만 transition-transform가 이제 4개의 속성, 즉 일반적인 transform와 3개의 새로운 사용자 정의 속성 translate, scale, rotate를 사용하는 것을 볼 때까지만 해도 말이죠. 이는 획기적인 변경 사항으로 언급되지 않았으며 업그레이드 도구에서도 이를 포착하지 못했습니다.

이제 해당 속성도 전환해야 합니다:

 

<!-- v3 -->
<div class="transition-[transform,opacity]" />

<!-- v4 -->
<div class="transition-[transform,translate,scale,rotate,opacity]" />

물론 이러한 속성 중 일부만 전환해야 하는 경우에는 모두를 지정할 필요는 없습니다.

 

 

Tailwind 타이포그래피 플러그인 사용

 

Tailwind의 타이포그래피 플러그인는 훌륭하며 항상 사용해야 한다고 생각합니다(또는 좋은 표준 텍스트 렌더링을 위한 대안이 있다면 어떤 것이든). 구성을 수동으로 마이그레이션할 때 마침내 타이포그래피 구성에 도달했고 이를 새로운 CSS 기반 구성으로 마이그레이션하는 방법이 궁금했습니다. 플러그인의 설명서에는 새 구성에 대한 언급이 없었고 업그레이드 가이드에도 아무 언급이 없었습니다. 그러던 중 함수 및 지시어 문서에서 메모를 발견했습니다:

 

@plugin "@tailwindcss/typography";

 

 

그래서 추가로 위 @pulgin 구문을 추가해야 했습니다.

레거시 JavaScript 기반 플러그인을 로드하려면 @plugin 지시문을 사용합니다:

@config './typography.config.js';

@theme {
  /* ... */
}

 

 

// typography.config.js

/** @type {import('tailwindcss').Config} */
module.exports = {
  plugins: [require('@tailwindcss/typography')],
  theme: {
    extend: {
      typography: () => ({
        DEFAULT: {
          css: {
            color: '#333',
            a: {
              color: '#3182ce',
              '&:hover': {
                color: '#2c5282',
              }
            }
            // etc

 

 

최종 의견

업그레이드 과정은 다소 험난했지만, 저는 Tailwind의 전반적인 방향 전환이 마음에 듭니다. 이제 플랫폼의 새로운 기능을 지원할 뿐만 아니라 이를 수용하여 사용자에게 보여줍니다. 단순한 유틸리티 클래스 모음이라기보다는 플랫폼의 확장에 가깝습니다.