@surflane/ui

React 19 components for the Surflane design system, built on Base UI, with data, chart, date, tree, code highlighting and Markdown components. Browse them in the catalog.

npm install @surflane/ui @surflane/design-tokens @surflane/css @base-ui/react

@surflane/ui, @surflane/design-tokens and @surflane/css are released together with one version. Base UI is a peer dependency, 1.9 or later, so your app and Surflane share one copy. The package is ESM-only.

Usage

Import the stylesheets once at the application root. all.css brings the tokens, the theme transition, controls, composition, document typography and component styles:

@import '@surflane/ui/all.css';

To ship only what you use, import component stylesheets instead, such as @surflane/ui/button.css and @surflane/ui/dialog.css. Each brings the tokens and the styles of what its component renders. The rules sit in surflane.* cascade layers, so your unlayered CSS overrides them. Set data-theme="light" or data-theme="dark" on <html> before the first paint and add surf-typography to <body>. With AppShell, which fills the window, also give <body> no margin and the --surf-chrome background. The install guide walks through Vite, Next.js, React Router and Astro, with or without Tailwind CSS.

import {
  Button,
  DialogContent,
  DialogRoot,
  DialogTitle,
  DialogTrigger,
} from '@surflane/ui'

export function Example() {
  return (
    <DialogRoot>
      <DialogTrigger render={<Button variant='primary' />}>Open</DialogTrigger>
      <DialogContent>
        <DialogTitle>Surflane</DialogTitle>
      </DialogContent>
    </DialogRoot>
  )
}

Compound components are available both as namespaces (Dialog.Root) and as flat names (DialogRoot). Use flat names in React Server Components, which cannot dot into client exports. Every component also has its own entry point, named after its page in the catalog, such as @surflane/ui/checkbox or @surflane/ui/sheet.

Optional components

LineChart, AreaChart, BarChart, ScatterChart, DatePicker, Markdown, Tree and syntax highlighting have their own entry points, and their libraries are optional peer dependencies. Install a library only when you use its component:

| Import | Install | | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------ | | LineChart, AreaChart, BarChart from @surflane/ui/chart | recharts | | ScatterChart from @surflane/ui/scatter-chart | recharts | | DatePicker, DateRangePicker, TimeField, DateLocaleProvider from @surflane/ui/date-picker | react-aria-components | | Markdown from @surflane/ui/markdown | react-markdown remark-gfm | | Tree from @surflane/ui/tree | @headless-tree/core @headless-tree/react @tanstack/react-virtual | | SyntaxHighlighting from @surflane/ui/syntax-highlighting | shiki |

CodeBlock and SyntaxHighlighter render plain text until a <SyntaxHighlighting> provider wraps them. With <SyntaxHighlighting suspense>, a server render waits for the tokens and writes highlighted HTML.

Frameworks

Next.js (App Router), React Router, Astro and Vite are verified in CI with example applications. See framework integration and examples.

License

Copyright (c) 2026 ashon. Licensed under either of MIT or Apache-2.0, at your option.