아이콘 라이브러리 메이저 업데이트와 브랜딩 일괄 치환 시 주의점

아이콘 라이브러리 메이저 업데이트 충돌

오랜만에 공통 헤더/메타/CSS 묶음을 한꺼번에 손봤음. 트리거는 두 가지였음. 첫째, 아이콘 라이브러리 6.x → 7.x 메이저 점프 후 일부 아이콘이 안 그려짐. 둘째, 내부 코드네임을 새 브랜드명으로 갈아끼워야 했음.

릴리즈 노트 훑어보니 CSS 변수 prefix 변경, stroke-width 기본값 변경, 일부 아이콘 alias 제거가 핵심이었음.

<!-- before -->
<i class="iconoir-user-circle"></i>

<!-- after -->
<i class="iconoir-user-circle" style="--iconoir-stroke: 1.5"></i>

실제 영향은 어드민 로그인 화면이 가장 컸음. 입력 필드 좌측 아이콘 굵기가 어색해서 디자인 검수에서 바로 걸렸음.

브랜딩 일괄 치환의 함정

코드네임을 정식 브랜드명으로 갈아엎는 작업은 sed 한 방 유혹이 강한데, 실제로는 곳곳에 흩어져 있어서 위험했음.

• meta 태그(title/og:title/og:site_name): SEO와 메신저 카드 미리보기 영향
• favicon·로고 이미지 경로: 캐시 강제 갱신 필요
• footer copyright: 연도까지 함께 점검
• 로그인 화면 워터마크/타이틀: UX 첫인상

치환할 때 주의한 포인트:

• 대소문자 변형 4가지(전대문자/캐멀/케밥/소문자) 각각 grep
• 주석·문서 내 옛 이름은 히스토리 보존 차원에서 일부 유지
• 외부 노출 문구만 새 브랜드로 교체, 내부 변수명은 손대지 않음

검증 포인트

작업 후 한 바퀴 돌면서 체크한 것들임.

• og:image 미리보기를 외부 디버거로 새로 긁어서 캐시 깨짐 확인
• 어드민 로그인 화면을 다크/라이트 모두 확인
• 아이콘 들어간 공통 컴포넌트 한 번씩 렌더링 테스트
• 모바일 브레이크포인트에서 아이콘 정렬 깨짐 없는지

배운 점

아이콘 라이브러리 메이저 업데이트는 "그냥 버전만 올리면 되겠지" 하면 100% 디자인이 어긋남. CSS 변수 이름이 바뀐 건 IDE 자동완성으로도 못 잡고 빌드도 통과해버려서, 시각 검수가 유일한 안전망이었음. 브랜딩 작업은 grep으로 끝내지 말고 실제 외부 노출 페이지를 눈으로 한 바퀴 돌아야 안전함. 공통 영역은 한 번 잘못 건드리면 전 페이지가 동시에 깨지니까, PR 단위를 작게 쪼개고 스크린샷 첨부하는 습관이 결국 시간을 아껴줬음.

다음