Themes | Surflane

Principles

Choose a theme with data-theme. Without it the page follows the system setting, and light or dark on <html> fixes the choice.
Resolve the theme before the first paint. Read the saved choice on the server, from a cookie for example, so the page never flashes the other theme.
Scope a theme only for previews. Tokens resolve again under any data-theme, which suits an embedded preview but not a second theme on one page.
Change hue and chroma, never lightness. The builder keeps each step at its lightness, so text contrast stays close to the default palette's, and its report shows the result.
Leave status colors alone. An accent theme recolors primary actions, checked controls, progress and focus, while success, danger and caution keep their meaning.

Theme selection

Set data-theme on <html>, or on any element to scope that theme to its subtree. The value is 'light' or 'dark'.

<html data-theme="light">
  <body>
    <!-- A dark preview inside the light page -->
    <section data-theme="dark">…</section>
  </body>
</html>

To animate a change, see Motion. Saving the choice belongs to your app.

shadcn/ui

shadcn.css maps shadcn/ui variables such as --background, --primary and --radius to Surflane tokens. shadcn components then follow every theme, scoped regions included.

@import 'tailwindcss';
@import '@surflane/design-tokens/tokens.css' layer(components);
@import '@surflane/design-tokens/themes/slate.css' layer(components);
@import '@surflane/design-tokens/themes/accent-cyan.css' layer(components);
@import '@surflane/design-tokens/themes/radius-default.css' layer(components);
@import '@surflane/design-tokens/shadcn.css' layer(components);
@import '@surflane/design-tokens/tailwind.css';

/* In your shadcn CSS, keep @theme inline. Delete the :root and .dark
   color blocks and the @custom-variant dark line. */

Theme builder

Pick a neutral tint, an accent and a radius scale. The preview, the contrast report and the CSS below follow your choices.

Neutral

Tints every gray: surfaces, lines and text. Lightness stays fixed per step.

Neutral hue

248°

Tint strength

1.0×

Accent

Fills primary buttons and checked controls, marks progress, and colors focus rings and hovered links. Success keeps its own color.

Accent hue

210°

Accent chroma

0.120

Radius

Scales every corner token. Buttons, badges and switches are pills at half the tallest control's height, so a smaller scale rounds the larger ones first.

Acme Platformplatform-core

2 deployments need review

Approve them before the next release window.

Promote to production automaticallyNotify owners

Service	Environment	Duration (s)	Status
checkout-api	production	184	Live
search-indexer	staging	412	Needs review
report-builder	development	96	Failed

Contrast report

Text pairs in both themes, against the 4.5:1 text minimum.

Contrast of text pairs in the current theme
Pair	Dark	Light	Status
Body text on the sheet `--surf-ink-body / --surf-canvas`	11.35:1	14.65:1	Passes
Secondary text on the sheet `--surf-ink-muted / --surf-canvas`	8.31:1	10.05:1	Passes
Headings on the chrome `--surf-ink / --surf-chrome`	15.57:1	15.57:1	Passes
Secondary text on a recessed surface `--surf-ink-muted / --surf-surface`	9.40:1	9.44:1	Passes
Text on the accent `--surf-on-brand / --surf-brand`	9.87:1	9.87:1	Passes
Focus and hovered links on the sheet `--surf-brand-ink / --surf-canvas`	8.73:1	16.58:1	Passes

CSS

Load this with the tokens. It sits in the surflane.themes layer, so import order doesn't matter, and scoped data-theme regions keep working.

