AI에게 화면 맡기면 버튼이 매번 달라질 때, 메타 디자인 시스템 Astryx로 맞추기

AI 코딩 에이전트에게 관리 화면을 맡기면 화면마다 버튼 색과 여백이 조금씩 달라지곤 합니다. 요청할 때마다 에이전트가 색과 픽셀 값을 새로 고를 수 있기 때문입니다. 메타(Meta)가 깃허브에 공개한 Astryx는 이 선택을 컴포넌트와 테마에 넘기는 오픈소스 디자인 시스템(Design System)이고, 이 글은 그 쓰는 법을 정리합니다.

설명은 공식 README와 CLI 문서를 2026년 11월 10일에 받아 확인한 것이고, 화면과 검사 결과는 같은 날 임시 폴더에 새 프로젝트를 만들어 실행한 결과입니다. 같은 상품 관리 화면을 디자인 시스템 없이 한 번, Astryx로 한 번 만들어 코드와 검사 결과를 나란히 놓았습니다.

AI 에이전트에게 맡긴 화면이 매번 달라지는 이유

에이전트는 “상품 표와 추가 폼을 만들어 줘”라는 말을 받으면 그때그때 CSS를 씁니다. 파란 버튼의 색 코드, 입력칸 모서리 6픽셀, 카드 안 여백 20픽셀 같은 값이 그 자리에서 정해집니다. 다음 화면을 만들 때 앞의 값을 기억하리라는 보장이 없으니, 화면이 늘수록 모양이 흩어집니다.

디자인 시스템은 이 값들을 미리 정해 둔 부품 묶음입니다. README에 따르면 Astryx는 메타 안에서 8년 동안 자라 사내에서 가장 많이 쓰이는 디자인 시스템이 됐고, 1만 3천 개가 넘는 앱(13,000+ apps)을 받친다고 메타가 밝혔습니다. 접근성을 챙긴 컴포넌트 150개 이상, 브랜드 테마, 다크 모드, 템플릿, CLI가 한 묶음으로 들어 있습니다.

사람과 AI 어시스턴트가 같은 도구로 만든다는 것이 README가 내세우는 점입니다. API, 문서, CLI를 함께 설계해서 사람과 에이전트가 같은 참고 자료를 보고 같은 방식으로 짓게 했다고 적혀 있습니다. 아래 시험도 그 부분을 중심으로 했습니다.

Astryx 디자인 시스템 설치와 init, 실제로 돌린 순서

공식 README의 시작하기 절은 React 19 이상을 요구하고, 패키지 4개를 설치하라고 안내합니다. 시험은 Vite로 만든 빈 React 프로젝트에서 했고, 설치된 버전은 core와 CLI 모두 0.7.12였습니다.

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

README는 package.json에 CLI 실행 스크립트를 하나 넣어 두라고 권합니다. 에이전트나 새 개발자가 CLI를 부를 때 경로 오류를 피하기 위해서라고 적혀 있습니다. 그 뒤 npm run astryx -- component --list를 실행하자 설치한 0.7.12 버전의 컴포넌트 174개가 나왔습니다. README의 150개 이상과 세는 기준이 다른 것으로 보이며, CLI 목록에는 TableBody, TableCell 같은 하위 부품도 따로 올라 있습니다.

가장 중요한 단계는 init입니다. core 패키지 README는 AI 에이전트로 만들 때 CLI를 넣고 init을 실행하라고 안내하는데, 이 명령이 AGENTS.md나 CLAUDE.md에 컴포넌트 색인을 적어서 에이전트가 짐작하지 않고 찾아 쓰게 한다고 설명합니다.

생성된 지침에는 작업 순서와 규칙이 같이 들어 있습니다. 화면은 템플릿에서 시작하고, 날것의 <div>를 쓰지 말고, 색 코드와 픽셀 값을 직접 넣지 말고, 넘기기 전에 astryx doctor --built로 검사하라는 내용입니다. 에이전트가 매번 고르던 값을 규칙으로 막는 부분이 여기입니다.

astryx build "만들 화면 설명"은 시작할 템플릿을 골라 줍니다. “상품 표와 상품 추가 폼이 있는 관리 페이지”를 영어로 넣자 form-wizard-dialog 템플릿을 1순위로, table-page와 table-grouped를 다른 후보로 내놓았고, 표 선택·일괄 작업 블록도 함께 추천했습니다. 0.7.12의 템플릿 목록에는 페이지 템플릿 58개와 블록 템플릿 718개가 들어 있었습니다.

같은 관리 화면을 두 번 만들어 비교했다

비교용 화면은 상품 4개가 든 표와 상품 추가 폼입니다. 하나는 디자인 시스템 없이 평범한 React와 CSS로, 하나는 init을 마친 프로젝트에서 컴포넌트로 만들었습니다. 두 코드 모두 이 글을 위해 AI 코딩 에이전트(클로드 코드)로 만든 시험 코드이고, 상품과 가격은 시연용 값입니다.

눈으로 보면 둘 다 멀쩡합니다. 차이는 코드 안에 있습니다. 디자인 시스템 없이 짠 쪽은 22줄짜리 CSS 파일에 색 코드가 20번(16종), 픽셀 값이 38번 들어갔습니다. 아래는 그중 버튼과 입력칸 부분입니다.

