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

API Conventions의 디자인 쪽 형제 문서입니다. API Conventions가 코드 convention이 무엇인지 명시한다면, 이 페이지는 Astryx에서 좋은 디자인이 어떤 모습인지 — 그리고 기본값이 왜 지금과 같은지 — 를 명시하여, 디자이너와 엔지니어가 규정에 맞게 만들고 리뷰어가 공유된 기준에 대해 평가할 수 있게 합니다.

이 페이지는 프로세스가 아니라 콘텐츠입니다: convention을 명시하고 각각이 어떻게 검증되는지 표시합니다. Token 시스템, 컴포넌트 소스, 리뷰 rubric에 이미 존재하는 것을 모으는 것이지 — 새로 발명하지 않습니다. 🟢 검사는 Night Watch Component Auditor가 실행하고, 🟡/🔴 판단은 Component Audit Rubric §5b에서 내려집니다. 새로운 표준은 Component Specification Protocol을 통해 들어옵니다; Component Hardening Protocol의 인간 디자인 리뷰에서 내려진 결정은 이 페이지로 다시 올라와서 판단이 축적됩니다.

원칙 (Principles)

• 결정 뒤의 의도를 이해하십시오. Token은 시스템의 디자인 사고를 인코딩하므로 믿을 만한 가이드입니다 — 의심스러울 때는 token을 따르십시오. 그러나 token은 가이드이지 절대 법칙이 아닙니다: 잘못된 역할(role)에 쓰인 token은 여전히 잘못된 것입니다. 어떤 값이 왜 존재하는지 알아야 그 차이를 구별할 수 있습니다.
• Theme은 look을, core는 구조를 제어합니다. 모든 시각적 값은 token을 참조합니다; theme이 그것이 무엇으로 resolve될지 결정합니다.
• 상태당 시각 표현을 최소화하십시오. 같은 상태에 대한 서로 다른 시각 표현 하나하나가 사용자가 학습해야 하는 오버헤드입니다. 새로 발명하기 전에 기존 표현을 재사용하십시오.
• 일관성의 범위는 family가 먼저, 그다음이 시스템입니다.
• 모든 상태를 위해 디자인하십시오 — rest, hover, focus, active, disabled, loading, 그리고 관련된 status/selected 상태.
• Enforcement보다 guidance. 런타임 디자인 가드레일이 아니라 capability입니다.

Design Foundations — token 선택 뒤의 의도

각 foundation은 디자인 원칙과 그것을 표현하는 token 범주를 짝짓습니다. 기본값은 임의적이지 않습니다 — 이 의도들을 인코딩하며, 이 의도들은 커스텀 theme이 잘 디자인되었는지 판단하는 rubric이기도 합니다. 각각에 대해: 왜 중요한가, 그다음 Principle, drift를 알리는 Smells, 그리고 **잘 해냈을 때(Got it right)**의 모습입니다.

명확한 관계 위계 (Spacing)

왜 중요한가. 단어 하나를 읽기 전에, 근접성(proximity)이 이미 무엇이 함께 속하는지 사용자에게 말해줍니다(Gestalt). 관계를 올바르게 잡으면 밀도 높은 화면도 여전히 정돈되어 보입니다; 잘못 잡으면 어떤 색상이나 border도 구해주지 못합니다. Spacing은 구조적인 일을 합니다 — 그래서 한 값을 모든 곳에 쓰는 것이 아니라 다양하고 의도적이어야 합니다.

Principle

공간은 요소들이 어떻게 관계 맺는지에 대한 일차 신호입니다. 밀접하게 관련된 것들은 붙어 있고, 별개의 관심사는 떨어져 있으며, 간격은 그룹핑의 각 수준마다 커집니다 — label→input < 그룹 안의 field들 < 섹션 안의 그룹들 < 섹션→섹션. 4px 그리드(--spacing-*, optical 작업을 위한 2px half-step)는 이 계층들을 표현하기에 충분한 단계를 제공합니다.

Smells