Optzn UI

Optzn UI is a source-friendly, accessible React component library for internal portals. It intentionally does not own routing, server state, authorization, or business-data persistence.

Use

Install the packages with React 19 and Tailwind CSS 4 (4.1.14 or later; ^4.1 installs the newest 4.x release). Keep @tailwindcss/vite on the same version as tailwindcss: its Vite peer range decides which Vite works (Vite 8 needs 4.2.2 or later):

npm install @optizon/[email protected] @optizon/[email protected] react@^19 react-dom@^19
npm install -D tailwindcss@^4.1 @tailwindcss/vite@^4.1

Configure Tailwind 4 (for Vite, add @tailwindcss/vite to the Vite plugins). In your application stylesheet:

@import "@optizon/tokens";
/* Relative to this stylesheet; adjust for your project layout. */
@source "../node_modules/@optizon/ui/src";

Import this application stylesheet once from your entry point, then wrap your application with UIProvider:

import { UIProvider, Button } from "@optizon/ui";

<UIProvider defaultTheme="system" locale="en-US" timeZone="UTC"><Button>Save</Button></UIProvider>

Everything else is a separate package at the same version, installed only when the app uses it, each with its own stylesheet line: @optizon/charts (charts), @optizon/markdown (Markdown and model output), @optizon/math (TeX math; @import "@optizon/math/styles.css";), @optizon/code (code blocks, editors and diffs), @optizon/diagrams (Mermaid diagrams) and @optizon/chat (AI agent chat). For example, npm install @optizon/[email protected] and @source "../node_modules/@optizon/charts/src"; to draw charts. @optizon/ui imports none of them.

React and React DOM 19 are peers. Packages ship compiled ESM, TypeScript declarations, and component source. CommonJS is not supported. Licensed under Apache-2.0.

To prevent a light flash on refresh or navigation, initialize the document theme before styles and application code. In a server-rendered document, render <ThemeScript /> from @optizon/ui inside <head>. For static HTML, embed the JavaScript returned by getThemeScript() from the React-free @optizon/ui/theme entry point in a synchronous head script. The bundled agent skill's references/setup.md shows build-time injection with a small Vite plugin for development and production.

Use matching defaultTheme and storageKey options in the initializer and UIProvider. The provider persists light/dark/system preferences under optzn-ui-theme, follows system changes, and synchronizes other tabs. Set storageKey={null} to disable persistence. Root providers theme the document; nested providers default to local scopes without persistence. Use themeScope="local" for an embedded widget.

For CSP, ThemeScript accepts a request nonce; static hosts can authorize the exact generated script with a hash or serve it as an allowed blocking external script. When hydrating the document, set suppressHydrationWarning on <html> because initialization intentionally changes its theme attributes before hydration. Complete, typechecked SSR and static examples are in the repository's preview app (Configuration page), https://github.com/optzn/ui.

Source and documentation: https://github.com/optzn/ui

Agent skill

npx @optizon/[email protected] install-skill
npx @optizon/[email protected] install-skill --scope user

Installs the bundled optizon-ui-design skill for Codex and Claude Code; it covers every @optizon package, with a reference for each. The default scope is the current project; user scope applies across your projects. Select one agent with --agent codex or --agent claude, or choose a project with --project <directory>. --dry-run previews destinations. Existing skills are protected unless --force is passed, which replaces local edits too.

Codex installs under .agents/skills; Claude Code under .claude/skills. User scope uses those paths in your home directory. The skill, license, component reference, and version manifest come from this exact npm release.

Invoke $optizon-ui-design in Codex or /optizon-ui-design in Claude Code.