기술을 뜯고, 사고를 담다.

3 분 소요

프레임 헤더(Frame Header) UI 리팩토링 회고

오늘 작업 요약

프레임 헤더 UI의 시각적 일관성을 정리하고, 편집 모드(Edit Mode)에서만 노출되는 인터랙션 요소(이동 핸들, hover 아이콘)를 추가한 프론트엔드 UI 리팩토링 작업을 진행했다. 총 3개 커밋에 걸쳐 진행됨.

  • 헤더 컬럼 선택 시 보더 색상 토큰화 + 모드별(View/Design) hover 아이콘 SVG 분리
  • 아이콘을 개별 .svg 파일에서 React 아이콘 컴포넌트로 통합 이전
  • 미선택 프레임의 컨트롤 요소 은닉 → 선택 상태 명확화
  • 편집 모드 전용 컴포넌트 이동 핸들 추가

STAR 정리

Situation (상황)

프레임 헤더 영역에서 선택/미선택 상태, 편집/사용 모드 간의 시각적 구분이 명확하지 않았고, 아이콘 리소스가 개별 .svg 파일로 흩어져 있어 모드별 색상 변형을 다루기 어려운 구조였다.

Task (과제)

  1. 헤더 컬럼 선택 상태를 색상으로 명확히 표현하는 토큰 체계 구축
  2. 아이콘 리소스를 컴포넌트 기반으로 통합해 상태별 스타일링을 코드 레벨에서 제어 가능하게 만들기
  3. 편집 모드에서만 필요한 인터랙션(컴포넌트 이동 핸들)을 추가하면서 미선택 프레임의 시각적 노이즈 제거

Action (행동)

  • 헤더 컬럼 선택 시 separator 색이 바뀌도록 디자인 토큰을 신설하고, 타입 정의부터 엔진 기본값, 실제 컴포넌트까지 일관되게 연결
  • 드래그 hover 아이콘을 View/Design 모드별 SVG 상수로 분리해 모드에 따라 다른 비주얼이 필요한 요구사항 반영
  • 확대/축소/그리드 아이콘 3종을 .svg 파일에서 제거하고 React 아이콘 컴포넌트로 이전, 확장/축소 아이콘 신규 작성
  • 미선택 프레임의 헤더 칩, 소스 그리드 아이콘, 권한 그룹을 숨기고 컨트롤 아이콘 컬러를 비활성 톤으로 변경
  • 헤더 타이틀 영역의 flex 속성을 조정해 텍스트 overflow 문제 해소, 삭제 버튼 정렬 및 input padding 미세 조정
  • 편집 모드 전용 컴포넌트 이동 아이콘을 추가하고 hover/press 상태에 따라 아이콘이 토글되도록 구현
  • 외부 벤더링(vendored) 그리드 라이브러리 소스를 직접 수정한 부분은 별도 문서에 기록해 업스트림과의 차이를 추적 가능하게 관리

Result (결과)

  • 선택된 프레임만 컨트롤이 노출되는 명확한 UX 규칙 확립 → 편집 화면의 시각적 노이즈 감소 (관찰 기반, 정량 측정은 아직 진행 전)
  • 아이콘 관리 방식이 파일 기반에서 컴포넌트 기반으로 전환되어, 이후 모드/상태별 아이콘 변형 추가 시 코드 재사용성 향상 (구조적 개선, 정량 측정 대상은 아님)
  • vendored 패치 문서화로 향후 업스트림 라이브러리 업데이트 시 충돌 리스크를 사전에 파악할 수 있는 기반 마련

실제 측정 가능한 지표

오늘 작업 범위에서 로그나 도구로 직접 확인 가능한 것은 다음과 같다. (아직 측정 전이면 “예정”으로 표시)

지표 확인 방법 비고
삭제된 .svg 파일 수 git show <commit> --stat 확대/축소/그리드 아이콘 3개 파일 제거 확인 가능
변경된 파일/라인 수 (커밋별) git diff --stat <commit>^ <commit> 커밋 크기, 변경 범위 파악
번들 사이즈 변화 Bundle Analyzer (webpack-bundle-analyzer 등) 전/후 비교 svg → 컴포넌트 전환이 번들에 미치는 영향 확인 가능
렌더링 노드 수 변화 React DevTools Profiler (미선택 프레임 렌더링 전/후) 숨김 처리가 실제 DOM 노드 감소로 이어졌는지 확인
vendored 패치 diff 크기 패치 문서 + git diff 업스트림 대비 커스텀 변경량 정량화 가능

