Post

데이터가 늦게 오면 화면이 밀린다 — 레이아웃 이동(CLS) 측정과 제거, 그리고 CLS가 못 잡는 흔들림

데이터가 늦게 오면 화면이 밀린다 — 레이아웃 이동(CLS) 측정과 제거, 그리고 CLS가 못 잡는 흔들림

사내 업무용 웹 화면들(작업 목록 화면, 편집 도구, Vue 관리자 화면 9개)에서 API 응답이 늦게 오면 요소가 끼어들거나 크기가 바뀌어 화면이 밀렸다. 원인은 대부분 하나였다. 나중에 채워질 자리를 미리 잡아 두지 않은 것. 자리 예약, 고정 폭, tabular-nums, 「준비되면 한 번에 보여 주기」, 지난 응답 기억으로 고쳤다. 레이아웃 이동 점수는 최대 0.084에서 0이 됐다(한 화면만 0.02 남음). 측정하다 보니 표준 지표 CLS가 가장 큰 흔들림을 거의 못 잡는다는 것도 알게 됐다. 그래서 보조 지표를 직접 만들었다.


문제 — 무엇이 불편했나

목록 화면을 쓰다 보면 이런 느낌이 들었다. 「내용이 다 뜨기 전이랑 뜨고 나서 크기가 달라서 깜빡거린다」.

이 화면들은 하루 종일 켜 두는 업무 도구다.

  • 0.5초 사이에 버튼이 옆으로 밀리면, 누르려던 것과 다른 것을 누른다(오클릭).
  • 작은 흔들림도 하루 종일 쌓이면 피로가 된다.

그래서 한 화면만 고치지 않고, 앞으로 만드는 모든 화면의 규칙으로 정했다.

개념 — 레이아웃 이동과 CLS

레이아웃 이동(layout shift)이란

브라우저는 HTML을 받으면 먼저 그린다. 그 뒤 자바스크립트가 API 응답을 받아 숫자·배지·버튼·카드를 넣거나 글자를 바꾼다. 그러면 그 요소의 크기가 변하고, 같은 줄과 아래쪽 요소들이 밀린다. 사용자가 아무것도 누르지 않았는데 보이는 요소의 위치가 바뀌는 것, 이것이 레이아웃 이동이다.

이번에 찾은 원인은 여섯 갈래였다. 늦게 온 데이터로 요소를 추가, 글자 길이에 따라 폭이 변함, v-if로 나타났다 사라짐, 위쪽에 끼워 넣기, 크기를 모르는 아이콘, 첫 화면을 그린 뒤 크게 접거나 펼침. 실제 사례는 아래 「원인과 고친 방법」에 화면별로 정리했다.

CLS(Cumulative Layout Shift) 계산법

CLS는 구글 Core Web Vitals 지표 중 하나다. 브라우저의 Layout Instability API가 이동마다 점수를 낸다.

  • 이동 점수 = 영향 비율(impact fraction) × 거리 비율(distance fraction)
    • 영향 비율: 움직인 요소들의 이전·이후 영역을 합친 면적 ÷ 화면 면적
    • 거리 비율: 가장 많이 움직인 거리 ÷ 화면의 긴 변
  • 예: 화면 절반 크기의 영역이 화면 높이의 10%만큼 내려가면 대략 0.5~0.6 × 0.1 ≈ 0.05.
  • 세션 창: 1초 안에 이어진 이동들을 하나로 묶는다(최대 5초). 가장 큰 창의 합이 그 페이지의 CLS다.
  • 입력 직후 제외: 사용자 입력 직후 0.5초 안의 이동은 세지 않는다(hadRecentInput). 클릭해서 펼친 건 의도한 변화이기 때문이다.
  • 기준: 좋음 ≤ 0.1, 나쁨 > 0.25. 이번엔 더 엄격하게 0.02 미만을 목표로 잡았다.

CLS가 못 잡는 것 — 보조 지표 VS를 만든 이유

CLS는 앞뒤 두 장면에 모두 있던 요소의 위치 변화만 센다.

목록 화면은 응답을 받으면 카드를 지우고 새로 만들어 정렬한다. 브라우저 입장에서는 옛 요소가 사라지고 새 요소가 생긴 것이다. 이동으로 치지 않는다. 그래서 눈으로 본 「시작 버튼 130px 점프」가 CLS로는 0.0003밖에 안 나왔다.

