기본 버튼 그대로라면 Tailwind가 CSS를 만들었는지부터 확인하세요

AI에게 버튼을 예쁘게 만들어 달라고 했는데 화면에는 여전히 기본 버튼만 보일 때가 있습니다. 코드에는 className="px-4 py-2 bg-blue-600 text-white rounded-lg"가 들어가 있는데, 브라우저에서는 흰 배경에 얇은 테두리만 남습니다. 이때 초보자는 보통 컴포넌트를 다시 만들게 시킵니다. 하지만 Tailwind CSS 문제는 대부분 컴포넌트 전체보다 더 좁은 곳에서 멈춥니다.

오늘 목표는 Tailwind를 전부 배우는 것이 아닙니다. 전체 컴포넌트 재작성 전에 원인을 좁히는 것입니다. 먼저 개발자 도구의 Styles에서 해당 규칙이 존재하는지 봅니다. 규칙이 없으면 CSS import, 파일 감지, 동적 클래스를 확인하고, 규칙이 취소선이면 스타일 충돌을 확인합니다.

Tap to zoom

Tailwind 공식 문서는 프로젝트 파일에서 유틸리티 클래스 토큰을 찾고 필요한 CSS를 생성한다고 설명합니다. 현재 Next.js 설치 문서는 Tailwind를 app/globals.css에서 import하고 PostCSS 플러그인을 연결하는 흐름을 안내합니다. 그래서 className이 안 먹을 때 첫 질문은 "버튼 코드를 다시 짜야 하나"가 아닙니다. Tailwind가 그 클래스를 실제 CSS로 만들고 있는가입니다.

먼저 Tailwind CSS가 앱에 연결됐는지 봅니다

먼저 전역 CSS 파일을 엽니다. Vite나 최신 Tailwind 설정에서는 보통 CSS 파일에 아래 줄이 있어야 합니다.

@import "tailwindcss";

Next.js 프로젝트라면 app/globals.css 같은 전역 CSS 파일을 app/layout.tsx에서 import하는지도 봅니다.

import "./globals.css";

둘 중 하나가 빠져 있으면 className은 화면에 있어도 Tailwind 스타일이 들어오지 않습니다. 이때 AI에게 "버튼 다시 만들어줘"라고 말하면 문제 없는 컴포넌트만 계속 바뀔 수 있습니다. 먼저 이렇게 물어보는 편이 안전합니다.

Tailwind className은 있는데 스타일이 적용되지 않습니다.
전역 CSS import와 layout import가 맞는지 먼저 확인해 주세요.
컴포넌트 구조는 바꾸지 말고, 필요한 import 수정만 제안해 주세요.

초보자가 기억할 기준은 간단합니다. 클래스가 맞아도 CSS 파일이 앱에 연결되지 않으면 아무 일도 일어나지 않습니다.

그다음 Tailwind가 파일을 감지하는지 확인합니다

Tailwind는 소스 파일을 읽고 그 안의 클래스 토큰을 찾습니다. Tailwind 공식 문서도 소스 파일을 일반 텍스트처럼 스캔한다고 설명합니다. 그래서 버튼 파일이 Tailwind가 보는 범위 밖에 있으면 bg-blue-600 같은 클래스가 CSS로 만들어지지 않을 수 있습니다.

Tap to zoom

확인할 것은 세 가지입니다.

1. 문제가 있는 파일 경로: app/components/Button.tsx
2. Tailwind 설정 또는 CSS source 설정이 그 경로를 포함하는지
3. 파일이 node_modules, 빌드 산출물, 무시된 폴더 안에 있지 않은지

Tailwind v4 문서에서는 자동 감지가 기본이지만, 필요하면 CSS에서 @source로 소스 경로를 등록할 수 있다고 안내합니다. v3 프로젝트라면 tailwind.config.js의 content 경로를 확인해야 할 수 있습니다. 프로젝트마다 다르므로 버전을 추측하지 말고 package.json에서 tailwindcss 버전을 먼저 봅니다.

AI에게는 이렇게 좁혀서 물어봅니다.

이 프로젝트의 Tailwind 버전을 package.json에서 확인한 뒤,
현재 Button.tsx 파일이 Tailwind의 class scan 범위에 들어가는지 봐 주세요.
버전이 v3이면 content 경로를, v4이면 CSS의 source 설정 필요 여부를 확인해 주세요.

여기서 중요한 점은 설정 파일을 무작정 새로 만들지 않는 것입니다. 이미 설정이 있는데 AI가 새 설정을 덮어 쓰면 다른 화면이 깨질 수 있습니다.

클래스 이름이 완성된 문자열인지 봅니다

Tailwind는 JavaScript 코드를 실행해서 className을 이해하는 방식이 아닙니다. 공식 문서는 문자열 연결이나 보간으로 만든 동적 클래스 이름을 Tailwind가 이해할 수 없다고 설명합니다. 이 말은 초보자에게 아주 중요합니다.

아래 코드는 보기에는 자연스럽지만 위험합니다.

function Button({ color }: { color: string }) {
  return (
    <button className={`bg-${color}-600 text-white px-4 py-2 rounded-lg`}>
      저장
    </button>
  );
}

코드 실행 중에는 bg-blue-600이 될 수 있지만, Tailwind가 소스 파일을 스캔할 때는 완성된 bg-blue-600 문자열이 보이지 않습니다. 그래서 CSS가 만들어지지 않을 수 있습니다. 이때는 완성된 클래스 문자열을 미리 적어 둡니다.

const colorClass = {
  blue: "bg-blue-600 hover:bg-blue-700 text-white",
  red: "bg-red-600 hover:bg-red-700 text-white"
};

