adobe/react-spectrum 딥다이브
— "상태 · 동작 · 디자인"을 완전히 분리한 컴포넌트 모노레포

1한 줄 정체

react-spectrum은 컴포넌트를 "완제품"이 아니라 "재료·중간재·완제품"의 3단 생산 라인으로 나눠 파는 저장소다. 예를 들어 드롭다운 하나를 만들 때, ① @react-stately/select가 "지금 뭐가 선택됐는지, 메뉴가 열렸는지"를 관리하고, ② @react-aria/select가 거기에 "키보드 화살표·포커스·스크린리더 안내"를 씌워 순수 DOM 속성(props)만 돌려주고, ③ @react-spectrum/picker 또는 react-aria-components의 <Select>가 그 위에 실제 화면을 그린다. 세 층 모두 따로 npm에 배포되고 따로 테스트된다.

이 구조 덕에 Adobe는 "같은 로직 위에 Spectrum 1(구 디자인)과 Spectrum 2(신 디자인)를 동시에" 얹을 수 있고, 외부 팀은 "Adobe 디자인은 필요 없고 접근성 로직만" 가져다 자기 디자인 시스템을 만들 수 있다. React Aria 자체가 "unstyled(스타일 없는) 컴포넌트" 생태계의 대표 주자로 꼽히는 이유다.

2왜 지금 뜨는가

① "unstyled 컴포넌트" 붐의 뿌리

Radix Primitives·Headless UI·Base UI·Ark UI 같은 "스타일 없이 동작만 주는" 컴포넌트 라이브러리가 최근 프론트엔드의 표준 문법이 됐다. React Aria는 이 흐름을 2020년부터 밀어붙인 선구자 중 하나다. 다른 라이브러리들이 여기 합류하면서 오히려 "react-spectrum의 접근성 깊이"가 재조명받고 있다.

② AI 코드 생성 시대의 "접근성 부채" 문제

AI가 UI 코드를 순식간에 찍어내는 시대에, 키보드 내비게이션·스크린리더 라벨·포커스 관리 같은 디테일은 오히려 더 쉽게 누락된다. React Aria처럼 "동작을 훅으로 캡슐화"해두면 AI가 만든 커스텀 UI에도 검증된 접근성 로직을 그대로 꽂을 수 있어, 최근 AI 코딩 워크플로에서 재조명되고 있다. 실제로 이 저장소에는 packages/dev/mcp/react-aria·packages/dev/mcp/s2라는 공식 MCP(Model Context Protocol) 서버가 포함돼, AI 에이전트가 React Aria/S2 문서를 직접 조회하며 코드를 짤 수 있게 되어 있다.

③ Spectrum 2(S2) 전환과 스타일 매크로 실험

Adobe는 자체 디자인 시스템을 Spectrum 2로 새로 그리는 중이며, @react-spectrum/s2 패키지가 그 결과물이다. 여기서 쓰는 컴파일 타임 스타일 매크로(style macro)는 "런타임 CSS-in-JS 없이, 빌드 시점에 원자적 CSS로 컴파일"하는 실험적 접근이라 프론트엔드 성능 커뮤니티에서 자주 언급된다.

3무엇을 해결하나

4전체 구조

