Hideki-Kobayashi/apply-digital-agency-design-system

디지털청 디자인 시스템 적용하기

승인된 공식 마크다운 스냅샷에서 요청에 필요한 근거만 선택하여 적용합니다. 일반 작업과 공식 업데이트 확인을 분리하고, 업데이트 후보는 사용자의 승인 없이 활성화하지 않습니다. 이후 <skill-root>는 이 SKILL.md가 위치한 디렉토리의 절대 경로로 대체합니다. 이후 <python>은 Python 3.10 이상을 실행할 수 있는 명령어로 대체합니다. macOS와 Linux에서는 보통 python3, Windows에서는 보통 py -3을 사용합니다.

정보의 경계

• references/source-manifest.json이 가리키는 active_snapshot.path를 일반 작업에서 사용하는 유효 스냅샷으로 합니다.
• 유효 스냅샷의 source-index.json, references/task-index.md, references/foundation-map.md는 파생 자료입니다. 공식상의 의미는 유효 스냅샷 내 해당 마크다운에서 확인합니다.
• 공식 마크다운은 AI 참조용 재구성물이며, 공식 사이트의 완전한 대체물이 아닙니다. 로컬 자료에 필요한 기술이 없는 경우, 미확인 사항으로 보고합니다.
• 이 Skill은 비공식이며, 디지털청의 제공, 승인, 제휴 또는 추천을 나타내지 않습니다.
• 기존 프로젝트의 현재 값은 CSS 변수, 테마 설정, 공통 스타일, 공통 컴포넌트에서 확인합니다. Skill 내로 복제하지 않습니다.
• 생성, 변경, 리뷰는 조작 권한의 분류입니다. 신규 생성, 기존 수정, 개별 컴포넌트는 자료 선택의 분류로 하며 혼동하지 않습니다.

시작 시 업데이트 기한 판정

먼저 다음 명령어를 실행합니다. 이 명령어는 로컬 파일만 읽고 네트워크에 연결하지 않습니다.

<python> <skill-root>/scripts/manage_upstream.py status

출력의 status를 status_at_start로 하여, 해당 요청 중에는 유지합니다.

• fresh: 업데이트 안내를 내지 않고 일반 작업을 계속합니다.
• due, never_checked, unknown: 일반 작업을 멈추지 않고 종료 시 상태를 재확인합니다.
• 사용자가 처음부터 "최신 버전을 확인해 주세요" 등으로 명시한 경우: 명시 요청을 외부 확인 동의로 간주하여 유지보수 절차로 진행합니다.

기한은 last_successful_check_at으로부터 30일로 판정합니다. 제안 일시, 실패 일시, 파생된 다음 확인일은 기한의 시작점으로 하지 않습니다.

일반 작업

1. 요청을 생성, 변경, 리뷰로 분류하고 허용된 조작 범위를 확정합니다.
2. 대상의 기술 구성, 기존 스타일, 브랜드 제약, 화면 구조를 확인합니다.
3. 다음 우선순위로 자료 선택 경로를 결정합니다.
   • 대상이 하나의 UI 부품과 그 상태로 제한되는 경우, 개별 컴포넌트로 합니다.
   • 공통 스타일이 이미 존재하는 경우, 기존 수정으로 합니다.
   • 그 외에는 신규 생성으로 합니다.
4. references/task-index.md에서 대상 문서를 선택합니다. 해당되지 않는 경우, 다음 명령어로 유효 스냅샷을 검색합니다.

<python> <skill-root>/scripts/search_guidance.py \
  --query '<검색어를 공백으로 구분>' \
  --manifest-file <skill-root>/references/source-manifest.json

5. 자료 선택 경로에 따라 references/foundation-map.md를 사용합니다.
   • 신규 생성: 8분류를 채택, 대상 외, 보류로 나누고 값을 결정할 분류의 공식 마크다운을 읽습니다.
   • 기존 수정: 기존 값을 먼저 조사하고 영향받는 분류만 읽어 유지, 이전, 의도적 이탈로 나눕니다.
   • 개별 컴포넌트: 기존의 공통 기준, 대상 컴포넌트, 영향받는 기본 디자인만 읽습니다. 공통 값을 부품 내에서 다시 결정하지 않습니다.
