A lightweight, powerful engine for real-time CSS theme generation and management. convergence-ui makes it effortless to create, preview, and export design tokens for your web applications using modern OKLCH color spaces and advanced typography controls.
- 🎨 Real-time Theme Generation: Instantly visualize changes as you adjust colors.
- 📐 OKLCH Color Space: Uses modern perceptual color models for consistent and vibrant palettes.
- 🔡 Typography Management: Customizing sans-serif, serif, and monospace fonts along with letter-spacing.
- 📏 Layout Tokens: Manage border radius and border width variables.
- 🌐 Google Fonts Integration: Automatically loads popular Google Fonts (Inter, Poppins, Roboto, etc.) when selected.
- 🔄 Two-way Syncing: Initializes from your existing CSS variables on mount.
- 📦 Zero-Config UI Component: Includes a drop-in
<Convergence />component for an immediate theme editor overlay. - 💾 Presets: Built-in presets: Light, Dark, Cold, and Warm.
- 📋 Export to CSS: One-click copy of generated CSS variables (colors, typography, and layout) to your clipboard.
npm install convergence-ui
# or
yarn add convergence-ui
# or
pnpm add convergence-uiThe easiest way to use Convergence is to drop the <Convergence /> component into your application's root layout or a specific page. It provides a collapsible UI for tweaking your application's design tokens in real-time.
import { Convergence } from "convergence-ui";
export default function RootLayout({ children }) {
return (
<html lang="en">
<body>
{children}
{/* Add the Convergence overlay */}
<Convergence />
</body>
</html>
);
}The component will appear as a floating toggle button with a Paint Roller icon in the bottom-right corner of your screen.
You can also use the underlying ConvergenceEngine to manipulate themes programmatically.
import { ConvergenceEngine, ThemeConfig } from "convergence-ui";
const myTheme: ThemeConfig = {
// define your oklch colors here
primary: { l: 0.5, c: 0.2, h: 250 },
background: { l: 0.99, c: 0, h: 0 },
// ... and other required keys
};
// Initialize the engine
const engine = new ConvergenceEngine(myTheme, { autoApply: true });
// Update a specific color
engine.setOklch("primary", { l: 0.6, c: 0.2, h: 250 });The <Convergence /> component accepts the following props:
| Prop | Type | Default | Description |
|---|---|---|---|
initialConfig |
ThemeConfig |
DARK_THEME |
The starting configuration for the theme editor. |
syncStart |
boolean |
true |
If true, the editor will read the current CSS variables from the DOM on mount, overriding initialConfig. |
className |
string |
undefined |
Optional CSS class for the wrapper element. |
Convergence UI provides built-in support for managing global typography and layout variables. It injects a style tag to apply chosen fonts and letter-spacing across your application, and outputs common design system layout variables.
- Sans-Serif: Inter, Poppins, Roboto, Open Sans.
- Serif: Georgia, Merriweather, Playfair Display, Garamond.
- Monospace: Menlo, JetBrains Mono, Fira Code, Courier.
- Letter Spacing: Fine-grained control with real-world units (px/em).
- Border Radius (
--radius): Controlled inremunits for accessible, scalable rounding. - Border Width (
--border-width): Controlled in exactpxunits for sharp strokes. - Border Style (
--border-style): Toggle betweensolid,dashed, anddottedborders.
The package comes with several curated presets out of the box:
- Light: Minimalist, clean light theme.
- Dark: Deep zinc-based dark mode.
- Cold: A professional blue-toned "oceanic" theme.
- Warm: A cozy, red-tinted "sunset" theme.
convergence-ui is written in TypeScript and exports all necessary types.
import { OklchColor, ThemeConfig, ThemeKey } from "convergence-ui";
// OklchColor structure
// { l: number; c: number; h: number; }MIT