Astryx 설치하고 Next.js에서 Meta 오픈소스 디자인 시스템 붙이기

개요

오픈소스 UI 라이브러리를 고를 때 스타일 우선순위 충돌과 커스터마이징 한계가 자주 걸립니다. Astryx는 Meta 내부에서 13,000개 이상 앱에 쓰이던 디자인 시스템을 공개한 React UI 프레임워크입니다. 사람과 AI 에이전트가 같은 CLI·문서로 화면을 맞춥니다.

별도 빌드 플러그인 없이 사전 빌드 CSS만 임포트하면 됩니다. Tailwind CSS나 CSS Modules 쪽 className 오버라이드도 허용합니다. 지금은 Beta 단계라 운영 서비스에 바로 넣기 전에 Storybook과 릴리스 노트를 먼저 확인하는 편이 안전합니다.

1. 왜 쓸 만한가

기존 디자인 시스템은 사람용 문서와 AI용 컨텍스트가 갈라지기 쉽습니다. Astryx는 @astryxdesign/cli로 컴포넌트 API, 템플릿, 토큰 문서를 한 경로로 제공합니다. Claude Code 같은 에이전트가 추측 UI를 만들기보다 같은 인덱스를 읽게 됩니다.

공식 README 기준 150개 이상 접근성 컴포넌트, 브랜드 단위 테마, 다크 모드, 페이지 템플릿이 한 묶음입니다. 테마는 CSS custom property 오버라이드라 래핑 없이 브랜드 색을 바꿉니다.

2. Next.js 설치 경로

설치 명령은 공식 README의 npm 경로만 다룹니다. Vite·CDN 분기는 문서를 따로 보시면 됩니다.

npm install @astryxdesign/core @astryxdesign/theme-neutral
npm install -D @astryxdesign/cli

package.json에 CLI 스크립트를 두면 에이전트가 경로를 헷갈릴 여지가 줄습니다.

{
  "scripts": {
    "astryx": "node node_modules/@astryxdesign/cli/bin/astryx.mjs"
  }
}

Next.js에서는 src/app/globals.css 최상단에 아래 순서를 유지합니다. 레이어 cascade가 이 순서에 묶입니다.

@import '@astryxdesign/core/reset.css';
@import '@astryxdesign/core/astryx.css';
@import '@astryxdesign/theme-neutral/theme.css';

src/app/providers.tsx에서 Theme 래퍼를 감쌉니다.

'use client';
import {Theme} from '@astryxdesign/core/theme';
import {neutralTheme} from '@astryxdesign/theme-neutral/built';

export function Providers({children}: {children: React.ReactNode}) {
  return <Theme theme={neutralTheme}>{children}</Theme>;
}

에이전트 작업 전에 한 번 초기화를 돌리면 AGENTS.md/CLAUDE.md에 컴포넌트 인덱스가 기록됩니다.

npx @astryxdesign/cli init

3. 컴포넌트 조회와 swizzle

목록·문서 조회와 소스 분리(eject)는 CLI로 이어집니다.

npx @astryxdesign/cli component --list
npx @astryxdesign/cli component Button
npx @astryxdesign/cli template dashboard
npx @astryxdesign/cli swizzle Button

swizzle은 선택한 컴포넌트 소스를 프로젝트로 빼 줍니다. Wrapper를 쌓지 않고 내부 구조를 직접 고칠 때 씁니다. 최신 릴리스는 v0.1.8이며 Avatar size 축약 같은 breaking change가 포함되어 있어, 업그레이드 시 astryx upgrade codemod를 확인해주시면 됩니다.

저라면 React·TypeScript 프론트와 AI 보조 UI 작성을 같이 돌리는 팀에서 먼저 검토하겠습니다. 문서 인덱스와 컴포넌트 조회 경로가 같기 때문입니다. 반면 Vue/Svelte 전용 스택이거나, 이미 사내 디자인 시스템이 굳어 있고 에이전트 문서 연동이 필요 없다면 굳이 옮기지 않아도 됩니다. shadcn/ui처럼 파일 복사 중심 워크플로만 원해도 과한 선택이 됩니다. 여기까지가 범위입니다.

모델 라우터를 한 엔드포인트로 묶는 로컬 구성은 OmniRoute로 Claude Code와 Codex를 한 엔드포인트에 묶기에서 확인하시면 됩니다.

확인

설치 후 컴포넌트 목록이 출력되고 템플릿 소스가 나오면 준비가 끝난 것입니다. 아래 명령을 순서대로 실행해주시면 됩니다.

npx @astryxdesign/cli component --list
npx @astryxdesign/cli template dashboard

Storybook 화면에서 원하는 컴포넌트 props가 보이면 UI 연결 전 점검이 끝난 상태입니다.