Getting started

Start here: install the package, load CSS (and React if you want), wrap your app in .ca-root, then wander the product overview, components, and examples when you’re ready to feel the glass.

Why “Caustica Design”

A caustic is the bright shape light makes when it passes through glass or water — like the shimmer on a pool floor, or the glow under a drinking glass.

We chose the name because that is the feeling we want on screen — soft light through glass — and the future of design we are shaping: open and layered, not heavy and boxed-in — thin borders, quiet highlights, and motion that stays out of the way. The npm package is caustica-design so it stays distinct from unrelated Blender / 3D tools that also use “caustica.”

Why use Caustica Design

Reach for it when you want that quiet shimmer — and a hand in what interfaces feel like next. Glass UI from OKLCH tokens and CSS, with React only when you need typed behavior.

  • Like light through glass — not chrome

    Screens breathe. See-through surfaces, thin borders, and soft highlights — closer to the shimmer on a pool floor than a wall of solid boxes.

  • Color that stays calm in light and dark

    Color, space, and type live in OKLCH custom properties. Themes swap semantic aliases only — the look shifts without a color engine or runtime theme scripts.

  • CSS owns the look; React is optional

    caustica-design/css class names define the look in any stack. Add caustica-design/core when you want typed props, portals, and keyboard behavior.

Install

npm install caustica-design

Pin a release with npm install caustica-design@0.2.4 if you want an exact version. Peer dependencies for React wrappers: react and react-dom ≥ 18.

CSS imports

Prefer the foundation entry when you only need fonts, tokens, and body chrome. Use the full stylesheet for component classes (.btn, .panel, …).

Foundation

import 'caustica-design/css/foundation'

Full system

import 'caustica-design/css'

Or link the built file from node_modules:

<link rel="stylesheet" href="node_modules/caustica-design/dist/index.css" />

CDN (CSS only)

For stylesheets without a bundler, use jsDelivr or unpkg. React components still need a bundler via caustica-design/core. 

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/caustica-design@0.2.4/dist/index.css" />
<!-- unpkg equivalent -->
<link rel="stylesheet" href="https://unpkg.com/caustica-design@0.2.4/dist/index.css" />

Importing only token CSS is not enough — without base.css / foundation you lose body font, canvas glow, and grain.

App shell

Wrap the page in .ca-root. Glow and grain sit behind content either way; the class is the recommended single stacking root for host apps. 

<body>
  <div class="ca-root">…</div>
</body>

Glass performance

Avoid nesting many blurred surfaces (sticky navbar + panel grids + cards). For dense UIs, lower --ca-blur-glass / --glass-blur (default 32px). Hosts without backdrop-filter get stronger opaque glass tokens automatically. 

:root {
  --ca-blur-glass: 16px;
  --glass-blur: var(--ca-blur-glass);
}

React

import 'caustica-design/css'
import { Button } from 'caustica-design/core'

export function Example() {
  return <Button variant="primary">Continue</Button>
}

Theme toggle

Dark is the default. Set data-theme on <html> to switch light/dark — the same contract as the living style guide. 

<html lang="en" data-theme="dark">
document.documentElement.setAttribute('data-theme', 'light')
// or from React: import { setTheme, useTheme } from 'caustica-design/core'

If you persist theme across full page loads, restore it with a blocking <head> script before CSS paints — see Avoid a theme flash.

Icons

Mask icons resolve from /icons/*.svg. Serve this package’s public/icons (or dist/icons) from your app’s public root so classes like .ui-icon--send resolve.

Next steps