원문: https://github.com/facebook/astryx/wiki/Astryx-Philosophy · 번역 기준: 2026-09-03
Astryx를 만들며 우리가 어떻게 생각하는지 — 우리가 풀고 있는 문제, 우리가 배운 것, 그리고 우리가 일하는 방식. 시스템에 기여하거나 협업하는 모든 분을 위한 문서입니다.
컴포넌트 라이브러리에는 공통적인 실패 유형이 있습니다. 이는 생태계 전반에서 나타나며 — 우리 스스로도 직접 겪어 왔습니다.
소유권이 소비자에게 떠넘겨집니다. 복사-붙여넣기 컴포넌트 모델은 유지보수를 전적으로 개발자에게 전가합니다. 업스트림 의존성이 깨지면, 그 코드를 복사한 모든 앱이 각자 독립적으로 고쳐야 합니다. 통제와 유지보수 비용 사이의 트레이드오프는 실재하며, 대부분의 팀은 유지보수 쪽 비용을 과소평가합니다.
스타일링 시스템이 lock-in을 만듭니다. 컴포넌트 로직을 특정 스타일링 접근법에 결합하면, 라이브러리를 도입하는 것이 곧 그 CSS 철학을 도입하는 것이 됩니다 — 그것이 프로젝트에 맞든 맞지 않든 말입니다. 컴포넌트는 원하지만 스타일링 프레임워크는 원하지 않는 팀은 갇혀 버립니다.
커스터마이징이 너무 어렵거나 너무 얕습니다. 어떤 라이브러리는 input의 색상 하나 바꾸는 데에도 수십 줄의 코드를 요구합니다. 다른 라이브러리는 가드레일 없는 완전한 유연성을 제공하는데, 거기서 빠져나오는 데 드는 노력이 직접 만드는 것보다 큽니다. 그 중간 지점 — 합리적인 제약을 갖춘 깊은 커스터마이징 — 은 찾기 어렵습니다.
AI 어시스턴트가 컴포넌트 라이브러리를 잘 다루지 못합니다. 이는 흔히 라이브러리가 out of distribution — 학습 데이터에 없기 때문 — 이라고 설명됩니다. 하지만 인기 있고 잘 알려진 라이브러리도 같은 문제를 겪습니다. 진짜 문제는 API 복잡성, 암묵적 컨벤션, 그리고 빈약한 에러 복구 경로입니다.
일관성은 규모가 커지면 무너집니다. 강한 컨벤션이 없으면, 서로 다른 팀원이 같은 컴포넌트를 조금씩 다르게 구현하고 UI는 파편화됩니다. 팀들이 빈틈을 메우려고 컴포넌트를 fork하기 시작하면, 그들은 제품 위에 라이브러리의 그림자 버전까지 유지보수하게 됩니다.
디자이너와 개발자가 결국 대립하게 됩니다. 컴포넌트 라이브러리가 사실상의 design system이 되면, 디자이너는 시각 언어에 대한 통제권을 잃습니다. 흔한 조언 — 그냥 자체 컴포넌트를 만들라 — 은 공유 컴포넌트를 두는 목적 자체를 무너뜨립니다.
엄격한 시스템은 메인테이너에게 부담을 지웁니다. 반대쪽 극단도 똑같이 비쌉니다. 모든 변경을 시스템 팀을 통해 게이트하는 엄격하게 통제된 design system은 병목을 만듭니다. 메인테이너 입장에서 이는 빠르게 움직여야 하는 제품 팀과 일관성이 필요한 디자이너 사이에서 끊임없이 협상해야 한다는 뜻입니다 — 모든 업데이트, 모든 예외, 모든 엣지 케이스가 같은 사람들에게 몰립니다. 시스템은 조력자가 아니라 의존 대상이 되고, 메인테이너는 시스템을 앞으로 발전시키는 대신 경쟁하는 우선순위들 사이의 통역사가 됩니다.
우리는 이것을 내부에서 직접 겪었습니다. Astryx의 이전 버전은 백만 개가 넘는 callsite를 지원했고 7년에 걸쳐 강력한 기여자 커뮤니티를 만들었습니다. 그건 진짜 성공입니다. 하지만 기존의 모든 Meta 내부 도구를 지원하기 위해 요구된 안정성 때문에, 빠르게 움직여야 하는 팀들에게는 시스템이 충분히 빠르게 진화할 수 없었습니다. 제품 팀은 갇혀 있다고 느꼈고, 리더십은 결과물이 낡았다고 보았으며, OSS 툴링과 TypeScript로부터의 거리 때문에 AI가 도움을 주기가 점점 더 어려워졌습니다. 보일러플레이트는 무거웠고, 생태계는 고립되어 있었으며, OSS 패키지를 import하는 일은 결코 간단하지 않았습니다. 이번 재작성은 백만 callsite 규모까지 확장된 컨벤션과 조직적 지식은 그대로 이어가되 — 발목을 잡던 제약들은 벗어던집니다.
실패 유형은 스펙트럼의 양 끝 모두에 있습니다. 너무 느슨하면 소비자가 모든 비용을 지고, 너무 엄격하면 메인테이너가 집니다.
우리는 철학에서 시작하지 않았습니다. 실험에서 시작했습니다.
Vibe Tests — LLM과 인간이 컴포넌트 라이브러리를 어떻게 사용하는지에 대한 구조화된 평가 — 를 통해, 우리는 업계의 흔한 조언들을 시도해 보았습니다: llms.txt 파일 작성, AI 전용 문서 추가, 상세한 skill 제작, in-distribution 라이브러리 사용. 대부분은 효과가 없거나 오히려 상황을 악화시켰습니다.
대신 우리가 발견한 것은 이렇습니다:
AI 품질과 인간 품질은 같은 것입니다. AI 경험을 개선한 모든 수정은 인간의 경험도 개선했습니다. prop이 30개인 API는 둘 모두에게 혼란스러웠습니다. 사용의 97%를 2개가 커버하는 10개의 variant는 둘 모두에게 죽은 무게였습니다. 질문은 "어떻게 AI 친화적으로 만들까"에서 "어떻게 더 좋게 만들까"로 옮겨 갔습니다.