Oxygen UI Design System

Oxygen UI Design System

Oxygen UI (@wso2/oxygen-ui, https://github.com/wso2/oxygen-ui) is this organization's UI toolkit — WSO2's React component library on Material UI v7, with the Oxygen theme already applied to every export. Components, layout, icons, and styling all come from it. Never raw HTML styling, never another component library, never an invented component prop.

You are here because the component you are building pinned this skill, so the whole of it is yours — theming included. The organization's colors are settled in Brand colors below; nobody is interviewed about them, at design time or any other time.

react-webapp owns the app: layout, config, verify sequence, Dockerfile, nginx. This skill owns what goes inside src/ — the UI. Where the two appear to disagree, react-webapp wins; the conflicts worth naming are listed under Platform constraints below.

Correctness through the installed types, not memory

Everything @wso2/oxygen-ui exports is typed, and the types describe the installed version — a guessed prop is never right by comparison. The discipline: before writing a screen, print the API of the composites it uses, then write the JSX — never the reverse. One command does it, from the App Path, after npm install:

node "${AEP_SKILLS_DIR:-.claude/skills}/oxygen-ui-design-system/scripts/props.mjs" PageTitle StatCard ListingTable

It reads the installed .d.ts and prints, per component, every prop with its type and whether it is required, then every sub-component (PageTitle.Actions, ListingTable.Row) with its own props. Name.Sub prints one sub-component. A name that is not an Oxygen composite (Button, TextField, Tabs) is plain MUI v7, re-exported unchanged except for the theme; the script says so and names the MUI API page. Run it per screen, for the composites that screen uses — a lookup made for an earlier screen sits thousands of tokens back and does not count as confirmed. It reads nothing this skill carries, so it cannot drift from the version this app installed.

Oxygen's own docs sit beside the types: components.md is the index of every composite the library ships, patterns.md holds whole-screen compositions, theming.md and migration.md the rest. Read them from the installed package (node_modules/@wso2/oxygen-ui/.claude/), which is matched to the installed version; before npm install has run, the same four files are in references/oxygen/ beside this skill, taken from 0.13.1. Use the index to reach for Oxygen's composite first — ListingTable, PageTitle, Form.*, UserMenu, SearchBar, ComplexSelect, StatCard, NotificationPanel — and drop to a plain MUI primitive (Box, TextField, Chip, still imported from @wso2/oxygen-ui) only where no composite covers the element. The prose is hand-written and lags the types: never settle a prop from it — print it (Known errors below).

Known errors in the package's docs

Seven snippets in the package's .claude/*.md do not compile against the code they ship with — verified against the 0.13.1 types. The .d.ts is right and the prose is wrong. references/app-structure.md beside this skill carries a corrected scaffold.

A snippet that fails tsc is a doc bug, not a version you are missing — print the props and follow them.

Plain MUI components (Button, TextField, Dialog, Chip, Grid, …) keep MUI v7's API; they are re-exported from @wso2/oxygen-ui unchanged except for the theme.

Violating the letter of this rule is violating the spirit of it. "It's just a placeholder page," "the app doesn't have Oxygen wired up yet," and "this screen is throwaway" are reasons to wire Oxygen up faster, not reasons to skip it — a page built in raw <div>s is what deploys, because there is no human code-review gate between your PR and the dev environment.

Setup

react-webapp scaffolds the app. Add Oxygen to it before the first npm install — once the scaffold's package.json is written, from the App Path:

node "${AEP_SKILLS_DIR:-.claude/skills}/oxygen-ui-design-system/scripts/setup.mjs"   # --charts if a screen draws a chart

One command, one install. It pins react and react-dom to exactly the version Oxygen's peer dependency names (a newer 19.x fails npm install with ERESOLVE, and forcing past that ships two Reacts), adds @wso2/oxygen-ui, @wso2/oxygen-ui-icons-react and react-router to package.json, removes any @mui/*, @emotion/* or lucide-react a scaffold slipped in, and runs npm install once. --charts adds @wso2/oxygen-ui-charts-react; --no-install writes the manifest only. Running it again changes nothing. AEP_SKILLS_DIR is where a run finds the skill library; the fallback is the mirror the platform writes into every project, .claude/skills/, which is also where this skill's own scripts/ live.

Never install @mui/*, @emotion/*, or lucide-react yourself. @wso2/oxygen-ui bundles MUI, MUI X and Emotion as its own dependencies, and @wso2/oxygen-ui-icons-react brings lucide; a second copy in package.json gives the app two Emotion caches and two MUI runtimes, and the theme silently stops reaching half the tree. The package README's install line that names @mui/material predates this and is wrong for the version you install. Verify below fails on any of them.

Wire the provider once, outermost, in main.tsx — then the router, then the app. Oxygen bundles its font (Inter Variable) and applies its theme globally from the provider; there is no stylesheet to import or link:

// src/main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { BrowserRouter } from 'react-router';
import { OxygenUIThemeProvider, OxygenTheme } from '@wso2/oxygen-ui';
import App from './App';

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <OxygenUIThemeProvider theme={OxygenTheme}>
      <BrowserRouter>
        <App />
      </BrowserRouter>
    </OxygenUIThemeProvider>
  </StrictMode>,
);

OxygenTheme is the stock theme, and the fallback. It is what a project gets when this organization has not set brand colors — see Brand colors below. Then lay the app out as the sample app is laid out — the next section.

The sample app is the structure

Oxygen ships a reference application, and every web app this platform builds has its shape: the same shell, the same layouts, the same route table, the same page anatomy. Its source is in sample/src/ beside this skill (vendored from samples/oxygen-ui-test-app in the Oxygen UI repo; the npm package does not carry it). Read the real files before scaffolding, and match them rather than inferring structure from prose:

The shell is not negotiable. AppLayout is AppShell with the brand and the account cluster in the header, the app's navigation in the sidebar, the routed page in AppShell.Main, and a Footer. A generated app never moves navigation into the header, never drops the sidebar, and never invents a second shell: the wireframes are drawn against this shell too (wireframes draws a brand-only navbar and a sidebar on every screen), so the wireframe, the running app and the sample line up one to one. What the sample's sidebar shows for its console — organisations, projects, analytics — becomes the wireframe's sidebar items for this app; the categories, icons and footer items (Settings, Help) keep the sample's arrangement.

Known defects in the sample. It is vendored verbatim so a refresh stays a wholesale copy, and it carries a few demo shortcuts a generated app must not inherit — sample/README.md lists them (a login box pre-filled with credentials, a route param read under the wrong name, absolute paths that drop the organisation prefix, a detail page that shows the first record for an unknown id, an advanced filter that is never applied). Take the structure; where a line is on that list, write it right.

What the platform overrides in the sample. Three files are Oxygen's demo wiring, not this platform's — take the structure and not the code: main.tsx (its HashRouter, window.__APP_RUNTIME_CONFIG__ and theme picker; ours is the Setup snippet above, with BrowserRouter and one theme), mock-data/ (this platform's mock is react-webapp's mock/ with msw), and the org/project Header.Switchers selects, which a wireframe has to draw before they exist. references/app-structure.md carries the excerpts already adjusted to this platform.

Brand colors

A web app is themed at its FIRST build, and retrofitting a theme means revisiting every screen — so the colors cannot be a per-build decision. They are an organization decision, settled once in the section below, exactly like the language a service is written in.

Never ask anyone for them. Not at design time, not at coding time, not once per project. The answer is either set below or it is the stock theme, and both are complete answers — a question about theming is a defect, not diligence.

The organization's colors

• Accent (buttons, links, focus): not set — use the stock theme
• Neutral (backgrounds, surfaces): not set — use the stock theme

To brand every web app this organization builds, an org edits those two lines to hex values (Settings → Skills) — HEX only, never color words ("black and yellow" does not say WHICH yellow), e.g. #f5c518 / #0a0a0a. The edit reaches every subsequent build in the org with no conversation involved.

A per-project override still wins, per value, not per section: a hex under the ## Brand colors heading in the project's specs/requirements/prd.md overrides the same line here, and a line that heading omits still comes from this section. That heading is there for a project whose colors someone stated outright — it is not something to solicit.

At build time

Resolve each of the two colors independently, before you wire the theme: the project's ## Brand colors line in specs/requirements/prd.md if it has one, otherwise the line above. A color neither one sets is not chosen — that part of the theme stays stock and nothing is invented. With no hex resolved, the provider keeps OxygenTheme exactly as Setup wires it and this section is done. With one or two, derive src/theme.ts per references/brand-theme.md — a theme of your own from the stock one, never brand colors painted over components through sx.

Verify

This skill's step in react-webapp's verify sequence — after npm install, before npx tsc --noEmit, from the App Path:

node "${AEP_SKILLS_DIR:-.claude/skills}/oxygen-ui-design-system/scripts/verify.mjs"

AEP_SKILLS_DIR falls back to .claude/skills/, the mirror the BFF writes into every project (this skill lands at .claude/skills/oxygen-ui-design-system/). A non-zero exit fails verification like any other step in that sequence, and every failure line names its fix. It is there because Oxygen's wiring faults — a second MUI or Emotion installed beside the bundled one, an import that bypasses @wso2/oxygen-ui, a root not wrapped in OxygenUIThemeProvider, a React that is not the exact version Oxygen's peer dependency names — type-check and build perfectly clean, then render an unthemed or broken page in the cluster: cheap to fix here, expensive to debug after the Docker build.

Platform constraints that override this system's defaults

Five places where Oxygen's own defaults and docs do not fit this platform. Each is a runtime, build, or guidance failure, not a style preference:

1. Never run npx @wso2/oxygen-ui init (or update). That CLI writes CLAUDE.md, AGENTS.md, .claude/oxygen-ui/ and .claude/skills/ into the repo root. Guidance reaches you as skills, so a committed agent file is a second authority that nothing updates — it is stale the moment this skill changes, and it lands in a directory the platform owns. The same docs are already in the installed package (see Correctness above); read them there.
2. Never install the peer set Oxygen's README lists (@mui/material, @emotion/*, @mui/x-*). They are bundled — Setup above.
3. Never set base in vite.config.ts, and never give BrowserRouter a basename, whatever a sample shows. Each web app is served at its own gateway host root; a base 404s every asset and the page renders blank (react-webapp, Served at host root).
4. index.html gets no extra tags. Its only <script> rules are react-webapp's: the synchronous env-config.js tag first, the module bundle second. Oxygen bundles its font, so no <link> for Inter or a stylesheet, and no script tag around those two — it risks window._env_ being unset when the first module evaluates.
5. Theme values are not runtime config. Colors come from src/theme.ts at build time. window._env_ carries only what the browser needs — OIDC config and flags — so do not plumb a theme value through it.

Oxygen replaces hand-written UI, not the platform's data layer: openapi-fetch and the committed src/generated/ client stay exactly as react-webapp specifies. "Install no other library" above is about UI and styling.

Critical rules

1. Import everything from @wso2/oxygen-ui — never from @mui/material, @mui/x-*, Tailwind, Chakra, Ant Design, Bootstrap, or a hand-rolled component. The package re-exports the entire MUI API with the theme applied.

2. Icons come from @wso2/oxygen-ui-icons-react, never lucide-react. It re-exports all of lucide plus the brand icons WSO2, GitHub, GitLab, Bitbucket, Google, Facebook, MCP, Lambda. Two rules the compiler enforces and memory does not:

   • A lucide icon works bare or Icon-suffixed (Pencil and PencilIcon both resolve). Prefer the bare name for consistency, but neither is an error — what fails is a name lucide does not have, like DashboardIcon for LayoutDashboard. Check it at https://lucide.dev/icons/.
   • A brand icon has no Icon alias and is cased exactly as listed — Google not GoogleIcon, GitHub not Github.

   Size with the size prop: <Search size={18} />.

3. MUI X is namespaced: DataGrid.DataGrid, DatePickers.DatePicker, TreeView.SimpleTreeView — import the namespace from @wso2/oxygen-ui.

4. Confirm a composite component's API before using it — print it with scripts/props.mjs (Correctness above); don't guess a sub-component or prop, and don't settle one from the package's prose docs.

5. Colors and spacing are theme tokens through sx, never literals. p: 2, gap: 2, bgcolor: 'background.paper', color: 'text.secondary', borderColor: 'divider' — no hex, no rgb, no raw px. Brand colors live in src/theme.ts (above), never in a component.

6. Layout is Stack/Box/Grid from @wso2/oxygen-ui — never a raw <div>/<span> for spacing or arrangement, and never style={{…}}.

7. Page-level structure follows a precedent, not intuition. Every page is PageContent > PageTitle (PageTitle.Header, .SubHeader, .Actions, .BackButton) > content, inside the AppShell of AppLayout. A screen's header buttons go in PageTitle.Actions — never a Stack around PageTitle with the button beside it, which squeezes the button until its label wraps. Before composing a listing, detail, dashboard, settings, or login screen, find it in the package's .claude/patterns.md and match its composition.

8. Navigation goes through react-router: Sidebar.Item link={<Link to="…" />}, useNavigate() for actions, never a hardcoded <a href>.

9. Dense data is rows, not cards. Use ListingTable for lists of records (variant="card" when each row wants breathing room); Card is for widgets, galleries, or grouped settings — not one card per record.

Reach for these components (not raw MUI, never raw HTML)

Implementing a wireframe with Oxygen

wireframes/references/implementing.md says what each DSL line must become; this is what it becomes here. Every row names the exact component and its props, and what to do when the DSL carries more than the component holds — each was checked against a rendered screen, so follow the row rather than improvising around the component:

The row lines under a table, the stat cards and the selects are the demo data the reviewer compares the screen against. Do not retype them: node "${AEP_SKILLS_DIR:-.claude/skills}/wireframes/scripts/seed.mjs" <wireframes.dsl> prints them per screen as JSON; mock handlers serve those rows, and every stat value derives from them, so the numbers agree with the table by construction.

Pitfalls

Red flags — stop and use Oxygen

• About to write <div style={{...}}>, a className with a stylesheet, or a raw <button>/<table>/<input> for layout, color, spacing, or a control
• About to npm install @mui/*, @emotion/*, lucide-react, or any other component or styling library
• About to run npx @wso2/oxygen-ui init
• About to write JSX for a form, list, card, dialog, nav, or page header from scratch instead of from the Reach-for table and the package's .claude/patterns.md
• Thinking "it's just a placeholder" or "Oxygen isn't set up in this app yet"
• Using a sub-component or prop without having printed it with scripts/props.mjs for this screen
• About to wrap PageTitle in a Stack to place a button beside it, use a bare Select with a label, or put a caption under a StatCard — each is a row in the wireframe table above, with the component that fits
• About to put navigation in the header, drop the sidebar, or lay a page out in a way sample/src/ does not — the sample app is the structure, and the wireframe was drawn against it
• About to satisfy a brand-color requirement by styling components instead of deriving a theme — or about to ignore one because no stock theme matches
• About to ask which theme or colors to use — that is settled in Brand colors, and "not set" means the stock theme, not an open question

All of these mean: stop, open the reference, and use what it documents.