This project uses WSO2 Oxygen UI (@wso2/oxygen-ui) as its design system. Use this skill for ANY React UI work here — setting up Oxygen UI in a new or existing app, and building or editing any component, page, layout, form, table, dialog, wizard, dashboard, card, modal, or theme — even when the request does not mention Oxygen UI by name. It covers installing the correct packages and versions, the OxygenUIThemeProvider + router setup, the canonical app structure (layouts + pages) that mirrors the sample app, reusing composite components (AppShell, ListingTable, Form.*, Header, Sidebar, UserMenu, …) for consistency, theming, and migrating @mui/material / lucide-react code to Oxygen UI.
يبقى الأمر في سطر واحد. مرّر أفقيًا لمراجعته كاملًا قبل النسخ.
تفضّل نسخة محلية؟ نزّل الملفات المتاحة حاليًا لدى SkillsMP.
مستكشف الملفات
40 ملفات
عرض SKILL.md
SKILL.md
تعليمات المصدر · معاينة للقراءة فقط
name
oxygen-ui
description
This project uses WSO2 Oxygen UI (@wso2/oxygen-ui) as its design system. Use this skill for ANY React UI work here — setting up Oxygen UI in a new or existing app, and building or editing any component, page, layout, form, table, dialog, wizard, dashboard, card, modal, or theme — even when the request does not mention Oxygen UI by name. It covers installing the correct packages and versions, the OxygenUIThemeProvider + router setup, the canonical app structure (layouts + pages) that mirrors the sample app, reusing composite components (AppShell, ListingTable, Form.*, Header, Sidebar, UserMenu, …) for consistency, theming, and migrating @mui/material / lucide-react code to Oxygen UI.
Oxygen UI
WSO2's React component library, built on Material UI v7. Everything ships from
@wso2/oxygen-ui with the Oxygen theme already applied. The canonical reference app ships
inside the installed package (read its real source — see
Reading the sample app); match its structure.
Why this skill exists: consistency through reuse
Reuse Oxygen's composite components and its canonical app structure instead of rebuilding
from scratch. Oxygen ships ready-made experiences — an app shell, header, sidebar, listing
table, forms, user menu — and the sample app shows exactly how to wire them into a routed
app. Building from those keeps every Oxygen app visually and behaviorally consistent. Drop
to primitives (Box/Grid) only for genuinely custom UI.
Setup
Oxygen UI bundles MUI and Emotion as dependencies — never install @mui/material,
@emotion/*, or a MUI version yourself; that causes version conflicts (a common cause of
broken/old setups). You only install the Oxygen packages plus React (and a router).
Versions (match the sample app): React 19, @wso2/oxygen-uilatest, Vite,
react-router . Always install rather than guessing a
version.
Then create the canonical structure (see references/app-structure.md — read it from the
installed package, see Reading the references): src/main.tsx
(provider + router), src/App.tsx (maps routes),
src/config/appRoutes.tsx, src/layouts/ (AppLayout with AppShell), src/pages/.
Wrap the app root once in OxygenUIThemeProvider (see Quick start). Then build pages in
the canonical structure (references/app-structure.md, read from the installed package).
Critical rules
Import everything from @wso2/oxygen-ui — never from @mui/material. The package
re-exports the entire MUI API with the Oxygen theme applied (Button, Box,
TextField, Typography, styled, …).
Icons from @wso2/oxygen-ui-icons-react. This package re-exports
lucide-react plus WSO2 brand icons (WSO2, Github,
Google, …). Use the bare lucide name — NOT an Icon suffix — to match the sample
app: import { Search, Plus, Settings, Home, Bell, Users, FolderOpen } from '@wso2/oxygen-ui-icons-react'. (e.g. Search, not SearchIcon; Trash2, not
TrashIcon; there is no EditIcon — use Pencil.)
Charts from @wso2/oxygen-ui-charts-react (Recharts-based).
MUI X is namespaced: DataGrid.DataGrid, DatePickers.DatePicker,
TreeView.SimpleTreeView.
Wrap the app root in OxygenUIThemeProvider with a theme.
Style with theme tokens via sx (p: 2, bgcolor: 'background.paper',
color: 'text.primary') — never hardcode hex colors or pixel spacing.
Page precedents first. Before composing ANY page or page-level surface (header/title,
listing, detail view, dashboard, login), check whether the sample app already has that
page, read its real source, and match its composition — compose from primitives only
when no page-level precedent exists. Skipping this rebuilds headers and listings from
Box/Typography/Grid into pages that don't match the design system; the sample page is
the spec. See Reading the sample app.
Read references/app-structure.md (from the installed package — see
Reading the references) before scaffolding an app or adding
pages/layouts — it has the full main.tsx, appRoutes.tsx, AppLayout, and page templates
from the sample app. In short:
src/main.tsx — OxygenUIThemeProvider (with theme or a themes={[…]} switcher) →
<BrowserRouter> → <App/>.
src/App.tsx — maps appRoutes to <Routes>/<Route>.
src/config/appRoutes.tsx — routes grouped under layouts (AppLayout for the signed-in
app, GateLayout for login, DefaultLayout for standalone pages).
src/pages/*.tsx — each page returns PageContent > PageTitle.Header /
PageTitle.SubHeader > content (a ListingTable for lists, a Grid of Cards, etc.).
Reach for these composite components (not raw MUI)
If you're about to build…
Use instead
Page layout with top bar + side nav
AppShell + Header + Sidebar (+ Footer)
A data table / list view
ListingTable.* (not MUI Table)
A form with grouped sections
Form.Section + Form.Stack (fields are normal TextField)
A multi-step flow / wizard
Form.Wizard
A user avatar + account menu
UserMenu
Light/dark toggle / theme picker
ColorSchemeToggle / ThemeSwitcher
Notifications
NotificationPanel / NotificationBanner
A page heading / page body wrapper
PageTitle / PageContent
A KPI/metric tile
StatCard
Breadcrumbs / search / rich select
AppBreadcrumbs / SearchBar / ComplexSelect
AppShell, Header, Sidebar, ListingTable, Form, NotificationPanel, UserMenu,
and ComplexSelect are compound components (AppShell.Main, Sidebar.Item,
ListingTable.Row, Form.Section, …).
This table is a quick guide; the authoritative component catalog is
references/components.md (see Reading the references for
which copy to read).
Reading the references
The reference files are bundled in references/ next to this SKILL.md, so they are always
available.
When this project also has @wso2/oxygen-ui installed, prefer that package's copy of the
references — they are matched to your installed version, so they stay accurate even if this
skill was installed a while ago (or by npx skills add from a different version). Locate
them:
If the package isn't installed or can't be resolved, use the bundled references/ next to
this file. During a fresh setup (before npm install), the Setup and
Quick start sections above are self-sufficient.
Reading the sample app
The canonical reference app's full source ships inside the installed @wso2/oxygen-ui
package, under .claude/skills/oxygen-ui/sample/src/. Once the package is installed (which
it always is by the time you're building), read the real files instead of inferring structure
from prose. Locate them the same way as the references:
node -p "require('path').dirname(require.resolve('@wso2/oxygen-ui/package.json'))"# then read <that-dir>/.claude/skills/oxygen-ui/sample/src/<file># in this monorepo, read samples/oxygen-ui-test-app/src/<file> directly# fallback: find . -path '*@wso2/oxygen-ui/.claude/skills/oxygen-ui/sample/src/*'
Resolution order: the installed package's copy → (in this repo) the live
samples/oxygen-ui-test-app/src. Read the real files when scaffolding an app or matching an
existing pattern. Where to look:
To see…
Read in sample/src/
Provider + router entry
main.tsx
Route table grouped by layout
config/appRoutes.tsx
App shell (Header/Sidebar/Footer/Outlet)
layouts/AppLayout.tsx
Login / unauthenticated layout
layouts/GateLayout.tsx
Listing page with a table
pages/Organizations.tsx, pages/Projects.tsx
Project / detail page (title, avatar, back button, repo link)
OxygenTheme (default), AcrylicOrangeTheme, AcrylicPurpleTheme, ClassicTheme,
HighContrastTheme, PaleBaseTheme, PaleGrayTheme, PaleIndigoTheme, WSO2Theme.
Custom theme: createOxygenTheme(overrides) (extends the Oxygen base). This list is a quick
guide; the authoritative set of themes is in references/theming.md (see
Reading the references for which copy to read).