그래서 VS(visual shift)라는 보조 지표를 만들었다.

  • 매 프레임(requestAnimationFrame)마다 버튼·카드·칩을 보이는 글자와 역할로 식별해 위치를 기록한다.
  • DOM 노드가 바뀌어도 「같은 글자, 같은 역할」이면 같은 요소로 본다.
  • 같은 요소가 움직이면 CLS와 같은 공식(영향 × 거리)으로 점수를 매긴다.

핵심만 줄이면 이런 모양이다.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
// vs_inject.js — 보이는 요소 위치를 매 프레임 추적 (개념만 줄인 형태)
const W = innerWidth, H = innerHeight, LONG = Math.max(W, H);
const SEL = 'button, a, [role], .card, .chip';
let prev = new Map();
window.__vs = 0;

const keyOf = el => (el.getAttribute('role') || el.tagName) + '|' + el.textContent.trim().slice(0, 40);
// 근사: 이전·이후 사각형을 감싸는 상자를 영향 영역으로 본다
const box = (a, b) =>
  (Math.max(a.right, b.right) - Math.min(a.left, b.left)) *
  (Math.max(a.bottom, b.bottom) - Math.min(a.top, b.top));

function frame() {
  const now = new Map();
  for (const el of document.querySelectorAll(SEL)) {
    const r = el.getBoundingClientRect();
    if (r.width && r.height) now.set(keyOf(el), r);
  }
  let area = 0, dist = 0;
  for (const [k, r] of now) {
    const p = prev.get(k);
    if (!p) continue;
    const d = Math.max(Math.abs(r.x - p.x), Math.abs(r.y - p.y));
    if (d < 1) continue;
    area += box(p, r);
    dist = Math.max(dist, d);
  }
  if (area) window.__vs += Math.min(area / (W * H), 1) * (dist / LONG);
  prev = now;
  requestAnimationFrame(frame);
}
requestAnimationFrame(frame);

결과 표에는 CLS와 VS 중 큰 값을 적었다.

측정 방법

항목내용
도구puppeteer-core + Chrome. PerformanceObserver를 페이지 스크립트보다 먼저 주입
느린 응답 재현시험용 가짜 API가 모든 응답을 0.8초 늦게 보냄(관리자 화면은 API별 0.2~2.4초). 로컬은 너무 빨라 흔들림이 안 보이기 때문
비교수정 전·후 코드를 같은 가짜 API로 나란히 띄움. 폭 1280px·390px, 첫 방문·재방문
반복3회 측정의 중앙값. 매번 브라우저 저장소를 비움
기록시점별 캡처 + 이동한 요소에 테두리(점선 = 이전 위치, 실선 = 옮겨 간 위치)

CLS 수집은 puppeteer의 page.evaluateOnNewDocument()로 아래 「바로 해 볼 것」의 PerformanceObserver를 페이지 스크립트보다 먼저 심고, 끝난 뒤 항목을 꺼내 세션 창 규칙으로 묶어 계산했다.

함정 — HTTP/1.1에서는 흔들림이 숨는다

  • 브라우저는 HTTP/1.1로는 한 호스트에 동시 연결을 6개까지만 연다. 요청이 줄을 서고 응답이 한꺼번에 도착해서, 이동이 한 번에 몰리거나 아예 안 보였다.
  • 운영 프록시는 HTTP/2라 응답이 제각각 도착한다. 시험 서버도 HTTP/2(자체 서명 인증서)로 바꾸고 나서야 실제와 같은 흔들림이 재현됐다.

흔한 원인인 글꼴 바꿔치기(FOUT)도 CDN 글꼴을 막은 경우와 허용한 경우를 둘 다 쟀다. 점수가 같아서 여기서는 원인이 아니었다.

원인과 고친 방법

작업 목록 화면 (서버 렌더링 + 바닐라 JS)

원인해결
필터 버튼 옆 개수가 응답 뒤에 붙음처음부터 같은 크기의 흐린 「–」 칩(min-width)을 그려 두고 숫자로 바꾸기만 함. 0도 「0」으로 표시
카드의 메뉴·담당자 줄을 응답 뒤 JS가 추가서버가 처음 HTML에 숨긴 채 자리만 잡아 그림. JS는 보이게만 바꿈
준비 안 된 카드와 정렬 순서가 응답 뒤에 바뀜응답이 올 때까지 카드 영역을 자리는 차지한 채 숨김. 응답이 오면 한 번에 등장(최대 2.5초, 오류가 나도 표시)
재방문 때도 같은 흔들림지난 응답을 브라우저에 하루 동안 기억. 다음 방문 때 바로 그리고, 뒤에서 조용히 갱신(stale-while-revalidate)
오류 문구가 안내문 위쪽에 끼어듦안내문 끝에 붙임

