HTML Artifacts
디스크에서 열고 오프라인에서 동작하는, 사람이 읽을 수 있는 단일 .html 파일을 제공합니다. 일본 디지털청 디자인 시스템(DADS) 문서 어댑터(번들 제공)를 사용하며, CDN이나 프레임워크는 사용하지 않습니다. 에이전트가 읽을 소스는 Markdown으로 유지합니다. 이 어댑터는 비공식 문서 어댑터이며, 모든 DADS 컴포넌트를 완전히 구현한 것은 아닙니다.
절차
1. 독자와 소스 이해하기
구조를 선택하기 전에 주제, 대상, 목적, 근거를 파악합니다. 계획서의 경우 목표, 완료 증거, 제약 사항, 체크포인트, 위험을 보존합니다. 설명적인 제목, 짧은 오리엔테이션, 출처/날짜 정보를 포함합니다. 유용한 경우에만 목차(TOC)를 추가하며, 섹션 수나 다이어그램을 강제하지 않습니다.
처음부터 설명하기: 구체적인 상황과 주제가 하는 일부터 시작한 후, 기술적 명칭을 소개합니다. 첫 사용 시 전문 용어를 정의하고, 각 단계는 하나의 아이디어만 담으며, 그림은 설명이 산문보다 더 명확할 때만 사용합니다. 비유는 연결점과 한계를 명시적으로 설명할 때만 사용하며, 어린이를 대상으로 하지 않는 이상 성인 대상의 직접적인 어조를 유지합니다. 초보자가 무슨 일이 일어나는지, 왜 그런지, 그리고 다음에 무엇을 해야 하는지 이해할 수 있어야 합니다.
2. 기계적으로 빌드하기 — CSS를 다시 입력하지 않음
build.md를 읽습니다. 이 파일의 위치에서 스킬 디렉토리를 확인하며, 현재 프로젝트 작업 디렉토리를 기준으로 하지 않습니다. Python 3.10+ 사용:
python /absolute/path/to/html-artifacts/scripts/build.py /absolute/path/to/output.html --title "주제"
빌더는 assets/template.html을 읽고, assets/dads.css와 assets/print.js의 전체를 임베드하며, 오프라인 Content Security Policy(CSP)를 삽입합니다. 기존 파일이 있으면 덮어쓰지 않습니다. 다운로드, 패키지 설치, 서버, 번들러, 별도 에셋 폴더가 필요하지 않습니다. 이 저장소에서는 Python 러너(uv run python도 동작)를 사용합니다.
3. 콘텐츠 편집, 기반은 유지하기
생성된 파일을 편집합니다. 시작 템플릿의 설명 콘텐츠, 출처 정보, 목차를 교체하고 불필요한 섹션을 제거합니다. style#dads-css, script#dads-print, CSP, charset, viewport, only light color-scheme 메타데이터는 그대로 유지합니다.
- 인라인 SVG 및 임베디드 래스터 이미지만 사용합니다. 원격/로컬 스타일시트, 스크립트, 폰트, 이미지, iframe, import, fetch, 분석 의존성은 사용하지 않습니다. 일반 소스 하이퍼링크는 웹을 가리킬 수 있으며, 로컬 소스 파일은 깨진 상대 링크 대신 텍스트로 표시합니다.
- 시맨틱 HTML과 번들된 클래스/토큰을 사용합니다. 클래스 API, 공식 출처, 로컬 적응 사항은 dads.md를 참조합니다. 업스트림
data-type/data-sizeAPI와 이 어댑터의 수정자를 혼용하지 마십시오. - SVG를 추가하기 전에 diagrams.md를 참조합니다. 각 의미 있는 다이어그램에는 제목, 설명, 레이블, 텍스트 대안이 있어야 합니다. 넓은 다이어그램은 레이블이 있고 키보드로 포커스 가능한
.dads-diagram-scroll영역에 배치합니다. - 설치된 폰트 폴백을 사용하며, Noto가 없어도 텍스트가 숨겨지지 않아야 합니다.
lang을 콘텐츠 언어와 일치시킵니다. 본문은 1rem/1.7(기본 설정에서 16px)입니다. 브라우저 확대/축소 및 리플로우를 보존합니다. - 기본적으로 링크와 기본 공개(disclosure) 요소를 사용합니다. 공개 요소는 초기에
open상태로 유지하여 스크립트 없이 인쇄해도 콘텐츠가 보존되도록 합니다. 번들 스크립트는 인쇄 시 독자가 접은 공개 요소를 열고 인쇄 후 복원합니다. 탭, 작동하지 않는 버튼, 임의의 JavaScript, 이벤트 핸들러 속성을 추가하지 마십시오. - 어두운 OS 설정에서 밝게 유지: 이 어댑터는 검증된 공식 어두운 팔레트가 없습니다. 페이지 배경만 반전시키거나 임의의 어두운 토큰 세트를 만들지 마십시오. forced colors와 reduced motion을 존중합니다.
- 기존 컴포넌트를 선호합니다. 필수적인 경우, 소규모 문서별 규칙은 별도의 인라인
<style>에 작성하며, 새 클래스는artifact-*형식이어야 하며 해당 스타일 블록에 정의가 있어야 합니다. 알려진 토큰을 사용하고, 번들 CSS를 재정의하거나 변경하지 마십시오. 브라우저에서 이 규칙들을 확인하십시오. 정적 검증은 CSS 파서나 대비 감사가 아닙니다.
4. 최종 자체 점검 — 전달 전에 오류 수정하기
마지막 편집 후 다음을 실행합니다:
python /absolute/path/to/html-artifacts/scripts/check.py /absolute/path/to/output.html
그런 다음, 가능하면 네트워킹을 비활성화한 상태에서 브라우저로 실제 파일을 확인합니다:
- 콘텐츠: 시작 템플릿의 산문/플레이스홀더가 제거되었음; 요청된 근거, 출처, 날짜, 다음 작업이 남아 있음. 다이어그램 설명을 독립적으로 읽었을 때 의미가 전달되어야 함.
- 오프라인: 리소스 요청, 실패한 에셋, CSP 위반, 콘솔 오류가 없음. 소스 하이퍼링크는 내장 의존성이 아닌 탐색 링크임.
- 모바일/데스크톱: 390px 및 1280px에서 스크린샷 검사; 추가로 320px/200% 텍스트 크기에서 리플로우 확인. 페이지 전체 가로 오버플로우 없음; 레이블이 지정되고 포커스 가능한 코드/테이블/다이어그램 영역만 스크롤 가능. 실제 일본어 글리프와 긴 URL 검사.
- 키보드/상태: 스킵 링크와 TOC를 따라가고, 스크롤 영역으로 탭 이동, 공개 요소 토글, 가시적 포커스 및 버튼-링크 대비(방문/호버 포함) 검사. 색상만으로 의미를 전달하지 않음.
- 어두운 모드/인쇄: 어두운 선호 설정 에뮬레이션(페이지는 밝은 상태로도 읽을 수 있어야 함), 공개 요소가 닫힌 상태로 인쇄, 본문이 인쇄되는지 확인, 넓은 테이블/코드 및 페이지 나누기 확인. JavaScript 없이 콘텐츠를 보존하기 위해 공개 요소는 초기에 열린 상태로 유지.
체커는 번들 에셋/정책 계약, 알려진 클래스/토큰, 보수적인 오프라인 리소스 규칙을 적용합니다. CSS 구문, 레이아웃, 대비, 접근성, 임의 HTML의 정확성을 증명하지 않습니다. 브라우저를 사용할 수 없는 경우, 어떤 시각적/상호작용 검사가 검증되지 않았는지 명시하십시오. 정적 검사만으로 스크린샷을 주장하지 마십시오.
5. 전달하기
소스 파일 옆 또는 작업 디렉토리에 주제 이름으로 저장합니다(계획서의 경우 PLAN.html). 아티팩트 링크와 주요 제한 사항을 반환하며, 문서 사본이나 두 번째 일반 자체 감사 결과는 반환하지 않습니다.
SSH/다른 기기의 경우 remote-preview.md를 따릅니다. 원격 경로 또는 xdg-open은 유용한 보기 전달 방식이 아닙니다. 격리된 복사본만 제공하고, 공유 승인된 콘텐츠에 대해서만 공개 터널을 사용하며, 그 외에는 SSH 포워딩/접근 제어를 사용하고 정리 지침을 제공합니다. 원본 HTML은 오프라인 안전 상태를 유지합니다.
리소스
assets/template.html,assets/dads.css,assets/print.js: 기계적으로 임베드되는 소스.scripts/build.py,scripts/check.py: 표준 라이브러리 기반 빌드 및 최종 계약 검사.- build.md: 편집 패턴 및 문제 해결.
- dads.md: 공식 출처, 토큰, 어댑터 컴포넌트 API.
- diagrams.md: 읽기 쉬운 인라인 SVG 패턴.
- remote-preview.md: 안전한 원격 전달.
처음부터 설명하기 접근 방식은 ELI5 스킬에서 영감을 받았습니다.