microsoft/fluentui 딥다이브
— "낡은 본관과 새 별관이 함께 있는" 마이크로소프트 UI 캠퍼스

1한 줄 정체

Fluent UI는 하나의 프로젝트가 아니라 세 개의 프로젝트가 든 저장소다. README가 스스로 밝히듯 "이 레포는 오늘날 3개의 별도 프로젝트를 담고 있다"(v9 React Components, v8 React, Web Components). 원래 이름은 office-ui-fabric-react였고, 지금의 v8이 그 직계 후신이다. v9는 v8의 문제(런타임 스타일 계산 비용, 일관되지 않은 API)를 고치기 위해 처음부터 다시 설계된 별도 라인업이며, @fluentui/react-components로 배포된다.

실무에서 이 저장소를 접하는 경로는 대개 하나다: yarn add @fluentui/react-components @fluentui/react-icons 후 최상위에 <FluentProvider theme={webLightTheme}>를 감싸고 그 안에서 <Button>, <Dialog> 같은 컴포넌트를 쓰는 것. Teams 애드인이나 Microsoft 365 스타일이 필요한 사내 도구를 만들 때 가장 먼저 검토되는 라이브러리다.

2왜 지금 뜨는가

① v9가 드디어 "완성형"으로 자리를 잡았다

README 상단에는 "Fluent UI React가 v9 최종 안정 릴리스를 출시하는 중"이라는 문구가 그대로 남아 있다. 즉 이 저장소는 오랫동안 "v8에서 v9로 넘어가는 과도기"였고, 그 이행이 실질적으로 마무리 단계에 들어서면서 v9를 실무에 도입하는 팀이 늘고 있다. react-migration-v8-v9라는 전용 패키지까지 별도로 유지될 만큼 이행 지원이 진지하다.

② v0(Northstar) 은퇴로 지형이 단순해졌다

Fluent UI React Northstar(v0)는 2025년 7월 공식 EOL을 맞았다. 한때 "v0·v8·v9"라는 3파전이었던 구도가 "v9로 수렴 + v8은 레거시 유지"라는 훨씬 단순한 그림으로 정리됐다. 신규 학습자가 "어떤 버전을 배워야 하나"라는 혼란 없이 v9에 집중할 수 있게 된 것이 최근의 관심 증가와 맞물린다.

③ "빌드타임에 CSS를 뽑아내는" 방식이 업계 표준처럼 자리잡는 중

v9의 스타일 엔진 Griffel은 styled-components류의 런타임 CSS-in-JS가 안고 있던 성능 문제(매 렌더마다 스타일 계산)를, 원자적 클래스 생성 + 가능하면 빌드타임 추출로 해결한다. Vanilla Extract·Panda CSS 등과 같은 흐름 위에 있고, 마이크로소프트 규모의 실사용(수백 개 Teams 화면)으로 검증된 사례라는 점이 매력 포인트다.

3무엇을 해결하나

Fluent UI가 푸는 근본 문제는 단순한 "예쁜 버튼 컴포넌트 모음"이 아니라, 수천 개의 제품 팀이 저마다 다른 스타일로 UI를 만들지 않도록 하는 조직 규모의 일관성 문제다. 이를 위해 세 가지 축을 해결한다.

① 디자인 토큰으로 "하드코딩된 값"을 없앤다

#0078d4 같은 색상 값을 직접 쓰면 다크모드·고대비 모드·브랜드 테마 전환이 불가능해진다. Fluent UI는 tokens.colorBrandBackground처럼 의미 기반 토큰만 쓰도록 강제해, 테마 하나만 바꾸면 앱 전체의 색·간격·타이포그래피가 일괄 전환되게 한다.

② 3계층 훅 패턴으로 "상태·스타일·마크업"을 분리한다

모든 v9 컴포넌트는 useX_unstable(상태 계산) → useXStyles_unstable(스타일 클래스 부여) → renderX_unstable(순수 JSX 렌더)로 쪼개져 있다. 덕분에 "동작은 그대로 두고 스타일만 바꾸기", "렌더링만 바꾸고 상태 로직은 재사용하기" 같은 부분 교체가 가능해지고, 버그를 고칠 때도 "이 버그는 세 파일 중 어디에 있는지"가 명확해진다.

③ 슬롯(slot) 시스템으로 "컴포넌트 내부를 안전하게 바꿔치기"할 수 있게 한다

