원문: https://github.com/facebook/astryx/wiki/Component-Audit-Rubric · 번역 기준: 2026-09-03
Version 1.15.1; 이것이 무슨 의미이고 무엇이 바뀌었는지는 Versions를 참고하세요.
이 페이지는 Astryx 컴포넌트의 품질을 판단하기 위한 체크리스트이자, 그 판단을 추적 가능한 점수로 바꾸는 방법입니다. 전체를 다 실행하는 일은 거의 없습니다. 아래에서 자신의 상황을 찾아 안내하는 곳으로 가세요.
| 당신은… | 할 일 | 위치 |
|---|---|---|
| Pull request를 리뷰 중 | 컴포넌트가 아니라 변경을 판단합니다. 얼마나 검사할지는 버그 수정인지, 새 기능인지, 새 컴포넌트인지에 따라 다릅니다 — 다음 섹션 참고. | Reviewing a change |
| 컴포넌트 전체를 채점 중 — 누군가 "이거 얼마나 좋아?"라고 물었거나, hardening 중 | 체크리스트 전체를 작업하고, 스크린샷을 캡처하고, 결과를 기록합니다. | Grading a whole component |
컴포넌트를 lab에서 core로 이동 중 |
가장 엄격한 pass입니다. 이 체크리스트가 존재하는 이유인 gate입니다. | Promoting to core |
| nightly 자동화 pass | 기계가 확정할 수 있는 검사만; 판단이 필요한 것은 실패 처리하지 않고 보고합니다. | The nightly pass |
| 규칙 하나만 찾아보는 중 | 아래 11개 섹션이 검사 항목을 담고 있고, 각각 리뷰에서 인용할 수 있는 id가 있습니다. | The checks |
점수가 작동하는 방식, 한 문단으로. 각 섹션은 5, 3, 1이 어떤 모습인지 서면으로 기술된 기준에 비추어 5점 만점으로 채점된 뒤, 가중치를 적용해 100점 만점의 총점과 A–F 문자 등급이 됩니다. 발견 사항은 blocking(이대로 배포하면 무언가 깨짐), should-fix(실제 부채, 사유를 명시하면 배포 가능), nit 중 하나입니다. 열린 blocking 발견 사항이 하나라도 있으면 나머지가 아무리 좋아도 등급은 C로 제한됩니다. 이 숫자는 craft가 아니라 bar까지의 거리를 측정하므로 — 항상 옆의 blocking 개수를 함께 읽고, 그것을 고치면 무엇을 얻는지 말하세요. 자세한 내용은 Scoring에 있습니다.
점수가 사는 곳. 이 위키의 component-scores.json — ledger는 서비스가 아니라 편집해서 push하는 파일입니다. 결과 기록은 audit 수행의 일부입니다 — Recording an audit을 참고하세요. 어떤 pull request도 점수로 gate되지 않습니다.
이 체크리스트는 우리가 리뷰하는 방법입니다. 정책은 repo 안의 현행 authority record가 관장하며, 링크된 위키 페이지는 실용적 설명과 워크시트입니다. 아래의 모든 검사는 출처를 인용하므로 발견 사항을 관장 기록이나 보조 지침까지 추적할 수 있습니다.
| 지침 또는 기록 | 역할 |
|---|---|
| API Conventions | Prop 및 컴포넌트 네이밍, required vs optional, composition vs config, prop surface 계약 |
| Theming Infrastructure | Token, 테마 target, cascade, custom variant, on-media 테마 |
| Design Conventions | Spacing, radius, size, type, 색, elevation, motion, 승인된 상태 비주얼 |
| Accessibility Checklist | 현행 접근성 요구 사항 적용을 위한 소비자/기여자용 실용 워크시트 |
| AST-009 assistive-technology verification | 실제 AT/브라우저 증거가 언제 요구되는지, 무엇을 증명하는지, pending receipt가 언제 stable 릴리스를 block하는지 |
| Component Lifecycle | Specify → build → harden, 그리고 그 사이의 gate |
| Component Specification Protocol · API Arbitration | 새 컴포넌트와 그 API가 결정되는 방법 |
| Component Hardening Protocol | Layer 3 human design review와 그 form |
| Component Authoring Guide | 파일 구조, StyleX 패턴, token 사용 |
| Night Watch Component Auditor | 누가 nightly pass를 실행하는지, 어떻게 |
| Contributing with AI Assistants | 에이전트와 함께 이 repo에서 작업하기 |
그 페이지들과 이 페이지가 충돌하면, 규칙이 무엇인지에 대해서는 그쪽이 이기고, 어떻게 검사하고 채점하는지는 이 페이지가 이깁니다. 모순을 발견하면, 그쪽에서 고치고 여기에 알려주세요.
Pull request에 전체 체크리스트를 절대 실행하지 마세요. 두 줄짜리 수정에 한 시간을 쓰는 리뷰는 건너뛰어지고, 작성자가 유발하지 않은 발견 사항 서른 개를 나열하는 리뷰는 정작 중요한 하나를 묻어버립니다. 변경이 무엇인지에 따라 깊이를 정하세요:
기여자가 물려받은 문제로 절대 불이익을 주지 마세요
PR을 그 자체의 가치로 리뷰하세요. 기여자는 자신의 diff가 도입하는 것에 책임이 있습니다 — 파일을 건드렸다는 이유로 물려받은 것에는 절대 책임이 없습니다.
- 이 컴포넌트의 ledger 항목이 없습니까? PR을 순수하게 그 가치로 판단하세요. 전체 audit을 실행하지 말고, 등급을 산출하지 말고, diff가 유발하지 않은 어떤 것에 대해서도 block하지 마세요. audit되지 않은 컴포넌트는 우리 커버리지의 공백이지, 그들의 기여의 결함이 아닙니다.