design-html은 승인된 HTML 설계를 앱에 옮길 때 마크업과 CSS를 보존하고, 브라우저에서 실제 차이를 확인하도록 돕는 초기 단계의 CLI와 HTML 플레이그라운드다. 명시적으로 정의한 UI 상태와 뷰포트를 기준으로 DOM, 스타일, 요소 위치 등의 차이를 보고한다.

저장소의 examples/compare.html을 브라우저에서 열면 Reference, Corrected, Intentional drift 세 가지 구현을 비교할 수 있다. 체크아웃 화면과 스포츠 인터페이스를 고르고 휴대전화·태블릿·데스크톱 뷰포트를 선택할 수 있다. GitHub에서는 HTML 소스만 보이며 플레이그라운드는 실행되지 않는다. 스포츠 예시는 가상의 팀·점수·시간을 사용하며, Scorecrowd에서 얻은 교훈을 보여줄 뿐 실제 앱의 화면이나 검증 결과는 아니다.

현재 Node.js LTS와 npm이 필요하다. 저장소를 복제한 뒤 다음 명령으로 예시를 준비한다. npm 레지스트리에 배포된 패키지에 의존하는 안내는 아니다.

bash
git clone https://github.com/giminycricket0-blip/design-html.git
cd design-html
npm ci
npx playwright install chromium --only-shell

예시는 서버, API 키, 외부 폰트 없이 브라우저에서 열 수 있다. 검증기의 의도적 실패 시연은 다음 명령으로 실행한다.

bash
npm run demo:verify

이 명령은 검증기가 예상한 이유로 실패하고, 심어 둔 결함 네 가지를 모두 잡아야 성공한다. 결과 보고서는 .design-html-drift.json에 저장된다. 결함에는 안쪽 여백을 16px에서 20px로 바꾸는 경우, 로딩 버튼 높이를 40px에서 44px로 키우는 경우, aria-busy 속성을 빼는 경우, 오류 배너 배경색을 잘못 지정하는 경우가 포함된다. 보고서는 잘못된 여백과 자식 요소의 4px 위치 차이, 렌더링 높이 불일치, 빠진 속성, 색상 불일치와 일치하는 var(--color-danger-bg) 토큰을 표시한다.

반응형 화면과 새로고침, 대화상자 닫기 동작을 확인하려면 다음 명령을 사용한다.

bash
npm run demo:scorecrowd
npm test

스포츠 예시는 390×844, 768×1024, 1440×900 뷰포트와 새로고침, 대화상자 닫기, 포커스 복원, 동작 줄이기 설정을 고려한 동작을 확인한다. 수정된 예시는 변경하지 않은 기준 화면과 비교해 통과해야 한다.

설계와 앱 구현 비교

프로젝트는 승인된 마크업·CSS·상태를 DESIGN.html에 유지하고, 앱에서는 DOM 구조와 CSS 값, 토큰, 자산을 보존한 채 프레임워크의 상태와 이벤트를 연결하는 방식을 제안한다. 각 data-ui-id와 data-ui-state 쌍, DOM 계층, 표현을 유지하고, ?ui_state=loading, error 등 선언한 상태를 재현할 수 있는 테스트 화면을 마련해야 한다. 합의한 뷰포트와 상태를 기준으로 앱을 검사하며, 차이가 생기면 기준 화면을 약화하는 대신 앱을 수정한다.

아래는 문서에 제시된 로딩 상태 버튼의 예다.

html
<button data-ui-id="checkout-submit" data-ui-state="loading"
 class="checkout-button" disabled aria-busy="true">
 Processing…
</button>

기준 화면이 있는 폴더에서 CLI를 실행한다. 다른 프로젝트에서는 복제한 CLI의 절대 경로를 사용한다.

bash
# In another project, use the absolute path to this cloned CLI.
node /path/to/design-html/bin/cli.mjs init
node /path/to/design-html/bin/cli.mjs open
node /path/to/design-html/bin/cli.mjs extract checkout-card --viewport 390x844
node /path/to/design-html/bin/cli.mjs verify http://localhost:3000/checkout --viewport 390x844

init은 기존 기준 화면을 보존하고 에이전트 안내 기능을 설치한다. AGENTS.md, CLAUDE.md, 기존 .cursorrules에서 표시된 규칙 블록을 추가하거나 갱신하되 주변 지침은 유지한다. 앱에 백엔드나 인증 상태를 만들어 주지는 않으므로, 앱 쪽에서 대응하는 테스트 화면을 제공해야 한다.

검증기는 아이콘 누락, 태그·자식 순서·SVG 경로·문구 변경, disabled와 aria-busy 같은 의미 속성 누락, 글꼴·여백·테두리·색상·그림자·넘침 변경, 요소의 너비·높이·부모 기준 위치 차이를 검사한다. 예상값에 맞는 루트 CSS 변수도 안내하며, 모호한 경우에는 이를 명시적으로 남긴다. 상태 누락, 중복 대상, 빈 선택도 실패로 처리한다. 각 실패에는 요소 경로, 예상값과 실제값, 선택한 뷰포트, 기준 HTML 해시가 기록된다. 자세한 내용은 검증 안내서에서 확인할 수 있다.

저장소에는 에이전트가 기준 화면 작성, 표현 이식, 동작 연결, 결과 확인을 따르도록 안내하는 Prototype to App 스킬도 포함돼 있다. 관련 안내는 상태와 뷰포트 미리보기 작성, React·Vue·Svelte·Angular 동작 연결, 검증 조건 설정, 네이티브 앱 적용을 다룬다. init을 앱의 루트에서 실행하면 스킬을 .agents/skills/prototype-to-app/에 복사하고 에이전트 지침에서 해당 경로를 가리킨다. 반복 실행해도 설치된 스킬과 로컬 수정은 보존한다. 다만 불완전한 규칙 블록이나 충돌하는 스킬 경로가 있으면 수동 해결을 위해 초기화를 중단한다.

이 도구는 초기 단계의 CLI와 HTML 플레이그라운드이며, 예시는 HTML끼리 비교한다. React 자동 변환, 영구 주석, 코딩 하네스와의 직접 연동은 향후 작업이다. 일반 검증기는 Chromium과 정해진 속성 목록, 1px의 기하 오차 허용치를 사용한다. 모든 CSS 속성이나 이미지 픽셀, 의사 요소, 섀도 트리, 모든 상호작용을 검사하지는 않는다. 동작 검증에는 스포츠 예시처럼 명시적인 테스트 여정이 필요하며, 검사 통과는 확인한 상태와 뷰포트에만 해당한다. 모든 환경에서 시각·동작·네이티브 앱이 동일하다는 보장은 아니다.

추가 자료는 Scorecrowd 사례 연구, 저장소 규칙에서 볼 수 있다. 기여 제안은 기준 화면을 보존하고, 실패와 통과를 확인할 수 있는 구체적인 사례를 추가하는 방식이다.