v1.5
npm install convergence-uiyarn add convergence-uipnpm 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 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 },
// ...
};
// 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. |
| 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.
--radius): Controlled in rem units for accessible, scalable rounding.--border-width): Controlled in exact px units for sharp strokes.--border-style): Toggle between solid, dashed, and dotted borders.The package comes with several curated presets out of the box:
Convergence UI is fully type safe. Key interfaces include ThemeConfig
import { OklchColor, ThemeConfig, ThemeKey } from "convergence-ui";
// OklchColor { l: number; c: number; h: number; }
// ThemeConfig includes:
// background, foreground, primary, secondary,
// OklchColor represents a color in the OKLCH color space.
// { l: number; c: number; h: number; }
// 'l' (lightness): 0-1 (0% to 100%)
// 'c' (chroma): 0-0.4 (0% to 40%)
// 'h' (hue): 0-360 (degrees)
// ThemeConfig is the main interface for defining your theme.
// It includes all the CSS variable keys that Convergence UI manages.
// Example keys:
// background, foreground, primary, secondary,
// accent, muted, destructive, border, input, ring,
// chart-1...5, sidebar, and more.Convergence UI operates by dynamically creating, updating, and synchronizing a set of CSS Custom Properties (CSS variables) right in the browser's Document Object Model (DOM).
The engine standardizes all color manipulation around the OKLCH color space to guarantee perceptual uniformity (meaning changes in lightness are perceived consistently across different hues).
Colors are stored internally as simple objects: { l: number, c: number, h: number }.
Hex inputs from native pickers are intercepted and mathematically converted to OKLCH on the fly.
Adjusting a color calls setProperty('--color-name', ...) directly on the documentRoot.
UI elements using var(--color-name) update instantly without requiring page reloads.
Typography manages global font families and letter spacing across your entire application.
A global <style> tag is injected on mount to apply CSS variables to base elements like body and button.
Google Fonts (like Inter or Poppins) are dynamically fetched and appended to the document head.
Changes to settings like letter-spacing immediately update root variables, ensuring cascading updates.
The Layout tab manipulates the core structural tokens defining your design system—specifically Border Radius, Border Width, and Border Style.
Utility overrides (like .border and .rounded-*) are injected into a style block on mount.
Standard utility toolkits (like Tailwind CSS) are mathematically overridden to use dynamic tokens.
Sliders update underlying rem and px variables, while styling tabs toggle border-style.
Adjusting any layout control triggers an instant global UI repaint based on your new settings.