원문: https://github.com/facebook/astryx/wiki/API-Conventions · 번역 기준: 2026-09-03

Astryx 컴포넌트 API convention의 통합 레퍼런스입니다. 이 문서는 결정 문서(decision doc)로, convention이 무엇인지를 명시합니다.

관련 결정 사항은 다음을 참고하십시오:

• Why StyleX — 스타일링 아키텍처의 근거
• Distribution — 패키지, 버저닝, Astryx가 배포되는 방식
• Theming Infrastructure — CSS token, themeProps, variant map, 서브 엘리먼트 타게팅
• Night Watch Component Auditor — 이 convention들의 자동화된 야간 enforcement

이 페이지는 규칙이 무엇인지를 소유합니다. Component Audit Rubric §3은 그것이 어떻게 검사되고 점수화되는지를 소유하며, Night Watch Component Auditor가 이를 매일 밤 실행합니다. 여기의 규칙을 업데이트할 때는 대응되는 rubric 항목도 업데이트하십시오. 감사(audit)에서 여기에 문서화되지 않은 gap이 발견되면, 먼저 여기에 추가하십시오.

원칙 (Principles)

Astryx Philosophy에 기반합니다. 아래의 모든 convention은 이 원칙들이 이끕니다.

• Enforcement보다 guidance. 컴포넌트는 capability를 제공하지, 디자인 가드레일을 제공하지 않습니다. 디자인에 대한 의견은 문서와 예제에 담기며, 런타임 prop gating에 담기지 않습니다. 소비자가 prop 값을 전달하면 컴포넌트는 그것을 렌더링합니다.
• Prop 독립성. 하나의 prop이 다른 prop의 출력을 억제하는 일은 결코 없습니다. Variant는 스타일링에 영향을 주지, 형제 prop이 나타나는지 여부에 영향을 주지 않습니다. 예외: 클리핑이 자명한 물리적 제약(isTruncated, maxLines).
• 직교하는 축(Orthogonal axes). 각 prop은 하나의 변형 차원(dimension of variation)만 제어합니다. 사용 사례를 설명하지 않고는 축의 이름을 지을 수 없다면, 그것은 primitive가 아니라 design recipe입니다.
• 의도적으로 측정하십시오. 런타임 측정(ResizeObserver, getClientRects)에는 실질적인 비용이 있습니다 — 추가 렌더 패스, style recalc, layout thrash. 어떤 컴포넌트는 측정을 위해 존재합니다(overflow 감지, virtualization). 그러나 측정은 의식적인 trade-off여야 하며, 가볍게 손을 뻗는 대상이 되어서는 안 됩니다. prop이나 CSS가 같은 의도를 표현할 수 있다면 그쪽을 선호하십시오.
• API에 design recipe를 넣지 마십시오. prop은 컴포넌트가 하는 일을 기술하는 것이지, 특정 시안(comp)이 어떻게 배치했는지를 기술하는 것이 아닙니다. 시각적 미세 조정(optical nudge)과 일회성 조정은 theme 인프라나 내부 스타일링에 속합니다.
• 배포 전에 테스트하십시오. 새 API surface에는 vibe testing이 필요합니다. 이름들이 실제 사용에 대해 검증되지 않았다면, 그 API는 아직 준비되지 않은 것입니다.
• 올바른 레이어에서 고치십시오. 컴포넌트를 패치하기 전에, 버그가 reset CSS, theme config, 또는 build tooling에 있는 것은 아닌지 확인하십시오. 증상을 패치하지 마십시오.

The Component Spectrum

컴포넌트는 순수한 utility에서 guided composition에 이르는 스펙트럼 위에 존재합니다. 각 대역(band)마다 다른 API 전략이 필요합니다: