Material Design 3 리뷰
사용자 인터페이스를 Material Design 3(M3)에 따라 검토하고, 프로젝트 자체 가이드라인을 존중하여 사용자가 항목별로 결정할 수 있는 번호가 매겨진 보고서를 생성합니다. 그런 다음 결정을 기록하고 승인된 변경 사항을 반영합니다.
사용 시기 / 사용하지 않을 시기
다음과 같은 경우에 사용합니다.
- "이 화면/페이지/컴포넌트를 Material 3에 따라 검토해 줘", "이게 M3를 준수하나요?", "M3 감사", "디자인 리뷰"
- 터치 대상, 대비, 타입 스케일, 색상 역할, 모양, 간격 또는 기존 UI의 컴포넌트 확인
- 릴리스 전에 스크린샷이나 실행 중인 페이지를 Material 가이드라인과 비교
- 유지할 Material 편차와 수정할 편차 결정
다음과 같은 경우에는 사용하지 않습니다.
- 사용자가 새 UI 생성, 테마 구축 또는 처음부터 코드 작성을 원하는 경우 ("M3 로그인 페이지를 만들어 줘"); 이 스킬은 검토만 수행하며 생성하지 않습니다.
- 대상 디자인 시스템이 명시적으로 Material이 아닌 경우 (Apple HIG, Fluent, M3 기반이 없는 사용자 정의 시스템). 단, 사용자가 기본적인 검사만 원하는 경우는 예외입니다.
- 단일 사실 조회 질문 ("FAB 높이는 얼마인가요?")인 경우; 참조 파일에서 직접 답변하세요.
검토 중에 코드를 변경하지 마십시오. 사용자가 결정을 내린 후 요청하는 경우에만 코드를 변경하세요.
계층 및 우선순위
규칙을 다음 순서로 적용합니다. 상위 계층이 하위 계층보다 우선합니다.
- 바닥 규칙, 계층 F: 접근성 및 사용성 최소 사항 (대상, 대비, 포커스, 레이블, 텍스트 스케일링, 모션 감소). 절대 협상 불가능. 프로젝트 가이드라인도 이를 면제할 수 없습니다.
- 프로젝트 가이드라인 및 기록된 결정: 어댑터 프로토콜(
references/adapter-protocol.md)을 통해 찾습니다. - M3 핵심, 계층 C: 역할, 토큰, 타입 스케일, 모양 스케일, 컴포넌트 사양. 편차에는 명시적인 결정이 필요합니다.
- M3 표현적 및 선택적 항목, 계층 E. 부재를 결함으로 보고하지 마십시오.
프로젝트 가이드라인 또는 기록된 결정이 계층 C 또는 E 규칙과 충돌하는 경우, 위반 사항을 보고하지 마십시오. "결정 후보" 아래에 충돌을 한 번 나열하세요 (원장에 이미 기록되지 않은 경우에만). 계층 F 규칙과 충돌하는 경우, F 소견을 보고하고 증거에 충돌하는 가이드라인을 명시하세요.
허용 오차
두 가지 모드. 기본값은 inspired입니다.
strict: 모든 계층 C 불일치는 문제이며, 계층 E 항목은 제안입니다.inspired: 계층 C 불일치는 사용성에 해를 끼치지 않는 한 제안입니다 (해를 끼치면 문제가 됨). 계층 E 항목은 명확한 가치를 추가하는 경우에만 제안입니다.- 두 모드 모두 모든 계층 F 소견은 문제입니다.
사용자가 지정한 모드를 사용하세요. 프로젝트 가이드라인에 명시된 경우 해당 모드를 사용하세요. 그렇지 않으면 inspired를 사용하고 보고서 헤더에 그 사실을 명시하세요.
증거 레이블
모든 소견과 모든 참고 사항에 다음 중 정확히 하나를 레이블로 지정하세요.
measured-rendered: 렌더링된 페이지(DOM, 계산된 스타일, 히트 테스트)에서 읽음, 선택자 및 값 제공.measured-code: 소스 코드 또는 선언된 CSS에서 읽음, 렌더링된 페이지에서 확인되지 않음.measured-simulation: 시뮬레이션 (텍스트 줌을 위한 좁은 뷰포트, 다크 모드, 모션 감소 또는 강제 색상과 같은 에뮬레이션된 설정) 하에 렌더링된 페이지에서 측정. 실제 장치에서 확인할 것을 권장합니다.estimated: 이미지에서 추론.
v0.1 레이블 measured는 measured-rendered로 처리합니다. 소견이 여러 출처를 결합하는 경우 가장 약한 레이블을 사용하세요. 축척(뷰포트 너비(CSS px) 및 devicePixelRatio, 또는 알려진 참조 요소)을 알지 못하는 한 스크린샷에서 정확한 dp 또는 px 값을 명시하지 마십시오. 축척을 한 번 요청하거나 범위를 제공하고 estimated로 레이블을 지정하세요. 압축된 이미지에서 정확한 대비비를 제공하지 마십시오. 근사 비율을 제공하고 estimated로 레이블을 지정하세요.
워크플로우
단계 0. 표면 식별
주어진 자료를 통해 또는 한 번 질문하여 다음을 결정합니다.
- 검토 대상: 스크린샷, 소스 파일, URL 또는 로컬 페이지, 디자인 도구 내보내기
- 플랫폼: 웹, Android(Compose 또는 Views), Flutter, iOS, 크로스 플랫폼
- 폼 팩터 및 창 크기 클래스: 컴팩트(< 600), 미디엄(600-839), 확장(840-1199), 대형 또는 초대형
- 라이트, 다크 또는 둘 다; 고대비, 모션 감소 또는 앱 내 텍스트 크기 설정이 있는지 여부
표면에 개인 데이터(이름, 금액, 주소, 메시지, 건강 또는 계정 데이터)가 표시되는 경우, 답변 상단에 이를 명시하고 수정되거나 데모 상태를 검토할 것을 제안하세요. 스크린샷이나 페이지 데이터를 파일, 메모리 또는 원장에 저장하지 마십시오. 요소를 식별하는 데 필요한 최소한의 텍스트만 인용하세요.
단계 1. 어댑터 로드
references/adapter-protocol.md를 따르세요. 프로젝트 디자인 가이드라인, 결정 원장, 규칙 목록, 변경 목록 형식 및 검토 설정(테스트할 너비 및 텍스트 크기 설정)을 찾으세요. 찾을 수 없으면 한 번의 짧은 질문으로 한 번만 물어보세요. 사용자가 응답하지 않거나 없다고 말하면 M3만 사용하여 기본값으로 계속 진행하세요.
디자인 브리프: 브리프가 제공되거나 발견된 경우(m3-design-brief에서, 또는 승인 기준 AC-nn이 있는 모든 브리프), 이를 프로젝트 가이드라인으로 취급하세요. 해당 브리프의 결정(B-nn)은 해당 범위 내에서 기록된 결정(결정 후보가 아님)으로 간주됩니다. 허용 오차, 너비 및 테마는 검토 설정입니다. 계층 F는 여전히 우선합니다. 모든 AC를 확인하고 보고서의 "브리프 승인 기준" 섹션을 증거와 함께 (통과, 실패 또는 확인되지 않음) 작성하세요.
단계 2. 허용 오차 선택
strict 또는 inspired (허용 오차 참조). 사용자나 가이드라인이 이미 결정하지 않은 경우 물어보지 마세요.
단계 3. 측정
측정을 추정보다 선호하세요. 다음 순서로 수행합니다.
- 렌더링된 페이지 사용 가능(Playwright, 브라우저 자동화 도구, DevTools): 페이지에서
scripts/measure.js를 평가하고 해당 JSON(references/measurement.md, "실행 방법" 및 "출력 필드 및 이를 공급하는 규칙")을 사용하세요. 각 너비와 테마를 별도로 측정합니다. 어댑터의 너비 및 텍스트 크기 설정, 그렇지 않으면 컴팩트 너비(예: 390px) 및 확장 너비(예: 1280px), 라이트 및 다크. - 소스 코드만 사용 가능: CSS/HTML/JS 또는 컴포넌트 코드를 읽고, 크기, 색상 및 반경을 계산하고 결과에
measured-code레이블을 지정하세요. - 이미지만 사용 가능: 추정하고
estimated레이블을 지정하고, 정확한 숫자가 중요한 경우 축척을 요청하세요.
설정 확인, 결과를 읽기 전(measurement.md, "설정 확인"):
- 테스트하려는 CSS 너비와 함께
expectWidth를 전달하세요. warnings에viewport-meta-missing또는viewport-width-mismatch가 포함된 경우 중지하세요. 페이지가 의도하지 않은 너비(종종 980px)로 레이아웃되었으므로 모든 크기가 잘못되었습니다. 설정을 수정하고(뷰포트 설정 또는 프로덕션에서 제공하는 것과 동일한 뷰포트 메타 태그 삽입), 다시 실행한 후에만 계속하세요. 이러한 실행에서 크기를 보고하지 마십시오. 프로덕션 자체에 태그가 없는 경우 한 번 보고하세요.
유효 히트 영역(measurement.md, "유효 히트 영역"): hitScan이 켜져 있는 경우(기본값), 시각적 상자가 아닌 hitWidth x hitHeight로 대상 크기를 판단하세요. hitAreaVia는 영역이 어떻게 발견되었는지(box, label, pseudo, probe)를 나타냅니다. probe는 히트 테스트가 이를 확인했는지(ok) 또는 확인하지 못했는지(covered, offscreen, limited: 기하학만 해당, 정확한 크기를 보고하기 전에 확인)를 나타냅니다.
::before/::after로 확대된 pseudo 영역은 유효합니다. 해당 상자가 테두리로 축소되거나 overflow: hidden 조상에 의해 잘리지 않았는지 확인하고 의심스러운 경우 코드에서 확인하세요.
텍스트 스케일링의 경우 measurement.md의 "레시피: 200% 텍스트"를 따르세요(결과는 measured-simulation). 메뉴, 대화상자, 시트, 탭, 라디오 그룹 및 보기 변경의 경우 measurement.md의 "레시피: 포커스 흐름"을 따르세요.
스크립트 출력(truncated, nonTextContrast, labelInName, ariaConflicts 포함)을 평결이 아닌 후보로 취급하세요. 보고하기 전에 각각을 해당 규칙에 대해 확인하세요. 상태 스타일 및 모션은 측정되지 않습니다. 중요할 때 코드에서 또는 상호 작용을 통해 확인하세요.
스크립트가 대비를 해결할 수 없는 경우(그라데이션, 이미지 또는 반투명 배경), 최악의 경우를 수동으로 계산하고(텍스트 아래의 가장 어둡고 가장 밝은 중단점, 또는 실제 배경 위에 합성된 알파 색상) 사용된 중단점과 함께 estimated로 보고하세요. color-mix() 또는 알파 텍스트 색상의 경우 최종 합성 색상을 사용하세요. 페이지에 다크 변형이 없는 경우, 요소별로 보고하지 말고 한 번 보고하세요(테마 패리티 규칙, references/color.md 참조).
단계 4. 관련 참조만 로드
점진적 공개: 모든 참조 파일을 로드하지 마십시오. 화면에 있는 내용에 따라 선택하세요.
| 표면 포함 내용 | 로드할 파일 |
|---|---|
| 모든 표면 (항상) | references/layout-interaction-a11y.md, 먼저 "접근성 바닥" 및 "크로스 컴포넌트 규칙" 섹션 |
| 색상, 테마, 다크 모드, 토큰, 대비 | references/color.md |
| 타이포그래피, 모서리, 고도, 간격, 모션, 아이콘 | references/styles.md |
| 앱 바, 배지, 바텀 시트, 버튼 그룹, 버튼, 카드, 캐러셀, 체크박스, 칩, 날짜 선택기, 대화상자, 디바이더 | references/components-1.md |
| 확장 FAB, FAB 메뉴, FAB, 아이콘 버튼, 목록, 로딩 표시기, 메뉴, 네비게이션 바 / 서랍 / 레일, 진행 표시기, 라디오 버튼 | references/components-2.md |
| 검색, 분할 버튼, 사이드 시트, 슬라이더, 스낵바, 분할 버튼, 스위치, 탭, 텍스트 필드, 시간 선택기, 도구 모음, 툴팁 | references/components-3.md |
| 표현적 기능, 스프링 모션, 형태 변형, 또는 사용자가 표현적(Expressive)에 대해 묻는 경우 | references/expressive.md |
| 보고서 작성 | references/report-template.md |
| 결정, 규칙, 변경 목록 기록 | references/adapter-protocol.md |
큰 파일 내에서는 화면에 있는 컴포넌트의 섹션만 읽으세요. 먼저 제목을 나열하고(grep -n '^## ' references/components-1.md), 해당 줄 범위만 읽으세요(sed -n 'START,ENDp' file). 참조 파일이 누락된 경우 이를 명시하고 다른 파일로 계속 진행하세요. 공백을 채우기 위해 규칙을 발명하지 마십시오.
단계 5. 확인, 분류, 그룹화
각 후보에 대해:
- 먼저 기능에 따라 컨트롤을 분류하고(CMP-01), 그런 다음 규칙을 찾으세요. 해당 ID와
Source를 참조 파일에 정확히 인용하세요. 여러 규칙이 겹치는 경우(동일한 대상 크기에 대한 컴포넌트 규칙 및 바닥 규칙), 가장 구체적인 규칙을 인용하고 그 뒤에 다른 규칙을 나열하세요("또한 A11-01"). - 규칙 ID가 이를 뒷받침하지 않는 경우 M3 소견으로 보고하지 마십시오. 프로젝트 가이드라인 또는 참조 파일에서 다루지 않는 WCAG 2.2 성공 기준을 위반하는 경우 "프로젝트 및 WCAG 참고 사항"(
N-01...)에 가이드라인 섹션 또는WCAG 2.2 SC x.y.z를 출처로 표시하여 넣으세요(일반적인 경우: 누락된lang속성, 확대/축소를 비활성화하는 뷰포트 메타 태그). 그렇지 않으면 생략하세요. - 원장 확인: 기록된 편차는 다시 보고되지 않습니다(한 줄에 억제된 항목 수를 언급).
- 프로젝트 가이드라인 확인: 계층 C 또는 E와의 충돌은 "결정 후보"로 이동하며 소견으로 이동하지 않습니다. 프로젝트 선택에 이탈할 M3 규칙이 없는 경우 후보는 Rule ID
none (project convention)을 사용합니다. - 허용 오차에 따라 분류: 계층(F, C, E) 및 종류(issue 또는 suggestion).
inspired모드에서 계층 C 불일치가 "사용성에 해를 끼치는" 경우(issue가 됨)는 일반 사용자가 콘텐츠를 읽기 어렵게 만들거나, 작동하기 어렵게 만들거나, 모호하게 만드는 경우에만 해당합니다: 12px 미만의 텍스트, 목적이나 상태가 불분명한 컨트롤, 지원되는 너비에서 깨지는 레이아웃. 그렇지 않으면 suggestion입니다. - 그룹화: 근본 원인당 하나의 소견. 동일한 문제가 여러 위치에 나타나거나 하나의 공유 컴포넌트, 클래스 또는 토큰에서 발생하는 경우, 한 번 보고하고 개수 및 모든 발생(또는 두세 가지 예와 총계: "32 x 32 px의 14개 아이콘 버튼, 예:
.toolbar button,#close")을 포함하여 단일 결정이 적용되도록 하세요. 수정 사항이 있는 영역에 소견을 넣으세요.
영향별로 정렬: 계층 F 문제가 먼저, 그 다음 작업 완료에 영향을 미치는 문제, 그 다음 계층 C 문제, 그 다음 제안. 그룹 내에서는 도달 범위(영향을 받는 요소 또는 화면 수)별로 정렬하세요. 보고서를 약 25개 소견으로 제한하세요. 더 많은 경우 생략된 수를 말하고 두 번째 패스를 제공하세요.
문제가 거의 없거나 전혀 없는 경우 명확히 말하세요. 칭찬을 추가하지 마십시오. 보고서를 채우기 위해 문제를 만들어 내지 마십시오.
단계 6. 제시
references/report-template.md를 정확히 사용하세요. 각 소견에는 다음이 포함됩니다: 실행 ID(F-01, 계층 아님), 영역, 계층 및 종류, 증거(선택자 또는 이미지 영역, 값, 증거 레이블, 발생 횟수), 출처가 포함된 규칙 ID, 중요한 이유(한 줄, 사용자 영향 우선), 구체적인 제안 변경 사항(min-height: 48px, color: var(--md-sys-color-on-surface-variant), "모서리 매우 큼, 28dp"; "대비 개선"은 안 됨), 노력(S: 하나의 속성 또는 토큰, M: 하나의 컴포넌트 또는 여러 파일, L: 구조적 또는 화면 간) 및 결정 상자.
보고서 헤더에는 다음이 명시됩니다: 검토된 표면 및 너비, 허용 오차, 참조 스냅샷 날짜(로드된 참조 파일 헤더 중 가장 오래된 "스냅샷 날짜"), 프로젝트 가이드라인 및 원장이 발견되었는지 여부, 증거 혼합(네 가지 레이블 각각에 대한 개수). 브리프가 있는 경우, 규칙을 위반하는 실패한 AC는 소견(또는 참고 사항)이기도 합니다. 해당 AC 행은 증거를 반복하는 대신 해당 F-nn/N-nn을 가리킵니다.
최신성: 스냅샷 날짜를 오늘 날짜와 비교하세요. 6개월 이상 지났거나 사용자가 최신 Material 릴리스를 언급하는 경우, 헤더에 그 사실을 명시하고, 계층 C 변경을 구현하기 전에 참조를 새로 고칠 것을 권장하고(리포지토리의 maintenance/UPDATING.md), 먼저 https://m3.material.io/ 에서 영향을 받는 규칙을 확인하겠다고 제안하세요. 계층 F 소견은 스냅샷 연령에 관계없이 유효합니다.
단계 7. 결정 적용
사용자가 응답할 때(예: "F-01에서 F-05, F-07 수락: 브랜드 알약 버튼, 나머지는 거절"):
- 계층 C 또는 E 규칙에 대한 각
deviation에 대해:references/adapter-protocol.md형식으로 결정 원장에 항목 하나를 추가합니다(날짜, 규칙 ID, 범위, 한 줄 근거, 소견 ID). 계층 F 소견은 편차가 될 수 없습니다.accepted risk로 기록하고 요약 줄에 계속 보고하세요. 원장이 없으면 경로를 제안하고 사용자가 동의한 후에만 생성하세요. - Rule ID가
none인 각 결정 후보에 대해: ...
(참고: 원문이 잘렸으므로, 원문의 전체 내용이 복원되면 해당 부분도 번역하여 포함해야 합니다.)