재방문용 캐시는 이 정도면 된다.

1
2
3
4
5
6
7
8
9
10
11
12
const KEY = 'list-cache-v1';
const DAY = 24 * 60 * 60 * 1000;

const cached = JSON.parse(localStorage.getItem(KEY) || 'null');
if (cached && Date.now() - cached.t < DAY) render(cached.data); // 지난 값으로 바로 그림

fetch('/api/list')
  .then(r => r.json())
  .then(data => {
    localStorage.setItem(KEY, JSON.stringify({ t: Date.now(), data }));
    render(data); // 바뀐 부분만 다시 그림
  });

편집 도구 (단일 HTML)

원인해결
첫 화면을 그린 뒤 오른쪽 패널 접기(790px), 목록·위 막대 채우기가 그대로 보임<body class="boot">로 로딩 화면 뒤에 숨겨 두고, 로딩 화면이 사라지는 같은 순간에 보여 줌
위 막대의 상태 글·저장 표시 길이가 바뀜상태 칸을 280px로 고정(긴 글은 「…」, 마우스를 올리면 전체 표시). 버튼·저장 표시는 최소 폭 지정
백업 배지가 늦게 생김처음부터 「백업 –」를 108px 폭으로 그려 둠
권한별 버튼 줄이 생겼다 사라짐해당 권한이면 자리를 항상 두고, 보이기만 바꿈
ⓘ가 글자 「i」에서 아이콘으로 바뀜처음부터 같은 16px 아이콘
숫자 자릿수가 바뀌며 폭이 변함font-variant-numeric: tabular-nums로 모든 숫자를 같은 폭으로

「준비되면 한 번에」는 클래스 하나로 된다.

1
2
3
4
5
6
7
8
9
<style>
  body.boot #app { visibility: hidden; } /* 자리는 잡고, 안 보이게만 */
</style>
<body class="boot">
  <div id="app">...</div>
  <script>
    init().finally(() => document.body.classList.remove('boot'));
  </script>
</body>

Vue 관리자 화면 (9개)

화면원인해결
목록 카드상태 칩이 1.4초 늦게 앞쪽에 끼어듦. 카드가 23px 커지고 다음 묶음이 45px 밀림목록과 같이 오는 칩을 앞에, 늦게 오는 칩은 뒤에. 칩 줄은 두 줄 높이를 예약
목록 표배지가 「O」→「34%」, 「대기 중」으로 바뀌며 폭이 변함값 칸 고정 폭, 「대기」로 짧게, 열 폭 172px, 데이터 전엔 「–」
상세상태 줄이 위에 끼어듦, 버튼이 늦게 나타남처음부터 40px 높이 줄에 「–」 칩. 버튼은 150px 고정 칸(해당 없으면 흐리게)
상태 대시보드작업 표가 2.4초 늦게 와서 아래 카드가 222px 밀림같은 높이의 뼈대 줄(skeleton). 줄 수는 지난번 값을 기억
나머지 화면버튼·칩이 데이터에 따라 생겼다 사라지거나 앞쪽에 생김항상 두고 흐리게·비활성(visibility), 고정 폭 칸

Vue에서 자주 쓴 패턴:

1
2
3
4
5
6
7
8
<!-- 나쁨: 데이터가 오면 생기고, 자릿수에 따라 폭이 변함 -->
<span v-if="count != null" class="chip">{{ count }}</span>

<!-- 좋음: 처음부터 같은 크기 자리, 숫자 고정폭 -->
<span class="chip num" :class="{ dim: count == null }">{{ count ?? '–' }}</span>

<!-- 생겼다 사라지는 버튼: 자리는 두고 숨김 -->
<button :style="{ visibility: canOpen ? 'visible' : 'hidden' }">열기</button>
1
2
3
.chip { display: inline-block; min-width: 2.5em; text-align: center; }
.num  { font-variant-numeric: tabular-nums; }
.dim  { opacity: 0.4; }

결과

화면수정 전수정 후
작업 목록 카드 (1280 / 390)0.057 / 0.0240 / 0
작업 목록 표 (1280 / 390)0.055 / 0.0570 / 0
작업 목록 재방문0.0570
편집 도구 (1280 / 390)0.079 / 0.0670 / 0
관리자 목록 표 / 카드0.0001 / 0.0170 / 0
관리자 상세0.0840
관리자 상태 대시보드 첫 방문 / 재방문0.057 / 0.0570.020 / 0
관리자 사이드바00

