깃허브 프로필을 터미널 테마로 전면 개편한 과정

오랜만에 깃허브 프로필 들어가봤더니 예전에 대충 박아둔 자기소개 한 줄이랑 뱃지 몇 개가 다였음. 깨진 뱃지도 두 개. 방문자가 와도 내가 뭘 하는 사람인지, 어떤 결과물을 만들어왔는지 30초 안에 파악이 안 되는 구조. 이게 왜 문제인지 생각해보면, 깃허브 프로필은 내가 직접 방문자를 안내하지 않는 공간이다. 누군가 오픈소스 기여 이력 보다 클릭하거나, 채용 담당자가 확인하거나, 아니면 그냥 지나가다 들어오거나. 어느 경우든 내가 거기 없다. 프로필 페이지가 나 대신 말해야 한다는 뜻이다.

그 기준 하나 잡고 뜯어고치기 시작함.

README가 실제로 하는 일

깃허브 프로필 README를 단순 자기소개 공간으로 보면 기대치가 낮아진다. 하지만 실제로는 개발자 포트폴리오의 가장 앞단, 로그인 없이 누구나 보는 공개 랜딩 페이지다. 이 성격을 명확하게 잡고 나면 뭘 넣어야 하는지가 자연스럽게 보인다.

목표는 두 가지로 잡았음.

• 첫 인상에서 정체성 전달: 어떤 스택을 쓰는지, 어떤 도메인을 주로 다루는지 스크롤 없이 보이게
• 프로젝트 쇼케이스: 그동안 작업한 결과물들을 카드 형태로 노출

두 번째보다 첫 번째가 훨씬 어렵다. 기술 스택을 나열하는 건 쉬운데, "이 사람이 무슨 일을 하는 사람인가"를 스크롤도 하기 전에 전달하는 건 구조와 시각 언어를 동시에 잡아야 하는 문제다. 뱃지 30개 나열해두면 기술은 보이는데 사람은 안 보인다. 그 차이가 생각보다 크다.

터미널 테마로 간 이유

처음엔 그라데이션 헤더 이미지로 갈까 했음. 진한 색 배경에 이름이랑 타이틀 딱 박는 스타일. 그런데 깃허브에서 개발자 프로필 20개쯤 열어보면 비슷비슷한 톤이 많다. 차별화 포인트가 없어서 기억에 안 남음.

결국 검정 배경 + 모노스페이스 + 프롬프트 기호 조합으로 결정. 내가 매일 보는 화면을 그대로 옮기는 방식이라 억지스럽지 않고, "이 사람 터미널 많이 치는 사람이구나"가 시각적으로 읽힌다. 스택 표현 방식도 같이 바꿨는데, 뱃지를 전부 나열하기보다 "자주 쓰는 것 / 가끔 쓰는 것 / 배우는 중"으로 그루핑하는 게 정보 밀도가 높다. 방문자 입장에서 궁금한 건 "이 사람이 뭘 다 아는가"가 아니라 "이 사람이 뭘 주로 쓰는가"니까.

$ whoami
> backend engineer · payments · 이커머스
$ ls ~/projects
> partner-settlement/  shorts-pipeline/  retro-blog/

이 헤더 블록 손볼 때 의외로 시간이 많이 잡혔음. SVG 중앙 정렬이 깃허브 마크다운 렌더러에서 자꾸 어긋났는데, align="center" attribute가 SVG에는 적용이 안 되는 경우가 있다. 결국 <div align="center">로 바깥을 감싸는 정공법 사용. 여기에 <picture> 태그로 라이트/다크 모드 분기까지 추가했더니 의도한 화면이 나왔음.

<div align="center">
  <picture>
    <source media="(prefers-color-scheme: dark)" srcset="./assets/header-dark.svg">
    <source media="(prefers-color-scheme: light)" srcset="./assets/header-light.svg">
    <img alt="header" src="./assets/header-dark.svg">
  </picture>
</div>

<picture> 쓰면 다크/라이트 모드 각각 SVG를 별도로 두게 되는데, 관리 포인트가 두 배가 된다는 트레이드오프는 있음. 대신 렌더링 결과가 훨씬 깔끔하다. 단순히 img 태그 하나 박으면 라이트 모드에서 배경 흰색이랑 터미널 검정이 충돌해서 테마 자체가 무너진다.

막혔던 지점들

이모지 폭 문제는 터미널 테마 구현할 때 거의 필연적으로 만나는 지점이다. 모노스페이스로 열 맞춰놨는데 이모지 렌더링 폭이 OS마다, 폰트마다 다르다. Unicode에서 이모지는 대부분 "wide" 문자로 처리되는데 실제 렌더링은 환경마다 제각각이라 어느 쪽에 맞춰도 어딘가에선 어긋난다. 결과적으로 이모지는 헤더 한 줄에만 쓰고 정렬이 필요한 본문 영역은 텍스트로만 처리함.

통계 위젯 캐시는 처음엔 이유를 몰라서 시간을 날렸음. github-readme-stats 같은 외부 서비스들은 CDN 레이어에 캐시를 두는데, URL 파라미터로 테마나 색상을 바꿔도 캐시된 이미지가 그대로 내려오는 경우가 생긴다. URL에 &cache_seconds=1800 박아두면 최대 캐시 유지 시간을 30분으로 강제할 수 있음. 이거 모르고 "왜 색이 안 바뀌지"하고 한참 헤맸다.

프로젝트 카드 비율은 썸네일을 1280×640으로 통일하니 해결됐음. 깃허브 소셜 프리뷰 이미지 권장 사이즈가 1280×640이고, 카드 두 개를 나란히 배치할 때 이 비율로 맞춰야 열이 안 깨진다. 임의 크기로 캡처해서 쓰면 카드 높이가 제각각이 돼서 레이아웃 전체가 무너진다.

README 하나 다듬는 게 별거 아닐 줄 알았는데, "이 사람 뭐 하는지 한눈에 보이게"라는 기준 하나 잡고 끝까지 끌고 가니까 의외로 디테일 작업이 많았음. 각 섹션을 추가할 때마다 "이게 방문자한테 실제로 뭔가를 전달하는가, 아니면 내가 채워 넣고 싶어서 넣는 건가"를 계속 물어야 했다. 그 질문 없이 추가하면 결국 뱃지 30개짜리 이전 상태랑 달라질 게 없어진다.

특히 카드 썸네일 톤을 터미널 배경색에 맞춰 통일했을 때 만족도가 컸음. 각 프로젝트 썸네일 배경을 #0d1117 기준으로 맞추고 텍스트를 #c9d1d9로 통일했더니 카드들이 서로 튀지 않고 전체 페이지 흐름에 자연스럽게 녹아들었다. 색을 통일한다는 건 단순한 미적 선택이 아니라, 방문자의 시선이 어디서 어디로 흘러가야 하는지를 조율하는 작업이기도 하다.

다음에 손볼 부분은 기여 그래프 위젯 색상 커스텀, 핀 프로젝트 자동 갱신 워크플로 추가. 핀 프로젝트는 GitHub Actions로 주기적으로 README를 갱신하는 방식이 있는데, 이번엔 일단 수동으로 뒀음. 워크플로까지 붙이면 관리 비용 대비 효과가 얼마나 될지 좀 더 써봐야 알 것 같다.