6. 공식의 선택지, 기본값, 예제, 원칙, 요구사항, 고정값을 구분하고 채택 값과 근거를 대응시킵니다.
7. 기존의 기술 구성으로 구현합니다. 공식 예제를 일률적인 고정값으로 적용하지 않고, 공식 요구사항을 외형 선호도로 완화하지 않습니다.
8. 대상에 따라 여러 화면 너비, 키보드 조작, 포커스, 상태 변화, 확대, 리플로를 확인합니다.
9. 리뷰 요청에서는 파일을 변경하지 않고 근거가 있는 지적만 반환합니다.

일반 작업 완료 보고

다음을 간결하게 보고합니다.

• 참조판: source-manifest.json의 스냅샷 ID, 디지털청 디자인 시스템판, 마크다운 공개일.
• 확인 범위: 읽은 공식 문서와 실행한 확인.
• 미확인 사항: 실기기, 보조 기술, 외부의 현재 페이지 등 확인하지 않은 범위.
• 이탈: 프로젝트 고유의 이유로 공식 예제 또는 권장사항에서 변경한 내용.

시작 시 상태가 due, never_checked, unknown인 경우에만 보고 직전에 status를 재실행합니다. 다른 처리로 fresh가 되지 않은 경우, 최종 보고의 끝에서 한 번만 업데이트 확인을 제안합니다.

이전 공식 업데이트 확인 후 30일 이상 경과했습니다. 이번 작업은 승인된 현재 버전으로 완료했습니다. 업데이트 확인도 진행하시겠습니까?

never_checked 또는 unknown에서는 경과 일수를 단정하지 않고 이유를 제시합니다. 제안만으로는 외부 통신도 상태 업데이트도 수행하지 않습니다. 사용자가 거절한 경우도 거절 일시를 저장하지 않으므로, 성공 확인까지 다음 번에도 제안합니다.

공식 업데이트 확인

사용자가 동의한 경우에만 다음을 실행합니다. --network-approved는 사용자의 동의를 확인한 후에만 붙입니다. 30일 미만이라도 명시적으로 최신 버전을 확인하는 경우 --force를 추가합니다.

가져오기 백엔드는 기본 auto에 맡깁니다. auto는 ax가 발견되면 공식 페이지 가져오기, 링크 추출, ZIP 저장을 ax에 맡기고, 발견되지 않으면 Python 표준 라이브러리를 사용합니다. ax는 권장되지만 임의이며, 도입을 업데이트 확인의 전제로 하지 않습니다. ax 경로는 리다이렉트 후의 최종 URL을 검증하지만, 중간의 전송 대상을 통신 전에 검증할 수 없습니다. 전송 대상도 사전 제한할 필요가 있는 경우 --fetch-backend stdlib를 사용합니다. 한 번 선택한 백엔드가 실패해도 다른 백엔드로 암묵적으로 전환하지 않습니다. 가져오기 후 URL, 용량, ZIP 형식 확인, 해시 계산, 차이 생성, 상태 저장은 Python으로 수행합니다. 동작 확인 등으로 방식을 고정하는 경우에만 --fetch-backend ax 또는 --fetch-backend stdlib를 추가합니다.

<python> <skill-root>/scripts/manage_upstream.py check \
  --network-approved

• unchanged: 확인 성공 일시를 업데이트하고 가져오기 백엔드와 변경 없음을 보고합니다.
• candidate_created 또는 candidate_exists: 가져오기 백엔드, 후보 ID, 가져온 출처, 해시, 추가, 변경, 삭제 건수를 보고합니다.
• skipped_fresh: 30일 미만이므로 외부 확인을 생략했다고 보고합니다.
• 실패: last_successful_check_at과 유효 스냅샷을 변경하지 않고 실패한 가져온 출처와 이유를 보고합니다.

외부 확인 동의를 후보 채택의 승인으로 간주하지 않습니다. 후보가 발견되어도 공식 소스 확인과 후보 저장이 완료되었다면 확인 성공 일시는 업데이트합니다.

ZIP 수동 가져오기

자동 가져오기가 결국 실패하고 check가 공식 ZIP URL까지 특정하여 수동 가져오기를 안내할 수 있는 경우에만 이 절차를 최후의 수단으로 제안합니다. URL을 특정하기 전에 실패한 경우 URL이나 파일명에서 가져온 출처를 추측하지 않고 실패만 보고합니다.

