Tailwind CSS 인터랙티브 가이드: iframe 격리와 템플릿 렌더링
Tailwind v4로 올리고 나니 문서가 필요했다
FullStackFamily를 Tailwind CSS v3에서 v4로 올렸다. 클래스명이 바뀐 것도 있고(shadow-sm → shadow-xs), 설정 방식이 아예 달라진 것도 있다(tailwind.config.ts → CSS 안에서 @theme {}). 공식 문서를 보면 되긴 하는데, 두 가지가 불편했다.
하나는 수업. 학생들에게 "이 클래스 쓰면 이렇게 됩니다"를 보여주려면, 공식 문서를 띄우고 스크롤을 내리고 예제를 찾아야 한다. 클래스 하나 고르면 바로 결과가 보이는 페이지가 있으면 좋겠다 싶었다.
다른 하나는 AI 협업. Claude에게 "flex로 가운데 정렬해줘"라고 하면 대부분 잘 해주는데, v4에서 바뀐 클래스를 쓰거나 @theme 설정을 빠뜨릴 때가 있다. "v4 문법으로 해줘"를 매번 붙이기보다, 프롬프트 자체를 생성해주는 도구가 있으면 편하겠다 싶어서 만들었다.
화면 구성
UI/UX 가이드(/uiux)와 같은 3패널 구조다.
┌──────────────┬──────────────────────────┬──────────────────┐ │ │ │ │ │ 사이드바 │ Preview (iframe) │ 유틸리티 목록 │ │ (272px) │ + 코드 에디터 │ 옵션 컨트롤 │ │ │ │ 바이브 프롬프트 │ │ · 22 카테고리 │ 실시간 렌더링 │ │ │ · 검색 │ 수정 → 즉시 반영 │ (384px) │ │ │ │ │ └──────────────┴──────────────────────────┴──────────────────┘
왼쪽에서 카테고리를 열고 예제를 고르면, 가운데에 렌더링 결과가 나온다. 아래쪽 코드 에디터에서 HTML을 수정하면 결과가 바로 바뀌고, 오른쪽에서는 옵션을 조절하거나 Claude용 프롬프트를 복사할 수 있다.
22개 카테고리, 200개 넘는 예제
Tailwind CSS v4의 주요 유틸리티를 거의 다 넣었다.
┌────────────────────┬────────────────────┬───────────────────┐ │ v4 Fundamentals │ Layout (15개) │ Flexbox & Grid │ │ Spacing │ Sizing │ Typography (13개) │ │ Backgrounds │ Borders │ Effects │ │ Filters │ Tables │ Transitions │ │ Transforms │ Interactivity │ SVG │ │ Accessibility │ Responsive Design │ Dark Mode │ │ States & Variants │ Colors │ Customization │ │ Container Queries │ │ │ └────────────────────┴────────────────────┴───────────────────┘
예제 하나의 구조를 보면 이렇다.
{ id: 'layout.display', name: 'Display', utilities: [ { className: 'block', cssValue: 'display: block', tip: '...' }, { className: 'flex', cssValue: 'display: flex' }, // ... ], templateId: 'sibling-compare', // 8가지 중 하나 options: [...], // 조절 가능한 값 vibePromptTemplate: '...', // Mustache 템플릿 codeTemplate: '...', // HTML 코드 템플릿 }
데이터 파일만 약 6,000줄이다. 만드는 데 시간이 꽤 걸렸지만, 한번 만들어두니 검색과 참조가 편하다.
왜 iframe인가: CSS 격리 문제
가이드를 만들면서 가장 먼저 부딪힌 게 CSS 격리다.
FullStackFamily 자체가 Tailwind를 쓴다. 가이드 페이지도 Tailwind로 만들었다. 그런데 가이드 안에서 보여주는 예제도 Tailwind다. 같은 페이지에 Tailwind가 두 겹으로 올라가는 상황.
예를 들어 예제에서 bg-red-500을 보여주고 싶은데, 페이지 자체의 Tailwind 스타일이 간섭한다. reset 스타일이 예제의 마진을 없애거나, 페이지의 font-family 설정이 예제에 스며들거나.
문제 상황: 페이지 Tailwind (v4, 커스텀 테마) └── 예제 Tailwind (v4, 기본 테마) → 클래스 충돌, 테마 충돌, reset 충돌
해결책은 iframe이다. 예제를 iframe 안에서 렌더링하면 CSS가 완전히 격리된다. iframe 안에서는 Tailwind CDN(@tailwindcss/browser@4)을 별도로 로드한다.
┌──────────────────────────────────────┐ │ FullStackFamily 페이지 │ │ (Tailwind v4 + 커스텀 테마) │ │ │ │ ┌────────────────────────────────┐ │ │ │ iframe (srcdoc) │ │ │ │ Tailwind Browser CDN v4 │ │ │ │ 기본 테마, 독립된 CSS 컨텍스트 │ │ │ │ │ │ │ │ <div class="bg-red-500"> │ │ │ │ 예제 내용 │ │ │ │ </div> │ │ │ └────────────────────────────────┘ │ │ │ └──────────────────────────────────────┘
iframe 높이는 ResizeObserver로 내용에 맞게 자동 조절한다. 고정 높이를 주면 예제마다 스크롤바가 생기거나 빈 공간이 남으니까.
8가지 렌더링 템플릿
Tailwind 클래스 종류에 따라 보여주는 방식이 달라야 한다. font-size와 display와 색상 팔레트를 같은 레이아웃으로 보여줄 수는 없으니까. 그래서 8가지 템플릿을 만들었다.
┌──────────────────────┬───────────────────────────────────┐ │ 템플릿 │ 용도 │ ├──────────────────────┼───────────────────────────────────┤ │ SingleBox │ 하나의 박스에 클래스 적용 │ │ ParentChildren │ 부모-자식 관계 (flex, grid 방향) │ │ SiblingCompare │ 여러 요소 비교 (block vs inline) │ │ TextDemo │ 텍스트 스타일 (폰트, 줄간격) │ │ ColorPalette │ 색상 50~950 단계 전체 표시 │ │ BeforeAfter │ v3 → v4 변경점 비교 │ │ Interactive │ hover, focus 같은 상태 체험 │ │ TableDemo │ 테이블 레이아웃 │ └──────────────────────┴───────────────────────────────────┘
예제의 templateId에 따라 TemplateRenderer가 맞는 템플릿을 골라 렌더링한다. 예제 데이터를 추가할 때 templateId만 지정하면 레이아웃은 템플릿이 알아서 처리해준다.
BeforeAfter 템플릿은 v4 마이그레이션 학습용이다. 왼쪽에 v3, 오른쪽에 v4 코드를 나란히 놓아서 뭐가 바뀌었는지 한눈에 비교할 수 있다.
라이브 코드 에디터
Preview 아래에 코드 에디터가 있다. HTML을 직접 수정하면 iframe이 즉시 업데이트된다.
옵션 변경 또는 코드 직접 수정 │ ▼ Mustache 템플릿 처리 (codeTemplate + 옵션 값) │ ▼ HTML 문자열 생성 │ ▼ iframe srcdoc 업데이트 │ ▼ ResizeObserver → iframe 높이 재계산 │ ▼ 화면 갱신 (스크롤바 없이)
코드 에디터에서 수정한 내용은 초기화 버튼으로 원본으로 되돌릴 수 있다. "이 클래스 대신 저걸 쓰면 어떻게 되지?" 같은 실험을 마음껏 해볼 수 있다.
URL 기반 상태 관리
예제를 선택하면 URL이 바뀐다.
/tailwindcss?item=layout.display&util=flex&tab=utilities
이게 왜 중요하냐면, 새로고침해도 같은 화면이 나오고, 수업 중에 "이 URL 열어보세요"로 학생한테 같은 예제를 보여줄 수 있고, 브라우저 뒤로가기도 된다.
useSearchParams로 쿼리 파라미터를 읽고, 예제 선택 시 router.replace로 URL을 갱신한다. push 대신 replace를 쓰는 이유는, 예제를 하나하나 고를 때마다 히스토리가 쌓이면 뒤로가기가 무의미해지기 때문이다.
바이브 프롬프트: AI에게 v4 문법을 알려주는 장치
오른쪽 패널의 "바이브 프롬프트" 탭을 누르면, 현재 선택된 예제와 옵션에 맞는 Claude용 프롬프트가 자동으로 만들어진다.
Display 예제에서 flex를 선택하면 이런 프롬프트가 나온다.
Tailwind CSS의 Display (display) 유틸리티를 사용해주세요. 클래스는 "flex"을 적용해주세요. [공통 규칙] - Tailwind CSS v4 문법을 사용하세요 (bg-linear-to-r, shadow-xs 등) - CSS-first 설정: @import "tailwindcss" + @theme {} 방식 - 반응형은 모바일 우선(mobile-first) 접근법을 따르세요
이걸 복사해서 Claude에게 넘기면, v3 클래스명을 쓰거나 tailwind.config.ts 방식으로 설정하는 실수를 줄일 수 있다. v4 문법 규칙을 프롬프트에 미리 넣어두는 셈이다.
검색은 한글로도 된다
사이드바 검색은 영문 클래스명뿐 아니라 한글 키워드도 된다. 각 예제에 searchKeywords 배열을 넣어뒀다.
{ name: 'Font Size', searchKeywords: ['글자 크기', '폰트 크기', 'text size', 'font-size'], // ... }
"글자 크기"라고 검색하면 Font Size 예제가 나온다. 검색 대상은 예제명, 설명, CSS 속성, 카테고리, 키워드, 유틸리티 클래스명까지 포함한다. "그림자"로 Box Shadow가, "간격"으로 Spacing 관련 예제들이 나온다.
사용법
- https://www.fullstackfamily.com/tailwindcss 접속 (PC 1024px 이상)
- 왼쪽 사이드바에서 카테고리 열기 또는 검색
- 예제 선택 → 가운데에서 실시간 결과 확인
- 오른쪽 옵션으로 값 조절 → 프리뷰 즉시 반영
- 코드 에디터에서 HTML 직접 수정해서 실험
- 바이브 프롬프트 복사 → Claude에게 전달
마무리
공식 문서를 대체하려는 건 아니다. Tailwind 공식 문서는 잘 되어 있다.
이 가이드가 하는 일은 "보면서 이해하기"다. justify-between이 뭔지 텍스트로 읽는 것과, 박스 세 개가 양 끝과 가운데로 벌어지는 걸 직접 보는 건 체감이 다르다. 옵션을 바꿔가며 justify-around와 justify-evenly의 차이를 비교할 수 있으니까.
수업에서도 "이 URL 열어보세요" 한마디면 학생들이 같은 화면을 보며 따라할 수 있어서 편하다. 바이브 프롬프트는 덤인데, v4 마이그레이션 기간에 생각보다 쓸 일이 많았다.
댓글
댓글을 작성하려면 이 필요합니다.