packages/ 아래에 라이브러리별로 스코프가 나뉜다. 실제 클론해서 세어보면 @react-stately 33개, @react-aria 55개, @react-spectrum 66개 스코프 패키지가 있고, 여기에 react-aria-components(선언형 레이어, 컴포넌트 소스 파일 69개), @internationalized/*(date·number·message·string·string-compiler), @react-types/*(순수 타입), @spectrum-icons/*가 더해진다.

핵심 포인트: @react-stately/select·@react-aria/select 같은 스코프 패키지들은 껍데기다. 진짜 훅 구현은 packages/react-stately/src/와 packages/react-aria/src/라는 "번들 패키지"에 있고, 스코프 패키지는 그 파일을 package.json의 exports 서브패스 매핑을 통해 재수출만 한다. (이 구조는 5장·9장에서 실제 코드로 추적한다.)

5핵심 설계·동작 원리

① 3층 아키텍처를 실제 소스로 추적하기 — "Select"

가장 좋은 증명은 실제로 하나의 컴포넌트를 끝까지 따라가는 것이다. 여기서는 드롭다운 선택 컴포넌트(Spectrum에서는 Picker라는 이름)를 추적한다.

1단계 — 상태만 아는 useSelectState (React Stately)

packages/react-stately/src/select/useSelectState.ts는 DOM도, ARIA도, 렌더링도 전혀 모른다. 하는 일은 딱 세 가지: useListState로 항목 컬렉션과 선택 상태를 관리하고, useOverlayTriggerState로 "메뉴가 열렸는지"를 관리하고, useFormValidationState로 폼 유효성 상태를 관리한 뒤, 이 셋을 하나의 SelectState 객체로 합쳐 돌려준다.

export function useSelectState<T, M>(props): SelectState<T, M> {
  let triggerState = useOverlayTriggerState(props);       // 열림/닫힘
  let listState = useListState({ ...props, selectionMode }); // 선택/컬렉션
  let validationState = useFormValidationState({ ...props });  // 폼 검증
  return { ...validationState, ...listState, ...triggerState, value, setValue, open, toggle };
}

이 함수만 떼어서 React Native나 서버 컴포넌트 상태 관리에 그대로 쓸 수 있을 만큼 플랫폼 독립적이다.

2단계 — 동작·접근성을 입히는 useSelect (React Aria)

packages/react-aria/src/select/useSelect.ts는 위 state와 DOM ref를 받아, 순수 DOM 속성 객체(props bag)만 돌려준다. 내부적으로 useMenuTrigger(버튼-메뉴 연결), useTypeSelect(문자 입력으로 항목 점프), useField(라벨·에러 연결), ListKeyboardDelegate(방향키 이동 규칙)를 조합하고, ArrowLeft/ArrowRight로 값을 순환시키는 단축키까지 직접 등록한다. 반환값은 triggerProps·labelProps·menuProps·valueProps·descriptionProps·errorMessageProps·hiddenSelectProps — 전부 <button {...triggerProps}>처럼 그대로 엘리먼트에 뿌릴 수 있는 순수 객체다. 여기엔 CSS 클래스도, 화면에 그려지는 모양도 전혀 없다.

3단계 — 디자인을 입히는 완제품 컴포넌트 (React Spectrum / RAC / S2)

같은 두 훅(useSelectState + useSelect) 위에 세 가지 다른 옷이 입혀진다.

세 완제품 모두 import {useSelect} from 'react-aria/useSelect'와 import {useSelectState} from 'react-stately/useSelectState'를 토씨 하나 다르지 않게 그대로 가져다 쓴다. 다른 것은 오직 "그 결과를 어떤 태그·어떤 클래스로 그리느냐"뿐이다.

② Collections API — "리스트를 리스트답게 다루는" 공통 언어

Select·ListBox·Menu·Table·GridList·Tabs 등 "항목이 여러 개인" 모든 컴포넌트는 같은 컬렉션 모델을 공유한다. 사용자는 <Item>/<Section>(정적) 또는 배열 + 렌더 함수(동적, items={data} children={item => <Item>...</Item>})로 항목을 선언하고, 내부적으로 CollectionBuilder가 이를 Node<T> 트리로 변환한다. @react-types/shared/collections.d.ts에 ItemProps·AsyncLoadable(isLoading·onLoadMore) 같은 공통 타입이 정의돼, 모든 컴포넌트가 같은 방식으로 무한 스크롤·비동기 로딩을 지원한다.

③ 가상화(Virtualizer) — 수만 개 항목도 가볍게

@react-stately/virtualizer(레이아웃 계산: 어떤 항목이 어디 위치하는지 순수 계산)와 @react-aria/virtualizer(그 계산 결과를 실제 DOM에 붙이고 스크롤·포커스를 관리)로 나뉜다. Table·큰 ListBox·Calendar처럼 항목 수가 많은 컴포넌트가 이를 사용해, 화면에 보이는 행만 실제 DOM에 그리고 나머지는 가상 좌표로만 계산한다. 여기서도 "레이아웃 계산(상태)"과 "DOM 반영(동작)"이 각각 Stately/Aria로 나뉘는 동일한 철학이 반복된다.

④ 국제화 — 날짜·숫자·문자열·RTL을 프레임워크 독립적으로

@internationalized/date는 리액트에 의존하지 않는 순수 날짜 계산 라이브러리다. CalendarDate 클래스 하나로 그레고리력뿐 아니라 불교력·에티오피아력·헤브루력·인도력·이슬람력(여러 변형 포함)·일본력·페르시아력·타이완력까지 9종의 달력 시스템을 계산한다(packages/@internationalized/date/src/calendars/). @internationalized/number의 NumberParser는 latn·arab·hanidec(한자)·deva(데바나가리)·beng(벵골)·fullwide 6개 숫자 체계를 파싱한다. RTL(오른쪽에서 왼쪽 언어)은 I18nProvider가 isRTL(locale) 결과로 direction: 'rtl'|'ltr'을 context에 심어, 모든 하위 컴포넌트가 자동으로 좌우 반전된다.

⑤ usePress — 마우스·터치·펜·키보드·스크린리더를 하나의 "누름" 이벤트로

packages/react-aria/src/interactions/usePress.ts는 이 저장소에서 가장 정교한 로우레벨 훅 중 하나다. 브라우저의 PointerEvent·TouchEvent·클릭 이벤트가 기기·브라우저마다 미묘하게 다르게 발생하는 문제를, 하나의 통일된 onPress 이벤트로 추상화한다. 스크린리더가 발생시키는 "가상 클릭"(isVirtualClick/isVirtualPointerEvent)을 실제 마우스 클릭과 구분하고, 터치로 드래그하다 원래 요소를 벗어나면 포인터 캡처를 해제해 다른 요소로 상호작용이 넘어가게 하며, iOS의 "포인터업 시 크기 0" 버그도 우회 처리한다. continuePropagation()이라는 탈출구로 상위 컴포넌트가 이벤트를 가로챌 수도 있다.

6기술 스택·의존성

① 패키지 매니저·버전 관리 — "버전의 진실원"

② 프론트엔드 의존성

③ CI 파이프라인 — CircleCI

.circleci/config.yml(3만 자 이상) 안에 30여 개 잡이 정의돼 있다: rsp/rsp-large/rsp-xlarge(리소스 등급별 실행기), test/test-ssr/test-canary/test-ssr-canary(SSR·React canary 호환성까지 검증), test-browser(Playwright 브라우저 테스트), lint, ts-diff/skills-diff/weekly-api-diff(공개 API 표면 변경 자동 감지), storybook, verdaccio(로컬 npm 레지스트리에 실제로 배포해보는 통합 테스트), v-nextjs/v-rac-rsp-tailwind/v-starters(실사용 스타터 앱 검증), weekly-chromatic(비주얼 회귀), publish-nightly, prod-docs/beta-docs.

7설치·요구사항

8실제 사용 흐름

9함정·오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가

react-spectrum(정확히는 그 안의 React Aria + React Stately)은 "우리 회사만의 디자인 시스템을 밑바닥부터 만들어야 하는 팀"에게 가장 큰 가치가 있다. 상태와 동작을 이미 검증된 훅으로 가져오고, 디자인만 온전히 자기 것으로 만들 수 있기 때문이다. @adobe/react-spectrum을 완제품으로 그대로 쓰고 싶은 팀에게도 물론 유효하지만, 이 경우엔 Adobe 톤앤매너를 그대로 받아들여야 한다.

접근성(a11y)을 진지하게 다뤄야 하는 프로덕트 — 공공기관·금융·의료·대기업 내부 툴 — 팀에게도 강력히 추천된다. 키보드·스크린리더·RTL·다국어 달력까지 이미 검증된 로직을 쓸 수 있다는 점이 가장 큰 무기다. 반대로 "빠르게 프로토타입만 찍고 싶다"면 Radix+shadcn/ui나 Headless UI 쪽이 진입 장벽이 낮다.

이 저장소를 공부하는 것 자체로도 배울 게 많다. "로직과 렌더링을 분리하는 설계", "하나의 npm 패키지를 재수출 계층으로 잘게 쪼개 배포하는 기법", "브라우저 입력 이벤트를 하나로 통합하는 정교한 이벤트 시스템(usePress)"은 이 저장소가 아니어도 어디서나 써먹을 수 있는 프론트엔드 아키텍처 지식이다.

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

모든 경로와 명령은 react-spectrum 레포 루트 기준이다. 개발 서버와 테스트를 실행하는 과제는 해당 작업본의 Node·Yarn 설정에 맞는 환경과 의존성이 이미 준비되어 있다고 가정한다. 소스를 바꾸지 않고 기존 예제와 테스트만으로 진행할 수 있다.

cat packages/@react-aria/select/src/index.ts
cat packages/@react-stately/select/src/index.ts
cat packages/react-aria/exports/useSelect.ts
cat packages/react-stately/exports/useSelectState.ts

yarn start

yarn test packages/react-aria/test/interactions/usePress.test.js --runInBand -t 'keyboard events|disabled elements'

import {CalendarDate} from '@internationalized/date';

const date = new CalendarDate(2020, 8, 31);
const nextMonth = date.add({months: 1});
const leapDay = new CalendarDate(2020, 2, 28).add({days: 1});

yarn test packages/@internationalized/date/tests/manipulation.test.js --runInBand -t 'CalendarDate manipulation'

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

한 주마다 읽은 내용을 작은 결과물 하나로 남긴다. 아래 경로는 모두 레포 루트 기준이며, 앞 주의 Select 경로 지도를 다음 주의 상태표와 동작표에 계속 덧붙이면 된다.

14핵심 키워드 사전