자주 깨지는 곳 10가지

전부 실제로 겪은 것들입니다. 증상 → 원인 → 해결 → AI에게 그대로 줄 문장 순서로 적었습니다. 터미널을 열 필요가 없습니다. 파란 박스를 복사해 AI 대화창에 붙여넣으세요.

1. 스타일이 아예 안 먹는다

원인 CSS 링크 경로가 틀렸거나, 다른 CSS가 뒤에서 덮어쓰고 있습니다. 해결 콘솔에서 getComputedStyle(document.documentElement).getPropertyValue('--jt-ds-version') → 빈 문자열이면 CSS가 안 실린 것입니다. 링크를 <head> 안, 앱 자체 CSS 앞에 두세요.

우리 디자인 시스템 CSS가 실제로 적용되고 있는지 확인해줘.
1. jt-tokens.css 와 jt-utilities.css 링크가 <head> 안에 있는지
2. 그 링크가 우리 앱 자체 CSS보다 '앞'에 있는지
3. 콘솔에서 --jt-ds-version 값이 나오는지 검사하는 방법
확인 결과를 알려주고, 문제가 있으면 어디인지 짚어줘.

2. 개발서버는 멀쩡한데 배포하면 스타일이 사라진다

원인 Tailwind content / @source 경로 누락. 개발 중에는 JIT가 전부 훑지만 프로덕션 빌드는 명시된 경로만 봅니다. 해결 경로에 실제 소스 폴더가 전부 들어 있는지 확인하고, 배포 전 프로덕션 빌드로 눈으로 확인하세요.

개발할 땐 되는데 배포하면 스타일이 사라져. Tailwind content / @source 경로에
실제 소스 폴더가 전부 들어 있는지 확인하고, 빠진 경로를 알려줘.
그다음 프로덕션 빌드로 확인하는 방법도 알려줘.

3. Tailwind 설정을 고쳤는데 아무 반응이 없다

원인 Tailwind v4에서는 tailwind.config.js가 에러 없이 조용히 무시됩니다. 해결 npx tailwindcss --help | head -1로 버전 확인 → v4면 jt-tailwind-v4.css(@theme inline)를 쓰세요.

이 프로젝트의 Tailwind 버전을 확인해줘.
v4 라면 tailwind.config.js 가 조용히 무시되니까,
https://ds.janytree.app/v5/jt-tailwind-v4.css 를 쓰도록 설정을 바꿔줘.
바꾸기 전에 무엇을 어떻게 바꿀지 먼저 설명해줘.

4. 글자가 전부 커졌다 / 여백이 벌어졌다

원인 v5.0에서 본문 기준이 14px → 16px로 바뀌었습니다. 14px 기준으로 만든 앱은 모든 것이 함께 커집니다. 해결 정상 동작입니다. 데이터 밀집 화면만 [data-density="compact"](14px)를 그 영역에만 거세요. 전역으로 줄이지 마세요.

v5.0에서 본문 기준이 14px 에서 16px 로 바뀌어서 화면이 전체적으로 커졌어.
전역으로 글자 크기를 줄이지는 마. 대신 데이터가 빽빽한 영역(표, 목록)만 골라서
그 영역에만 data-density="compact" 를 걸어줘.
어디에 걸지 후보를 먼저 목록으로 보여주고, 내가 고른 뒤에 적용해줘.

5. 다크 모드에서 라디오 버튼만 흰 원으로 튄다

원인 체크박스·라디오·달력·스크롤바는 브라우저가 직접 그리는 부분이라 CSS로 색을 못 바꿉니다. 해결 color-scheme을 선언합니다. v5.0 토큰 파일에 이미 들어 있으니, 파일을 v5.0으로 교체하면 해결됩니다.

다크 모드에서 체크박스·라디오·달력 아이콘만 이상하게 보여.
지금 쓰는 jt-tokens.css 가 v5.0 인지 확인해줘 (--jt-ds-version 값).
구버전이면 v5.0 링크로 바꿔줘 — color-scheme 선언이 v5.0 부터 들어 있어.

6. 아이콘 자리에 settings, inventory_2 같은 글자가 보인다

원인 아이콘 폰트를 display=swap으로 로드했습니다. 폰트가 뜨기 전에 리가처 원문이 그대로 노출됩니다. 해결 display=block으로 바꾸세요. 사내망에서 CDN이 막히는 환경이면 아예 SVG 방식(.jt-ico-mask)을 쓰세요.

아이콘 자리에 settings, inventory_2 같은 영어 글자가 보여.
아이콘 폰트를 display=swap 으로 불러오고 있는지 확인하고, display=block 으로 바꿔줘.
사내망에서 폰트 CDN 이 막힐 수 있으면 SVG 방식(.jt-ico-mask)도 대안으로 알려줘.

7. 모바일에서 가로로 밀린다

원인 셋 ① 고정 width ② word-break:keep-all을 전역/중일태국어에 적용 ③ box-sizing 누락. 해결 고정 width를 min-width로 바꾸고, keep-all은 토큰 파일에 맡기세요(:lang(ko) 한정으로 이미 처리). .jt-* 클래스는 자체적으로 border-box입니다.

폭 390px 에서 가로 스크롤을 만드는 요소를 전부 찾아줘.
특히 고정 width 를 쓴 곳과, 표를 감싸는 overflow-x 상자가 없는 곳을
파일 이름·줄 번호와 함께 표로 보여줘. 아직 고치지는 마.

8. 버튼 글자가 안 보인다 (흰 배경 + 흰 글자)

원인 어두운 막대 위의 ghost 버튼에서 글자색만 바꿨습니다. 배경은 여전히 흰색입니다. 해결 --jt-btn-bg: transparent까지 함께 덮어쓰세요. .jt-bulkbar 안에서는 시스템이 이미 처리해 둡니다.

어두운 막대 위에서 버튼 글자가 안 보여 (흰 배경에 흰 글자).
글자색만 바꾸고 배경은 그대로 둔 버튼을 찾아서,
--jt-btn-bg: transparent 까지 함께 덮어쓰도록 고쳐줘.

9. 모바일에서 도움말 툴팁이 안 열린다

원인 .jt-tooltip은 hover 기반입니다. 터치 기기에는 hover가 없습니다. 해결 .jt-toggletip(클릭형)으로 바꾸세요. → Tier 3

휴대폰에서 도움말 툴팁이 안 열려.
hover 로만 열리는 .jt-tooltip 을 쓴 곳을 찾아서
클릭으로 열리는 .jt-toggletip 으로 바꿔줘. 바꾼 목록을 알려줘.

10. 변수 이름이 충돌해서 기존 앱 색이 바뀐다

원인 기존 앱이 이미 --color-text·--space-4 같은 이름을 쓰고 있습니다. 해결 기존 변수를 먼저 정리하거나, 시스템을 좁은 범위(.jt-scope 등)로만 적용하세요. 한 앱 안에서는 한 가지 방식으로 통일합니다.

이 앱이 이미 쓰고 있는 CSS 변수 이름을 전부 찾아줘.
그중 --color-*, --space-*, --fs-*, --r-* 로 시작해서
제니트리 토큰과 이름이 겹치는 것만 표로 보여줘.
겹치는 게 있으면 .jt-scope 로 범위를 좁혀 적용하는 방법도 알려줘. 아직 고치지는 마.