`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:
```bash
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:
```tsx
// 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(
,
);
```
`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:
| To see… | Read in `sample/src/` |
|---|---|
| The app shell: `Header` (toggle, brand, actions) in `AppShell.Navbar`, `Sidebar` categories and items in `AppShell.Sidebar`, `AppShell.Main`, `Footer` | `layouts/AppLayout.tsx` |
| The route table grouped under layouts | `config/appRoutes.tsx`, `App.tsx` |
| Login / unauthenticated layout | `layouts/GateLayout.tsx` |
| A listing page with a table and a page-title action | `pages/Organizations.tsx`, `pages/Projects.tsx` |
| A detail page (title, avatar, back button, sections) | `pages/ProjectOverview.tsx` |
| Rows-as-cards listing (`ListingTable variant="card"`) | `pages/ProjectOverview.tsx` (MCP Servers section) |
| A multi-step form / wizard | `components/ComponentCreate/IntegrationWizard.tsx` |
| A settings page | `pages/SettingsPage.tsx` |
| A dashboard with stat tiles and charts | `pages/Analytics.tsx` |
| Empty and error states | `pages/EmptyComponentList.tsx`, `pages/ErrorPage.tsx` |
**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:
```bash
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 `