Button의 아이콘, Dialog의 제목 영역처럼 컴포넌트를 이루는 각 부분을 슬롯으로 노출해, 사용자가 그 부분만 다른 엘리먼트나 컴포넌트로 갈아끼울 수 있게 한다. "컴포넌트를 통째로 다시 만들지 않고도 세부만 커스터마이징"할 수 있는 확장성이 여기서 나온다.

4전체 구조

저장소는 Yarn 4 워크스페이스(packageManager: "yarn@4.12.0")로 묶인 모노레포이고, 실제 빌드·테스트·캐싱은 Nx가 담당한다(nx.json에 build·test·type-check 등 타깃별 캐시 규칙이 정의돼 있다). packages/ 아래에 최상위 패키지 46개가 있고, 그중 packages/react-components/ 폴더 하나가 다시 v9 컴포넌트별 서브패키지 87개를 품고 있다 — react-button, react-dialog, react-theme처럼 컴포넌트 하나당 패키지 하나가 원칙이다.

이 계층 규칙은 실제로 docs/architecture/layers.md에 문서화돼 있으며, "react-button이 react-menu에 의존해서는 안 된다"처럼 같은 티어(Tier 3) 안에서 수평 의존을 금지한다. 공유가 필요하면 반드시 Tier 2(유틸리티·컨텍스트)를 거치게 해, 컴포넌트 하나만 설치해도 다른 컴포넌트를 줄줄이 끌고 오지 않게 막는다.

5핵심 설계·동작 원리

① 3층 훅 패턴 — 실제 Button.tsx로 보기

packages/react-components/react-button/library/src/components/Button/ 아래를 열면 아래 세 함수가 그대로 보인다. Button.tsx는 이 셋을 순서대로 호출할 뿐, 로직을 직접 갖지 않는다.

export const Button = React.forwardRef((props, ref) => {
  // ① 상태: props를 정규화하고 슬롯을 만든다
  const state = useButton_unstable(props, ref);

  // ② 스타일: state.root.className 을 Griffel 클래스로 채운다
  useButtonStyles_unstable(state);

  // ③ 렌더: state 를 그대로 JSX로 바꾼다(로직 없음)
  return renderButton_unstable(state);
});

useButton_unstable은 appearance(secondary 기본), shape(rounded 기본), size 같은 props에 기본값을 채우고, slot.optional(icon, …)로 아이콘을 슬롯 객체로 바꾼 뒤 { appearance, shape, size, icon, root, iconOnly, … } 형태의 state 객체를 만든다. renderButton_unstable은 그 state를 받아 <state.root>{state.icon && <state.icon />}{state.root.children}</state.root>만 반환하는 순수 함수다 — 조건 분기 외에 다른 로직이 전혀 없다.

② Griffel — 빌드타임을 지향하는 원자적 CSS-in-JS

useButtonStyles.styles.ts는 @griffel/react의 makeStyles·makeResetStyles로 스타일을 정의한다. 실제 소스를 보면 appearance별(outline·primary·subtle·transparent), size별(small·medium·large), 심지어 강제 색상 모드(forced-colors: active, 즉 Windows 고대비 모드)까지 별도 스타일 객체로 나뉘어 있고, 이들을 mergeClasses()로 조건부 병합한다.

const useRootStyles = makeStyles({
  primary: { backgroundColor: tokens.colorBrandBackground, /* ... */ },
  subtle:  { backgroundColor: tokens.colorSubtleBackground, /* ... */ },
  small:   { minWidth: '64px', fontSize: tokens.fontSizeBase200 },
  // ...
});

// 사용부 — 규칙: 사용자가 넘긴 className은 항상 "맨 마지막"
state.root.className = mergeClasses(
  buttonClassNames.root,
  rootBaseClassName,
  appearance && rootStyles[appearance],
  rootStyles[size],
  state.root.className, // ← 항상 마지막
);

makeStyles는 하나의 규칙(예: { color: 'red' })마다 단 하나의 원자적(atomic) CSS 클래스를 만들어 여러 컴포넌트가 재사용하게 하고, 가능하면 빌드타임(babel/swc 플러그인)에 CSS를 미리 뽑아내 런타임 계산을 최소화한다. makeResetStyles는 컴포넌트당 한 번만 계산되는 "리셋용 기본 클래스"를 만들어 인라인 스타일 재계산 비용을 더 줄인다.

