아카이브 CSS 깨짐 사고로 드러난 스타일가이드 부재의 대가

한 멤버가 아카이브 페이지의 뒤로가기 버튼과 내비게이션 바가 무너져 보인다며 스크린샷을 올렸다. 확인해보니 아카이브 하위의 mag/, w/, repos/ 세 경로에서만 CSS가 통째로 빠져 있었다. 운영자는 스타일가이드 없이 기능을 하나씩 붙여온 탓에 놓친 부분이라고 인정했다. 왜 하필 이 세 경로만 스타일이 사라졌을까. 같은 사고가 네 번째 경로에서 반복되지 않으려면 무엇이 필요한지도 짚어본다.

특정 경로에서만 스타일이 사라지는 흔한 이유

정적 사이트에서 페이지마다 스타일시트를 따로 연결하는 구조라면 새 섹션을 추가할 때 그 연결 코드를 빠뜨리는 실수가 반복적으로 나온다. 스타일시트 경로가 페이지 위치에 따라 상대 경로로 걸려 있으면 디렉터리 구조가 하나만 어긋나도 링크가 깨진다.

더 흔한 함정은 따로 있다. 요청한 CSS 파일이 404로 응답할 때 일부 렌더링 경로가 상태 코드를 확인하지 않고 그 404 응답 본문을 CSS로 잘못 해석해 버린다. 그래서 화면이 깨지는 경우가 있다. 오픈소스 프로젝트 pagedjs의 이슈 트래커에도 이런 사례가 올라와 있다.

Next.js 저장소의 공식 디스커션 게시판에는 이런 사례도 보고돼 있다. 전역 CSS를 여러 컴포넌트가 나눠 쓰면 임포트 순서가 페이지 이동 경로에 따라 달라지면서 첫 진입과 뒤로가기 후 스타일이 서로 달라지기도 한다. 서버 렌더링 구조라도 사정은 비슷하다. 새 페이지 템플릿을 만들 때마다 공용 스타일시트를 불러오는 코드를 손으로 다시 넣어야 한다면, 그 한 줄을 빠뜨리는 실수는 언젠가 나온다.

아카이브의 세 경로만 깨졌다는 건, 그 경로들이 공용 레이아웃이 아니라 각자 만들어질 때 스타일 연결을 개별적으로 넣어야 하는 구조였을 가능성을 가리킨다.

기능부터 붙이고 스타일은 나중이라는 습관

이번 사고의 원인으로 운영자가 지목한 건 코드 실수가 아니라 순서였다. 스타일가이드를 먼저 정하지 않고 기능을 계속 얹어온 개발 방식 자체가 문제였다는 진단이다.

소프트웨어 개발 뉴스레터들 중에는 이른바 바이브 코딩, 곧 AI 코딩 도구로 기능을 빠르게 찍어내는 방식을 다루는 곳들이 있다. 이들은 만드는 비용이 거의 0에 가까워지면 예전 같으면 자연스럽게 걸러졌을 기능까지 다 만들어버리는 경향이 생긴다고 짚는다. 디자인 쪽에서도 비슷한 경고가 나온다. 빠르고 반복적인 해법을 우선하면 디자이너가 그때그때 땜질식 처방을 내놓게 된다. 그 처방이 쌓여 제품 확장을 어렵게 만드는 디자인 부채가 된다는 지적이다.

스타일가이드는 이런 부채를 막는 최소 장치다. 다만 정작 애플리케이션 유지보수에 밀려 뒷전으로 처지다가 코드와 어긋나 버리면 존재 의미 자체가 사라진다. 스타일가이드 운용 사례를 정리한 론리플래닛(Lonely Planet) 엔지니어링팀 기록의 결론이었다.

AI가 만든 화면일수록 스타일이 먼저 어긋난다

AI 코딩 도구가 만든 화면에서 페이지마다 스타일이 미묘하게 달라지는 문제는 이번 사고와 결이 같다. 같은 앱 안에서 사이드바가 한 페이지에서는 클릭되는데 다른 페이지에서는 안 되거나, 메뉴 항목이 빠지거나, 카드 하나만 다른 카드보다 여백이 4픽셀 좁은 식의 불일치가 반복해서 보고된다.

원인으로 지목되는 건 AI 코딩 도구가 실제 디자인 토큰 값을 참조하지 못할 때 학습 데이터에서 본 값을 바탕으로 근사해 써넣는다는 점이다. 참조할 구조화된 문서가 없으면 이런 불일치가 커질 수 있다는 분석이다.

이번 방에 올라온 스크린샷 제보도 같은 종류의 결핍이었다. 세 경로가 참조할 공통 스타일 기준이 어디에도 정리돼 있지 않았다.

재발을 막는 구체적 방법

2026년 들어 이 문제를 겨냥해 나온 규격이 DESIGN.md다. 구글 랩스가 공개한 이 포맷은 DESIGN.md 파일 하나에 디자인 시스템을 담는다. 앞부분 YAML 프런트매터에는 색상·타이포그래피·간격 같은 디자인 토큰을 기계가 읽을 수 있는 값으로 적는다. 그 아래 마크다운 본문에는 사람이 읽을 설명을 붙이는 구조다. 코딩 에이전트는 이 파일을 디자인 기준으로 참조할 수 있다. 새 페이지를 만들 때 그 안의 색상·여백 값을 참고할 수 있다. 앤트로픽의 공식 skills 저장소에도 프런트엔드 디자인 스킬이 이 구글 오픈 규격을 받아들일지 논의하는 이슈가 올라와 있다. 에이전트 기반 개발 생태계에서 채택 여부가 논의되는 단계다.

다만 한계도 분명하다. 파일이 너무 길어지면 에이전트가 핵심 규칙을 놓치거나 일부 값을 여전히 잘못 짚어내는 사례가 보고돼 있다. 그래서 만능 해결책은 아니다.

코드 수준에서는 Stylelint를 Husky·lint-staged와 묶어 커밋 전에 깨진 CSS 문법을 걸러내는 방법이 있다. Playwright에 내장된 toHaveScreenshot으로 페이지별 스크린샷을 기준 이미지와 비교하는 방식도 있다. 이 방식은 별도 유료 서비스 없이 소규모 사이트에서도 운영할 수 있다. 여러 브라우저를 함께 검증해야 하는 규모라면, 매달 스크린샷 5000장까지 무료로 제공하는 Percy 같은 클라우드 서비스로 넘어갈 만하다.

규모에 맞는 선택이 먼저다

이 모든 걸 한꺼번에 갖출 필요는 없다. 초기 단계 제품이고 만드는 사람이 한둘이라면, 색상과 타이포그래피, 간격값 몇 개만 문서 하나에 정리해두는 스타일가이드부터 시작할 수 있다. 닐슨노먼그룹(NN/g)의 분석은 디자인 시스템 도입 때 프로젝트의 규모와 반복 가능성, 가용 자원과 시간을 따져야 한다고 짚는다.

이번 사고는 그 경계선 이전 단계에서 흔히 나오는 종류였다. 세 경로의 CSS 링크를 다시 거는 작업 자체는 몇 분이면 끝난다. 그보다 앞서 답해야 할 질문은 따로 있다. 다음에 새 경로를 추가할 때 그 스타일 값을 어디서 가져올지, 그 기준을 한 곳에 모아두는 절차를 지금 갖추느냐다.