다음 내용을 사용자에게 제시합니다.

ZIP 자동 가져오기에 실패했습니다. 다음 공식 URL에서 수동으로 가져올 수 있습니다.
<공식 ZIP URL>

ZIP은 임의의 폴더에 저장해 주세요. 저장 후 파일명까지 포함한 절대 경로를 알려주세요.
받은 ZIP은 네트워크에 연결하지 않고 검증하여 업데이트 후보로 저장합니다. 유효 버전으로 전환은 별도로 확인합니다.

사용자로부터 절대 경로를 받으면 다음을 실행합니다. 상대 경로만 알고 있는 경우 절대 경로를 확인한 후 실행합니다.

<python> <skill-root>/scripts/manage_upstream.py import-archive \
  --archive-file '<ZIP의 절대 경로>'

import-archive는 실패 시 기록한 공식 URL에 로컬 ZIP을 연결하고, 네트워크에 연결하지 않고 일반적인 용량, ZIP 형식, 내부 경로, 마크다운 집합, 해시 검증 및 후보화를 수행합니다. 원본 ZIP을 변경하거나 삭제하지 않습니다. 로컬 가져오기는 외부 확인 성공으로 간주하지 않으며 last_successful_check_at과 확인된 계약 버전을 업데이트하지 않습니다. 결과가 candidate_created 또는 candidate_exists여도 자동으로 승격하지 않고 "업데이트 후보 평가와 승격"으로 진행합니다.

공식 URL 특정으로부터 30일을 초과했거나 업데이트 계약이 변경된 경우 가져오기를 우회하지 않고 새로운 업데이트 확인 동의를 구합니다. 수동 가져오기나 로컬 가져오기에 실패해도 last_successful_check_at과 유효 스냅샷을 변경하지 않습니다.

업데이트 후보 평가와 승격

1. 후보 내의 candidate-manifest.json과 diff-summary.json을 읽습니다.
2. verify_snapshot.py로 후보를 검증합니다.

후보의 기본 저장 위치는 사용자별 상태 디렉토리 내의 candidates입니다.

<python> <skill-root>/scripts/verify_snapshot.py \
  --snapshot-dir <state-dir>/candidates/<후보ID>/snapshot \
  --index-file <state-dir>/candidates/<후보ID>/source-index.json

3. 추가, 변경, 삭제된 공식 문서를 읽고 task-index.md와 foundation-map.md에 미치는 영향을 확인합니다.
4. 대표적인 생성, 수정, 리뷰 요청을 구버전과 후보 버전으로 시도합니다.
5. 후보 ID, 의미 변화, 파생 자료 변경, 확인 결과를 사용자에게 제시하고 채택을 명시적으로 확인합니다.
6. 사용자가 후보 ID를 지정하여 승인한 후에만 다음을 실행합니다.

<python> <skill-root>/scripts/manage_upstream.py promote \
  --candidate-id '<후보ID>' \
  --human-approved

승격 후에도 직전 스냅샷을 삭제하지 않습니다. 승격 작업에서는 last_successful_check_at을 변경하지 않습니다.

판단 규칙

• MANIFEST.md를 파일 목록의 정본으로 하지 않습니다. 모든 마크다운을 검사합니다.
• 문서 ID에는 정규화된 source_url을 사용합니다. slug는 본문과 업데이트 이력에서 중복되므로 단독 ID로 하지 않습니다.
• 찾을 수 없는 컴포넌트, 토큰, 클래스명을 공식 사양으로 만들지 않습니다.
• 기존 값과 공식 요구사항이 충돌하는 경우, 묵시적으로 유지 또는 대체하지 않고 영향과 수정 범위를 제시합니다.
• 화면 확인만을 근거로 디지털청 디자인 시스템 또는 WCAG에 대한 완전 적합을 선언하지 않습니다.
• 공개물에 출처를 기재하는 경우 유효 스냅샷의 introduction/notices/index.md를 읽습니다.
• 업데이트 상태와 후보는 사용자별 로컬 영역에 저장하고 Skill 본체의 배포 파일과 혼재시키지 않습니다. 저장 위치를 변경하는 경우에만 환경 변수 DADS_SKILL_STATE_DIR을 사용합니다.