WSO2 Oxygen-UI

WSO2 Oxygen-UI is the official design system and React component library for WSO2 products, built on top of Material-UI v7. It provides a consistent, modern, and accessible user experience across all WSO2 applications, enabling rapid development and seamless integration with the latest frontend technologies.

Oxygen-UI delivers:

• A comprehensive set of ready-to-use UI components + icons, themed for WSO2 brand and product needs
• Full compatibility with Material-UI v7.3.5 and its ecosystem
• Full compatibility with Lucide v0.553
• Support for custom WSO2 components, icons and design patterns
• Easy integration with Vite, Nx, and modern React workflows

Prerequisites

Before you begin, ensure you have the following installed:

• Node.js (v24 or newer recommended)
• pnpm (v10 or newer recommended)

Usage Example

Installing Oxygen UI

Install the main Oxygen UI library:

pnpm add @wso2/oxygen-ui @wso2/oxygen-ui-icons-react

This will automatically install all required dependencies including Material-UI, Emotion, and other peer dependencies.

Additional Packages

Charts:

pnpm add @wso2/oxygen-ui @wso2/oxygen-ui-charts-react

Note: If using npm or yarn, you may need to install peer dependencies manually. With pnpm, peer dependencies are installed automatically.

Using Components

Import any Material-UI or Oxygen-UI custom component:

import { OxygenUIThemeProvider, Button, TextField } from '@wso2/oxygen-ui';

function App() {
  return (
    <OxygenUIThemeProvider>
      <Button variant="contained">Hello World</Button>
      <TextField label="Name" />
    </OxygenUIThemeProvider>
  );
}

Note: import { Button } from '@wso2/oxygen-ui' is equivalent to import { Button } from '@mui/material'

Refer to Material-UI documentation for component usage details.

Using MUI X Components

For DataGrid and DatePickers, use namespace imports:

import { DataGrid } from '@wso2/oxygen-ui';

function MyDataGrid() {
  return (
    <DataGrid.DataGrid
      rows={rows}
      columns={columns}
    />
  );
}

See the @wso2/oxygen-ui README for detailed usage.

Using Icons

Import Lucide icons or Oxygen-UI custom icons:

import { Bell, WSO2 } from '@wso2/oxygen-ui-icons-react';

Note: import { Bell } from '@wso2/oxygen-ui-icons-react' is equivalent to import { Bell } from 'lucide-react'

Refer to Lucide documentation for the complete icon list.

Build Instructions

Install required dependencies:

pnpm i

To build the project and all packages:

pnpm build

To see view the usage instructions:

pnpm storybook

To run the sample app:

cd samples/oxygen-ui-test-app
pnpm dev

Project Structure

The workspace is organized as follows:

oxygen-ui/
├── packages/
│   ├── oxygen-ui/                        # Main Oxygen-UI component library (@wso2/oxygen-ui)
│   ├── oxygen-ui-charts-react/           # Oxygen-UI charts library (@wso2/oxygen-ui-charts-react)
│   ├── oxygen-ui-docs/                   # Oxygen-UI docs - storybook
│   ├── oxygen-ui-icons-react/            # Oxygen-UI icons library (@wso2/oxygen-ui-icons-react) 
│   └── eslint-plugin-oxygen-ui/          # ESLint plugin for enforcing Oxygen-UI import patterns
├── samples/
│   └── oxygen-ui-test-app/               # Example Vite + React app using Oxygen-UI
├── README.md
├── package.json
├── pnpm-workspace.yaml
└── nx.json

AI-Assisted Development

Oxygen UI includes built-in documentation for AI assistants, enabling AI coding tools to understand the component library and generate correct code.

Universal Setup (Works with any AI)

npx @wso2/oxygen-ui init

Creates:

• AGENTS.md - Streamlined AI guide at project root
• .ai/oxygen-ui/ - Detailed documentation:
  • components.md - Component API reference
  • patterns.md - Common UI patterns
  • theming.md - Theme customization
  • migration.md - Migration guide

Claude Code Setup (Recommended for Claude)

npx @wso2/oxygen-ui init --claude

Creates:

• .claude/oxygen-ui/ - Claude-optimized documentation
• .claude/skills/ - Invokable skills:
  • /oxygen-component - Generate Oxygen UI components
  • /oxygen-layout - Generate app layouts
  • /oxygen-form - Generate forms with validation
  • /oxygen-migrate - Migrate MUI code
• Updates root CLAUDE.md with reference

Updating After Upgrade

npx @wso2/oxygen-ui update           # Universal
npx @wso2/oxygen-ui update --claude  # Claude-specific

AI Documentation

For detailed information, see the generated files:

• Components: .ai/oxygen-ui/components.md or .claude/oxygen-ui/components.md
• Patterns: .ai/oxygen-ui/patterns.md or .claude/oxygen-ui/patterns.md
• Theming: .ai/oxygen-ui/theming.md or .claude/oxygen-ui/theming.md
• Migration: .ai/oxygen-ui/migration.md or .claude/oxygen-ui/migration.md

See the @wso2/oxygen-ui README for more details.

License

Licenses this source under the Apache License, Version 2.0 (LICENSE), You may not use this file except in compliance with the License.

---

(c) Copyright 2025 WSO2 LLC.