Adaptive HTML Final — 스킬 프로젝트 소개

자료 종류보다 읽는 목적을 먼저 고르기

같은 기술 자료라도 처음 배우는 사람에게는 용어와 따라 할 순서가, 도입을 판단하는 사람에게는 조건과 위험, 검증 방법이 필요합니다. Adaptive HTML Final에서는 자료가 PDF라는 이유만으로 요약문을 만들지 않도록 했습니다. 먼저 독자가 무엇을 하려는지 정하고, 그 목적에 맞는 시각 구조를 고르게 했습니다.

그래서 입력 형식만으로 문서 모양을 정하지 않았습니다. 학습, 전문가 검토, 비교, 매뉴얼처럼 목적을 먼저 고르고 필요한 블록을 정했습니다. 비교 문서라면 선택 기준과 장단점이 남아야 하고, 매뉴얼이라면 읽고 끝나는 요약보다 역할별 실행 경로와 문제 발생 시 돌아갈 지점이 필요합니다.

그 뒤에 레이아웃과 도식, 보조 위젯을 선택하도록 연결했습니다. 문서 목적과 화면 표현을 나눠 두어야 새로운 표현을 추가해도 필요한 설명의 순서가 바뀌지 않습니다. 제가 이 스킬에서 유지한 중심은 어떤 자료든 같은 카드에 담는 능력보다, 독자가 다음 판단을 할 수 있는 구조입니다.

학습 문서와 전문가 문서를 같은 틀에 넣지 않기

예제로 만든 패스키 로그인 학습 문서와 LLM 게이트웨이 전문가 문서는 서로 다른 읽기 흐름을 가집니다. 학습 문서는 낯선 개념을 풀고 이해를 확인하는 쪽으로, 전문가 문서는 운영 구조와 위험, 검증 기준을 살피는 쪽으로 구성했습니다. 두 문서는 실제 서비스의 사용 후기가 아니라 목적별 구성을 보여 주기 위해 만든 예제입니다.

이 차이를 생성 절차에 남기려고 목적별 필수 블록과 사용할 레이아웃을 연결했습니다. 결과물에 레이아웃 이름만 붙이고 본문은 임의로 합성하는 방식은 완료 조건에서 제외했습니다. 같은 이름을 썼다는 사실만으로 그 문서의 정보 구조를 적용했다고 볼 수 없기 때문입니다.

시각 구성도 구조를 설명하는 도식과 내용을 탐색하는 보조 위젯을 구분했습니다. 본문 속 관계를 보여 줄 때는 문서 흐름 안의 도식을 쓰고, 비교하거나 펼쳐 볼 내용에는 그 목적에 맞는 요소를 고릅니다. 이미지 한 장으로 모든 설명을 대신하면 작은 화면에서 필요한 정보를 읽기 어려워질 수 있어, 중요한 내용은 본문에도 남기도록 했습니다.

검사를 통과해도 화면에는 문제가 남았습니다

2026년 6월에는 새 산출물을 화면으로 검수하면서 정적 검사만으로 잡지 못한 문제들을 정리했습니다. 좁은 표에서 짧은 상태 코드가 두 줄로 깨지고, 어두운 섹션 안의 흰 카드 링크가 흐리게 보였습니다. 도식의 노드가 서로 겹치거나 목차가 첫 본문 섹션 안으로 들어간 경우도 있었습니다.

이 문제들을 한데 “디자인 개선”이라고 적으면 다시 검사하기 어렵습니다. 저는 표의 줄바꿈, 색상 상속, 도식 좌표, 목차의 위치처럼 원인이 다른 항목으로 나눴습니다. 문법에 문제가 없는 HTML에서도 일어날 수 있는 증상이어서, 화면에서 확인할 것과 구조로 검사할 것을 구분했습니다.

특히 링크 문제는 색 하나를 보기 좋게 고르는 것으로 끝나지 않았습니다. 어두운 배경에서 읽히도록 정한 링크 색이 안쪽의 밝은 카드에도 상속됐습니다. 당시 재현한 카드 안 링크의 대비는 1.65:1이었습니다. 바깥 섹션의 의도는 맞아도 안쪽 배경이 달라지면 읽기 조건을 다시 정해야 했습니다.

