Astryx 딥다이브
— Meta가 8년 키운 사내 디자인시스템, "사람과 에이전트가 같은 방식으로" 빌드하도록 오픈소스로 풀다

1프로젝트 한줄 요약

이 저장소가 대체 무엇인가.

README의 자기소개는 "An open source design system that's fully customizable and built for how we build now — by people and the agents working alongside them" — "완전히 커스터마이즈 가능하고, 사람과 그 옆에서 함께 일하는 에이전트가 지금 방식대로 만드는 디자인시스템"이다. 실제로 저장소를 열어보면 이 문장이 마케팅 카피가 아니라는 걸 바로 알 수 있다 — 루트에 CLAUDE.md와 .claude/ 디렉토리(커스텀 슬래시 명령·스킬 포함)가 그대로 커밋되어 있고, 컴포넌트 문서는 .doc.mjs라는 별도 형식으로 관리되어 CLI가 토큰 절약형("dense") 문서를 즉석에서 생성할 수 있게 되어 있다.

Meta 내부에서는 XDS라는 이름으로 불렸다(저장소 곳곳의 @astryxdesign/* 패키지명, xdsClassName() 같은 내부 함수명, CLAUDE.md 첫 줄의 "# XDS"에 그 흔적이 남아 있다). 오픈소스로 나오며 이름은 Astryx로 바뀌었지만, 코드베이스 내부 관례와 GitHub 위키 링크 상당수는 여전히 XDS/facebookexperimental/xds를 가리킨다 — 8년간 쌓인 실제 프로덕션 시스템을 그대로 옮겼다는 증거다.

2왜 주목받는가

트렌딩 이유 · MUI/Chakra/shadcn 등 기존 디자인시스템 대비 장점.

React 생태계에는 이미 MUI, Chakra UI, Ant Design, Mantine, 그리고 "복사해서 쓰는" shadcn/ui까지 다양한 선택지가 있다. Astryx가 새삼 주목받는 이유는 단순히 "컴포넌트가 많아서"가 아니라, "소유권(ownership)"이라는 오래된 딜레마를 정면으로 다루는 방식 때문이다. 라이브러리 도입 초기엔 편하지만, 나중에 "이 컴포넌트 딱 하나만 다르게 만들고 싶다"는 요구가 생기면 대부분의 시스템은 셋 중 하나를 강요한다 — ① 감싸서 땜질하기(wrapper hell), ② 라이브러리 CSS와 힘겨루기하기(specificity war), ③ 포크해서 영영 업스트림과 갈라서기.

기존 방식과 무엇이 다른가

또 하나의 차별점은 "사람과 에이전트가 같은 방식으로 빌드한다"는 철학이 슬로건에 그치지 않는다는 점이다. packages/cli는 --dense 플래그로 토큰 효율적인 문서를 뽑아주고, 컴포넌트 문서(.doc.mjs)는 애초에 기계가 파싱하기 쉬운 구조화된 형식으로 작성되며, 저장소 자체에 Claude Code용 커스텀 명령(.claude/commands/)까지 들어있다. "AI가 코드를 잘 짜게 도와주는 문서"가 아니라 "AI 에이전트를 위한 1급 인터페이스"로 설계했다는 증거다.

3기술 스택 전체 지도

React + StyleX 컴포넌트 라이브러리, pnpm 모노레포 툴링, 자체 CLI.

3-1. 프론트엔드 레이어

3-2. 빌드 · 모노레포 툴링

3-3. CLI 전용 스택

4아키텍처 심화 분석

Foundations → Components → Patterns 3계층 + StyleX 컴파일 흐름 + 테마 오버라이드 + swizzle eject.

README가 명시하는 아키텍처는 3단 계층이다. Foundations(타이포그래피·색상·레이아웃·접근성의 기초 토큰), Components(타입 완비된 재사용 UI 블록 150개 이상), Patterns(테이블 페이지·상세 페이지 레이아웃·폼 위저드·내비게이션·데이터 입력 같은 검증된 화면 조합). 아래 단계가 위 단계의 재료가 되는 전형적인 디자인시스템 피라미드지만, Astryx는 여기에 CLI가 각 계층을 넘나드는 진입점이라는 4번째 축을 더한다.

① StyleX 컴파일 흐름 — 소스 한 줄이 CSS 클래스가 되기까지

packages/core/src/Button/Button.tsx를 열어보면 컴포넌트 파일 안에 바로 stylex.create({...})가 있다 — 별도의 .css나 .module.css 파일이 아니라 TS 파일 안에서 타입 체크되는 스타일 객체다. 빌드 시 Babel의 @stylexjs/babel-plugin이 이 객체를 정적으로 분석해 아토믹 클래스로 치환한다.

// packages/core/src/Button/Button.tsx (실제 구조 축약)
import * as stylex from '@stylexjs/stylex';
import {colorVars, spacingVars, radiusVars} from '../theme/tokens.stylex';

const styles = stylex.create({
  base: {
    display: 'inline-flex',
    gap: spacingVars['--spacing-2'],
    borderRadius: `var(--_button-radius, ${radiusVars['--radius-element']})`,
    transitionDuration: {
      default: durationVars['--duration-fast'],
      // 모션 최소화 설정을 존중 — 접근성 기본값
      '@media (prefers-reduced-motion: reduce)': '0s',
    },
  },
  pressable: {
    transform: { default: 'scale(1)', ':active': 'scale(0.98)' }, // 의사클래스는 중첩 객체로
  },
});

주목할 점은 같은 라이브러리가 두 가지 다른 클래스 접두사(prefix)를 쓴다는 것이다. packages/build/src/babel.js는 파일 경로가 packages/core/·packages/themes/·node_modules/@astryxdesign/ 밑이면 astryx 접두사(.astryx78zum5)를, 그 외 사용자 프로덕트 코드는 x 접두사(.x78zum5)를 붙이도록 같은 StyleX 플러그인을 두 벌 인스턴스화해 파일 단위로 갈아 끼운다. 라이브러리 클래스와 사용자 클래스가 이름 공간에서 절대 충돌하지 않도록 하는 실전적인 트릭이다.

② 테마 = CSS 커스텀 프로퍼티 오버라이드 (래핑도 포크도 없이)

Astryx의 모든 디자인 토큰(--color-accent, --spacing-2, --radius-element 등 수십 개)은 packages/core/src/theme/tokens.stylex.ts의 stylex.defineVars()로 정의된 CSS 커스텀 프로퍼티다. 색상 값은 전부 light-dark(라이트, 다크) 함수 하나로 표현되어, 별도의 다크모드 스타일시트 없이 브라우저가 알아서 골라 쓴다.

// packages/core/src/theme/tokens.stylex.ts (실제 발췌)
export const colorDefaults = {
  '--color-accent': 'light-dark(#0064E0, #2694FE)',
  '--color-background-surface': 'light-dark(#FFFFFF, #1F1F22)',
  '--color-text-primary': 'light-dark(#0A1317, #DFE2E5)',
  // ... 색상/간격/반경/그림자/타이포그래피 토큰 계속
};

새 테마를 만드는 건 이 토큰 맵을 부분적으로만덮어쓰는 defineTheme() 호출 하나다. packages/themes/neutral/src/neutralTheme.ts는 OKLCH 색공간에서 색상환 위치를 계산해 뽑아낸 팔레트로 전체 색상 토큰만 오버라이드하고, 나머지(간격·반경 등)는 기본값을 그대로 물려받는다 — "테마 = 토큰 오버라이드 집합"이라는 설계가 코드로 정확히 드러난다.

CSS 배포 순서도 신중하게 설계되어 있다 — @layer reset, astryx-base, astryx-theme 3단 캐스케이드 레이어로 reset.css → astryx.css(컴포넌트 스타일) → theme.css(토큰 오버라이드) 순서를 강제한다. Tailwind와 함께 쓸 때는 tailwind-theme.css가 @theme inline으로 Astryx 토큰을 bg-surface·text-primary 같은 Tailwind 유틸리티 클래스에 자동으로 연결해준다.

③ swizzle — 컴포넌트 eject 흐름

packages/cli/src/commands/swizzle.mjs(417줄)를 직접 읽어보면 단순히 "파일 복사"가 아니라는 걸 알 수 있다. ① 경로 안전성 검사(assertWithin으로 --output이 .. 경로 탈출을 시도하는지 사전 차단), ② 기존 파일과 충돌 시 대화형 확인(또는 --overwrite), ③ 상대 경로 import를 패키지 경로로 재작성하는 3단계를 거친다.

swizzle 직후엔 선택적으로 gap report(간극 보고)를 남길 수 있다 — "왜 swizzle이 필요했는지"를 GitHub 이슈로 자동 접수(--gap "reason" --commit)해, 메인테이너가 "이 니즈를 컴포넌트 자체에 흡수해야 하는가"를 판단할 신호로 삼는다. 개별 사용자의 이탈(swizzle)이 프로젝트 전체의 개선 신호로 순환하는 피드백 루프다.

④ 핵심 설계 패턴 — 코드가 스스로를 검증하게 만들기

Astryx 코드베이스는 "규칙을 문서로만 적어두면 지켜지지 않는다"는 전제 위에서, 커스텀 ESLint 규칙과 SYNC 주석 계약으로 관례를 자동 강제한다. internal/eslint-plugin-astryx에는 no-classname-clobber(className이 내부 스타일을 완전히 덮어써 깨뜨리는 패턴 차단), require-ref-prop(포워딩 ref 누락 방지), no-hardcoded-anchor(라우터 없는 <a> 직접 사용 방지), boolean-prop-naming(불리언 prop 네이밍 통일) 등 14개 규칙이 있다.

각 소스 파일 헤더의 SYNC: 주석은 "이 파일을 고치면 어떤 다른 파일들도 같이 갱신해야 하는지"를 명시하고, scripts/check-sync.js가 CI에서 그 참조가 실제로 유효한지(존재하는 파일을 가리키는지) 검사한다. README 맨 위의 <!-- SYNC CONTRACT --> 주석도 같은 철학이다 — "아키텍처가 바뀌면 문서도 반드시 같이 바뀌어야 한다"는 규칙을 사람이 아니라 CI가 지키게 만든 것.

5디렉토리 구조 해부

apps/ · packages/{core,cli,build,themes} · internal/ · .changeset/ · .claude/.

6학습 포인트 (기술별)

이 저장소 하나로 배울 수 있는 것 + 실습 아이디어.

6-1. StyleX — 빌드타임 아토믹 CSS-in-JS 실전 사용법

Tailwind(유틸리티 클래스를 HTML에 직접 나열)나 Emotion(런타임에 스타일을 계산)과 다른 "제3의 길"을 몸으로 익힐 수 있다. stylex.create()로 정의한 스타일 객체가 타입 체크되고, 조건부 스타일은 stylex.props(condition && styles.x)처럼 다루며, 의사클래스(:hover, :active)는 CSS 파일이 아니라 객체 안에 중첩해서 쓴다는 점이 특히 낯설면서도 배울 가치가 있다.

6-2. 디자인 토큰 · 테마 시스템 설계

tokens.stylex.ts의 colorDefaults가 색상 하나하나를 light-dark(...) 함수로 정의하는 방식, defineTheme()이 "일부 토큰만 오버라이드"를 허용하는 API 설계, neutral 테마가 OKLCH 색공간에서 색상환 각도를 계산해 팔레트를 뽑아내는 방식까지 — "토큰 기반 테마"가 실제 프로덕션에서 어떻게 짜이는지 정석 사례로 볼 수 있다.

6-3. 모노레포 릴리스 — Changesets로 여러 패키지를 함께 배포하기

Astryx는 @astryxdesign/core·cli·build·테마 7종 등 9개 패키지를 .changeset/config.json의 fixed 그룹으로 묶어 항상 같은 버전 번호로 동시에 배포한다. 기여자는 PR마다 .changeset/{임의이름}.md 파일 하나(변경 요약 + 영향받는 패키지)를 추가하고, 릴리스 시점에 changeset version이 이걸 모아 CHANGELOG와 버전을 자동 생성한다.

6-4. CLI/코드모드 설계 — jscodeshift로 안전하게 마이그레이션하기

packages/cli/src/codemods/transforms/에는 v0.0.2부터 v0.1.2까지 버전별 코드 자동 변환 스크립트가 그대로 쌓여 있다. astryx upgrade --apply는 사용자의 @astryxdesign/core 버전을 감지해 그 사이 버전들의 코드모드를 순서대로 적용한다. jscodeshift는 정규식 치환이 아니라 AST(추상 구문 트리)를 파싱해 변형하므로, 문자열 우연 일치로 엉뚱한 코드를 건드릴 위험이 훨씬 적다.

6-5. 접근성(a11y) — 컴포넌트 라이브러리 차원에서 보장하는 법

Astryx는 @axe-core/playwright로 접근성 위반을 CI에서 자동 검출하고, StyleX 스타일 규칙에도 prefers-reduced-motion·@media (hover: hover) 가드가 관례로 박혀 있다(터치 기기에서 :hover 스타일이 "끈적하게" 남는 문제 방지). ESLint 규칙 중 require-ref-prop도 포워딩 ref가 빠지면 스크린 리더 연동이 깨질 수 있는 패턴을 잡아내는 접근성 관련 규칙이다.

6-6. "에이전트 친화적" API 설계 — vibe-tests라는 아이디어

internal/vibe-tests는 "AGENTS.md/CLAUDE.md 같은 문서가 LLM의 코드 생성 정확도에 실제로 얼마나 도움이 되는가"를 정량적으로 측정하는 자체 벤치마크다. 여러 프롬프트로 AI에게 컴포넌트 코드를 짜게 시키고, 결과가 "이스케이프 해치"(디자인시스템을 안 쓰고 날것의 HTML로 도망치는 패턴)를 썼는지 자동 평가한다. 심지어 "10턴 대화가 길어지면 품질이 얼마나 저하되는가"(degradation curve)까지 측정한다.

7시스템 요구사항

사용하는 쪽은 가볍다 — 기여·개발은 Node 22 + pnpm 10 + Corepack.

8직접 해볼 수 있는 실습 과제

난이도별 5단계 — 설치부터 codemod까지.

9관련 기술 심화 학습 로드맵

이 저장소를 출발점으로, 6주 코스.

10핵심 키워드 사전

본문에 나온 용어 빠른 참조.

11참고 링크

• GitHub: facebook/astryx
• 공식 문서 사이트: astryx.atmeta.com
• Storybook: facebook.github.io/astryx
• @astryxdesign/core README: packages/core/README.md
• @astryxdesign/cli README: packages/cli/README.md
• StyleX 공식 문서: stylexjs.com
• React 공식 문서: react.dev
• Changesets: github.com/changesets/changesets
• jscodeshift: github.com/facebook/jscodeshift
• CONTRIBUTING.md (기여 가이드): CONTRIBUTING.md
• npm 패키지: npmjs.com/package/@astryxdesign/core