Astryx: 사람과 AI 에이전트가 함께 쓰는 React 디자인 시스템
Astryx는 Meta의 GitHub 조직에서 공개한 React용 오픈소스 디자인 시스템으로, 사람과 AI 코딩 에이전트가 같은 문서와 같은 CLI를 보고 화면을 만들 수 있게 설계한 것이 가장 큰 특징이에요. 컴포넌트, 테마, CLI를 한 묶음으로 주고, 아직 베타 단계라 매일 여러 번 바뀌고 있어요.
무엇을 해 주나요
저장소 설명에 따르면 Astryx는 크게 네 가지를 해 줘요.
- 바로 쓰는 컴포넌트: 접근성을 고려한 컴포넌트를 150개 넘게 TypeScript 타입과 함께 제공한다고 해요. 미리 빌드된 CSS를 불러오고 타입이 붙은 React 컴포넌트를 가져다 쓰는 방식이라, 기본 사용에는 별도 빌드 플러그인이 필요 없다고 해요. README는 “CSS 몇 줄과 테마 공급자(theme provider)”면 시작할 수 있다고 설명하고, 자세한 설정은
@astryxdesign/core패키지 문서로 넘겨요. - CSS 변수로 하는 테마: 테마 하나는 CSS 사용자 정의 속성(변수)을 덮어쓰는 묶음이에요. 그래서 컴포넌트를 포크하거나 감싸지 않고도 브랜드 색과 다크 모드를 바꿀 수 있어요. neutral, butter, chocolate, matcha, stone, gothic, y2k 일곱 가지 테마가 패키지로 나와 있어요.
- 속을 열어 둔 구조: 컴포넌트를 이루는 작은 부품도 그대로 내보내고,
swizzle기능으로 컴포넌트 소스 전체를 내 프로젝트로 꺼내 직접 고칠 수 있다고 해요. 스타일은 내부적으로 StyleX로 작성됐지만, 쓰는 쪽은 StyleX를 몰라도 되고className에 Tailwind, CSS 모듈, 일반 CSS를 넣어 덮어쓸 수 있어요. - 에이전트가 읽기 쉬운 CLI:
@astryxdesign/cli는 컴포넌트 문서 조회, 템플릿과 뼈대 생성, 테마, 코드 자동 변환(codemod)을 맡아요. 이름 짓기, 속성, 조합 규칙을 일관되게 맞춰서 사람이든 AI든 처음 보는 컴포넌트의 쓰임을 짐작할 수 있게 했다고 해요. 표 페이지, 상세 화면, 단계별 입력 폼 같은 화면 패턴도 따로 정리돼 있어요.
README에는 MCP 이야기가 없지만, 오늘 커밋 중에 “astryx mcp가 모든 CLI 명령을 MCP 도구로 제공한다”는 기능 추가가 있었어요. 에이전트 연동이 README보다 앞서 나가고 있는 셈이라, 이 부분은 문서가 따라오는지 지켜볼 필요가 있어요.
설치와 사용
쓰는 쪽은 React 19 이상이 필요하고, react와 react-dom은 피어 의존성이에요. 기본 설치는 코어, 테마 하나, StyleX를 함께 넣고 CLI는 개발 의존성으로 넣는 구성이에요. pnpm이나 yarn 명령도 README에 같이 나와 있어요.
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex
npm install -D @astryxdesign/cli
README는 에이전트가 경로 문제로 헤매지 않도록 package.json에 스크립트를 하나 추가해 두라고 권해요. 그러면 프로젝트에 설치된 버전의 CLI를 그대로 부를 수 있어요.
"astryx": "node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs"
npm run astryx -- component --list
CLI를 전역으로 설치하면 어느 폴더에서든 astryx를 부를 수 있고, 프로젝트 안에서는 그 프로젝트의 버전이 실행된다고 해요. 저장소에 기여하려면 Node 22 이상(활성 LTS)과 pnpm 11이 필요해요.
누구에게 쓸모 있나요
React 19로 관리 화면이나 사내 도구, 데이터가 많은 대시보드를 만드는 팀에게 잘 맞아요. 특히 Claude Code나 Codex 같은 에이전트에게 화면 작업을 자주 맡기는 팀이라면, 에이전트가 CLI로 컴포넌트 목록과 사용법을 직접 찾아보게 할 수 있다는 점이 쓸모 있어요. 테마를 CSS 변수로만 바꾸는 구조라 브랜드 색을 입히려는 디자이너와 개발자가 함께 쓰기에도 편해요. 반대로 React 18 이하 프로젝트나, 안정된 API가 꼭 필요한 서비스에는 아직 이르다고 봐야 해요.
쓰기 전에 알아 둘 점
- 베타 단계: README가 스스로 “현재 베타”라고 밝혀요. 버전도 0.7.x이고 릴리스가 며칠 간격으로 나오니, 업데이트 때 바뀐 점을 확인하는 습관이 필요해요.
- 아직 안 되는 것: 차트 패키지인
@astryxdesign/vega와@astryxdesign/charts는 npm의@canary태그로만 나와 있고 안정 버전이 없어요. 실험용 컴포넌트를 담은@astryxdesign/lab은 npm에 공개되지 않았어요. - 열린 이슈 규모: 열린 이슈가 348개로 많은 편이에요. 최근 이슈에는 날짜 입력에서 지운 값이 남는 문제, 메뉴가 키보드로 열리지 않는 문제처럼 접근성·입력 관련 버그가 보여요.
- 텔레메트리: README에서 데이터 수집에 대한 설명은 찾지 못했어요. 문서 사이트, Storybook, 샌드박스 같은 외부 링크가 있지만 그쪽에 어떤 정보가 가는지는 확인되지 않았어요.
저장소 상태
- 별 약 2.98만 개, 포크 약 2,300개 (GitHub 표시값)
- 열린 이슈 348개, 열린 PR 486개 (닫힌 PR 9,930개)
- 언어: TypeScript (GitHub 트렌딩 페이지 표시 기준). README는 TypeScript 타입 제공을 말하고, 최상위에
tsconfig.json과pnpm-workspace.yaml이 있어요. - 라이선스: MIT
- 마지막 커밋: 2026년 11월 17일 (CLI의 MCP 제공 기능 등)
- 최신 릴리스: v0.7.16, 11월 14일 (릴리스 페이지에 연도는 표시되지 않았어요). 표 컴포넌트의 열 가상화와 무한 스크롤, 입력 오류 표시 시점 조절 등이 들어갔어요.
- 최상위 폴더:
packages,apps,docs,internal,scripts,plugins/astryx,.claude-plugin등. README가 말하는 패키지와 에이전트용 플러그인 폴더가 실제로 있어요.
확인 범위
2026년 11월 17일에 GitHub 웹 페이지로 확인(API 미사용)했어요. 읽은 페이지는 저장소 첫 화면과 README(주제를 나눠 두 번), 릴리스, 커밋, 이슈, 풀 리퀘스트 목록이에요. 릴리스 페이지는 앞부분만 읽었고, @astryxdesign/core 패키지 README와 문서 사이트, 플러그인 폴더 내용은 읽지 않았어요. 코드 분석은 하지 않았고, 설치하거나 실행해 보지도 않았어요.