@flextudio/ui

Flextudio 디자인 시스템 — 테마·토큰·React 컴포넌트.

사내 전용(proprietary). 공개 레지스트리에 배포하지 않으며, 내부 git 태그로만 설치합니다.

설치

# git 태그 버전 고정 설치 (레지스트리 불필요)
npm i git+ssh://[email protected]/<org>/flextudio-ui.git#v0.1.0

# peer deps (소비 앱에 이미 있으면 생략)
npm i react react-dom @emotion/react @emotion/styled

사용

스타일은 Emotion으로 런타임 주입되므로 별도 CSS import는 필요 없습니다(폰트는 예외 — 아래 참고). GlobalStyles(리셋·전역 스타일)는 최상위 ThemeProvider가 자동으로 주입합니다. 기존 앱에 부분 도입하는 등 전역 리셋이 부담스러우면 disableGlobalStyles prop으로 끌 수 있고, 중첩된 ThemeProvider는 이중 주입하지 않습니다.

import { ThemeProvider, Button } from '@flextudio/ui'

export function App() {
  return (
    <ThemeProvider defaultColorMode="dark">
      <Button>버튼</Button>
    </ThemeProvider>
  )
}

폰트

패키지는 폰트를 포함하지 않습니다. 기본 서체(Pretendard GOV)는 소비 앱에서 직접 로드하세요 — 로드하지 않으면 시스템 폰트로 폴백됩니다.

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard-gov.min.css"
/>

사내망 등 외부 CDN을 쓸 수 없는 환경에서는 폰트 파일을 자체 호스팅해서 같은 방식으로 로드하면 됩니다.

색상모드

색상모드는 setColorMode/toggleColorMode로 변경하는 시점에 localStorage(flextudio-color-mode)에 저장되어 새로고침 후에도 유지됩니다(storageKey prop으로 변경 가능). 단순 마운트만으로는 저장하지 않으므로 defaultColorMode를 나중에 바꾸면 미저장 사용자에게 반영됩니다.

SSR 환경에서는 서버가 defaultColorMode로 렌더한 HTML과 클라이언트 저장값이 다르면 하이드레이션 불일치가 발생할 수 있습니다. SSR을 쓴다면 저장된 모드를 서버로 전달하거나(cookie 등) 초기 모드를 고정하는 것을 권장합니다.

GlobalStyles는 ThemeProvider 없이 단독 렌더하면 light 테마 토큰 기준으로 동작합니다.

Toast

토스트는 앱 루트를 ToastProvider로 감싸고 useToast()로 띄웁니다. 위치·자동 닫힘 시간·최대 개수는 provider에서 설정합니다. 뷰포트가 지속 라이브 리전(aria-live="polite")을 소유하므로 스크린리더 낭독이 안정적으로 동작합니다.

import { ThemeProvider, ToastProvider, useToast } from '@flextudio/ui'

// 앱 루트
export function App() {
  return (
    <ThemeProvider>
      <ToastProvider position="bottom-center" duration={4000} limit={3}>
        <Page />
      </ToastProvider>
    </ThemeProvider>
  )
}

// 사용처
function Page() {
  const { toast, dismiss, dismissAll } = useToast()
  return (
    <button
      onClick={() => {
        toast({ text: '저장되었습니다.' })
        toast({ text: '수동으로 닫을 때까지 유지', rightButton: 'close', duration: null })
      }}
    >
      저장
    </button>
  )
}

<Toast>를 직접 렌더하면 순수 표시용 박스로 동작합니다(라이브 리전·자동 닫힘 없음).

Emotion 테마 타입

theme는 자동으로 Flextudio Theme로 타입됩니다 — emotion의 useTheme()와 styled 콜백의 theme가 별도 설정 없이 자동완성됩니다.

개발

npm install
npm run build       # dist/ 생성 (ES + CJS + d.ts)
npm run storybook   # 컴포넌트 카탈로그