function Button({ color }: { color: "blue" | "red" }) {
  return (
    <button className={`${colorClass[color]} px-4 py-2 rounded-lg`}>
      저장
    </button>
  );
}

AI에게 고칠 때도 "동적 클래스 없애줘"라고만 쓰지 말고 이유를 같이 줍니다.

Tailwind가 감지할 수 있게 동적 className 조합을 완성된 문자열 매핑으로 바꿔 주세요.
예: bg-${color}-600 형태를 쓰지 말고 blue, red 같은 값별로 완성된 클래스를 적어 주세요.
기존 버튼 props와 화면 구조는 유지해 주세요.

이 요청의 핵심은 AI가 색상 시스템을 새로 만들지 못하게 막는 것입니다. 지금 필요한 것은 디자인 개편이 아니라 Tailwind가 감지할 수 있는 문자열입니다.

클래스가 있는데도 안 바뀌면 충돌과 상태 변형을 나눠 봅니다

bg-blue-600은 먹는데 hover:bg-blue-700만 안 되는 경우도 있습니다. Tailwind의 hover:, focus: 같은 변형은 조건이 맞을 때 적용됩니다. 기본 상태가 아니라 hover 상태에서만 바뀌는 클래스라면, 마우스를 올렸을 때 확인해야 합니다.

반대로 bg-blue-600을 넣었는데도 다른 배경색이 계속 보이면 스타일 충돌일 수 있습니다. 기존 CSS, 인라인 스타일, 컴포넌트 라이브러리 스타일이 더 강하게 적용될 수 있습니다. Tailwind 문서에는 필요할 때 ! modifier나 important flag를 쓰는 방법도 있지만, 초보자 단계에서는 먼저 개발자 도구에서 실제 적용된 CSS를 봐야 합니다.

브라우저 개발자 도구에서 버튼 요소 선택
→ Styles 패널에서 bg-blue-600 규칙이 있는지 확인
→ 취소선이 있으면 어떤 CSS가 이기고 있는지 확인
→ 규칙 자체가 없으면 Tailwind 생성 또는 감지 문제로 돌아가기

아래처럼 나눠 보면 빨라집니다.

이 표에서 하나를 고른 뒤 AI에게 넘기면 답변이 짧아집니다. 증상을 하나로 분류한 뒤 질문해야 AI가 고칠 범위도 하나로 줄어듭니다.

설정을 바꿨다면 서버 재시작과 캐시를 확인합니다

설정 파일, CSS import, source 경로를 바꿨다면 개발 서버를 다시 시작합니다. Tailwind 설치 문서도 설정 후 build process를 실행하는 흐름을 안내합니다. 실제 작업에서는 이미 npm run dev가 켜져 있어도 설정 변경이 즉시 반영되지 않는 경우가 있습니다.

Ctrl + C
npm run dev

브라우저도 강력 새로고침을 합니다.

Windows: Ctrl + F5
Mac: Cmd + Shift + R

여기까지 했는데도 안 바뀌면 그때 AI에게 5칸 정보를 줍니다.

Tap to zoom

Tailwind className이 적용되지 않습니다.

문제 클래스:
기대 스타일:
실제 화면:
수정한 파일:
마지막으로 실행한 명령:

확인 요청:
1. 전역 CSS import 문제가 있는지 봐 주세요.
2. Tailwind가 이 파일을 감지하지 못하는지 봐 주세요.
3. 동적 className 조합이나 오타가 있는지 봐 주세요.
4. 전체 컴포넌트를 다시 만들지 말고 최소 수정만 제안해 주세요.

이 질문은 AI에게 더 많은 일을 시키는 문장이 아닙니다. AI가 건드릴 범위를 줄이는 문장입니다. 비슷한 방식으로 실행 결과에서 첫 단서를 좁히려면 React 흰 화면에서 Console로 원인 찾기와 TypeScript 빨간 줄에서 첫 오류만 복사하는 법도 이어서 볼 수 있습니다.

오늘은 className보다 연결 경로를 먼저 봅니다

Tailwind className이 안 먹을 때는 버튼 코드를 다시 쓰기 전에 다섯 가지를 확인합니다.

1. 전역 CSS에 Tailwind import가 있는가
2. 그 CSS가 앱에 연결되어 있는가
3. 문제가 있는 파일을 Tailwind가 감지하는가
4. 클래스 이름이 완성된 문자열로 존재하는가
5. 설정 변경 뒤 개발 서버를 다시 시작했는가

이 다섯 줄을 채운 뒤 AI에게 물어보면 답변이 짧아집니다. 오늘 고칠 것은 "디자인 전체"가 아니라 className이 CSS로 이어지는 경로입니다. 스타일이 안 먹을 때 첫 행동은 재작성 요청이 아니라 연결 경로 확인입니다.

공식 확인 링크

• Tailwind CSS Docs, Detecting classes in source files: https://tailwindcss.com/docs/detecting-classes-in-source-files
• Tailwind CSS Docs, Install Tailwind CSS with Next.js
• Tailwind CSS Docs, Styling with utility classes: https://tailwindcss.com/docs/styling-with-utility-classes
• Tailwind CSS Docs, Hover, focus, and other states: https://tailwindcss.com/docs/hover-focus-and-other-states

이 글은 AI 코딩과 개발 학습의 일반 정보 제공 목적입니다. 도구, 모델, 커리큘럼, 요금은 버전과 시점에 따라 달라질 수 있으므로 실습이나 도입 전 공식 문서와 최신 릴리스 노트를 확인하세요.