③ 디자인 토큰의 "진짜 소스"는 @fluentui/tokens

컴포넌트 코드는 @fluentui/react-theme에서 tokens를 가져오지만, 실제로 packages/react-components/react-theme/library/src/index.ts를 열어보면 그 안에서 하는 일은 @fluentui/tokens의 값을 그대로 재수출(re-export)하는 것뿐이다(tokens, webLightTheme, createLightTheme 등). 즉 토큰의 진실원(source of truth)은 react-theme가 아니라 tokens 패키지다.

④ FluentProvider — 테마를 실제 CSS 변수로 바꿔 주입하는 지점

<FluentProvider theme={...}>는 단순히 React 컨텍스트만 채우는 게 아니라, createCSSRuleFromTheme()로 테마 객체의 모든 키를 --colorNeutralForeground1: #242424; 같은 CSS 커스텀 프로퍼티 문자열로 직렬화한 뒤, useInsertionEffect(또는 SSR-세이프 폴백)로 <style> 태그를 만들어 document.head에 삽입한다. 이때 테마 값에 </>가 섞여 있으면 <style> 태그를 조기 종료시켜 HTML을 주입할 수 있으므로, 실제 코드는 이를 CSS 이스케이프 시퀀스로 치환하는 방어 로직까지 갖고 있다.

// createCSSRuleFromTheme.ts — 실제 로직을 요약하면
function createCSSRuleFromTheme(selector, theme) {
  const cssVars = Object.keys(theme).reduce((acc, key) =>
    acc + `--${key}: ${theme[key]}; `, '');
  return `${selector} { ${escapeForStyleTag(cssVars)} }`; // </> 이스케이프 필수
}

makeStyles로 만든 클래스들은 결국 color: var(--colorNeutralForeground1)처럼 이 CSS 변수를 참조하므로, 테마 객체 하나만 바꿔 끼우면 이미 그려진 컴포넌트들의 색이 재계산 없이 즉시 바뀐다 — 이것이 "런타임에 CSS 전체를 다시 만들지 않고도 테마를 바꾸는" v9식 접근이다.

⑤ 슬롯 시스템 — slot.always / slot.optional / assertSlots

@fluentui/react-utilities의 slot.ts는 "숏핸드(단순 값) 또는 완전한 props 객체"를 받아 항상 같은 모양의 슬롯 객체로 정규화한다. always는 반드시 렌더되는 슬롯(Button의 root), optional은 값이 없으면 undefined가 되어 아예 렌더되지 않는 슬롯(Button의 icon)을 만든다. renderX_unstable 안에서 쓰는 assertSlots<ButtonSlots>(state)는 타입스크립트가 "state의 각 필드가 진짜 슬롯 형태인지"를 컴파일 타임에 보증해 준다.

⑥ Tabster — 키보드 포커스만 전담하는 별도 패키지

방향키로 메뉴 이동, 모달 안에 포커스 가두기(focus trap), 루트에서 벗어나지 않는 탭 순환 같은 키보드 접근성 로직은 컴포넌트 코드에 흩어져 있지 않고 @fluentui/react-tabster라는 전용 패키지(내부적으로 마이크로소프트의 tabster 라이브러리를 감쌈)로 분리돼 있다. Button의 포커스 표시 스타일도 이 패키지의 createCustomFocusIndicatorStyle을 그대로 가져다 쓴다.

6기술 스택·의존성

7설치·요구사항

이 라이브러리를 "쓰기만" 할 때

yarn add @fluentui/react-components @fluentui/react-icons

import { FluentProvider, webLightTheme, Button } from '@fluentui/react-components';

function App() {
  return (
    <FluentProvider theme={webLightTheme}>
      <Button appearance="primary">안녕하세요</Button>
    </FluentProvider>
  );
}

peer dependency는 React 16.14~19대를 모두 허용하므로 최신 프로젝트든 다소 오래된 React 16/17 프로젝트든 도입에 큰 제약이 없다. Next.js 등 SSR 환경에서 쓸 때는 FluentProvider가 서버에서 만든 <style> 태그를 하이드레이션 시 재사용하도록 설계돼 있어(테스트 파일 FluentProvider-hydrate.test.tsx로 검증됨) 별도 설정 없이도 대체로 안전하다.

이 저장소 자체를 클론해 빌드/기여할 때

8실제 사용 흐름

9함정·오해 방지

10대안 비교

11정리 — 누가 쓰면 좋은가