/* Surflane theme: slate, accent cyan, radius default */
@layer surflane.tokens, surflane.themes, surflane.base, surflane.components, surflane.sizes;
@layer surflane.themes {
  :root,
  [data-theme='dark'],
  [data-theme='light'] {
    --surf-radius-sm: 6px;
    --surf-radius-md: 10px;
    --surf-radius-lg: 16px;
    --surf-radius-sheet: 20px;
    --surf-control-radius: 8px;
    --surf-radius-pill: 22px;
  }
  :root,
  [data-theme='dark'] {
    --surf-chrome: oklch(0.2368845 0.00973297 248.23792711);
    --surf-canvas: oklch(0.27850211 0.01320057 253.03643104);
    --surf-surface: oklch(0.2368845 0.00973297 248.23792711);
    --surf-code-bg: oklch(0.2050126 0.00860311 247.9381172);
    --surf-hover: oklch(0.31355761 0.01463569 251.36854651);
    --surf-selected: oklch(0.37866351 0.01730498 248.2836448);
    --surf-line: oklch(0.37866351 0.01730498 248.2836448);
    --surf-ink-muted: oklch(0.81668066 0.0183769 253.3626611);
    --surf-ink-body: oklch(0.91321146 0.017061 242.44074644);
    --surf-ink: oklch(0.9781762 0.0034179 247.8580546);
    --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-minor: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-major: oklch(0.37866351 0.01730498 248.2836448);
    --surf-guide: oklch(0.37866351 0.01730498 248.2836448);
    --surf-brand: oklch(0.82 0.12 210);
    --surf-brand-tint: oklch(0.82 0.12 210 / 0.25098039);
    --surf-brand-ink: oklch(0.82 0.12 210);
  }
  :root[data-theme='light'],
  [data-theme='light'] {
    --surf-chrome: oklch(0.9781762 0.0034179 247.8580546);
    --surf-canvas: oklch(1 0 0);
    --surf-surface: oklch(0.9781762 0.0034179 247.8580546);
    --surf-code-bg: oklch(0.95972296 0.00515149 247.87778139);
    --surf-hover: oklch(0.95972296 0.00515149 247.87778139);
    --surf-selected: oklch(0.93531009 0.01353396 240.96010253);
    --surf-line: oklch(0.93531009 0.01353396 240.96010253);
    --surf-ink-muted: oklch(0.37866351 0.01730498 248.2836448);
    --surf-ink-body: oklch(0.27850211 0.01320057 253.03643104);
    --surf-ink: oklch(0.2368845 0.00973297 248.23792711);
    --surf-brand-ink: oklch(0.2368845 0.00973297 248.23792711);
    --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
    --surf-grid-minor: oklch(0.95972296 0.00515149 247.87778139);
    --surf-grid-major: oklch(0.93531009 0.01353396 240.96010253);
    --surf-guide: oklch(0.91321146 0.017061 242.44074644);
    --surf-brand: oklch(0.82 0.12 210);
    --surf-brand-tint: oklch(0.82 0.12 210 / 0.30196078);
  }
  @media (prefers-color-scheme: light) {
    :root:not([data-theme='dark']):not([data-theme='light']) {
      --surf-chrome: oklch(0.9781762 0.0034179 247.8580546);
      --surf-canvas: oklch(1 0 0);
      --surf-surface: oklch(0.9781762 0.0034179 247.8580546);
      --surf-code-bg: oklch(0.95972296 0.00515149 247.87778139);
      --surf-hover: oklch(0.95972296 0.00515149 247.87778139);
      --surf-selected: oklch(0.93531009 0.01353396 240.96010253);
      --surf-line: oklch(0.93531009 0.01353396 240.96010253);
      --surf-ink-muted: oklch(0.37866351 0.01730498 248.2836448);
      --surf-ink-body: oklch(0.27850211 0.01320057 253.03643104);
      --surf-ink: oklch(0.2368845 0.00973297 248.23792711);
      --surf-brand-ink: oklch(0.2368845 0.00973297 248.23792711);
      --surf-on-brand: oklch(0.2368845 0.00973297 248.23792711);
      --surf-grid-minor: oklch(0.95972296 0.00515149 247.87778139);
      --surf-grid-major: oklch(0.93531009 0.01353396 240.96010253);
      --surf-guide: oklch(0.91321146 0.017061 242.44074644);
      --surf-brand: oklch(0.82 0.12 210);
      --surf-brand-tint: oklch(0.82 0.12 210 / 0.30196078);
    }
  }
}

Preset files

Each preset ships as a file. Import any neutral, accent and radius file with the tokens.

@import '@surflane/design-tokens/tokens.css';
@import '@surflane/design-tokens/themes/slate.css';
@import '@surflane/design-tokens/themes/accent-cyan.css';
@import '@surflane/design-tokens/themes/radius-default.css';

Themes in code

createTheme returns the same values for your own inputs, and themeCss turns them into CSS.

import { createTheme, themeCss } from '@surflane/design-tokens/theme-builder'

const theme = createTheme({
  neutral: { hue: 248, chroma: 1 },
  accent: { hue: 210, chroma: 0.12 },
  radius: 1,
})
const css = themeCss(theme)