추정 가능한 효과 (근거 포함)

  • 코드 재사용성 향상 (추정): .svg 파일 3개 → React 컴포넌트 통합으로, 이후 아이콘에 상태별 색상/크기 변형이 필요할 때 별도 파일을 만들지 않고 props로 제어 가능해짐. 근거: 커밋 diff에서 아이콘이 통합 컴포넌트로 이전되고 모드별 상수(View/Design)로 분기된 구조를 확인함. 다만 “몇 % 향상”과 같은 수치는 근거 없이 제시하지 않음.
  • 시각적 노이즈 감소 (추정): 미선택 프레임에서 헤더 칩·아이콘·권한 그룹을 숨기는 로직 추가로 편집 화면에서 한 번에 노출되는 인터랙티브 요소 수가 줄어듦. 근거: 커밋 메시지 및 코드 변경 내용상 조건부 렌더링 추가를 확인함. 실제 사용자 인지 부하 감소 여부는 사용자 테스트 없이는 확정할 수 없음.

더 측정하면 좋은 지표

  1. Lighthouse / Web Vitals: 헤더 영역 리렌더링이 잦은 화면이라면, 변경 전후 CLS(레이아웃 시프트)나 렌더링 시간 비교
  2. React DevTools Profiler: 미선택 프레임 다수 존재 시, 숨김 처리 전/후 렌더 커밋 개수 및 소요 시간 비교
  3. Bundle Analyzer: svg → 컴포넌트 전환이 최종 번들 크기에 어떤 영향을 줬는지 (아이콘이 많다면 tree-shaking 효과 확인 가치 있음)
  4. PR 리뷰 소요 시간: 다음번엔 토큰 마이그레이션과 레이아웃 수정을 커밋 분리해 리뷰 소요 시간이 줄었는지 비교
  5. 회귀 버그 발생 빈도: 테스트가 없는 영역이므로, 이번 변경 이후 실제로 회귀 이슈가 얼마나 발생하는지 추적

오늘 배운 것

  • 디자인 토큰을 추가할 때 타입 정의 → 엔진 기본값 → 실제 컴포넌트 순으로 일관되게 연결하는 흐름을 다시 확인함
  • 모드(View/Design)별로 달라지는 요소를 다룰 때, SVG 상수를 분리하는 방식이 조건 분기를 코드에서 명시적으로 드러내는 데 유리하다는 점
  • vendored 라이브러리를 수정할 때는 변경 사항을 즉시 문서화하는 습관이 향후 업스트림 머지/업데이트 시 리스크를 크게 줄여준다는 것

부족했던 점

  • 커밋 단위가 “색 토큰 + 레이아웃 + 숨김 로직”으로 뒤섞여 있어 리뷰어 입장에서 변경 의도를 파악하기 어려웠을 가능성이 높음 (단일 책임 원칙을 커밋 단위에도 적용했어야 함)
  • 시각/인터랙션 변경임에도 회귀 테스트를 전혀 추가하지 않음 — 조건이 명확한 로직은 최소한의 단위 테스트로 커버 가능했음
  • 작업 전후 정량적 지표(번들 사이즈, 렌더링 성능)를 전혀 측정하지 않아, 이번 회고에서 “추정”과 “실측”을 명확히 구분해야 했음

내일 하면 좋은 작업

  1. 흩어진 헤더 관련 색 토큰 전수 조사(audit) — 어떤 토큰이 중복되거나 일관성이 없는지 정리
  2. 오늘 변경한 커밋들을 대상으로 Bundle Analyzer 돌려서 svg → 컴포넌트 전환의 실제 사이즈 영향 확인
  3. “편집 모드 전용 요소 노출” 로직에 대한 최소 단위 테스트 1~2개 추가
  4. 다음 리팩토링부터는 커밋을 “토큰 마이그레이션 / 레이아웃 수정 / 숨김 로직”으로 분리해 커밋하는 습관 시도

댓글남기기

참고