설치 | Surflane

설정

아래 단계는 이 선택을 따르며, 페이지 주소에 선택이 남습니다.

프레임워크

패키지 관리자

추가 컴포넌트

각자 라이브러리를 함께 설치합니다. 쓰는 것만 고르면 나머지는 설치되지 않습니다.

옵션

Tailwind CSS v4유틸리티가 Surflane 토큰을 읽고 컴포넌트 스타일을 덮어씁니다.브랜드 글꼴Manrope, Pretendard, JetBrains Mono. 끄면 시스템 글꼴을 씁니다.테마 기억ThemeSwitch를 더합니다. 라이트, 다크, 기기 설정 중 고른 것을 기억합니다. 끄면 항상 라이트 테마입니다.

1. 설치

Surflane 패키지 세 개는 한 버전으로 함께 배포됩니다. Base UI는 피어 의존성이고, 모두 React 19가 필요합니다.

npm install @surflane/ui @surflane/design-tokens @surflane/css @base-ui/react @fontsource-variable/manrope @fontsource-variable/jetbrains-mono pretendard

2. 파일 추가

각 파일을 바꾸고, 없는 파일은 새로 만드세요.

@surflane/ui/all.css가 모든 Surflane 스타일시트를 불러옵니다. 템플릿의 스타일시트는 빼세요. 레이어 밖의 규칙이라 Surflane을 덮어씁니다. data-theme이 첫 페인트 전에 테마를 정하고, surf-typography가 문서 타이포그래피를 적용합니다.

import type { Metadata } from 'next'
import '@fontsource-variable/manrope'
import '@fontsource-variable/jetbrains-mono'
import 'pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css'
import '@surflane/ui/all.css'

export const metadata: Metadata = { title: 'My app' }

export default function RootLayout({ children }: LayoutProps<'/'>) {
  return (
    <html lang='en' data-theme='light'>
      <body className='surf-typography'>{children}</body>
    </html>
  )
}

3. 확인

페이지 소스의 <html>에 data-theme이 있습니다.
버튼이 브랜드 색으로 채워집니다. 글자만 보이면 스타일을 불러오지 못한 것입니다.

AppShell을 쓸 때

AppShell은 창 전체를 채우고 가장자리가 직각이므로, 그 바깥 문서가 보이면 안 됩니다. 브라우저의 기본 body 여백 8px를 없애고 배경을 셸의 크롬 색으로 칠하세요. 셸은 담는 요소의 높이를 따르므로, 문서와 앱을 그리는 요소(여기서는 #root)에 창 높이를 넘겨 주세요. 휴대폰에서는 안쪽 페이지가 화면 가장자리까지 닿습니다.

html,
body,
#root {
  height: 100%;
}
body {
  margin: 0;
  background: var(--surf-chrome);
}

앱 CSS와 레이어

Surflane은 규칙을 surflane.* 캐스케이드 레이어에 두므로, 레이어 밖의 앱 CSS가 명시도와 관계없이 Surflane을 덮어씁니다.
리셋은 “레이어 순서”의 예시처럼 레이어를 먼저 선언하면 Surflane 아래에 놓입니다.

테마 프레임워크 통합 예제 앱