caustica-design

Caustica Design System

Caustica Design takes its name from the bright patterns light makes when it shines through glass or water — like the shimmer on a pool floor, or the glow under a drinking glass.

It is a glass UI library for the web: glassmorphism components, OKLCH design tokens, and a CSS design system that keeps screens soft and see-through — with typed React and Vue component libraries when you need behavior, plus custom elements for Angular and other stacks. One foundation for color, theme, and translucent UI.

Migration: Install caustica-design (same CSS/React surface). Bare caustica and @apply-agent/design-system are retired — update import paths.

Install

npm install caustica-design

Peer dependencies: React (react / react-dom ≥ 18) or Vue (vue ≥ 3.4) only if you import those entries. Angular uses custom elements — no Angular peer.

import 'caustica-design/css' // or 'caustica-design/css/foundation'
import { Button, useTheme } from 'caustica-design/core'

Vue:

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

Angular:

import 'caustica-design/css'
import { provideCaustica } from 'caustica-design/angular'
provideCaustica()

<ca-button variant="primary">Continue</ca-button>

Wrap your app shell in .ca-root (recommended). Canvas glow and grain sit behind content either way.

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

Glass: avoid nesting many blurred surfaces (navbar + panel grids + cards). For dense UIs, lower frost or fill:

:root {
  --ca-blur-glass: 16px; /* default 32px */
  --ca-glass-fill: 0.8; /* default 1 */
  --ca-glass-edge: 1; /* default 1 */
  --glass-blur: var(--ca-blur-glass);
}

CSS-only via CDN (jsDelivr / unpkg):

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/caustica-design/dist/index.css" />

React still needs a bundler — import from caustica-design/core. Vue from caustica-design/vue. Angular calls provideCaustica() then uses <ca-*> tags (add CUSTOM_ELEMENTS_SCHEMA). Set data-theme="light" | "dark" on <html> (or use useTheme / setTheme in React). After the package CSS, recolor with --ca-hue / --ca-chroma and retune glass with --ca-blur-glass / --ca-glass-fill / --ca-glass-edge in a host stylesheet (Getting started → Brand palette, Glass knobs). Serve /icons/*.svg from this package’s public/icons or dist/icons.

Docs

Local: npm run docs:dev → http://127.0.0.1:5175/ (docs + examples at /examples/). npm run dev is the same stack on port 5174.

Guides: Getting started, Tokens, Theming. Product home: site/index.html. Component pages under site/components/. Examples-only server: npm run examples:dev.

What’s included

• Tokens — DTCG JSON (tokens/) + 3-layer CSS (src/css/tokens/)
• CSS — foundation or full stylesheet (caustica-design/css)
• React — typed wrappers from caustica-design/core
• Vue — typed wrappers from caustica-design/vue
• Angular / elements — light-DOM custom elements from caustica-design/angular
• Docs site — site/ (built to site-dist/ via npm run docs:build)

See DESIGN.md for principles. Full API surface is in the docs / src/core/.

License & notices

• Code: dual MIT OR Apache-2.0 — Copyright (c) 2026 Ali Abolwafa (Apache-2.0 adds an express patent grant)
• Disclaimer / liability: DISCLAIMER.md
• Trademarks: TRADEMARKS.md (Caustica Design marks; third-party names are not endorsed)
• Launch / domain checklist: LEGAL.md
• Site legal pages: Privacy, Terms, Cookies, License (/license on the docs site; raw /LICENSE.txt + /LICENSE-APACHE.txt)
• Third-party: NOTICE (IBM Plex Sans Arabic under SIL OFL 1.1; original icons)
• Security: SECURITY.md
• Contributing / DCO: CONTRIBUTING.md

This package ships no runtime npm dependencies (React is an optional peer). These docs are not legal advice.

Publishing

Requires npm login with rights to publish the caustica-design package.

npm run test:ci && npm publish --access public

publishConfig.access is already public. Do not publish without a green test:ci.

Scripts