메뉴 버튼을 누르면 화면 옆에서 패널이 들어오고, 손가락으로 밀면 다시 사라진다. 이 움직임을 구현할 때 드래그 위치와 속도를 직접 계산하는 대신, 브라우저의 스크롤 기능을 활용할 수도 있다. Modern Web Guidance의 메뉴 패널 지침은 이런 구현 선택을 코딩 에이전트에 전달하는 사례다.
Modern Web Guidance는 웹 플랫폼의 구현 지식과 권장 관행, 브라우저 호환성 정보를 코딩 에이전트에 전달하는 스킬 모음이다. Google Chrome, Microsoft Edge, Mozilla Firefox, MDN 팀과 웹 개발 커뮤니티가 함께 관리한다. 프로젝트가 겨냥하는 간극은 모델이 API의 존재를 아는 것과 실제 작업에서 적절하게 사용하는 것 사이에 있다.
작업과 관련된 스킬이 활성화되면 에이전트는 검색어로 지침을 찾고, 선택한 지침을 가져와 자신의 작업 맥락에 넣는다. 이때 전달되는 내용은 해당 구현의 코드 패턴과 주의점, 지원되지 않을 때의 대체 방법이다. ‘이 기능이 있다’는 설명에서 한발 더 나아가, 지금 만드는 UI에 어떻게 적용할지 참고할 자료를 건네는 방식이다.
검색 자체는 로컬에서 수행된다. 다만 README에 따르면 Google은 에이전트가 만든 검색어와 조회한 지침 ID 등을 익명 사용 정보로 수집하며, 사용자의 원래 프롬프트는 수집하지 않는다.
메뉴 패널의 움직임을 스크롤로 만들기
메뉴 패널 지침을 보면 브라우저에 무엇을 맡기는지 구체적으로 드러난다. 지침은 가로 스크롤 영역에 ‘열림’과 ‘닫힘’ 위치를 두고 CSS 스크롤 스냅으로 패널을 그 위치에 멈추게 한다. 손가락으로 밀 때의 관성과 속도, 도중에 멈추는 처리는 브라우저의 스크롤 동작이 맡는다. 배경을 어둡게 하는 효과는 스크롤 위치에 연결해, 패널이 움직이는 만큼 함께 변하게 한다.
자바스크립트는 이 움직임과 대화상자의 상태를 연결한다. 열 때는 대화상자를 먼저 표시한 뒤 패널이 보이는 위치로 스크롤한다. 닫을 때는 반대쪽으로 스크롤하고, 패널이 완전히 화면 밖으로 나간 것을 IntersectionObserver로 감지한 뒤 대화상자를 닫는다. 패널이 사라지기도 전에 대화상자를 닫아 퇴장 애니메이션이 끊기는 일을 피하는 순서다.
요구 조건에 따라 기본 요소도 달라진다. 지침은 패널로만 쓸 때 모달 <dialog>를 선택한다. 브라우저가 나머지 페이지를 조작할 수 없게 하고, 보조 기술에 모달 대화상자로 알리며, 닫힌 뒤 포커스를 돌려주는 동작을 맡기 때문이다. 반면 넓은 화면에서 같은 요소가 항상 보이는 사이드바가 되어야 한다면 수동 popover를 사용하고, 모달 상태와 포커스 복귀 등을 코드에서 처리하도록 안내한다.
지원되지 않을 때의 동작까지 전달한다
브라우저 기능을 활용하려면 지원 조건도 구현 선택에 포함해야 한다. 이 사례는 패널의 초기 스크롤 위치를 지정하는 scroll-initial-target을 Firefox와 Safari가 지원하지 않는다고 안내한다. 해당 기능이 없으면 패널을 표시한 직후 닫힌 위치로 먼저 옮겨 놓고, 열린 위치로 스크롤하는 대체 구현을 제시한다. 이 보완이 없으면 패널이 들어오는 움직임 없이 처음부터 열린 상태로 나타난다.
Modern Web Guidance는 이런 판단을 지침 전반에 적용한다고 설명한다. 구형 브라우저가 무시해도 되는 추가 효과와, 대화상자 제어처럼 작동을 유지해야 하는 핵심 기능을 구분한다. 실험적이거나 아직 안정화 중인 기능의 지침은 검색 결과에 나타나더라도, 개발자가 명시적으로 허용해야 내용을 가져올 수 있도록 제한한다.
프로젝트의 자체 평가에서는 같은 작업을 지침이 있을 때와 없을 때 각각 수행시키고, 완성된 앱을 브라우저에서 열어 DOM과 스타일, 소스가 요구 조건을 충족하는지 검사한다. 여기서 접근성 검사도 수행하지만, 평가 페이지는 자동 검사가 접근성 요구의 일부만 다루며 전체 WCAG 준수나 수동 검사를 대신하지 않는다고 밝힌다.
메뉴 패널 사례에서 에이전트가 참고할 내용은 API 이름 하나로 끝나지 않는다. 스크롤에 움직임을 맡기는 방법, 대화상자를 닫아야 하는 시점, 사이드바로도 쓰일 때 달라지는 역할, 미지원 기능을 보완하는 방법이 함께 전달된다. Modern Web Guidance가 제공하는 것은 이런 구현 선택을 작업에 필요한 순간에 찾아볼 수 있는 지침이다.
