작성자 주: Astryx는 Meta가 오픈소스로 공개한 React 디자인 시스템으로, 현재도 베타 단계예요. 컴포넌트와 테마, 에이전트가 읽을 수 있는 문서를 함께 제공해요. 모델이 아니며 대규모 언어 모델 인터페이스도 기본 제공하지 않아요.
Claude Code, Cursor, Codex 같은 에이전트로 React 화면을 수정하다 보면 이런 일이 자주 생겨요. 어떤 페이지의 버튼은 모서리가 둥근데 다음 페이지의 버튼은 그렇지 않고, 어떤 모달은 바깥쪽을 클릭하면 닫히지만 다른 모달은 닫히지 않아요. 간격도 어떤 곳은 12px, 다른 곳은 14px로 제각각이죠. 원인은 모델의 성능이 아니라 에이전트가 참고할 디자인 시스템이 없다는 데 있어요. 에이전트는 컴포넌트 이름과 props를 기억에 의존해 추측할 수밖에 없어요. Astryx는 사람과 에이전트가 같은 컴포넌트 참고 자료를 읽도록 하는 방식을 택했어요. 사람은 문서 사이트에서, 에이전트는 CLI, AGENTS.md 또는 MCP를 통해 같은 내용을 확인해요.
이 글은 설치 명령을 그대로 되풀이하는 글이 아니에요. 아래에서 Meta가 공식적으로 직접 밝힌 정보, 제3자 작성자가 한 차례 진행한 실험, 그리고 2026-11-10 기준으로 확인할 수 있지만 변동될 수 있는 수치를 구분해 설명해요. 현재 도입하기에 적합하지 않은 프로젝트도 따로 정리할게요.
핵심 가치: 이 글을 읽고 나면 Astryx가 내 React 프로젝트에 적합한지 판단하고, 4단계로 사람과 에이전트가 같은 경로를 사용하도록 연결할 수 있어요.
위 이미지는 Astryx가 공식적으로 공개한 배너예요. 실제 화면은 아래 세 가지 공식 경로에서 확인할 수 있어요. 이 글에서는 별도의 스크린샷을 만들지 않았어요.
- 문서 사이트:
astryx.atmeta.com - 컴포넌트 둘러보기(Storybook):
astryx.atmeta.com/storybook/ - 온라인 체험(Sandbox):
astryx.atmeta.com/sandbox/
Astryx 핵심 요점: 무엇이고, 무엇이 아닌가
먼저 범위를 분명히 짚고 넘어갈게요. 공식 저장소는 Astryx를 외관을 완전히 사용자 지정할 수 있고, ‘사람과 Agent가 함께 일하는’ 방식에 맞춰 설계된 오픈소스 디자인 시스템이라고 소개해요. 라이선스는 MIT이며, 주 언어는 TypeScript예요. README에는 현재 베타 단계이며 아직 1.0에 도달하지 않았다고 명시되어 있어요.
| 핵심 요점 | 설명 | 사용자에게 주는 의미 |
|---|---|---|
| 기술 기반 | 공식 설명에 따르면 React 19+와 StyleX 기반이에요 | React 18 프로젝트는 지원 대상이 아니에요 |
| 컴포넌트 규모 | 공식 발표 기준으로 접근성을 지원하는 컴포넌트가 150개 이상이고, TypeScript 타입도 제공해요 | 일반적인 페이지에 필요한 요소는 대부분 갖춰져 있어요 |
| 외관 설정 | 기본 테마 7개가 제공되며, 토큰 계층에서 색상, 글꼴, 모서리 둥글기, 애니메이션을 수정할 수 있어요 | 스타일을 바꿀 때는 컴포넌트마다 수정하는 대신 테마를 바꾸면 돼요 |
| Agent 연동 | CLI, 생성된 AGENTS.md, 원격 MCP를 제공해요 |
Agent가 기억에 의존해 코드를 작성하는 대신 문서를 확인해요 |
| 모델 인터페이스 | 모델 인터페이스는 제공하지 않아요. APIYI apiyi.com을 이용하는 방식처럼 코딩 도구에서 직접 모델을 연결해야 해요 | 컴포넌트를 렌더링하는 데 모델은 필요하지 않아요 |
Astryx의 배경: 공식 발표 내용은 무엇일까요?
다음 내용은 모두 README와 2026-06-18에 게시된 공식 소개 글(작성자: Astryx team)에서 나온 것으로, 공식 측의 발표이며 별도의 감사를 거친 내용은 아니에요. Astryx는 Meta 내부에서 8년간 발전했으며, 회사에서 가장 널리 사용되고 규모가 큰 디자인 시스템으로 13,000개 이상의 애플리케이션을 지원한다고 해요. 소개 글에서는 이런 견해도 밝혔어요. 과거의 디자인 시스템은 사람이 읽도록 작성됐지만, 이제는 코드의 상당 부분을 Agent가 작성하고 있어요. 그래서 Astryx는 먼저 완성한 뒤 Agent 지원을 덧붙인 것이 아니라, 처음부터 AI가 다룰 수 있도록 설계했다고 해요.
날짜는 두 가지이니 혼동하지 마세요. 공식 소개 글은 2026-06-18에 게시됐고, @astryxdesign/core가 npm에 처음 등록된 날짜는 2026-06-24예요. 또 GitHub 저장소는 2026-01-09에 생성됐어요. 이는 저장소가 만들어진 날짜이지, 외부에 공개된 날짜가 아니에요.
Astryx와 통째로 가져와 디자인만 바꾸거나 복사·붙여넣기 하는 방식의 차이
공식 소개 문서에서는 흔히 쓰이는 두 가지 방식을 비교해요. 아래 표는 공식적인 설명만 옮긴 것으로, 벤치마크 결과는 포함하지 않아요.
| 방식 | 공식 설명에서 지적한 문제 | Astryx의 역할 분담 |
|---|---|---|
| 통째로 가져와 디자인만 바꾸기: 대기업의 디자인 시스템 전체를 그대로 사용 | 앱에 해당 기업의 브랜드 느낌이 묻어날 수 있어요 | 시스템은 동작, 접근성, 품질을 담당해요 |
| 복사·붙여넣기: 프로젝트마다 컴포넌트 코드를 포크해 별도로 관리 | 일관된 업그레이드가 없고, 접근성은 사용자가 직접 보장해야 해요 | 테마는 외관을 담당하고, 토큰 계층에서 수정해요 |
| Astryx: 패키지를 설치한 뒤 테마로 외관을 바꾸기 | 아직 베타이며 0.x 버전이에요 | 필요하면 swizzle로 개별 컴포넌트의 소스 코드를 가져올 수 있어요 |
README에서는 차이점 네 가지도 소개해요. 첫째, 내부가 개방되어 있어 컴포넌트를 어느 계층에서든 조합할 수 있고, 자주 쓰는 요소를 바로 내보내요. swizzle을 사용하면 특정 컴포넌트의 전체 소스 코드를 프로젝트로 가져와 직접 관리할 수 있어요. 둘째, 스타일이 고정되지 않아요. className으로 덮어쓸 수 있고 Tailwind, CSS modules, 일반 CSS와 함께 사용할 수 있어요. 셋째, 별도의 래퍼를 만들지 않아도 커스터마이즈할 수 있어요. 테마는 본질적으로 CSS 사용자 지정 속성을 덮어쓰는 방식이에요. 넷째, API, 문서, CLI를 함께 설계해 사람과 AI 어시스턴트가 같은 참고 자료를 사용해요.
제3자 사례: 한 저자의 테마 변경 실험
LogRocket은 2026-08-13에 한 편의 글을 게재했어요. 저자 Chizaram Ken은 Claude Code를 Astryx에 연결해 인터페이스 세 개를 만들고, shadcn/ui로도 같은 세 개를 만들었어요. 저자의 설명에 따르면 테마를 neutral에서 gothic으로 바꿀 때 파일 두 개와 코드 네 줄만 수정했고, 컴포넌트 파일은 건드리지 않았어요.
이 내용은 저자가 직접 진행한 실험이지, 벤치마크나 이 글의 테스트 결과는 아니에요. 실험은 현재 버전인 0.7.11보다 앞서 진행됐고, 당시 버전은 지금과 달라요. ‘테마와 컴포넌트를 분리한다’는 설계를 보여 주는 사례로 볼 수는 있지만, 성능에 관한 결론으로 받아들여서는 안 돼요.
Astryx 빠른 시작: 사람과 Agent를 같은 흐름에 연결하는 4단계
아래 4단계는 공식 문서인 Getting Started와 Working with AI의 내용을 바탕으로 했어요. 각 단계에서 터미널이나 파일에서 무엇을 해야 하는지, 어떤 결과가 나오면 완료된 것인지 설명해요. 공식 문서를 토대로 정리한 단계이며, 이 글에서 설치를 직접 실행한 것은 아니에요.
1단계: Astryx 패키지 4개 설치하기
- 터미널에서 실행하세요:
npm install @astryxdesign/core @astryxdesign/theme-neutral @stylexjs/stylex - 이어서 실행하세요:
npm install -D @astryxdesign/cli - pnpm과 yarn에도 각각에 맞는 명령어가 있지만, 패키지 이름은 동일해요.
- 완료 기준:
package.json에 네 패키지 이름이 모두 표시되고,react와react-dom버전이 모두 19 이상이어야 해요.
StyleX는 core의 peer dependency이므로 설치해야 해요. 다만 공식 설명에 따르면 Astryx가 StyleX로 스타일을 작성한다는 점은 사용자에게 드러나지 않아요. 프로젝트에서 StyleX를 사용하도록 변경할 필요도 없어요. 직접 StyleX를 사용할 때만 컴포넌트가 xstyle로 스타일을 전달받아요.
2단계: init으로 에이전트가 읽을 문서 생성하기
- 터미널에서 실행하세요:
npx @astryxdesign/cli init - 이 명령은 별도의 입력을 요구하지 않아요. 사람, CI, 스크립트, 에이전트 모두 바로 실행할 수 있어요.
- 완료 기준: 프로젝트 루트 디렉터리에
AGENTS.md가 생성되어야 해요. 프로젝트에 이미CLAUDE.md가 있다면 같은 안내가 해당 파일에도 추가돼요.
CLAUDE.md에도 안내를 추가하는 이유는, 프로젝트에 CLAUDE.md가 있으면 Claude Code가 AGENTS.md를 건너뛴다고 공식 문서에서 설명하기 때문이에요. 사용할 도구를 지정하려면 --agent claude, --agent cursor, --agent codex, --agent all 같은 인수를 추가할 수 있어요. Gemini CLI는 GEMINI.md만 읽기 때문에, init은 해당 파일에 AGENTS.md를 참조하는 한 줄을 추가해요.
파일의 표시 구간 안에 있는 Astryx 섹션은 Astryx가 관리해요. init과 upgrade는 이 섹션만 수정하므로 직접 작성한 다른 내용에는 영향을 주지 않아요. 또한 공식 문서에서는 에이전트가 CLI 경로를 잘못 추측하는 경우가 많으니 package.json에 스크립트 별칭을 추가하라고 권장해요.
- 스크립트 이름:
astryx - 스크립트 값:
node node_modules/@astryxdesign/cli/clients/cli/bin/astryx.mjs - 호출 방법:
npm run astryx -- component --list
3단계: CSS를 추가하고 neutral 테마로 앱 감싸기
- 전역 CSS에
@astryxdesign/core/reset.css를 가져와요. - 이어서
@astryxdesign/core/astryx.css를 가져와요. - 터미널에서
npx @astryxdesign/cli theme add neutral을 실행해 앱에서 사용할 테마 모듈을 생성해요. @astryxdesign/core/theme에서Theme를 가져온 다음,themes[defaultThemeSlug]를 전달해 앱 전체를 감싸요.@astryxdesign/core/Button에서 Button을 가져와요. 공식 예제에서는label과onClick두 가지 props를 사용해요.- 완료 기준: 페이지에 브라우저 기본 버튼이 아닌 Astryx 스타일의 Button이 표시돼요.
이 방법은 빌드 플러그인이 필요 없고, PostCSS나 Babel을 설정할 필요도 없어요. 다만 미리 알아둘 점이 있어요. reset은 @layer reset에, 컴포넌트 스타일은 @layer astryx-base에 배치돼요. 프로젝트에 전역 CSS, 기존 reset 또는 Tailwind가 이미 있다면 레이어 순서를 직접 선언해야 해요. 레이어에 속하지 않는 스타일은 선택자 우선순위와 관계없이 astryx-base를 덮어쓸 수 있기 때문이에요. 공식 문서에서는 페이지 작업을 시작하기 전에 npx @astryxdesign/cli docs migration/migration-setup의 두 섹션을 먼저 읽어 보라고 권장해요.
미리 준비된 7가지 테마에 대한 공식 설명은 다음과 같아요. 특별히 선호하는 스타일이 없다면 neutral부터 사용해 보세요.
| 테마 패키지 | 공식 설명 | 적합한 용도 |
|---|---|---|
theme-neutral |
채도가 낮고 미니멀한 스타일 | 기본 시작점 |
theme-butter |
따뜻한 금색에 파란색 포인트를 더한 스타일 | 따뜻한 분위기의 제품 |
theme-chocolate |
초콜릿색과 캐러멜색 | 레트로 스타일 |
theme-gothic |
잉크와 느와르 분위기의 다크 전용 테마 | 다크 모드 전용 인터페이스 |
theme-matcha |
싱그러운 초록색 | 자연스러운 분위기의 스타일 |
theme-stone |
사암 계열의 따뜻한 중성색 | 차분한 백오피스 |
theme-y2k |
2000년대 초반의 발랄한 스타일 | 이벤트 페이지, 재미를 강조한 제품 |
4단계: Agent가 공식 3단계 절차에 따라 UI를 작성하도록 하고, 필요하면 MCP 연결하기
init으로 생성된 규칙은 Agent가 UI를 작성하기 전에 다음 순서로 작업하도록 안내해요.
npx @astryxdesign/cli build "<想法>": 가장 적합한 페이지 템플릿 하나(최소한 앱 셸 포함)와 대체 템플릿 두 개를 제안하고, 아직 필요한 블록과 컴포넌트를 알려줘요.npx @astryxdesign/cli template <名字> <路径>: 템플릿을 프로젝트에 추가해요. 기존 프레임워크와 간격은 유지하고 내용만 바꿔요.npx @astryxdesign/cli component <组件名>: 사용할 각 컴포넌트의 props와 예제를 확인해요.- 규칙에는 몇 가지 금지 사항도 있어요. 모든 페이지는 템플릿에서 시작하고, 순수한
div는 사용하지 않으며,style={{}}는 작성하지 않고, 매직 넘버 대신 토큰을 사용해요. - 완료 기준: Agent가 언급한 컴포넌트 이름과 props가 직접 만들어 낸 것이 아니라 CLI 출력에 근거해야 해요.
공식에서 제안하는 다음 세 가지 질문으로 확인해 볼 수 있어요. Button의 올바른 import 경로는 무엇인지, Dialog가 함부로 닫히지 않게 하려면 어떻게 설정하는지, Selector에서 items를 전달할 때 어떤 prop을 사용하는지 물어보세요. Agent가 답하지 못하면 먼저 init을 실행하세요. 정답은 로컬 CLI 출력 결과를 기준으로 확인하면 돼요.
원격 조회가 필요하다면 공식 MCP를 연결할 수 있어요. 주소는 https://astryx.atmeta.com/mcp예요. MCP는 컴포넌트, 문서, 템플릿을 찾는 search(query)와 전체 문서를 가져오는 get(name) 두 가지 도구를 제공해요. 클라이언트마다 설정 방법이 달라요.
| 클라이언트 | 설정 방법 | 참고 사항 |
|---|---|---|
| Claude Code | 터미널에서 claude mcp add --transport http astryx https://astryx.atmeta.com/mcp 실행 |
서비스 이름은 astryx예요 |
| Cursor | .cursor/mcp.json에 url만 입력 |
원격 서비스에는 type을 쓰지 않아요 |
| Cline | transport에 streamableHttp 입력 |
http가 아니에요 |
| Claude Desktop | 설정에서 Connectors → Add custom connector를 선택한 뒤 URL을 붙여 넣어요 | 설정 파일에는 로컬 stdio만 입력해요 |
| 기타 범용 클라이언트 | type에 http를 입력하고 url을 추가해요 |
인식하지 못하는 transport는 건너뛰므로, 연결된 것처럼 보여도 도구가 없을 수 있어요 |
공식 문서에는 이 원격 주소의 SLA나 서비스를 사용할 수 없을 때의 처리 방법이 안내되어 있지 않아요. CLI는 같은 문서의 로컬 접속 수단이므로 MCP에 연결되지 않아도 계속 사용할 수 있어요.
코딩 Agent의 모델은 어디서 가져오나요?
디자인 시스템은 컴포넌트와 문서를 담당하지만, 코딩 Agent가 실제로 코드를 생성하려면 별도의 모델을 연결해야 해요. 팀에서 Claude Code나 Cursor 같은 도구에 직접 모델을 제공하려면 APIYI apiyi.com의 OpenAI 호환 인터페이스를 사용할 수 있어요. base_url에는 https://api.apiyi.com/v1을 입력하고, 모델명은 당일 모델 목록에 표시된 이름으로 설정하면 돼요. 모델 종류와 가격은 APIYI 플랫폼의 모델 목록을 기준으로 하며, APIYI는 목록에 있는 사용 가능한 모델을 제공해요.
컴포넌트는 브라우저에서 렌더링되므로 모델 인터페이스가 필요하지 않다는 점도 알아두세요. APIYI를 사용할지는 Astryx의 설치 및 실행에 영향을 주지 않아요.
🚀 빠른 시작 제안: 위의 4단계를 따라 새 브랜치에서 템플릿 페이지를 만든 다음, Agent에 같은 모델을 사용해
AGENTS.md가 있는 경우와 없는 경우 각각 한 번씩 작성하게 해 보세요. 두 결과의 컴포넌트 이름과 props를 비교할 수 있어요. 신규 사용자는 APIYI apiyi.com에서 무료 테스트 크레딧을 받아 이런 비교에 사용할 수 있어요.
Astryx의 위험 요소와 마이그레이션이 적합하지 않은 경우
Astryx 제품 자체의 위험 요소
Astryx는 아직 베타 단계이며 버전은 0.x예요. 2026-11-10 기준 npm의 latest는 0.7.11(2026-11-07 출시)이고, 이전 안정 버전인 0.7.10은 2026-11-06에 출시됐어요. 안정 버전이 거의 매일 업데이트되는 셈이에요. 업그레이드할 때는 프로젝트에서 사용하는 모든 @astryxdesign/* 패키지를 같은 버전으로 올린 다음, npx @astryxdesign/cli upgrade --from <旧的 core 版本> --apply를 실행해야 해요. 각 테마는 해당하는 core 버전을 지정하므로, 테마 업그레이드를 빠뜨리면 테마와 core 버전이 맞지 않게 돼요. 패키지 관리자가 출시 시점보다 늦게 새 버전을 설치한다면 @astryxdesign/* 전체 범위를 제외해야 해요. pnpm에서는 minimumReleaseAgeExclude에 @astryxdesign/*를 추가하면 돼요.
차트 관련 패키지인 @astryxdesign/vega와 @astryxdesign/charts는 npm의 canary 태그로만 배포되며, 안정 버전은 없어요. 2026-11-10 기준 canary는 0.7.12-canary.dfd75a6예요. 버전 번호는 latest보다 높지만, 프로덕션 의존성으로 사용하면 안 돼요.
APIYI를 통해 모델을 연동할 때의 위험 요소
이 내용은 코딩 에이전트의 모델 호출에만 해당해요. 요청은 APIYI 게이트웨이를 거치며, API 키와 비용은 호출자가 직접 관리해야 해요. 모델의 실제 성능은 선택한 모델과 게이트웨이에서 실제로 반환하는 결과에 따라 달라져요. Meta 계정에 로그인하는 방식도 아니고, 계정 풀을 이용하는 방식도 아니에요.
아직 마이그레이션을 권장하지 않는 프로젝트
- 아직 React 18을 사용하고 있는 프로젝트: core의 peer 의존성은
react와react-dom모두 19.0.0 이상을 요구해요. - 지금 당장 1.0 수준의 안정성을 보장받아야 하는 프로젝트: 현재 공식적으로 베타로 표시되어 있으며, 이러한 보장은 제공하지 않아요.
- 지금 당장 안정 버전의 차트가 필요한 프로젝트: 차트 패키지는 canary 버전만 제공해요.
- 첫날부터 모든 컴포넌트의 소스 코드를 자체 저장소에 두고 싶은 프로젝트: 이는 소스 코드를 복사해 붙여 넣는 방식이에요. Astryx는 기본적으로 패키지를 설치해 사용하며, 필요할 때
swizzle로 개별 컴포넌트의 소스 코드를 가져와요.
Astryx의 인기와 버전: 2026-11-10 기준 집계
아래 수치는 2026-11-10 기준이며 이후 달라질 수 있으므로 고정된 사실로 보아서는 안 돼요.
| 지표 | 수치 | 출처 |
|---|---|---|
| GitHub stars | 20,217 | GitHub API meta/astryx |
| forks | 1,536 | GitHub API |
| 미해결 issue / PR | 297 / 373 | GitHub Search API (총 670건이며, 버그 670개를 뜻하는 것은 아님) |
| core 주간 다운로드 수 | 661,968회 (2026-11-02~11-08) | npm 다운로드 API. 사용자 수가 아니라 다운로드 횟수예요. |
| core 최근 30일 다운로드 수 | 1,725,492회 (2026-10-10~11-08) | npm 다운로드 API |
자주 묻는 질문 FAQ
Q1: Astryx는 Tailwind 컴포넌트 라이브러리인가요?
아니요. 공식 문서에 따르면 Astryx는 React 19 이상과 StyleX를 기반으로 하며, 사전 컴파일된 CSS를 배포해요. Tailwind와 함께 사용할 수도 있어요. `className`으로 외관을 덮어쓸 수 있고, 저장소의 `apps/` 디렉터리에는 `example-vite-tailwind`와 `example-nextjs-tailwind` 예제도 있어요. 함께 사용할 때는 앞서 설명한 CSS 레이어 순서에 주의해야 해요.
Q2: React 18 프로젝트에서도 Astryx를 사용할 수 있나요?
사용할 수 없어요. 0.7.11 버전의 core 패키지는 `react`와 `react-dom` 모두 19.0.0 이상을 요구하므로 React 18은 조건을 충족하지 않아요. 먼저 프로젝트를 React 19로 업그레이드해야 해요.
Q3: MCP를 연결하지 않아도 Agent가 Astryx 문서를 사용할 수 있나요?
네. `init`으로 생성한 `AGENTS.md`와 로컬 CLI를 사용하면 `build`, `template`, `component` 세 단계를 진행할 수 있어요. MCP는 원격으로 조회할 때 사용하는 또 다른 방법일 뿐이에요. 내용을 웹 버전 대화에 붙여 넣으려면 `–detail brief`, `–detail compact` 또는 `–dense` 옵션을 추가해 출력 길이를 줄일 수 있어요.
Q4: facebook/astryx와 meta/astryx는 서로 다른 저장소인가요?
같은 저장소예요. 2026-11-10 기준으로 `github.com/facebook/astryx`에 접속하면 301 리디렉션을 통해 공식 저장소 주소인 `github.com/meta/astryx`로 이동해요. 예전 글에 나온 facebook/astryx도 바로 이 저장소를 가리켜요.
Q5: Astryx 차트 컴포넌트를 프로덕션 환경에서 사용할 수 있나요?
현재는 권장하지 않아요. `@astryxdesign/vega`와 `@astryxdesign/charts`는 canary 태그로만 배포되고, README에도 안정 버전이 없다고 안내되어 있어요. 프로덕션 프로젝트에서는 기존 차트 솔루션을 당분간 계속 사용하는 편이 좋아요.
Q6: 업그레이드할 때 core만 올려도 되나요?
안 돼요. 공식 안내에 따르면 프로젝트에서 사용하는 모든 `@astryxdesign/*` 패키지를 같은 버전으로 올려야 해요. 그렇지 않으면 테마와 core 버전이 맞지 않게 돼요. 업그레이드한 뒤 `upgrade –from <旧版本> –apply`를 실행하면 오래된 Astryx 섹션도 `AGENTS.md`에서 갱신해 줘요.
Q7: Astryx를 사용하려면 모델 API가 필요한가요? APIYI와는 어떤 관계인가요?
컴포넌트를 렌더링하는 데 모델 API는 필요하지 않아요. 코딩 Agent가 코드를 작성하도록 할 때만 모델을 연결하면 돼요. 이 작업은 Claude Code, Cursor 같은 도구가 담당해요. 팀에서 직접 모델을 제공하려면 APIYI apiyi.com에서 하나의 API 키로 여러 주요 모델을 호출할 수 있어요. APIYI는 Meta 또는 Astryx와 협력 관계가 없어요.
Q8: 특정 컴포넌트의 소스 코드를 복사해 내 저장소에서 수정해도 되나요?
가능하지만 기본적으로 권장하는 방식은 아니에요. `swizzle`을 실행하면 개별 컴포넌트의 전체 소스 코드가 프로젝트에 복사되고, 이후에는 직접 관리해야 해요. 나중에 업그레이드할 때도 직접 처리해야 해요. 공식 문서에서도 `theme eject`는 독립적인 소스 코드 분기가 꼭 필요할 때만 사용하라고 권장해요.
Astryx 핵심 요점
- 포지셔닝: Meta가 오픈 소스로 공개한 React 디자인 시스템이에요. MIT 라이선스를 사용하며, 현재 Beta 및 0.x 버전이에요.
- 역할 분담: 시스템은 동작과 접근성을 담당하고, 테마는 외관을 담당해요. 테마를 바꿔도 컴포넌트 파일을 수정할 필요가 없어요.
- 필수 조건: React 19 이상이 필요하고, peer dependency인 StyleX도 설치해야 해요.
- 에이전트 사용 경로: 먼저
init을 실행해AGENTS.md를 생성한 다음, build → template → component 순서로 페이지를 작성해요. - MCP는 선택 사항: 원격 주소는
https://astryx.atmeta.com/mcp이고, 로컬 CLI를 통해서도 동일한 문서를 이용할 수 있어요. - 업그레이드 규칙:
@astryxdesign/*패키지는 모두 같은 버전으로 함께 업그레이드해야 해요. 차트 패키지는 canary 버전만 제공돼요. - 모델은 별도 연결: 코딩 에이전트에 필요한 모델은 APIYI apiyi.com을 통해 통합해 사용할 수 있어요.
정리: Astryx가 에이전트의 일관된 UI 작성을 도울 수 있을까요?
에이전트가 작성하는 UI가 일관되지 않은 이유는 컴포넌트 이름과 props를 추측할 수밖에 없기 때문이에요. Astryx는 컴포넌트, 테마, 에이전트가 참고할 문서를 하나의 시스템에 담는 방식으로 이 문제를 해결해요.
- 4단계로 도입: 패키지 4개를 설치하고
init을 실행한 뒤, CSS를 불러오고 앱을 Theme으로 감싸요. 에이전트는 세 단계에 걸쳐 정보를 확인한 다음 코드를 작성하면 돼요. - 정보의 출처 구분: 13,000개 이상의 앱과 8년간의 내부 사용 이력은 공식 측의 자체 발표예요. 테마를 바꿀 때 네 줄만 수정하면 된다는 내용은 제3자 작성자가 직접 시험한 결과예요. 별 수와 다운로드 수는 2026-11-10 기준 집계예요.
- 먼저 적합성 확인: 프로젝트가 아직 React 18을 사용하거나 안정 버전 차트 또는 1.0 버전 출시 보장이 필요하다면 마이그레이션을 미뤄도 괜찮아요.
프로젝트가 이미 React 19를 사용하고 있고 에이전트가 props를 지어내는 일을 줄이고 싶다면, 브랜치 하나에서 템플릿 페이지를 시험해 보세요. 코딩 에이전트에 필요한 모델은 APIYI apiyi.com을 통해 연결할 수 있으며, 무료 테스트 크레딧으로 같은 AGENTS.md를 기반으로 여러 모델이 생성한 코드를 비교해 볼 수 있어요.
📚 참고 자료
- Astryx GitHub 저장소: README, 패키지 목록, 테마 목록 및 원칙 설명
- 링크:
github.com/meta/astryx -
설명: 공식 발표 정보를 확인할 수 있는 주요 출처예요.
facebook/astryx는 이 저장소로 리디렉션돼요. -
Astryx 공식 소개 글: 2026-06-18에 게시된 설계 철학 설명
- 링크:
astryx.atmeta.com/blog/introducing-astryx -
설명: 전체 패키지를 통째로 바꾸는 방식과 복사·붙여넣기 방식의 비교 내용이 담겨 있어요.
-
Getting Started 및 Working with AI 문서: 설치, 테마, init 및 MCP 설정
- 링크:
astryx.atmeta.com/docs/getting-started,astryx.atmeta.com/docs/working-with-ai -
설명: 이 글에서 소개한 4단계의 공식 근거예요.
-
Astryx v0.7.11 릴리스 노트: 현재 안정 버전 및 업그레이드 방법
- 링크:
github.com/meta/astryx/releases/tag/v0.7.11 -
설명: 모든 패키지의 버전을 통일해야 한다는 내용의 원문 출처예요.
-
LogRocket 비교 글: 2026-08-13, 작성자 Chizaram Ken
- 링크:
blog.logrocket.com/astryx-vs-shadcn-meta-ai-react-claude - 설명: 서드파티의 단일 실험 결과로, 테스트한 버전은 0.7.11보다 이전 버전이에요.
작성자: APIYI 기술팀
기술 문의: 코딩 에이전트의 모델 연동과 관련해 궁금한 점이 있다면 APIYI 공식 홈페이지에서 문의해 주세요.