.field input, .field select { padding: 9px 12px; border: 1px solid #d1d5db; border-radius: 6px; font-size: 15px; }
.btn { padding: 10px 18px; border-radius: 8px; border: none; font-size: 15px; cursor: pointer; margin-right: 8px; }
.btn-primary { background: #2563eb; color: #fff; }
.btn-secondary { background: #e5e7eb; color: #111827; }

컴포넌트로 짠 쪽은 CSS 파일이 아예 없습니다. 버튼은 variant로 종류만 고르고, 간격은 gap={4}처럼 정해진 단계 값으로만 줍니다.

<Card>
  <VStack gap={4}>
    <Heading level={2}>상품 추가</Heading>
    <TextInput label="상품명" value={name} onChange={setName} isRequired />
    <HStack gap={4}>
      <Selector label="카테고리" options={['주방', '잡화', '디지털']} value={category} onChange={setCategory} />
      <NumberInput label="가격(원)" value={price} onChange={setPrice} min={0} />
      <NumberInput label="재고" value={stock} onChange={setStock} min={0} />
    </HStack>
    <HStack gap={2}>
      <Button label="상품 추가" variant="primary" onClick={add} />
      <Button label="취소" variant="secondary" />
    </HStack>
  </VStack>
</Card>

두 프로젝트에 init이 지침으로 권한 astryx doctor --built를 돌린 결과는 아래와 같습니다.

CSS로 짠 쪽은 “이 결과물은 디자인 시스템을 쓰지 않는다”는 판정으로 실패했고, 날것의 <div>와 <h1>, className, CSS 가져오기 등 48건이 지적 목록에 올랐습니다. 컴포넌트로 짠 쪽은 지침대로 CSS 가져오기를 main.tsx에 두었고, 13개 항목 통과에 경고 0. 에이전트가 스스로 돌려 볼 수 있는 검사 기준이 생기는 셈이라, 화면을 넘기기 전 마지막 단계로 쓰기 좋습니다.

테마 하나 바꾸면 모서리·색·다크 모드까지

여기서 테마는 CSS 사용자 정의 속성(Custom Property)을 덮어쓰는 묶음이라고 README가 설명합니다. 그래서 표와 폼 코드는 그대로 두고 테마만 갈아 끼울 수 있습니다. 시험에서는 matcha 테마 패키지를 추가로 설치해 main.tsx에 테마 CSS 가져오기 한 줄을 더했고, App.tsx에서는 Theme 컴포넌트에 넘기는 값만 바꿨습니다.

다크 모드는 Theme 컴포넌트의 mode 값으로 고릅니다. 문서에 적힌 값은 light, dark, system 세 가지이고 기본은 system(운영체제 설정을 따름)입니다. 상태 표시 점의 색도 다크 모드에서 밝은 톤으로 함께 바뀌었습니다.

MCP 서버로 에이전트가 컴포넌트를 직접 찾게 하기

README 본문에는 MCP 이야기가 없지만, CLI의 docs 명령(npx astryx docs working-with-ai)으로 여는 “Working with AI” 문서에 MCP 서버 절이 있습니다. 메타가 원격 MCP 서버를 운영하고, 연결하면 에이전트가 CLI 출력을 붙여 넣지 않아도 컴포넌트를 검색하고 문서를 받아 온다는 설명입니다. Claude Code는 아래 한 줄로 등록한다고 안내합니다.

claude mcp add --transport http astryx https://astryx.atmeta.com/mcp

이 시험에서는 사용 중인 에이전트 설정을 바꾸지 않으려고 등록 대신 같은 주소에 MCP 요청을 직접 보내 응답을 확인했습니다. 서버는 문서 설명대로 search와 get 두 도구를 내놓았고, “table”을 검색하면 Table과 표 관련 훅·하위 부품이 차례로 돌아옵니다.

에이전트에게 화면을 시킬 때 붙이는 요청문

init이 지침 파일을 써 두면 에이전트는 작업을 시작할 때 그 규칙을 읽습니다. 그래도 요청문에 순서를 한 번 더 적어 두면 빠뜨리는 단계가 줄어듭니다. 아래는 이 글의 시험 순서를 그대로 옮긴 요청문 예시이고, 화면 설명만 바꿔 쓰면 됩니다.

주문 목록 화면을 만들어 줘. 표에는 주문번호, 상품명, 수량, 상태를 넣어.
1. 먼저 npx astryx build "order list page with a table" 로 시작할 템플릿을 확인해.
2. 컴포넌트를 쓰기 전에 npx astryx component <이름> 으로 속성을 읽어.
3. 색 코드나 px 값을 직접 쓰지 말고 컴포넌트 속성과 토큰만 써.
4. 끝나면 npx astryx doctor --built . 를 돌려서 경고가 0인지 보여 줘.

마지막 줄이 중요합니다. 검사 결과를 보여 달라고 해 두면 경고가 남았을 때 에이전트가 고칠 목록을 바로 손에 쥐게 되고, 사람은 마지막 출력만 보고 넘길지 정할 수 있습니다. 새 화면을 추가할 때마다 같은 요청문을 쓰면 버튼과 간격이 화면마다 갈라지는 일을 줄일 수 있습니다.

시작하기 전에 알아 둘 점

한국어 화면이라면 하나 더 볼 것이 있어요. TextInput에 필수 표시(isRequired)를 켜자 라벨 옆에 영어 “Required”가 붙었습니다. 컴포넌트 목록에 InternationalizationProvider가 있으니, 한국어 서비스라면 문구를 바꾸는 방법부터 확인하고 시작하는 편이 낫습니다.

혼자 쇼핑몰 관리 화면이나 사내 도구를 AI로 만들고 있다면, 화면을 여러 개 만들기 전에 init과 doctor 두 단계를 먼저 넣어 두는 것을 권합니다. 화면이 열 개를 넘어간 뒤 색과 간격을 맞추는 것보다 처음부터 규칙을 주는 쪽이 손이 덜 갑니다.

업무에 맞춘 AI 설계 상담은 AI특별시에서 받습니다.

글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.

이 글은 공식 자료와 실제 화면을 기준으로 정리했습니다. 정책·가격은 기준일 이후 바뀔 수 있습니다.