화면 한 장의 수정에서 공통 자산의 수정으로

링크는 밝은 카드 내부에서 카드용 색을 다시 적용하고 밑줄을 유지하도록 바꿨습니다. 고정 색을 여러 결과물에 따로 넣는 대신 공통 색상 토큰을 사용했습니다. 테마가 바뀌어도 해당 카드의 배경과 글자가 함께 달라지는 구조를 유지하려는 선택이었습니다.

표의 짧은 상태 코드는 모든 코드에 줄바꿈 금지를 적용하지 않았습니다. 긴 정규식이나 여러 토큰이 들어간 코드까지 한 줄로 밀어 버리면 다른 문서가 넓어질 수 있습니다. 상태 코드에 쓰는 전용 표지를 사용하도록 작성 조건을 좁혔습니다. 같은 code 요소라고 해도 한 칸의 상태값과 설명용 코드 문장은 다르게 다뤄야 했습니다.

목차와 제목 간격은 색이나 글꼴보다 HTML 구조를 살폈습니다. 목차는 독립된 위치에 두고, 제목 앞의 빈 요소 때문에 첫 제목의 간격 규칙이 적용되지 않는 경우도 확인하도록 했습니다. 화면에서 보인 문제를 공통 자산과 생성 조건으로 옮겨야 다음 문서에서도 같은 선택을 사용할 수 있습니다.

좌표와 실제 색은 렌더링해서 확인하기

도식 노드가 겹치는지는 클래스 이름만으로 판단하기 어렵습니다. 저는 브라우저에서 노드의 실제 영역을 재고 겹침을 검사하는 흐름을 추가했습니다. 카드 내부 링크도 렌더링된 글자색과 배경색을 함께 확인하도록 했습니다. 정적 검사로 확인하는 구조와 화면으로 확인하는 결과를 각각 남긴 것입니다.

완료 조건에는 모바일 390px와 데스크톱 1280px의 캡처와 렌더 기록을 포함했습니다. 캡처 파일이 있다는 사실만 보지 않고, 표 캡션이나 긴 제목이 잘리지 않는지, 긴 코드와 URL이 문서 전체 폭을 밀어내지 않는지 확인합니다. 검사 도구가 브라우저를 직접 실행하는지, 다른 단계에서 만든 결과를 읽는지도 구분했습니다.

공통 스타일을 수정하면 이미 만들어 둔 예제의 스타일도 다시 맞춰야 합니다. 본체만 바꿨는데 결과물은 예전 스타일을 품고 있다면 검수 기준이 어긋납니다. 사용한 스타일의 스냅샷과 해시를 함께 남기는 구조는 바로 이 차이를 찾기 위한 장치입니다. 내용과 화면 자산이 어느 조합으로 만들어졌는지 확인할 수 있어야 수정 결과를 다시 살필 수 있습니다.

다음 문서에서는 무엇을 먼저 확인할까

이 작업을 거치며 저는 예쁜 HTML이라는 목표를 구체적인 질문으로 바꿨습니다. 독자가 하려는 일을 먼저 정했는지, 그 목적에 필요한 설명이 빠지지 않았는지, 선택한 구조를 실제로 적용했는지, 작은 화면에서도 해당 내용을 읽을 수 있는지입니다.

정적 검사가 통과했다면 문서 구조를 확인한 범위까지 판단합니다. 노드 겹침이나 배경 안의 링크 대비는 실제 렌더링으로 이어 갑니다. 반대로 화면이 보기 좋더라도 비교 기준이나 실행 절차가 빠졌다면 문서 목적을 충족했다고 보지 않습니다.

새 표현을 늘리는 것보다 중요한 것은 새 표현이 기존 읽기 조건을 깨지 않는지 확인하는 일입니다. 목적 선택과 시각 구성을 분리하고, 화면에서 발견한 증상을 다음 생성의 검수 조건으로 옮긴 것이 이 스킬을 다듬으며 남긴 개발 기준입니다.