Install | Surflane

Your setup

The steps below follow these choices, and the page address keeps them.

Framework

Package manager

Extra components

Each brings its own library. Pick only what you use; the rest stays out of your install.

Options

Tailwind CSS v4Utilities read Surflane tokens and override components.Brand fontsManrope, Pretendard and JetBrains Mono. Off, system fonts.Remember the themeAdds ThemeSwitch: light, dark or the device's setting, remembered. Off, always light.

1. Install

The three Surflane packages ship with one version. Base UI is a peer, and everything needs React 19.

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

2. Add the files

Replace each file, or create it where it is missing.

@surflane/ui/all.css loads every Surflane stylesheet. Drop the template's own stylesheet: its unlayered rules would override Surflane. data-theme picks the theme before the first paint; surf-typography applies document 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. Check

The page source has data-theme on <html>.
The button fills with the brand color. Plain text means the styles did not load.

With AppShell

AppShell fills the window and its edge is square, so the document around it must not show: remove the browser's 8px body margin and paint the background in the shell's chrome. The shell takes its container's height, so give the window's height to the document and to the element your app renders into, #root here. On a phone the page inside meets the screen's edges.

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

Your CSS and the layers

Surflane keeps its rules in surflane.* cascade layers, so your own unlayered CSS overrides them, whatever the specificity.
A reset stays below Surflane when you declare its layer first, as in the example under “Layer order”.

Themes Framework integration Example apps