Measure Twice React

Measure Twice의 공개 CSS 토큰과 React 컴포넌트를 한 배포 단위로 제공합니다.

Storybook 문서 · 변경 이력

지원 범위

• React와 React DOM 18.2 이상 20 미만
• ESM
• Chrome·Edge·Firefox·Safari와 iOS 계열 브라우저

네이티브 Popover API가 없는 브라우저에서도 닫기·Escape·바깥 영역 클릭 동작을 같은 계약으로 제공합니다.

설치

pnpm add @measure-twice/react pretendard

Pretendard를 사용하지 않으면 패키지만 설치하고 --mt-font-sans를 앱 글꼴로 재정의할 수 있습니다.

시작하기

애플리케이션 진입점에서 글꼴과 패키지 스타일을 한 번 불러옵니다. 앱 스타일은 패키지 스타일 다음에 불러옵니다.

import 'pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css';
import '@measure-twice/react/styles.css';
import { Button } from '@measure-twice/react';
import './app.css';

export function SaveAction() {
  return <Button>확인하고 계속</Button>;
}

테마

내장 라이트·다크 테마는 공개 함수로 앱 전체나 필요한 하위 영역에 적용합니다. 시스템 설정 추종과 사용자 선택 저장은 앱이 담당하고, 결정된 값만 전달합니다.

import { applyTheme, type Theme } from '@measure-twice/react';

export function updateTheme(theme: Theme) {
  applyTheme(document.documentElement, theme);
}

applyTheme는 light와 dark만 허용합니다. 문서화된 공개 토큰으로 별도 테마를 만드는 경우에는 고유한 data-mt-theme 경계를 직접 선언합니다.

컴포넌트

• 기본과 이동: Button, ButtonLink, Link, SkipLink, Icon, IconButton
• 피드백과 오버레이: Alert, InlineMessage, Dialog, DialogActions, Popover, Progress, Spinner, StatusIndicator
• 폼: TextField, Textarea, Select, Checkbox, RadioGroup, Radio, Switch

컴포넌트는 네이티브 요소와 키보드 동작을 우선하며, 필요한 보이는 이름과 상태 계약을 타입과 JavaScript 경계에서 함께 검증합니다. 전체 API, 접근성 기준, 조합 경계와 상태별 예시는 Storybook 문서에서 관리합니다.

스타일과 토큰

@measure-twice/react/styles.css는 컴포넌트 스타일과 기본 라이트·다크 토큰을 포함합니다. 문서에 이름을 표시한 의미 기반 토큰은 공개 계약이며 앱에서 재정의할 수 있습니다. 원시 색상 팔레트는 빌드 입력에만 존재하며 패키지 CSS에 배포하지 않습니다.

컴포넌트 루트에 전달하는 앱 소유 클래스와 부모 레이아웃의 gap·margin은 소비자가 자유롭게 정합니다. 내부 라벨이나 옵션 그리드처럼 루트 클래스만으로 안전하게 표현할 수 없는 구조는 문서화된 appearance와 공개 컴포넌트 토큰을 사용합니다. .mt-* 클래스, 내부 DOM 순서, --_mt-* 변수는 공개 계약이 아닙니다.

토큰만 사용하는 일반 HTML에서는 소비자가 마크업, 스타일, 입력 동작과 접근성을 구현하고 검증합니다. 공개 CSS를 불러와도 일반 HTML에 컴포넌트 스타일이 자동으로 적용되지는 않습니다. 포커스의 적용 기준과 실행 가능한 HTML·CSS 예제는 Storybook의 Effects & Motion에서 관리합니다.

소비자 경계 린트

내부 구현 의존을 에디터와 CI에서 차단하려면 소비자 프로젝트에 ESLint와 Stylelint를 설치하고 Measure Twice 설정을 활성화합니다. React 컴포넌트만 사용하는 프로젝트는 이 도구를 설치하지 않아도 됩니다.

pnpm add -D eslint@^9 typescript-eslint@^8 stylelint@^17

// eslint.config.mjs
import measureTwice from '@measure-twice/react/eslint';

export default [measureTwice.configs.recommended];

// stylelint.config.mjs
import measureTwice from '@measure-twice/react/stylelint';

export default measureTwice;

두 설정은 생성된 실제 내부 클래스 목록과 공개 토큰 목록을 사용합니다. 따라서 className="mt-button", .mt-radio__input, 테스트 정규식의 내부 클래스, CSS-in-JS의 --_mt-*, 문서에 없는 --mt-*는 오류이고 Tailwind의 mt-2, 앱 소유 .ts-*, 문서화된 의미 기반 --mt-* 토큰은 허용됩니다. 패키지 자체 구현은 소비자 설정의 검사 대상에 포함하지 않습니다.

0.x에서는 실제 소비자 피드백에 따라 공개 API가 바뀔 수 있습니다.