작업 목록·편집 도구는 CLS와 VS 중 큰 값, 관리자 화면은 CLS. 모두 응답 지연 조건에서 측정했다.

기존 UI 자동 시험은 전부 통과했고, 관리자 화면은 vite build까지 확인했다.

수정 전 점수도 이미 「좋음」(≤ 0.1)이었다. 그런데도 불편했던 이유는 CLS가 화면 넓이 대비 점수이기 때문이다. 작은 버튼이 26px 밀리는 건 점수로는 작지만 오클릭에는 치명적이다. 숫자 기준보다 「누를 것이 움직이는가」가 실제 기준이다.

대가와 남은 것

  • 첫 방문에 카드 영역이 0.5~1초 비어 있다. 흔들리는 것보다 한 번에 나타나는 쪽을 골랐다. 카드 모양 뼈대(skeleton)를 그리면 더 낫다.
  • 고정 폭 칸은 긴 글을 자른다. 마우스를 올리면 툴팁으로 전체가 보인다.
  • 없을 때 사라지던 버튼이 이제 흐리게 남는다. 대신 위치가 늘 같아 익히기 쉽다.
  • 상태 대시보드 첫 방문 0.02는 기억해 둔 줄 수(기본 3)와 실제 줄 수가 다를 때 생긴다.

앞으로 만드는 화면의 규칙

  1. 나중에 채워지는 숫자·배지·버튼은 처음부터 같은 크기의 자리를 그린다(흐린 「–」, min-width, tabular-nums).
  2. 목록·카드·표는 뼈대 또는 고정 높이로 그리고, 이미지는 aspect-ratio 상자에 넣는다.
  3. 데이터가 도착한 뒤 위쪽·앞쪽에 끼워 넣지 않는다. 뒤에 붙이거나 자리를 예약한다.
  4. 생겼다 사라지는 요소는 v-if/display:none 대신 visibility로 숨기거나 흐리게 둔다.
  5. 초기 정리 과정이 보이면 준비될 때 한 번에 보여 준다. 재방문 때는 지난 응답으로 바로 그린다.
  6. 확인은 느린 응답 + HTTP/2 조건에서 CLS·VS를 재고, 수정 전·후를 캡처한다.

배운 점

  • visibility vs display: visibility:hidden은 자리를 차지한 채 안 보이고, display:none은 자리가 없어 나타날 때 주변이 밀린다. Vue의 v-if(요소를 만들고 지움)와 v-show(display:none)는 둘 다 자리가 없다.
  • tabular-nums: 비례 글꼴에서는 1이 8보다 좁다. 「9→10」처럼 바뀌는 숫자에는 기본으로 거는 게 좋다.
  • stale-while-revalidate: 지난 값을 먼저 보여 주고 뒤에서 새 값으로 고친다. HTTP Cache-Control 지시어 이름이면서 SWR, TanStack Query 같은 상태 관리 패턴의 이름이기도 하다.
  • CLS가 낮아도 불편할 수 있다: 점수는 면적 가중이라 작은 클릭 대상의 이동을 과소평가한다. 요소를 지우고 새로 만드는 렌더링은 아예 이동으로 안 잡힌다.
  • 시험 환경의 프로토콜을 운영과 맞춰라: HTTP/1.1과 HTTP/2는 응답이 도착하는 모양이 달라서, 다르면 성능·흔들림 측정이 틀어진다.

바로 해 볼 것

지금 보고 있는 페이지의 콘솔에 붙여 넣으면, 이동이 생길 때마다 점수와 움직인 요소가 찍힌다.

1
2
3
4
5
6
new PerformanceObserver(list => {
  for (const e of list.getEntries()) {
    if (e.hadRecentInput) continue;
    console.log(e.value.toFixed(4), e.sources?.map(s => s.node));
  }
}).observe({ type: 'layout-shift', buffered: true });

DevTools의 Performance 패널에서 녹화하면 Layout shifts 트랙에서도 같은 것을 볼 수 있다. Network 패널의 쓰로틀링(Slow 4G)을 걸면 로컬에서도 흔들림이 잘 보인다.

키워드: Cumulative Layout Shift, Core Web Vitals, Layout Instability API, hadRecentInput, session window, font-variant-numeric: tabular-nums, visibility vs display, skeleton UI, stale-while-revalidate, puppeteer evaluateOnNewDocument, HTTP/2 multiplexing

This post is licensed under CC BY 4.0 by the author.